Autentifikácia v 4invoices API

Vymeníte client_id a client_secret za hodinový Bearer token, iba server-to-server.

Vymeníte client_id a client_secret za hodinový Bearer token, iba server-to-server.

← Späť na dokumentáciu API

Prvá faktúra v 6 krokoch

  1. Vytvorte prístupové údaje v paneli v časti Fakturácia → Nastavenia → Prístup k API a hneď skopírujte client_secret — zobrazí sa iba raz.
  2. Pošlite POST /v1/auth/token s grant_type client_credentials, client_id a client_secret.
  3. Späť dostanete access_token, token_type Bearer, expires_in 3600 a zoznam udelených rozsahov.
  4. Token vložte do hlavičky Authorization: Bearer <access_token> pri každom ďalšom volaní.
  5. Čo ste skutočne dostali, overíte cez GET /v1/me: tenant, rozsahy a aktuálne kvóty.

Všetky endpointy

MetódaEndpointScopeIdempotency-KeyPožiadaviek / minútu
POST/auth/token
Vymeniť prihlasovacie údaje za prístupový token
——120
GET/me
Tenant, scopes a aktuálne limity
invoices:read—120

Čo je 4invoices API

bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
bash
curl -sS https://api.4invoices.net/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → tenant, udelené scopes a aktuálne limity
javascript
// Token uložte do cache; nevytvárajte nový pri každej požiadavke.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Scopes

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Iba server-to-server. Nikdy nevolajte API z JavaScriptu v prehliadači: client_secret by sa dostal k návštevníkovi a CORS aj tak blokuje každý origin.

Chyby

StavTypKód
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Časté chyby

  • Endpoint tokenu má vlastný limit na IP adresu. Jeden token na proces, obnovený pred vypršaním — nie jeden na požiadavku.
  • client_secret sa ukladá iba ako hash; ak ho stratíte, vytvoríte nové prístupové údaje a staré zrušíte.
  • Pre ERP, e-shop a interné skripty vydajte samostatné prístupové údaje, každé s minimálnymi rozsahmi. Zrušenie jedných neovplyvní ostatné.
  • CORS nepovoľuje žiadny prehliadačový pôvod: API je už zo zásady určené len na komunikáciu server–server.

Otázky a odpovede pre vývojárov

Čo sa stane, ak je client_secret nesprávny?

Dostanete 401 s kódom invalid_client. Príliš krátke tajomstvo zlyhá skôr, už pri validácii, s 422 validation_failed a param client_secret.

Existuje samostatné testovacie prostredie?

Nie. Existuje jeden produkčný host. Testujte na zálohových faktúrach (document_kind proforma) a cez /invoices/preview-totals, ktoré nespotrebúva fiškálne číslo.

Môžem zúžiť rozsahy existujúcich prístupových údajov?

Áno, v paneli. Už vydané tokeny si ponechajú rozsahy, s ktorými boli vytvorené, až do vypršania, teda najneskôr do jednej hodiny.