API reference

Základní informace

Base URL	https://api.fakturos.cz/v1
Formát	JSON
Autentizace	Authorization: Bearer <token>
Verze	v1

Autentizace

V1 endpointy přijímají Bearer API klíč nebo platný OAuth access token. Klíč vytvoříte v klientské zóně v nastavení API. OAuth tokeny se vyměňují a obnovují přes POST /oauth/token; token lze odvolat přes POST /oauth/revoke.

cURLcurl https://api.fakturos.cz/v1/documents \
  -H "Authorization: Bearer fos_live_xK9p…q2Ws"

Firma a oprávnění se vždy odvozují z ověřeného tokenu. firm_id v těle požadavku neslouží k přepnutí firmy.

Dostupné zdroje

Klienti

• GET /v1/clients a /v1/clients/:id
• POST /v1/clients
• PUT /v1/clients/:id
• POST /v1/clients/:id/archive

Doklady

• GET /v1/documents a /v1/documents/:id
• POST /v1/documents — vytvoření konceptu
• POST /v1/documents/issue — vystavení dokladu
• PUT /v1/documents/:id
• DELETE /v1/documents/:id

Náklady

• GET /v1/expenses a /v1/expenses/:id
• POST /v1/expenses
• PUT /v1/expenses/:id
• DELETE /v1/expenses/:id
• POST /v1/expenses/:id/confirm, /archive, /cancel a /corrections

Sklad

• GET /v1/stock/items a /v1/stock/items/:id
• POST /v1/stock/items
• PUT /v1/stock/items/:id
• POST /v1/stock/items/:id/archive
• GET /v1/stock/items/:id/movements
• POST /v1/stock/items/:id/movements
• PUT a DELETE /v1/stock/movements/:id

Idempotence

Idempotency-Key je aktuálně vyžadován pro zápis skladového pohybu přes POST /v1/stock/items/:id/movements. Klíč je svázán s firmou, přihlašovacím údajem a konkrétní routou; opakování stejného požadavku vrátí uloženou odpověď. U ostatních zápisových endpointů obecná garance idempotence zatím neplatí.

Stránkování a limity

Seznamové endpointy podporují limit a cursor. Odpověď obsahuje next_cursor. Rate-limit middleware vrací aktuální limit, zbývající počet požadavků a čas obnovení v HTTP hlavičkách; při vyčerpání vrací 429 a Retry-After.

Chyby

Chybové odpovědi používají JSON problem detail a korelační ID. Běžné stavy jsou 400, 401, 403, 404, 409, 422 a 429.