Chei API

O cheie API este credențialul folosit de un partener POS, de o integrare cu un program de contabilitate sau de orice alt sistem extern pentru a se autentifica la API-ul e-bon. Este o autentificare mașină-la-mașină: cheia este trimisă în antetul Authorization al fiecărei cereri și identifică organizația în numele căreia se face apelul, nu un utilizator uman. Cheile API sunt complet separate de autentificarea cu email și parolă pe care o folosesc oamenii pentru a accesa Portalul.

Găsește-ți cheile API

Deschide meniul lateral al Portalului și alege Chei API. Pagina se află la /portal/api-keys și listează fiecare cheie emisă pentru organizația ta, împreună cu eticheta, prefixul, permisiunile, momentul ultimei utilizări și starea activă/inactivă.

Generează o cheie

Permisiuni

Permisiunile sunt drepturile atașate unei chei API. O cerere autentificată cu o anumită cheie poate ajunge doar la endpoint-urile acoperite de permisiunile acelei chei; orice altceva returnează 403 Forbidden. e-bon definește nouă permisiuni:

• all — Acces complet. Fiecare endpoint, fiecare resursă. Folosește această permisiune doar pentru integrări interne de încredere, unde restrângerea permisiunilor nu aduce niciun beneficiu real; pentru integrări cu parteneri preferă permisiunile specifice de mai jos.
• receipts — Bonuri (citire + scriere). Emite bonuri și citește istoricul de bonuri.
• receipts:read — Bonuri (doar citire). Citește istoricul de bonuri fără a putea emite sau modifica nimic. Ideal pentru export contabil și dashboard-uri de raportare.
• receipts:admin — Bonuri (operațiuni admin). Stornări și operațiuni de arhivare pe bonuri existente. Acordă această permisiune doar integrării care gestionează fluxurile de retur.
• reports — Rapoarte. Citește rapoartele X, Z, MF (Memorie Fiscală) și JE (Jurnal Electronic) pentru toate dispozitivele organizației.
• devices — Dispozitive (citire + scriere). Gestionare completă a dispozitivelor: înregistrarea unor AMEF noi, redenumirea sau ștergerea celor existente, citirea stării dispozitivelor.
• devices:read — Dispozitive (doar citire). Acces doar-citire la flota de dispozitive — model, status, locație, momentul ultimei conectări.
• devices:write — Dispozitive (scriere). Înregistrează, redenumește și șterge dispozitive fără a acorda acces de citire la bonuri sau rapoarte.
• commands — Comenzi. Pune la coadă comenzi de tipărire/operare (de exemplu declanșarea unui raport X sau Z) către dispozitivele organizației.

Gestionează cheile existente

Fiecare cheie din listă are două acțiuni alăturate: un buton de editare (creion) și un buton de ștergere roșu.

• Editare deschide un modal în care poți modifica eticheta și poți comuta switch-ul Activă. Dezactivarea unei chei (switch oprit, salvează) păstrează cheia în listă, dar face ca fiecare cerere care o folosește să eșueze cu 401. O reactivezi în același mod. Este unealta potrivită pentru a suspenda temporar o integrare fără a renunța la secret.
• Câmpul Ultima utilizare de pe fiecare rând arată când a fost acceptată ultima dată cheia de către API. O cheie care nu a mai fost folosită de luni întregi este un bun candidat pentru curățenie.
• Insigna Activă / Inactivă reflectă aceeași stare ca switch-ul din modalul de editare.

Rotește sau revocă o cheie

Nu există o operațiune de rotire a secretului pentru cheile API — secretul este afișat doar în modalul de afișare la momentul creării, iar API-ul păstrează exclusiv hash-ul. Pentru a roti o cheie, creează una nouă, comută integrarea pe noua cheie și apoi șterge cheia veche.

Pentru a revoca o cheie, apasă butonul roșu de coș de gunoi de pe rând și confirmă în modalul Șterge cheia API.

Secretele de webhook sunt diferite. Webhook-urile au propriul flux de rotire a secretului în pagina Setări → Webhook-uri; nu are legătură cu cheile API. Vezi Webhook-uri mai jos.

Folosește cheia într-o cerere

Trimite cheia în antetul standard Authorization: Bearer … la fiecare cerere. Valoarea exactă este cea afișată în modalul de afișare — copiaz-o ca atare, inclusiv prefixul ebon_live_….

curl https://api.e-bon.ro/api/v1/devices \
  -H "Authorization: Bearer ebon_live_<orgId>_xxxxxxxxxxxxxxxx"

Același antet funcționează pentru orice endpoint din API-ul e-bon acoperit de permisiunile cheii tale:

GET /api/v1/devices HTTP/1.1
Host: api.e-bon.ro
Authorization: Bearer ebon_live_<orgId>_xxxxxxxxxxxxxxxx
Accept: application/json

O autentificare eșuată returnează 401 Unauthorized (cheie lipsă, ștearsă sau dezactivată). O cerere care se autentifică, dar iese din permisiunile cheii, returnează 403 Forbidden.

Pentru un parcurs complet de la zero — emiterea primului bon prin API folosind una dintre aceste chei — vezi Ghidul de integrare API.

Webhook-uri (context conex)

Cheile API sunt modul în care un sistem extern trage date din e-bon. Webhook-urile sunt cealaltă jumătate a poveștii de integrare — modul în care e-bon împinge evenimente către URL-ul tău atunci când se întâmplă ceva (este emis un bon, se închide un raport Z, un dispozitiv intră în offline). Le configurezi din pagina Setări → Webhook-uri la /portal/settings/webhooks.

Tipic vei folosi ambele: o cheie API ca sistemul tău să poată citi și acționa pe date și un abonament la webhook-uri ca e-bon să poată notifica sistemul tău în momentul în care un eveniment relevant se produce — fără polling. Referința completă a evenimentelor de webhook și detaliile de verificare a semnăturii sunt parte din referința API.

Pași următori

• Dispozitive — vezi la ce îți dau acces permisiunile devices și devices:read.
• Bonuri — datele care stau în spatele permisiunilor receipts*.
• Rapoarte — ce citește reports și ce poate declanșa commands.