Přihlášení

API přijímá dva druhy přihlášení: API klíč pro vlastní integrace a OAuth 2.0 pro aplikace, které se připojují k firmám dalších uživatelů.

API klíč

Klíč vytvoří administrátor firmy v Nastavení › API klíče. Ukáže se jen jednou, ukládáme pouze jeho otisk. Klíč začíná abf_ a posílá se jedním z těchto způsobů:

Authorization: Bearer abf_VAS_KLIC
X-Api-Key: abf_VAS_KLIC

Klíč patří jedné firmě a jednají s ním jako uživatel, který ho vytvořil. Může mít datum konce platnosti a dá se kdykoli zrušit; zrušený klíč přestane fungovat okamžitě.

Klíč je stejně cenný jako heslo. Nedávejte ho do kódu, který běží v prohlížeči nebo v mobilní aplikaci; tam patří OAuth 2.0 s PKCE.

Oprávnění

Klíč i OAuth aplikace mají oprávnění zvlášť pro každou oblast, vždy čtení a změny. Změny zahrnují čtení. Čtení pustí GET, změny POST, PUT a DELETE.

Oblast	Endpointy	OAuth scope
Faktury vydané	`/invoices` včetně PDF, ISDOC, odeslání a daňového dokladu k záloze	`invoices:read`, `invoices:write`
Faktury přijaté	`/received-invoices`	`received-invoices:read`, `received-invoices:write`
Úhrady	`/invoices/{id}/payments` a `/received-invoices/{id}/payments`	`payments:read`, `payments:write`
Kontakty	`/contacts`	`contacts:read`, `contacts:write`
Ceník	`/products`	`products:read`, `products:write`
Webhooky	`/webhooks`	`webhooks:read`, `webhooks:write`

Požadavek mimo oprávnění skončí 403 ApiKeyScope dřív, než se začne zpracovávat; v detail je chybějící oprávnění, např. payments:write. Pro vystavení faktury s kontaktem z adresáře stačí invoices:write a contacts:read.

Starší souhrnné scope pořád platí: read = čtení všeho, invoices = vše kromě webhooků, full = vše.

OAuth 2.0

Program zaregistrujete v Nastavení › API klíče › OAuth aplikace. Dostanete client_id a u serverového programu i client_secret.

Autorizace	`https://api.abfaktura.cz/api/v1/oauth/authorize`
Token	`https://api.abfaktura.cz/api/v1/oauth/token`
Scope	Oprávnění podle oblastí (např. `invoices:write contacts:read`) a `offline_access` pro obnovovací token. Bez scope dostane aplikace vše, co jí bylo povoleno.
Platnost tokenu	1 hodina

Serverový program za vlastní firmu (client credentials)

curl https://api.abfaktura.cz/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=VAS_CLIENT_ID \
  -d client_secret=VAS_SECRET \
  -d "scope=invoices:write contacts:read"

{ "access_token": "eyJhbGciOi…", "token_type": "Bearer", "expires_in": 3600, "scope": "invoices:write contacts:read" }

Aplikace pro další uživatele (authorization code + PKCE)

Pošlete uživatele na autorizační adresu s parametry response_type=code, client_id, redirect_uri, scope (např. invoices:write payments:write offline_access), state, code_challenge a code_challenge_method=S256.
Uživatel se přihlásí do abFaktury, vybere firmu a souhlasí s přístupem.
Vrátí se na redirect_uri s parametrem code. Ten vyměníte za token:

curl https://api.abfaktura.cz/api/v1/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=VAS_CLIENT_ID \
  -d code=KOD_Z_PRESMEROVANI \
  -d redirect_uri=https://vase-aplikace.cz/oauth/callback \
  -d code_verifier=PUVODNI_VERIFIER

Se offline_access dostanete i refresh_token, kterým získáte nový přístupový token (grant_type=refresh_token). Uživatel může přístup kdykoli zrušit v Nastavení › API klíče › Povolené aplikace; tokeny pak přestanou fungovat hned.