Volání API a formát odpovědi

Stažení každé sekce probíhá ve dvou krocích: nejdřív požádáte o export a dostanete odkaz, pak z odkazu stáhnete soubor s daty.

Krok 1: požádat o export

Pošlete POST na adresu ve tvaru {apiUrl}{version}/data/{sekce}/, tedy například:

https://client.datadepo.cz/api/1/data/business/

Tělo požadavku je běžný formulář (application/x-www-form-urlencoded) s poli:

Odpověď je JSON a má jednu ze tří podob:

{"state":"ok","url":"https://client.datadepo.cz/api.access/pick-data/?token=xxxxxxxxxxxxxxxxxxxx"}
{"suspend":true,"until":"2026-09-08 03:00:00"}
{"error":"Chyba autorizace: chybné uživatelské jmeno nebo heslo!"}

Pole url berte vždy z odpovědi a její tvar sami neskládejte, může se změnit.

Krok 2: stáhnout data

Z adresy v poli url stáhněte soubor (GET i POST, bez dalších parametrů). Odkaz je jednorázový: po prvním stažení přestane platit a další pokus vrátí {"error":"Podle zadaného tokenu nebyla nalezena žádní data"}. Pro nové stažení zopakujte krok 1.

Soubor je ve formátu NDJSON: první řádek je hlavička, každý další řádek jeden samostatný JSON objekt.

{"generatedAt":1788794476,"numRecords":"305"}
{"id":"21584777","code":"ABC-123", ... }
{"id":"21584778","code":"ABC-124", ... }

Soubor se generuje průběžně při stahování, u celého katalogu může být velký a trvat i minuty. Nastavte proto dostatečný timeout spojení (původní PHP knihovna používá 80 sekund na navázání spojení a čte proud až do konce).

Přírůstky přes lastDownload

Pošlete-li v kroku 1 lastDownload, dostanete jen záznamy změněné od tohoto času. Server od hodnoty sám odečte 60 sekund překryvu, takže o změny na hraně dvou stažení nepřijdete; počítejte s tím, že se občas některý záznam vrátí dvakrát.

Doporučený postup:

1. Při prvním spuštění pošlete lastDownload=0 a stáhněte celý katalog.
2. Z hlavičky si uložte generatedAt, zvlášť pro každou sekci.
3. Při dalších bězích pošlete uloženou hodnotu jako lastDownload a po úspěšném zpracování ji přepište novou.
4. Když potřebujete katalog srovnat celý (například po výpadku na vaší straně), pošlete znovu lastDownload=0.

I přírůstkový export umí přinést nárazově velké množství záznamů, například po hromadném přecenění u dodavatele. Zpracování proto pište tak, aby zvládlo i celý katalog.

Rozumný interval je jedno stažení za hodinu, v pořadí data a pak business. Častější dotazování nemá smysl, data se v DataDepu přepočítávají průběžně, ale ne po sekundách.

Pozastavení (suspend)

Během údržby může krok 1 místo odkazu vrátit {"suspend":true,"until":"..."}. V takovém případě:

1. přestaňte se dotazovat až do času until,
2. potvrďte, že jste pozastavení přijali, voláním POST https://client.datadepo.cz/api/1/put/suspend/ s poli user, pwd a until (hodnota z odpovědi). Odpověď je {"state":"ok"}.

Chyby

Chyba přijde vždy jako JSON s polem error a HTTP kódem 200, kontrolujte proto obsah odpovědi, ne jen HTTP stav. Nejčastější příčiny: špatné jméno nebo heslo (zkontrolujte tvar kod-klienta/nazev-uctu), neaktivní účet, neznámá sekce v adrese, použitý token.

Kompletní příklad

Přírůstek sekce business od 7. 9. 2026 17:12 (unixový čas 1788793577):

curl -X POST https://client.datadepo.cz/api/1/data/business/ \
     -d "user=moje-firma/repricing" \
     -d "pwd=TajneHeslo" \
     -d "lastDownload=1788793577"

{"state":"ok","url":"https://client.datadepo.cz/api.access/pick-data/?token=xxxxxxxxxxxxxxxxxxxx"}

curl "https://client.datadepo.cz/api.access/pick-data/?token=xxxxxxxxxxxxxxxxxxxx" -o business.ndjson

head -c 300 business.ndjson
{"generatedAt":1788794476,"numRecords":"305"}
{"id":"21584777","code":"ABC-123","supplierSet":"dodavatel-a","allowed":"1","active":"1","isExportable":"1","suppliers":{"dodavatel-a":{"prices":{"czk":{"tax":"21.00", ...

Při příštím běhu pošlete lastDownload=1788794476, tedy generatedAt z hlavičky tohoto souboru.