Hitelesítés a 4invoices API-ban

A client_id és client_secret párost egy órás Bearer tokenre váltja, kizárólag szerver-szerver módon.

Az első számla 6 lépésben

Hozza létre a hitelesítő adatot a panelen a Számlázás → Beállítások → API-hozzáférés menüpontban, és azonnal másolja ki a client_secret értékét — csak egyszer jelenik meg.
Küldjön POST /v1/auth/token kérést grant_type client_credentials, client_id és client_secret értékekkel.
Válaszként megkapja az access_token, token_type Bearer, expires_in 3600 értékeket és a megadott jogosultsági körök listáját.
Minden további hívásnál tegye a tokent egy Authorization: Bearer <access_token> fejlécbe.
Hogy ténylegesen mit kapott, azt a GET /v1/me hívással ellenőrizheti: tenant, jogosultsági körök és az aktuális keretek.

Minden végpont

Metódus	Végpont	Scope	Idempotency-Key	Kérés / perc
POST	/auth/token Hitelesítő adatok cseréje hozzáférési tokenre	—	—	120
GET	/me Bérlő, scope-ok és jelenlegi limitek	invoices:read	—	120

Mi a 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"

# → bérlő, megadott scope-ok és a jelenlegi sebességkorlátok

javascript
// Gyorsítótárazza a tokent; ne kérjen újat minden kéréshez.
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

Scope-ok

invoices:read
invoices:write
clients:read
clients:write
efactura:read
efactura:submit

Csak szerver-szerver. Soha ne hívja az API-t böngészős JavaScriptből: a client_secret eljutna a látogatóhoz, és a CORS egyébként is minden origint blokkol.

Hibák

Státusz	Típus	Kód
401	authentication_error	invalid_client
401	authentication_error	token_expired
401	authentication_error	invalid_token
403	permission_error	insufficient_scope

Gyakori hibák

A token-végpontnak saját, IP-címenkénti korlátja van. Folyamatonként egy token, lejárat előtt frissítve — nem kérésenként egy.
A client_secret csak hash formában tárolódik; ha elveszíti, új hitelesítő adatot hoz létre, a régit pedig visszavonja.
Adjon ki külön hitelesítő adatot az ERP-nek, a webshopnak és a belső szkripteknek, mindegyiket minimális jogosultsággal. Az egyik visszavonása nem érinti a többit.
A CORS egyetlen böngészős origint sem enged: az API eleve szerver–szerver használatra készült.

Kérdések és válaszok fejlesztőknek

Mi történik, ha a client_secret hibás?

401-es választ kap invalid_client kóddal. A túl rövid titok már korábban, a validáláskor elbukik, 422 validation_failed hibával és param client_secret értékkel.

Van külön tesztkörnyezet?

Nincs. Egyetlen éles host van. Díjbekérőkkel (document_kind proforma) és a /invoices/preview-totals hívással teszteljen, amely nem használ fel fiskális sorszámot.

Szűkíthetem egy meglévő hitelesítő adat jogosultsági köreit?

Igen, a panelen. A már kiadott tokenek lejáratukig, vagyis legfeljebb egy órán belül megtartják azokat a jogosultsági köröket, amelyekkel létrehozták őket.

Lásd még