OAuth — Pripojiť cez eFaktúru

Pre aplikácie, ktoré pracujú v mene používateľov eFaktúry (e-shop, ERP, CRM, fakturačný nástroj). Používateľ sa prihlási do eFaktúry, vyberie firmu a odsúhlasí, čo smie vaša aplikácia robiť. Vy dostanete token viazaný na túto firmu — nikto si nemusí vytvárať ani posielať API kľúč.

OAuth alebo API kľúč?

Postup

1. Zaregistrujte aplikáciu (Dynamic Client Registration, raz). V poli resources uveďte Agent API — bez neho dostanete iba tokeny pre MCP.

curl -X POST https://api.efaktura.sk/api/auth/oauth2/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Môj e-shop",
    "redirect_uris": ["https://moj-eshop.sk/efaktura/callback"],
    "token_endpoint_auth_method": "client_secret_basic",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "resources": ["https://api.efaktura.sk/v1/agent"]
  }'

Odpoveď obsahuje client_id (a client_secret pri serverovej aplikácii). Mobilná alebo desktopová aplikácia použije "token_endpoint_auth_method": "none".

2. Presmerujte používateľa na súhlas. PKCE (S256) je povinné.

https://api.efaktura.sk/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=<client_id>
  &redirect_uri=https://moj-eshop.sk/efaktura/callback
  &scope=openid offline_access invoice:read invoice:create invoice:send
  &state=<náhodná hodnota>
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256
  &resource=https://api.efaktura.sk/v1/agent

Používateľ sa prihlási, vyberie firmu a odsúhlasí rozsahy. Potom ho vrátime na redirect_uri s parametrami code a state.

3. Vymeňte kód za token.

curl -X POST https://api.efaktura.sk/api/auth/oauth2/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=https://moj-eshop.sk/efaktura/callback \
  -d code_verifier=<code_verifier> \
  -d resource=https://api.efaktura.sk/v1/agent

4. Volajte Agent API s tokenom. Firma je v tokene, hlavičku X-Organization-Id netreba. Ak ju pošlete, musí sa zhodovať.

curl https://api.efaktura.sk/v1/agent/invoices \
  -H "Authorization: Bearer <access_token>"

5. Obnovte token pred vypršaním (platí 1 h) cez grant_type=refresh_token. Refresh token dostanete, ak ste žiadali scope offline_access.

Technické parametre

Zoznam rozsahov nájdete v API kľúče a scopes.

Čo token smie

Chyby