Autentificare

API-ul e-bon acceptă două moduri de autentificare, iar majoritatea endpoint-urilor le acceptă pe oricare dintre ele printr-un middleware combinat:

1. Cheie API — autentificare server-la-server pentru sisteme POS, ERP-uri, conectori contabili și orice altă integrare de back-end. Acesta este modul principal pentru referința API de mai jos.
2. JWT (token de acces de tip Bearer) — token de sesiune cu durată scurtă, folosit de Portalul e-bon și de aplicația mobilă E-BON. Menționat aici pentru completitudine; fluxul de înregistrare / autentificare / reînnoire este documentat în secțiunea Portal.

Folosește chei API pentru orice integrare care rulează nesupravegheată pe un server. Rezervă JWT-ul pentru sesiuni interactive în care se autentifică un om.

Formatul cheii API

O cheie API e-bon este un singur șir opac cu această structură:

ebon_live_<orgId>_<32 caractere hexazecimale>

• ebon_live_ — prefix fix care identifică o cheie API live e-bon. Middleware-ul de autentificare refuză să calculeze chiar și hash-ul unei chei care nu începe cu acest prefix.
• <orgId> — identificatorul organizației tale. Poate conține caractere de subliniere.
• <32 hex> — 32 de caractere hexazecimale aleatorii ([0-9a-f]{32}). Serverul verifică formatul strict.

Secretul complet este afișat o singură dată, în Portal, la momentul creării. Serverul stochează doar hash-ul; nu există nicio modalitate de a recupera secretul ulterior. Dacă îl pierzi, șterge cheia și creează una nouă.

Trimite cheia

Ambele antete de mai jos sunt acceptate la fiecare cerere. Alege unul și folosește-l consecvent în toată integrarea ta:

x-api-key: ebon_live_<orgId>_<32-hex>

Authorization: Bearer ebon_live_<orgId>_<32-hex>

Middleware-ul verifică întâi x-api-key, apoi cade pe Authorization: Bearer …. A le trimite pe amândouă nu strică, dar nu are rost.

Generează o cheie

Cheile sunt generate din Portalul e-bon. Ai nevoie de rolul de Owner sau Admin pe organizație.

Ghidul complet din Portal — inclusiv rotație, dezactivare, ștergere și urmărirea ultimei utilizări — se află la Portal › Chei API.

Alege permisiunile

O permisiune este un drept de acces atașat unei chei. O cerere autentificată cu o cheie dată poate ajunge doar la endpoint-urile care se potrivesc cu permisiunile sale; orice este în afara setului returnează 403 FORBIDDEN. e-bon livrează nouă permisiuni:

Folosește autentificarea JWT (pe scurt)

Autentificarea JWT alimentează Portalul și aplicația mobilă E-BON și este expusă pe /api/v1/auth/*. Este un flux standard de înregistrare / autentificare / reînnoire / deconectare:

Trimite token-ul de acces returnat ca Authorization: Bearer <jwt> la cererile ulterioare. JWT-urile au durată scurtă; reînnoiește-le când primești 401 TOKEN_EXPIRED. Endpoint-urile de autentificare au o limită de rată mai strictă decât restul API-ului — vezi tabelul Prezentare generală API › Limite de rată.

Pentru integrări de back-end vrei aproape întotdeauna o cheie API, nu un JWT. Folosește JWT doar când construiești o interfață prin care se autentifică un om real.

Tratează erorile de autentificare

Toate erorile de autentificare folosesc învelișul standard de eroare documentat la Prezentare generală API › Format de eroare.

Cheie lipsă:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Provide via x-api-key header or Authorization: Bearer <key>."
  }
}

Cheie malformată (prefix greșit sau formă greșită):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key format."
  }
}

Cheie necunoscută sau revocată:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key."
  }
}

Cheie dezactivată (oprită din Portal):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is inactive."
  }
}

Permisiuni insuficiente (cheia este validă, dar nu pentru acest endpoint):

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient scopes. Missing: devices:write"
  }
}

JWT expirat:

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired"
  }
}

Urmează bunele practici

Încearcă exemplele curl

1. Forma cu antet (x-api-key):

curl https://api.e-bon.ro/api/v1/devices \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

2. Forma Bearer (Authorization):

curl https://api.e-bon.ro/api/v1/devices \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

3. Cu o cheie de idempotență (recomandat la fiecare POST /commands și POST /receipts):

curl -X POST https://api.e-bon.ro/api/v1/commands \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: comanda-12345-incercarea-1" \
  -d '{
    "deviceId": "dev_abc123",
    "type": "print_receipt",
    "payload": {
      "operatorId": "casier_01",
      "items": [
        { "name": "Paine alba 500g", "quantity": 2, "price": 5.49, "vatRate": 9, "department": 1 }
      ],
      "payments": [{ "method": "cash", "amount": 10.98 }]
    }
  }'

O modalitate rapidă de a confirma că o cheie funcționează este GET /api/v1/me, care întoarce orgId, scopes și keyLabel ale cheii:

curl https://api.e-bon.ro/api/v1/me \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

{
  "orgId": "acme_corp",
  "scopes": ["receipts", "commands", "devices:read"],
  "keyLabel": "POS Integration"
}

Unde mergi mai departe

• Prezentare generală API — URL de bază, format de eroare, limite de rată, idempotență, paginare.
• Bonuri, Rapoarte, Dispozitive și Webhook-uri — referințe de endpoint-uri pentru suprafețele fiscale principale.
• Portal › Chei API — administrarea cheilor (rotație, dezactivare, ștergere) din interfață.