Referință API

Chei API

Endpoint-uri REST pentru a lista, crea, actualiza și revoca cheile API ale organizației. Secretul brut este returnat o singură dată la creare.

Chei API

API-ul de administrare a cheilor API este echivalentul programatic al ecranului Setări → Chei API din Portal. Le permite Owner-ilor și Admin-ilor unei organizații să creeze, listeze, redenumească, dezactiveze și revoce chei API fără să treacă prin UI — util pentru provisioning de integrări, rotirea cheilor dintr-un pipeline CI sau auditarea setului de chei active dintr-un instrument de back-office.

Toate endpoint-urile din acest grup sunt sub /api/v1/org/api-keys și sunt administrative, la fel ca endpoint-urile de administrare a Webhook-urilor.

Spre deosebire de majoritatea referințelor API, rutele de administrare a cheilor API nu se autentifică prin cheie API. Stau în spatele middleware-ului JWT din Portal și mai cer ca utilizatorul apelant să aibă rolul de Owner sau Admin pe organizație. Nu există nicio permisiune de cheie API care să dea acces la administrarea cheilor API — generează un token de sesiune din Portal (POST /api/v1/auth/login) și folosește-l ca Authorization: Bearer <jwt>. Vezi Autentificare › Autentificare JWT.

Valoarea brută a cheii API este returnată o singură dată, în câmpul key al răspunsului POST /api/v1/org/api-keys. Este hash-uită înainte de a fi persistată și nu există niciun endpoint care să o poată returna din nou — stocheaz-o în managerul tău de secrete înainte ca răspunsul să fie aruncat. Dacă pierzi cheia, revoc-o (DELETE) și creează una nouă.

Plicul de eroare, limitele de rată și convențiile de paginare sunt documentate o singură dată pe Prezentare API; pe această pagină listăm doar codurile de eroare specifice fiecărui endpoint.

Permisiuni

POST /api/v1/org/api-keys cere cel puțin o permisiune. Permisiunile disponibile sunt:

Permisiune	Acordă
`receipts`	Acces complet la bonuri (stocare, listare, citire).
`receipts:read`	Acces doar de citire la bonuri.
`receipts:admin`	Administrare bonuri (storno, exporturi de istoric).
`reports`	Generare și citire rapoarte (X / Z / JE / MF).
`devices`	Acces complet la dispozitive (citire + scriere + claim/release).
`devices:read`	Acces doar de citire la dispozitive (listare, status, alerte, info).
`devices:write`	Operații de scriere pe dispozitive (înregistrare, actualizare, ștergere, claim, comenzi de configurare).
`commands`	Trimitere, listare, citire și anulare de comenzi fiscale (Comenzi).
`all`	Echivalent cu toate celelalte permisiuni la un loc. Folosește cu reținere — preferă cel mai restrâns set posibil.

Catalogul complet de permisiuni, inclusiv ce rute acceptă ce permisiuni, este pe Autentificare › Permisiuni.

GET /api/v1/org/api-keys

Listează toate cheile API ale organizației, cele mai noi primele. Cheia hash-uită nu este returnată niciodată; doar prefixul (primele 12 caractere ale cheii originale plus …) este expus, ca să poți identifica ce cheie e care.

Autentificare: JWT din Portal.

Răspuns (`200 OK`)

[
  {
    "id": "apikey_abc123",
    "prefix": "ebon_live_a…",
    "label": "Integrare contabilitate",
    "scopes": ["receipts", "reports"],
    "active": true,
    "createdAt": "2026-03-01T12:00:00.000Z",
    "lastUsed": "2026-04-09T08:09:55.000Z"
  }
]

lastUsed este null pentru cheile care nu au fost folosite niciodată ca să autentifice o cerere.

Exemplu

curl https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>"

Coduri de eroare

UNAUTHORIZED (401) — JWT lipsă sau invalid.

Catalogul HTTP complet este pe Prezentare API › Catalogul codurilor de eroare HTTP.

POST /api/v1/org/api-keys

Generează o cheie API nouă cu eticheta și permisiunile specificate. Secretul brut este returnat o singură dată în câmpul key al răspunsului — stocheaz-o imediat.

Autentificare: JWT din Portal, rol Owner sau Admin.
Verificare plan: cererea trece prin middleware-ul enforceApiKeyCreation. Planul Free nu permite crearea de chei API; cererea este respinsă cu 403 TIER_LIMIT_EXCEEDED.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`label`	string	da	Etichetă lizibilă, 1–100 caractere.
`scopes`	string	da	Cel puțin o intrare din enum-ul `ApiKeyScope` (vezi Permisiuni mai sus).

Răspuns (`201 Created`)

{
  "id": "apikey_abc123",
  "key": "ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "prefix": "ebon_live_a…",
  "label": "Integrare contabilitate",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-04-09T08:10:00.000Z"
}

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/org/api-keys \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Integrare contabilitate",
    "scopes": ["receipts", "reports"]
  }'

Coduri de eroare

VALIDATION_ERROR (400) — corpul nu a trecut validarea Zod (etichetă goală, etichetă > 100 caractere, array scopes gol, valoare de permisiune necunoscută).
UNAUTHORIZED (401) — JWT lipsă sau invalid.
FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
TIER_LIMIT_EXCEEDED (403) — cheile API nu sunt disponibile pe planul Free; treci pe Pro ca să creezi chei API.

PATCH /api/v1/org/api-keys/{keyId}

Actualizează label și/sau starea active a unei chei API. Cel puțin un câmp trebuie furnizat. Permisiunile sunt imutabile — ca să schimbi setul de permisiuni, revocă cheia și creează una nouă.

Autentificare: JWT din Portal, rol Owner sau Admin.

Parametri de cale

Parametru	Tip	Note
`keyId`	string	ID-ul documentului cheii API.

Corpul cererii

Câmp	Tip	Note
`label`	string	1–100 caractere.
`active`	boolean	Pornește/oprește cheia. O cheie inactivă este respinsă la nivel de auth.

Răspuns (`200 OK`)

{
  "id": "apikey_abc123",
  "prefix": "ebon_live_a…",
  "label": "Integrare contabilitate (redenumită)",
  "scopes": ["receipts", "reports"],
  "active": true,
  "createdAt": "2026-03-01T12:00:00.000Z",
  "lastUsed": "2026-04-09T08:09:55.000Z"
}

Exemplu

curl -X PATCH https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Coduri de eroare

VALIDATION_ERROR (400) — corpul nu a trecut validarea Zod sau e gol (niciun câmp de actualizat).
UNAUTHORIZED (401) — JWT lipsă sau invalid.
FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
NOT_FOUND (404) — nu există nicio cheie API cu acel ID în organizația ta.

DELETE /api/v1/org/api-keys/{keyId}

Revocă definitiv o cheie API. Cheia este eliminată din Firestore — nu există soft-delete. Cererile în curs autentificate cu acea cheie continuă să se finalizeze; cererile ulterioare sunt respinse cu 401 UNAUTHORIZED. Returnează 204 No Content la succes.

Autentificare: JWT din Portal, rol Owner sau Admin.

Parametri de cale

Parametru	Tip	Note
`keyId`	string	ID-ul documentului cheii API.

Exemplu

curl -X DELETE https://api.e-bon.ro/api/v1/org/api-keys/apikey_abc123 \
  -H "Authorization: Bearer <portal-jwt>"

Coduri de eroare

UNAUTHORIZED (401) — JWT lipsă sau invalid.
FORBIDDEN (403) — apelantul nu are rol de Owner sau Admin.
NOT_FOUND (404) — nu există nicio cheie API cu acel ID în organizația ta.

Vezi și

Autentificare — formatul cheilor API, catalogul de permisiuni, fluxul de login JWT și erori de autentificare.
Comenzi, Bonuri, Dispozitive — endpoint-urile care consumă cheile generate aici.
Prezentare API — URL de bază, plic de eroare, limite de rată, idempotență, paginare.

Editează această pagină

Prezentare generală API

Cum este structurat API-ul REST e-bon — URL de bază, versionare, format de eroare, limite de rată, idempotență și restricții pe planuri — pentru parteneri POS și integratori.

Evenimente webhook

Primește notificări în timp real despre evenimentele fiscale — bonuri, comenzi, dispozitive și rapoarte — prin callback-uri HTTPS semnate.