Autentifică cererile API

Fiecare cerere către API-ul e-bon trebuie să poarte unul dintre două credențiale: o cheie API (pentru integrări server-to-server și parteneri POS) sau un jeton de acces din Portal (pentru utilizatorii autentificați în Portalul e-bon sau în aplicația de pe AMEF). Această pagină arată cum obții fiecare credențial, cum îl trimiți și ce faci când autentificarea eșuează.

Alege metoda de autentificare

Cele două credențiale nu sunt interschimbabile. Cheile API sunt legate de o organizație și au permisiuni (scopes). Jetoanele de Portal sunt legate de un utilizator dintr-o organizație și au un rol.

Autentifică cu o cheie API

Cheile API sunt metoda recomandată pentru a apela API-ul e-bon de pe orice server, AMEF sau sistem de back-office. O cheie arată astfel:

ebon_live_{orgId}_{32-hex}

Cheia completă îți este afișată o singură dată, în fereastra în care o creezi. Salveaz-o imediat într-un seif de secrete — e-bon nu mai afișează niciodată secretul complet. Portalul îți va arăta în continuare doar prefixul (totul înainte de coada aleatoare), ca să poți identifica ulterior cheia.

Trimite prima cerere autentificată

POST /api/v1/receipts HTTP/1.1
Host: api.e-bon.ro
Content-Type: application/json
x-api-key: ebon_live_abc123def456_0123456789abcdef0123456789abcdef

{ "deviceId": "dev_…", "items": [ … ] }

Authorization: Bearer ebon_live_abc123def456_0123456789abcdef0123456789abcdef

Revocă sau rotește o cheie

Cheile API nu expiră singure. Ca să oprești o cheie, deschide Portalul, găsește cheia după prefix și apasă Revocă. Următoarea cerere care o folosește primește imediat 401 UNAUTHORIZED — API key is inactive..

Nu există rotație în loc. Ca să rotești o cheie, creează una nouă, actualizează seiful de secrete, apoi revoc-o pe cea veche după ce noua versiune a fost lansată.

Autentifică-te în Portal

Utilizatorii Portalului se autentifică cu email și parolă și primesc o pereche de jetoane:

• Un jeton de acces valabil 15 minute, trimis la fiecare apel API ca Authorization: Bearer <jeton>.
• Un jeton de reîmprospătare valabil 7 zile, folosit doar pentru a obține un nou jeton de acces.

Parcurge fluxul de autentificare

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "tu@exemplu.ro", "password": "…" }

GET /api/v1/devices
Authorization: Bearer <accessToken>

POST /api/v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }

POST /api/v1/auth/logout
Authorization: Bearer <accessToken>
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }

Pentru forma completă a cererilor și răspunsurilor, vezi Referința API-ului de autentificare.

Gestionează permisiunile cheii API

Fiecare cheie API poartă una sau mai multe permisiuni. Fiecare cerere are nevoie de o permisiune anume; dacă lipsește din cheie, API-ul returnează 403 FORBIDDEN — Insufficient scopes.

Gestionează rolurile utilizatorilor

Utilizatorii Portalului au unul dintre trei roluri, setat când sunt adăugați în organizație:

Rolurile sunt evaluate la fiecare apel către API-ul Portalului. Dacă un utilizator încearcă o acțiune pe care rolul lui nu o permite, API-ul returnează 403 FORBIDDEN — Insufficient role.

Înțelege limitele de plan

Unele acțiuni sunt limitate de planul tău de abonament:

Când atingi o limită de plan, API-ul returnează 403 TIER_LIMIT_EXCEEDED cu un mesaj care îți spune ce limită ai atins și cum o ridici (de obicei: upgrade de plan).

Tratează limitele de rată

API-ul aplică trei plicuri de limitare a ratei. Toate trei returnează același răspuns la epuizare:

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests, please try again later.",
  "status": 429
}

Fiecare răspuns 429 include un antet Retry-After în secunde — așteaptă cel puțin atât înainte de a reîncerca.

Tratează erorile de autentificare {#trateaza-erorile-de-autentificare}

Fiecare eșec de autentificare și autorizare returnează un plic JSON structurat cu un câmp code stabil. Folosește code (nu mesajul în limbaj natural) când construiești tratarea de erori.

Unde mergi mai departe

• Referința API-ului de autentificare — formele complete ale cererilor și răspunsurilor pentru /auth/{register,login,refresh,logout,forgot-password}.
• Referința API-ului de chei API — referința REST pentru gestionarea cheilor programatic.
• Portal: Chei API — fluxul de UI pentru creare, atribuire de permisiuni și revocare a cheilor.
• Portal: Înregistrare — fluxul de bootstrap pentru primul Owner și pentru organizație.
• Ghidul de integrare — bucla sandbox cap-coadă care exercită împreună autentificarea, bonurile fiscale și webhook-urile.