Stránkování, řazení a filtry

Stránkování

Seznamy dokladů, plateb a adresáře se vrací vždy po stránkách (od API 1.2) — celý seznam najednou z API nedostanete. Samotné parametry povinné nejsou: bez nich platí page=1 a pageSize=50.

Parametr	Význam	Výchozí	Maximum
page	číslo stránky (od 1)	1	—
pageSize	počet záznamů na stránku	50	200

GET /api/1.3/invoice_issued?page=2&pageSize=100

pageSize posílejte vždy s page

Server bere pageSize v úvahu jen tehdy, když je v dotazu zároveň page. Oba parametry se čtou společně; když dorazí jen jeden z nich, použijí se výchozí hodnoty. Samotné ?pageSize=200 se tedy tiše ignoruje a odpověď má 50 záznamů — a průchod stojí čtyřikrát víc dotazů, než jste čekali.

Odpověď obsahuje informace o stránkování:

{
  "pageCount": 22,
  "page": 2,
  "pageSize": 100,
  "_embedded": { "invoice_issued": [] }
}

Kolekce jsou vždy v _embedded pod klíčem podle názvu zdroje, odkaz na sebe sama v _links.self.href — viz HAL+JSON.

Řazení

Výchozí pořadí určuje aplikace a je sestupné — nejnovější záznamy první. Konkrétní pole, podle kterého se řadí, popis API neurčuje, takže se na ně nespoléhejte.

Vlastní řazení je podporované parametrem sort od API verze 1.3. Volitelný prefix - řadí sestupně, bez něj se řadí vzestupně.

Podle čeho jde řadit

Řazení podporuje deset zdrojů — faktury, zálohové faktury, opravné daňové doklady, objednávky a platby, vždy vydané i přijaté. Ostatní zdroje ho nemají; z dokladů se to týká i interních předpisů nákladů a přímého zaúčtování. Jediné pole, podle kterého lze řadit, je modified, tedy datum poslední změny záznamu:

GET /api/1.3/invoice_issued?sort=-modified

Výsledek: faktury vydané od naposledy změněné.

Jakákoli jiná hodnota skončí chybou Neplatné pole pro řazení.

Filtrování seznamů

Seznam jde zúžit parametry v dotazu. Které z nich zdroj umí, je u každé operace v referenci — tady jsou ty, které se opakují napříč doklady, protože právě je potřebuje skoro každá integrace.

Parametr	Co vybere
date_from, date_to	datum vystavení, včetně krajních dnů
date_vat_from, date_vat_to	podle DUZP
maturity_date_from, maturity_date_to	podle data splatnosti
price_from, price_to	cena celkem; ve výchozím stavu v CZK, s filter_price_by_doc_currency=true v měně dokladu
paid	true uhrazené, false neuhrazené
accounted	true zaúčtované, false nezaúčtované
deleted	true vrátí jen logicky smazané doklady; bez parametru se nevracejí
currency, payment_type	kód měny, způsob úhrady
variable_symbol, sequence_code	variabilní symbol, číslo dokladu
customer_id, supplier_id	ID protistrany z adresáře
customer_ico, supplier_ico	IČO protistrany, když ID neznáte

Adresář má vlastní sadu (external_code, name, comid, vatid, email, phone, account_number, vat_payer, customer_group_id); právě external_code je klíč pro synchronizaci adresáře. Nejbohatší je účetní deník — filtruje se v něm i podle účtů chartaccount_md a chartaccount_dal, střediska, zakázky a typu i ID zdrojového dokladu.

Porovnává se na přesnou shodu, ne částečnou; výjimkou jsou name_search a description_search u stavů dokladů. Dvojice *_from / *_to fungují i samostatně.

Překlep ve jménu parametru projde bez chyby

Parametr, který zdroj nezná, server tiše zahodí a vrátí nezúžený seznam. ?paid=true vrátí uhrazené faktury, ?payd=true vrátí všechny — a nic nenapoví, že se filtr neuplatnil. Za chybu stojí naopak špatná hodnota: booleany se posílají jako true a false, ?paid=1 skončí odpovědí 400 s tělem {"paid":["Hodnota musí být 'true' nebo 'false'."]}.

Filtr podle data změny neexistuje: žádný zdroj nemá parametr typu modified_from, i když podle modified jde řadit. Pro inkrementální stahování proto zbývá sort=-modified a čtení stránek, dokud nenarazíte na záznam starší než váš vodoznak — postup je v Limitech a kvótách.