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í.

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í export
callback	string	ne	Webhook URL - API pošle POST požadavek s daty exporty (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

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	pole	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

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

Exporty ve stavu PROCESSING, COMPLETED nebo FAILED zrušit nelze – vrátí 404.

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 jobu
exportType	string	Kód typu exportu
success	boolean	Zda zpracování proběhlo úspěšně
status	string	Výsledný stav (COMPLETED, FAILED, CANCELLED)
errorMessages	pole	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

Doporučení pro implementaci

• Využijte callback nebo e-mail notifikaci, abyste se nemuseli aktivně dotazovat na stav.