Exporty

XDENT Enterprise používá asynchronní model zpracování exportů. Export se nezpracovává synchronně při odeslání požadavku, místo toho se zařadí do fronty a zpracovává se na pozadí. Výsledek exportu stáhnete až po dokončení zpracování.

Dostupnost

Exporty jsou dostupné pouze pro tarify Business a Enterprise.

Omezení datového rozsahu

U exportů, které filtrují podle období, je obecný maximální interval 1 rok. Některé typy exportu však mohou mít tento limit nastaven jinak.

Přehled stavového diagramu

POST /ExportRequest/{typ}
         │
         ▼
      QUEUED ──── DELETE /Cancel/{id} ──► CANCELLED
         │
         ▼
    PROCESSING
         │
    ┌────┴────┐
    ▼         ▼
COMPLETED   FAILED ──► (automatický retry)
                              │
                       (po vyčerpání pokusů)
                              │
                              ▼
                          CANCELLED

Krok 1 – Odešlete požadavek na export

Zavolejte příslušný POST endpoint na základě typu dat, která chcete exportovat.

API odpoví objektem s identifikátorem exportu a stavem QUEUED. Export se zařadí do fronty a bude se zpracovávat na pozadí.

Volby exportu

Všechny exporty přijímají tyto volitelné query parametry:

Parametr	Typ	Povinný	Popis
format	string	ne	Formát výstupu: JSON, CSV (výchozí: JSON)
password	string	ne	Heslo pro šifrování výstupního ZIP souboru
email	string	ne	E-mail pro notifikaci po dokončení exportu
callback	string	ne	Webhook URL - API pošle POST požadavek s daty exportu (ne výsledkem) na tuto URL po dokončení zpracování

Formáty výstupu

Formát	Popis
JSON	Výsledek jako JSON soubor
CSV	Výsledek jako CSV soubor s tabulkovými daty

Časová razítka v JSON exportech

Datumové a časové hodnoty v exportních souborech bez Utc v názvu jsou lokální čas XDENT.

Pole s Utc v názvu označují skutečný UTC čas a mohou používat UTC zápis s příponou Z.

Upozornění

Ne každý typ exportu podporuje všechny formáty. Viz přehled typů exportů.

Krok 2 – Sledujte stav zpracování

Pokud není nastavena notifikace po zpracování (e-mail/webhook), můžete se na stav exportu dotázat:

GET /api/v1/ExportResult/Status/3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Api-Key: YOUR_API_KEY

Popis stavů

Stav	Popis
QUEUED	Export čeká ve frontě, zpracování ještě nezačalo
PROCESSING	Export se aktivně zpracovává, soubor se generuje
COMPLETED	Zpracování dokončeno, soubor je připraven ke stažení
FAILED	Zpracování selhalo, systém provede automatický opakovaný pokus
CANCELLED	Export byl trvale zrušen - buď ručně, nebo po vyčerpání všech pokusů

Automatický retry

Pokud zpracování selže (FAILED), systém automaticky zkusí export znovu vygenerovat. Teprve po vyčerpání maximálního počtu pokusů přejde export do stavu CANCELLED.

Přehledně zobrazit všechny čekající exporty lze tímto voláním:

GET /api/v1/ExportResult/Queued
X-Api-Key: YOUR_API_KEY

Krok 3 – Výsledek zpracování

Po přechodu do stavu COMPLETED nebo FAILED/CANCELLED obsahuje odpověď i pole Result:

Pole	Typ	Popis
Result.Success	boolean	Zda zpracování proběhlo úspěšně
Result.Errors	ExportError[]	Seznam chybových zpráv (pokud zpracování selhalo)
Result.DurationMs	int	Doba zpracování v milisekundách
Result.FileSizeBytes	int	Velikost výstupního souboru v bajtech
Result.CallbackSent	boolean	Zda byl callback úspěšně odeslán
Result.NotifyEmailSent	boolean	Zda byl notifikační e-mail úspěšně odeslán

ExportError

Pole	Typ	Popis
ErrorMessage	string	Text chyby

Krok 4 – Stáhněte výsledek

Jakmile je stav COMPLETED, stáhněte výsledný soubor:

GET /api/v1/ExportResult/Download/3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Api-Key: YOUR_API_KEY

Odpověď je soubor formátu zip. Tento soubor může být zaheslován, pokud exportu byl nastaven query parametr password. Uvnitř tohoto souboru naleznete soubor(y) exportu ve výchozím formátu, nebo ve formátu, který byl nastaven v query parametru format.

Zrušení čekajícího exportu

Export, který ještě nebyl převzat ke zpracování (stav QUEUED), lze zrušit:

DELETE /api/v1/ExportRequest/Cancel/3fa85f64-5717-4562-b3fc-2c963f66afa6
X-Api-Key: YOUR_API_KEY

Pokud export neexistuje (např. chybné idExportJob v URL), API vrátí 404 s kódem EXPORT_NOT_FOUND.

Exporty ve stavu PROCESSING, COMPLETED, FAILED nebo CANCELLED zrušit nelze – API vrátí 409 Conflict s kódem EXPORT_NOT_CANCELLABLE.

Notifikace a callback

E-mail notifikace

Přidejte parametr email k požadavku na export. Po dokončení (nebo selhání) zpracování obdržíte upozornění na zadanou adresu.

POST /api/v1/ExportRequest/Invoices?format=JSON&email=integrace@firma.cz

Webhook callback

Přidejte parametr callback s URL vaší aplikace. Po dokončení zpracování API odešle na tuto adresu HTTP POST s daty:

Pole	Typ	Popis
IdExportJob	uuid	Identifikátor exportu
ExportType	string	Kód typu exportu
Success	boolean	Zda zpracování proběhlo úspěšně
Status	string	Výsledný stav (COMPLETED, FAILED, CANCELLED)
ErrorMessages	ExportError[]	Seznam chyb (pokud zpracování selhalo)
DurationMs	int	Doba zpracování v milisekundách
FileName	string	Název výstupního souboru
FileSizeBytes	int	Velikost souboru v bajtech

ExportError

Pole	Typ	Popis
ErrorMessage	string	Text chyby

Doporučení pro implementaci

• Využijte callback nebo e-mail notifikaci, abyste se nemuseli aktivně dotazovat na stav.
• Callback obsahuje metadata o výsledku zpracování, samotný soubor vždy stahujte přes download endpoint.