Datové typy

Typy jsou pojmenované tak, jak je uvidíte u každého pole v referenci.

Typ	Popis
string	Textový řetězec (UTF-8)
integer	Celé číslo — ID záznamů, page, pageSize
number	Desetinné číslo, oddělovač tečka (1500.10) — částky, počty jednotek (items[].amount) i sazby DPH (items[].vat)
boolean	true nebo false
string(date)	Datum ve tvaru YYYY-MM-DD
string(date-time)	Datum a čas podle ISO 8601

U částek žádný počet desetinných míst předepsaný není — server je vrací tak, jak mu vyjdou (6000.0). Volitelná pole mohou být null.

Tělo zápisu není tvar odpovědi

Nejčastější omyl na začátku integrace: vzít objekt z GET a poslat ho zpátky do POST nebo PUT. Server ho odmítne. Tvar pro čtení a tvar pro zápis se liší ve třech věcech a platí to napříč zdroji, ne jen u dokladů.

Co	GET (odpověď)	POST / PUT (požadavek)
vazba na jiný záznam	vnořený objekt (customer, supplier, bank_account)	ID v poli s příponou _id, případně bank_account jako číslo
dopočtené částky	price, price_czk, price_inc_vat, to_be_paid	neposílají se, server je spočítá sám
pole jen pro čtení	id, deleted, accounted, _links	server je ignoruje

Přesnou dvojici tvarů má každý zdroj v referenci: detail popisuje schéma …Detail, tělo zápisu schéma …Params.

PUT je úplná náhrada

Není to částečná úprava. PUT vyžaduje všechna povinná pole stejně jako vytvoření a co v těle nepošlete, se přepíše výchozí hodnotou nebo se smaže — u dokladů se to nejčastěji projeví na položkách. Než doklad měníte, načtěte si detail, ne položku seznamu: seznam vrací jen podmnožinu polí.

API zároveň nezná If-Match ani ETag, takže dva souběžné zápisy nikdo nerozsoudí — vyhrává ten pozdější. Když nad jedním dokladem pracuje víc procesů, musí si pořadí pohlídat integrace.

Když se odpověď ztratí

Zápisy nejsou idempotentní a API nemá hlavičku typu Idempotency-Key. Zopakovaný POST po vypršení spojení tedy založí druhý záznam.

Obrana se liší podle zdroje. Pole external_code pro váš vlastní identifikátor jde zapsat u zákazníků, dodavatelů, faktur přijatých, zálohových faktur přijatých, interních předpisů nákladů, plateb přijatých a položek ceníku. Před opakováním se jím dá dohledat, jestli záznam už nevznikl — postup je v Synchronizaci adresáře.

Ostatní zdroje tuhle pojistku nemají. Týká se to celé vydané strany včetně faktur vydaných, a objednávek přijatých, kde je external_code jen pro čtení. Tam po neúspěšném zápisu zbývá dohledat doklad podle data, protistrany a částky, než se zápis zopakuje.

Doklady v cizí měně

Doklad nese měnu v poli currency (kód podle Měn, dostupné jen s rozšířením Účtování v cizích měnách). Vedle částek v měně dokladu vrací server dopočtené koruny v polích s příponou _czk — price_czk, price_inc_vat_czk.

Použitý kurz API nevrací ani nepřijímá; v popisu API žádné pole pro kurz není. Když integrace potřebuje přepočet zpětně doložit, musí si ho odvodit z dvojice price a price_czk.

Při filtrování podle částky se price_from a price_to rozumí ve výchozím stavu v korunách. Když je chcete brát v měně dokladu, přidejte filter_price_by_doc_currency=true — viz Filtrování seznamů.

Typy dokladů

Interní identifikátory používané v parametrech typu doctype:

Kód	Zdroj
FV	Faktury vydané
FP	Faktury přijaté
ZFV	Zálohové faktury vydané
ZFP	Zálohové faktury přijaté
ODV	Opravné daňové doklady vydané
ODP	Opravné daňové doklady přijaté
PV	Platby vydané
PP	Platby přijaté
OP	Objednávky
OV	Objednávky vydané
PZ	Přímé zaúčtování
IPN	Interní předpisy nákladů
UD	Uzávěrkový doklad — vzniká uzávěrkou, přes API se nezakládá

Číselníky Typy DPH a Typy účetních položek přijímají jen prvních devět kódů; OP, OV, PZ a UD u nich skončí chybou.

Verzování polí

Pole nebo chování dostupné až od novější verze je v referenci označené v popisu — např. (API 1.3+) u realtime_payment_fetch u bankovních účtů nebo (od verze 1.2) u připojování zálohových faktur k faktuře vydané.