Stránkovanie a chyby
Načítanie ďalších strán, aplikačné kódy a limity API.
Stránkovanie dokladov
Pri POST /v2/documents používajte searchAfter:
- Prvú požiadavku pošlite bez
data.searchAftera nastavte zoradenie, napríkladorderBy: "issue_date". - Spracujte vrátené doklady.
- Ak odpoveď obsahuje neprázdne
searchAfter, preneste celé pole bez úprav dodata.searchAfternasledujúcej požiadavky. Zachovajte organizáciu, filtre aj zoradenie. - Pri
APP_NO_MORE_DATAukončite načítanie. Ak chýba ďalší token alebo sa token opakuje, neposielajte rovnakú požiadavku v nekonečnej slučke.
Pole continuationToken je v tejto schéme označené ako zastarané.
Pre /v2/documents špecifikácia uvádza limit 2 000 exportovaných dokladov na požiadavku. Pri APP_MAX_EXPORT_LIMIT_EXCEEDED zúžte rozsah filtrov, napríklad obdobie.
Bankové transakcie majú vlastnú schému stránkovania. Ich searchAfter môže obsahovať reťazce aj čísla; zachovajte pôvodné typy hodnôt.
Limit výsledkov a súhrnné odpovede
| Endpoint | data.limit | Správanie pri limit: 0 |
|---|---|---|
/v1/unprocessed-documents | 0–50; bez hodnoty sa použije predvolená veľkosť strany servera | Iba počty totalDocuments a notApprovedDocuments, bez dokladov |
/v1/organization/bank-transactions | 0–50, predvolene 50 | Iba dostupné zostatky bankových účtov, bez transakcií |
Na stránkovanie položiek použite hodnotu 1–50 a kurzor searchAfter. Režim limit: 0 slúži na súhrnné údaje. Tieto limity sa nevzťahujú automaticky na /v2/documents, ktorý má vlastné pravidlá uvedené vyššie.
HTTP a aplikačné chyby
Kontrolujte HTTP status aj JSON odpoveď. Štruktúra a dostupné kódy sa líšia podľa endpointu.
| Stav alebo kód | Význam a ďalší postup |
|---|---|
HTTP 400 | Pri nahrávaní súboru nesprávne vstupné údaje. Overte JSON, údaje súboru, príponu a veľkosť podľa referencie. |
HTTP 409 | Pri nahrávaní súboru už súbor existuje. Overte stav pred opakovaním požiadavky. |
HTTP 403 | Požiadavka nie je autorizovaná. Skontrolujte kľúč a oprávnenia. |
HTTP 404 | Požadovaný zdroj sa nenašiel. Overte cestu a identifikátory. |
HTTP 500 | Chyba servera. Zaznamenajte čas a odpoveď pre diagnostiku bez API kľúča. |
APP_UNAUTHENTICATED | Skontrolujte autentifikáciu hlavičkou api_key. |
APP_INCORRECT_INPUT_DATA | Overte vstupné polia, filtre, typy a povolené hodnoty podľa schémy. |
APP_ORGANIZATION_NOT_FOUND_CODE | Organizácia podľa zadaného IČO sa nenašla. |
APP_MAX_EXPORT_LIMIT_EXCEEDED | Zúžte rozsah exportu dokladov. |
APP_READ_DATA_ERROR | Chyba pri načítaní údajov. |
APP_NO_MORE_DATA | Koniec dostupných údajov pri načítavaní dokladov. |
Limity API prepojenia
Podľa návodu API prepojenia API po vyčerpaní nastaveného denného alebo mesačného limitu vráti HTTP 429 Too Many Requests. Odpoveď obsahuje informáciu o prekročenom limite. Takto odmietnuté požiadavky sa v Histórii aktivity nezobrazia.
Limity využitia API kľúča sú odlišné od limitu počtu dokladov na jednu exportnú požiadavku. Počet jednotiek za jednotlivé operácie a pravidlá pri chybách nájdete na stránke Pricing.
Opakovanie požiadaviek
Pri dočasnej chybe načítania odporúčame obmedzený počet opakovaní s rastúcim odstupom. Po chybe autentifikácie alebo vstupu najskôr opravte príčinu.
Pri vystavení faktúry, odoslaní emailu alebo inej zmene údajov neodosielajte požiadavku po timeoute automaticky znova. Najskôr overte výsledný stav; špecifikácia negarantuje idempotenciu ani nedefinuje idempotency key.
Zdroj technických parametrov: OpenAPI špecifikácia Doklado.