FAQ

Zde najdete nejčastější otázky a odpovědi k integraci XDENT API.
FAQ o službě, tarifech a cenách naleznete zde.

Přístup a autentizace

Jaká hlavička je povinná pro autentizaci?

Každé chráněné volání musí obsahovat hlavičku X-Api-Key.

Akceptuje API i jiný zápis názvu hlavičky?

Ano. API akceptuje X-Api-Key i X-API-Key.

Jaký je formát hodnoty API klíče?

Klíč posílejte ve formátu KeyId.Secret.

Co se stane, když X-Api-Key chybí?

API vrací 400 s kódem MISSING_API_KEY.

Kdo může vytvářet/spravovat klíče?

Správu API klíčů může provádět pouze administrátorský účet v XDENT.
Klíče se spravují přímo v sekci Můj účet → Správa API.

Lze mít více API klíčů?

Ano, v rámci společnosti lze mít více API klíčů. Dostupný počet klíčů záleží na vašem tarifu.

Zapomenutý API klíč

Pokud jste zapomněli API klíč, je nutné ho odstranit a vytvořit znovu. Z bezpečnostních důvodů zobrazujeme celý klíč pouze jednou při jeho vytvoření, proto doporučujeme klíč ihned zkopírovat a uložit na bezpečné místo.

IP autorizace

Lze omezit přístup na whitelist IP adres?

Ano, přes IP autorizaci ve správě API.

Co se stane při volání z nepovolené IP?

API vrací 403 s kódem IP_NOT_AUTHORIZED.

Jak se API chová, když je IP autorizace zapnutá, ale whitelist je prázdný?

Autorizace se neaplikuje, dokud není přidaná alespoň jedna IP adresa.

Za jak dlouho se změna IP whitelistu projeví?

Změna se projeví do 5 minut.

Endpointy a data

Jaká je struktura endpointů?

Základní struktura route je vždy:

• /api/ – základ URL pro API.
• /v{verze}/ – segment verzování (např. v1).
• /{Controller} – název controlleru (např. Identity).
• /{Endpoint} – konkrétní endpoint/metoda daného controlleru (pokud existuje).

Příklad:

• GET /api/v1/Identity

Podrobnosti k verzování najdete v dokumentaci Verzování API.

Jaké typy endpointů jsou dostupné?

API nabízí dva typy endpointů:

• Live endpointy pro přímé čtení dat, například Client, Location, Staff.
• Queue endpointy pro asynchronní zpracování, typicky exporty. V tomto režimu nejprve vytvoříte požadavek na export a API jej zpracuje na pozadí podle aktuální zátěže systému.

Jak formátujete endpointy?

Tam, kde je potřeba získat data, se typicky používají tyto varianty:

• Simple: jednoduchý stránkovaný seznam.
• Extended: stránkovaný seznam rozšířený o filtry.
• Detail: vrací jednu konkrétní položku, obvykle s detaily, které v Simple a Extended nejsou.

Jaké stránkování používají endpointy, které vrací seznamy?

List endpointy používají Page (výchozí 1) a PageSize (výchozí 25). Maximální PageSize je specifická pro konkrétní endpoint.

Exporty

Jsou exporty dostupné pro všechny tarify?

Ne. Exporty jsou dostupné pouze pro tarify Business a Enterprise.
Pokud tarif exporty nepodporuje, API vrátí 403 Forbidden s kódem PLAN_REQUIRED.

Jak fungují exporty?

Exporty zpracováváme asynchronně přes frontu. Po vytvoření požadavku se export zařadí do fronty a následně se zpracuje na pozadí podle aktuální zátěže systému. Díky tomu nedochází k přetěžování API a je zajištěn stabilní provoz pro všechny klienty.

Lze zrušit export?

Ano, pouze pokud je ve stavu QUEUED.

Pokud export neexistuje (např. chybné idExportJob v URL), API vrací 404 s kódem EXPORT_NOT_FOUND. Pokud export není ve stavu QUEUED, API vrací 409 Conflict s kódem EXPORT_NOT_CANCELLABLE.

Jak se stahuje výsledek exportu?

Přes GET /api/v1/ExportResult/Download/{idExportJob}.

Jaké obecné query parametry exportu jsou podporované?

U exportu lze nastavit formát a heslo. Pro notifikaci vašeho systému, že je export připravený ke stažení, můžete nastavit callback URL nebo si nechat zaslat email.

Více informací najdete v sekci Volby exportu.

Jaké výstupní formáty exportů existují?

Aktuálně podporujeme hlavně JSON a CSV, ale ne každý typ exportu podporuje oba formáty.

Posílá callback výsledný soubor exportu?

Ne. Callback posílá metadata o výsledku zpracování. Soubor stáhněte přes download endpoint.

Proč je výstup exportu ZIP?

Download endpoint vrací ZIP, protože výstup může být zaheslovaný přes parametr password a některé exporty mohou obsahovat více souborů ve strukturovaném adresáři.

Je omezené volání endpointu pro zjištění stavu exportu?

Ano. Endpoint pro kontrolu stavu exportu je omezen počtem volání, aby nedocházelo ke spamování dotazy na dokončení exportu. Pro zjištění dokončení proto doporučujeme primárně používat callback URL nebo e-mail notifikaci.

Limity, chyby, diagnostika

Jak API signalizuje překročení rate limitu?

Při překročení limitu volání API vrací 429 Too Many Requests, hlavičku Retry-After, chybový kód RATE_LIMIT_EXCEEDED a pole RetryAfterSeconds.

Jaký je jednotný formát chybové odpovědi?

Chybové odpovědi mají jednotnou strukturu:

{ "Code": "...", "Message": "..." }

U odpovědi 429 je navíc vraceno i RetryAfterSeconds, které udává doporučený počet sekund před dalším pokusem.

Co logovat při řešení incidentu?

HTTP status, Code, X-Request-Id, endpoint a čas volání.

Je dostupný health endpoint?

Ano, GET /api/v1/Diagnostics/Ping vrací Pong.

Existuje endpoint pro test serverové chyby?

Ano, GET /api/v1/Diagnostics/Exception vrací testovací chybu 500.

---

Nenašli jste odpověď na svou otázku?
Technické dotazy k API nám můžete zaslat na e-mail enterprise@xdent.cz.

V případě dotazů ke službě, cenám nebo obchodním podmínkám kontaktujte prosím naši zákaznickou podporu, nebo svého obchodního zástupce.