Ako správne pracovať s API

Spôsob spracovania, uloženie údajov aj riadenie ďalších volaní sú plne na strane klienta. Doklado neurčuje, do akého systému údaje prenášate. Nasledujúce príklady ukazujú dva možné postupy pri práci s dokladmi.

Vyberte si postup

Prístupy si vyberte podľa potrieb integrácie. Filter podľa stavu exportu a dátumový rozsah možno aj kombinovať.

Pripravte API kľúč

V termináli nahraďte vzorovú hodnotu svojím kľúčom z Doklado:

DOKLADO_API_KEY="VYGENEROVANY_API_KEY_V_DOKLADO"

cURL príklady spúšťajte v tom istom termináli. Vzorové IČO 12345678, identifikátory dokladov a dátumy nahraďte vlastnými údajmi. Podrobnosti o prístupe nájdete na stránke Autentifikácia.

Možnosť 1: Používajte stav exportu

1. Načítajte neexportované doklady

Volanie POST /v2/documents s filtrom isExported: false vyberie neexportované doklady.

curl --request POST \
  'https://api-gateway-prod-europe-west-1-7epuecvu.ew.gateway.dev/v2/documents' \
  --header "api_key: ${DOKLADO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "data": {
    "organizationId": "12345678",
    "isExported": false,
    "orderBy": "creation_date",
    "orderByDescending": false
  }
}'

Skontrolujte HTTP stav aj polia success a code. Doklady nájdete v poli data. Ak výsledok pokračuje na ďalšej strane, postupujte podľa sekcie Stránkovanie nižšie.

2. Spracujte a uložte údaje na svojej strane

Údaje uložte alebo spracujte podľa účelu svojej aplikácie. K záznamu si uchovajte aj documentId z odpovede Doklado, aby ste pri opakovanom doručení rozpoznali už spracovaný doklad.

Tento krok implementujete vo vlastnom systéme. Pokračujte až po potvrdení, že sa údaje úspešne a trvalo uložili alebo sa dokončila požadovaná operácia.

3. Označte úspešne spracované doklady

Zavolajte POST /v2/documents/setExported iba pre doklady, ktoré ste úspešne spracovali. Nasledujúci príklad používa stav sync_with_acc_soft zo schémy API:

curl --request POST \
  'https://api-gateway-prod-europe-west-1-7epuecvu.ew.gateway.dev/v2/documents/setExported' \
  --header "api_key: ${DOKLADO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "data": {
    "documents": [
      {
        "documentId": "ID_SPRACOVANEHO_DOKLADU_1",
        "status": "sync_with_acc_soft"
      },
      {
        "documentId": "ID_SPRACOVANEHO_DOKLADU_2",
        "status": "sync_with_acc_soft"
      }
    ]
  }
}'

Názov hodnoty sync_with_acc_soft je technické označenie stavu v API. Spôsob spracovania údajov vo vašej integrácii určujete vy. Ďalšie stavy nájdete v REST API referencii.

Okrem celkového výsledku skontrolujte data.results pre každý doklad. Položka obsahuje documentId, success a prípadný code. Úspech jedného dokladu nepotvrdzuje úspech ostatných.

4. Ďalší dopyt opäť obmedzte na neexportované doklady

Pri ďalšom spustení použite rovnaké načítanie z kroku 1 s isExported: false. Doklady úspešne označené ako exportované sa už do tohto výberu nezaradia.

Samotné načítanie exportný stav nemení. Tento postup tiež neslúži na sledovanie neskorších úprav už exportovaných dokladov.

Možnosť 2: Používajte dátumový rozsah

Ak nechcete meniť stav exportu, vyberajte konkrétne obdobie. Klient si uchová, ktoré obdobia a doklady už úspešne spracoval.

1. Načítajte zvolené obdobie

Príklad vyberá podľa dátumu vytvorenia v Doklado (dateType: "create"). Filter isExported je zámerne vynechaný, takže výber nie je obmedzený na stav exportu.

curl --request POST \
  'https://api-gateway-prod-europe-west-1-7epuecvu.ew.gateway.dev/v2/documents' \
  --header "api_key: ${DOKLADO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "data": {
    "organizationId": "12345678",
    "dateFrom": "2026-09-14T00:00:00Z",
    "dateTo": "2026-09-15T00:00:00Z",
    "dateType": "create",
    "orderBy": "creation_date",
    "orderByDescending": false
  }
}'

Typ dátumu zvoľte podľa potreby:

Dátum vystavenia môže patriť do minulého obdobia aj pri novo pridanom doklade. Ak chcete priebežne preberať novovytvorené doklady, zohľadnite tento rozdiel pri výbere filtra.

2. Spracujte všetky strany a uložte si dokončené obdobie

Spracujte údaje aj prípadné ďalšie strany výsledku. Až po úspešnom dokončení celého obdobia si klient uloží, že ho spracoval. Pri chybe ponechajte možnosť pokračovať alebo obdobie zopakovať s rozpoznaním už uložených dokladov.

3. Posuňte rozsah ďalšieho dopytu

Nasledujúci príklad pokračuje ďalším obdobím. Hodnoty si v reálnej integrácii vypočítava klient:

curl --request POST \
  'https://api-gateway-prod-europe-west-1-7epuecvu.ew.gateway.dev/v2/documents' \
  --header "api_key: ${DOKLADO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "data": {
    "organizationId": "12345678",
    "dateFrom": "2026-09-15T00:00:00Z",
    "dateTo": "2026-09-16T00:00:00Z",
    "dateType": "create",
    "orderBy": "creation_date",
    "orderByDescending": false
  }
}'

Pri tomto postupe nemusíte volať setExported. Každé opakované načítanie rovnakého rozsahu však znova započítava spotrebu.

Stránkovanie

Pre oba postupy platí:

1. Prvú stranu načítajte bez searchAfter.
2. Ak odpoveď obsahuje neprázdne pole searchAfter, celé ho preneste do data.searchAfter ďalšej požiadavky.
3. Počas stránkovania zachovajte organizáciu, filtre, dátumový rozsah a zoradenie.
4. Pri APP_NO_MORE_DATA ukončite načítanie. Chýbajúci alebo opakujúci sa token nesmie viesť k nekonečnej slučke.

Príklad ďalšej strany pri postupe s dátumovým rozsahom:

curl --request POST \
  'https://api-gateway-prod-europe-west-1-7epuecvu.ew.gateway.dev/v2/documents' \
  --header "api_key: ${DOKLADO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "data": {
    "organizationId": "12345678",
    "dateFrom": "2026-09-14T00:00:00Z",
    "dateTo": "2026-09-15T00:00:00Z",
    "dateType": "create",
    "orderBy": "creation_date",
    "orderByDescending": false,
    "searchAfter": [
      "2026-09-14T12:00:00.000",
      "ID_Z_ODPOVEDE_SEARCH_AFTER"
    ]
  }
}'

Ukážkové pole searchAfter nahraďte presným poľom z predchádzajúcej odpovede. Nevytvárajte ho ručne z dátumu a identifikátora dokladu.

Pre jednoduchý postup s isExported: false najskôr dokončite načítanie a uloženie všetkých strán, potom potvrďte export úspešne spracovaných dokladov. Tak počas stránkovania sami nemeníte exportný stav dokladov vo výbere. Pri novom behu začnite bez starého searchAfter.

Ďalšie pravidlá nájdete na stránke Stránkovanie a chyby.

Spotreba pri oboch postupoch

Príklady predpokladajú úspešné volania, presne 70 prečítaných dokladov a žiadne ďalšie operácie. Aj doklady vyradené dodatočným filtrovaním môžu ovplyvniť skutočnú spotrebu.

Podrobné účtovanie jednotlivých operácií nájdete na stránke Pricing. Nastavenie limitov opisuje návod API prepojenia.

Zdroj technických parametrov: OpenAPI špecifikácia Doklado.