API - BillApp.cz

Obsah

Faktury
Výdaje
Účty
Kontakty
Položky
Měny
ActiveResource

Úvod

BillApp.cz Vám umožňuje přistupovat k datům uvnitř Vašeho účtu pomocí API. Naše API následuje REST konvenci a provádí přenos dat pomocí HTTP protokolu. Všechna komunikace probíha pouze přes SSL (tedy HTTPS), pokud se pokusíte připojit bez SSL budete přesměrováni.

Autorizace

Autorizace probíha přes HTTP Basic Authentication skrze standardní účet ve Vaší agendě, k použití API není potřeba vytvářet žádné další uživatele.

Formáty

BillApp.cz API dokáže pracovat jak s XML formátem, tak s JSON formátem. Ve zbytku této dokumentace se bude pracovat s XML formátem.

HTTP návratové kódy

BillApp.cz používá návratové kódy HTTP protokolu k informování o výsledku požadované akce. Stavové kódy jsou následující:

200	OK	Požadavek byl úspěšný.
201	Created	Objekt byl vytvořen.
404	Not Found	Objekt nebyl nalezen.
422	Unprocessable entity	Objekt nebyl vytvořen kvůli chybnému vstupu. Chyba nebo chyby jsou vráceny v XML výstupu.
500	Internal Server Error	Vnitřní chyba při zpracování požadavku.

Příklad

Funkčnost API si můžete ověrit například pomocí nástroje curl:

curl -H 'Accept: application/xml' \
     -H 'Content-Type: application/xml' \
     -u vas_email:vase_heslo  https://vaseagenda.billapp.cz/invoices.xml

1. Faktury

Detail faktury

Požadavek: GET /invoices/ID.xml

Odpověd:

<invoice>
  <id type="integer">ID</id>
  <number>Číslo faktury</number>
  <account-id type="integer">ID účtu</account-id>
  <client-id type="integer">ID klienta</client-id>
  <due-date type="date">Datum splatnosti</due-date>
  <issue-date type="date">Datum vystavení</issue-date>
  <paid-on type="date">Datum uzavření (zaplacení) faktury</paid-on>
  <notes>Poznámky</notes>
  <status>Stav faktury</status>
  <tax-amount type="decimal">Celková částka DPH</tax-amount>
  <total-amount type="decimal">Celková částka faktury</total-amount>
  <created-at type="datetime">Datum vytvoření</created-at>
  <updated-at type="datetime">Datum poslední úpravy faktury</updated-at>
  <currency>
    <code>Kód měny</code>
    <name>Název měny</name>
  </currency>
  <lines type="array">
    <line type="InvoiceLine">
      <description>Popis polozky</description>
      <quantity type="integer">Počet</quantity>
      <unit-price type="decimal">Cena za jednotku</unit-price>
      <vat type="decimal">DPH</vat>
      <unit-type>Typ položky</unit-type>
    </line>
  </lines>
</invoice>

Odeslání faktury emailem

Požadavek: POST /invoices/ID/emails.xml

Data požadavku:

<invoice-email>
  <to>Příjemce</to>
  <attach-pdf>Připojit PDF soubor (true|false)</attach-pdf>
  <cc-to-me>Poslat kopii uživateli</cc-to-me>
  <reply-to></reply-to>
  <subject>Předmět emailu</subject>
  <body>Tělo emailu</body>
</invoice-email>

Platba faktury

Požadavek: POST /transactions.xml

Data požadavku:

<transaction>
  <bill-type>Invoice</bill-type>
  <bill-id>ID faktury</bill-id>
  <to-account-id>ID účtu, na kterém proběhla platba</to-account-id>
  <date>Datum platby</date>
  <amount>Zaplacená částka</amount>
  <notes>Poznámky</notes>
</transaction>

Historie faktury

Požadavek: GET /invoices/ID/history.xml

Odpověd:

<events type="array">
  <event>
    <created-at type="datetime">Čas</created-at>
    <description>Událost</description>
  </event>
  ...
</events>

Seznam všech faktur

Požadavek: GET /invoices.xml

Odpověd:

<invoices>
  <invoice>
    ...
  </invoice>
  ...
</invoices>

Vytvoření nové faktury

Požadavek: POST /invoices.xml

Data požadavku:

<invoice>
  <number>Číslo faktury</number> Povinné
  <account-id>ID účtu</account-id> Povinné
  <client-id>ID klienta</client-id>
  <due-date>Datum splatnosti</due-date> Povinné
  <issue-date>Datum vystavení</issue-date> Povinné
  <notes>Poznámky</notes>
  <show-logo>Zobrazit logo na faktuře?</show-logo>
  <lines-attributes>
    <line>
      <description>Popis položky</description> Povinné
      <quantity>Počet</quantity> Povinné
      <unit-price>Cena za jednotku</unit-price> Povinné
      <vat>DPH</vat>
      <unit-type>Typ položky</unit-type> Povinné
    </line>
  </lines-attributes>
</invoice>

Úprava existující faktury

Požadavek: PUT /invoices/ID.xml

2. Výdaje

Detail výdaje

Požadavek: GET /expenses/ID.xml

Odpověd:

<expense>
  <id type="integer">ID</id>
  <number>Číslo výdaje</number>
  <account-id type="integer">ID účtu</account-id>
  <due-date type="date">Datum splatnosti</due-date>
  <issue-date type="date">Datum vystavení</issue-date>
  <notes>Poznámky</notes>
  <paid-on type="date">Datum uzavření (zaplacení) výdaje</paid-on>
  <status>Stav</status>
  <total-amount type="decimal">Celková částka</total-amount>
  <vendor-id type="integer">ID dodavatele</vendor-id>
  <created-at type="datetime">Datum vytvoření</created-at>
  <updated-at type="datetime">Datum poslední úpravy</updated-at>
  <currency>
    <code>Kód měny</code>
    <name>Název měny</name>
  </currency>
</expense>

Historie výdaje

Požadavek: GET /expenses/ID/history.xml

Odpověd:

<events type="array">
  <event>
    <created-at type="datetime">Čas</created-at>
    <description>Událost</description>
  </event>
  ...
</events>

Seznam všech výdajů

Požadavek: GET /expenses.xml

Odpověd:

<expenses type="array">
  <expense>
    ...
    <currency>
    ...
    </currency>
  </expense>
  ...
</expenses>

Vytvoření nového výdaje

Požadavek: POST /expenses.xml

Data požadavku:

<expense>
  <number>Číslo výdaje</number> Povinné
  <issue-date>Datum vystavení</issue-date> Povinné
  <due-date>Datum splatnosti</due-date> Povinné
  <total-amount>Celková částka</total-amount> Povinné
  <tax-amount>Částka DPH</tax-amount>
  <notes>Poznámky</notes>
  <account-id>ID účtu</account-id>
  <vendor-id>ID dodavatele</vendor-id>
</expense>

Úprava existujícího výdaje

Požadavek: PUT /expenses/ID.xml

3. Účty

Detail účtu

Požadavek: GET /accounts/ID.xml

Odpověd:

<account>
  <balance type="decimal">Bilance</balance>
  <id type="integer">ID</id>
  <kind>Typ účtu</kind>
  <name>Název účtu</name>
  <created-at type="datetime">Datum vytvoření</created-at>
  <updated-at type="datetime">Datum poslední úpravy</updated-at>
  <currency>
    <code>Kód měny</code>
    <name>Název měny</name>
  </currency>
  <bank-account>
    <bank-name>Název banky</bank-name>
    <iban>IBAN účtu</iban>
    <number>Číslo účtu</number>
  </bank-account>
</account>

Seznam všech účtů

Požadavek: GET /accounts.xml

Odpověd:

<accounts type="array">
  <account>
    ...
  </account>
  ...
</accounts>

Vytvoření nového účtu

Požadavek: POST /accounts.xml

Data požadavku:

<account>
  <kind>Typ účtu (bank|cash)</kind> Povinné
  <name>Název účtu</name> Povinné
  <currency-id>ID měny</currency-id>
  <bank-account-attributes>
    <bank-name>Název banky</bank-name>
    <iban>IBAN účtu</iban>
    <number>Číslo účtu</number>
  </bank-account-attributes>
</account>

Úprava existujícího účtu

Požadavek: PUT /accounts/ID.xml

4. Kontakty

Detail kontaktu

Požadavek: GET /contact/ID.xml

Odpověd:

<contact>
  <id type="integer">ID</id>
  <full-name>Jméno</full-name>
  <company>Název společnosti</company>
  <email>Email</email>
  <web>Web</web>
  <phone-number>Telefonní číslo</phone-number>
  <id-number>IČ</id-number>
  <vat-number>DIČ</vat-number>
  <notes>Poznámky</notes>
  <street>Ulice</street>
  <city>Město</city>
  <postcode>PSČ</postcode>
  <country>Země</country>
  <created-at type="datetime">Datum vytvoření</created-at>
  <updated-at type="datetime">Datum poslední úpravy</updated-at>
</contact>

Seznam všech kontaktů

Požadavek: GET /contacts.xml

Odpověd:

<contacts type="array">
  <contact>
    ...
  </contact>
  ...
</contacts>

Vytvoření nového kontaktu

Požadavek: POST /contacts.xml

Data požadavku:

<contact>
  <company>Název společnosti</company>
  <full-name>Jméno</full-name>
  <email>Email</email>
  <web>Web</web>
  <phone-number>Telefonní číslo</phone-number>
  <id-number>IČ</id-number>
  <vat-number>DIČ</vat-number>
  <notes>Poznámky</notes>
  <city>Město</city>
  <street>Ulice</street>
  <postcode>PSČ</postcode>
  <country>Země</country>
</contact>

Úprava existujícího kontaktu

Požadavek: PUT /contacts/ID.xml

5. Položky

Detail položky

Požadavek: GET /items/ID.xml

Odpověd:

<item>
  <id type="integer">ID</id>
  <name>Název</name>
  <description>Popis</description>
  <price type="decimal">400.0</price>
  <unit-type>Typ položky</unit-type>
  <vat type="decimal">Sazba DPH</vat>
  <created-at type="datetime">Datum vytvoření</created-at>
  <updated-at type="datetime">Datum poslední úpravy</updated-at>
  <category>
    <name>Název kategorie</name>
  </category>
</item>

Seznam všech položek

Požadavek: GET /items.xml

Odpověd:

<items type="array">
  <item>
    ...
  </item>
  ...
</items>

Vytvoření nové položky

Požadavek: POST /items.xml

Data požadavku:

<item>
  <name>Název</name>  Povinné
  <description>Popis</description>
  <price>Cena</price>  Povinné
  <unit-type>Typ položky</unit-type> Povinné
  <vat>Sazba DPH</vat>
  <category-id>ID kategorie</category-id>
</item>

Úprava existující položky

Požadavek: PUT /items/ID.xml

7. Měny

Seznam všech měn

Požadavek: GET /currencies.xml

Odpověd:

<currencies type="array">
  <currency>
    ...
  </currency>
  ...
</currencies>

8. ActiveResource

Pokud používáte Ruby On Rails, doporučujeme Vám použít knihovnu ActiveResource. Příklad použití:

class BillApp::Resource < ActiveResource::Base
  self.site     ="https://vaseagenda.billapp.cz"
  self.user     = "vasejmeno@email.cz"
  self.password = "vaseheslo"
end

class BillApp::Account < BillApp::Resource
  self.element_name = "account"
end

class BillApp::Contact < BillApp::Resource
  self.element_name = "contact"
end

class BillApp::Invoice < BillApp::Resource
  self.element_name = "invoice"
end

BillApp.cz - Online Fakturace

Dokumentace API

Obsah

Úvod

Autorizace

Formáty

HTTP návratové kódy

Příklad

1. Faktury

Detail faktury

Odeslání faktury emailem

Platba faktury

Historie faktury

Seznam všech faktur

Vytvoření nové faktury

Úprava existující faktury

2. Výdaje

Detail výdaje

Historie výdaje

Seznam všech výdajů

Vytvoření nového výdaje

Úprava existujícího výdaje

3. Účty

Detail účtu

Seznam všech účtů

Vytvoření nového účtu

Úprava existujícího účtu

4. Kontakty

Detail kontaktu

Seznam všech kontaktů

Vytvoření nového kontaktu

Úprava existujícího kontaktu

5. Položky

Detail položky

Seznam všech položek

Vytvoření nové položky

Úprava existující položky

7. Měny

Seznam všech měn

8. ActiveResource