Referință API

Bonuri

Endpoint-uri REST pentru stocarea, listarea și consultarea bonurilor fiscale după tipărirea pe AMEF — scheme cerere/răspuns, exemple curl și coduri de eroare per endpoint.

Bonuri

API-ul de bonuri este stratul de jurnal al e-bon: după ce o comandă fiscală a fost executată de AMEF și imprimanta a returnat un ID fiscal, integrarea stochează o copie a bonului în e-bon, ca să poată fi căutat, exportat și auditat ulterior. Endpoint-urile de sub /api/v1/receipts nu tipăresc nimic — tipărirea se face prin stratul Comenzi pentru dispozitive; colecția de bonuri este un jurnal write-once cu ce s-a tipărit deja.

Toate endpoint-urile din acest grup acceptă fie o cheie API (x-api-key / Authorization: Bearer …), fie un JWT din Portal și sunt guvernate de un singur scope: receipts. Nu există acces read-only separat pentru aceste rute — receipts:read și receipts:admin acoperă alte operațiuni (export istoric, storno) documentate în altă parte. Vezi Autentificare › Alege permisiunile pentru catalogul complet.

Plicul de eroare, regulile de idempotență și convențiile de paginare folosite mai jos sunt documentate o singură dată pe Prezentarea API-ului; pe această pagină listăm doar codurile de eroare specifice fiecărui endpoint.

POST /api/v1/receipts

Stochează un bon după o tipărire fiscală reușită. Apelează acest endpoint imediat ce o comandă print_receipt pe dispozitiv întoarce un ID fiscal, ca să păstrezi jurnalul e-bon sincronizat.

Scope auth: receipts
Idempotență: acceptă header-ul Idempotency-Key (replay-urile întorc răspunsul 201 inițial).
Efect lateral: difuzează un eveniment receipt.created pe WebSocket-ul de evenimente al organizației și trimite un webhook receipt.created către abonați.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`deviceId`	string	da	Trebuie să fie un dispozitiv care există în organizația ta.
`type`	string	da	Una dintre `sale`, `refund`, `storno`.
`items`	array	da	Cel puțin un articol. Fiecare `{ name, quantity, price, vatGroup, department?, discount? }` — omite `department` pentru o vânzare cu denumire, contabilizată pe propria grupă TVA a articolului. `vatGroup` ∈ `VAT1`..`VAT16`, `exempt` (grupa TVA a dispozitivului).
`payments`	array	da	Poate fi gol (un bon tipărit fără linii de plată explicite este închis de dispozitiv cu numerar). Fiecare `{ method, amount }`. `method` ∈ `cash`, `card`, `check`, `credit`, `coupons`, `meal-vouchers`, `value-tickets`, `voucher`, `modern-payment`, `card-advance`, `foreign-currency`, `bank`, `ext-coupons`, `packaging`, `internal-usage`, `damage`, `reserved1`, `reserved2`, `other`.
`total`	number	da	Totalul bonului (suma plăților).
`vatBreakdown`	array	da	Poate fi goală (best-effort — citirea tabelei de cote TVA după tipărire poate eșua). Fiecare `{ group, rate, base, amount }` — `group` este grupa TVA a dispozitivului, `rate` procentul extras din tabela de cote a imprimantei.
`operatorId`	string	da	Identificatorul operatorului / casierului.
`fiscalId`	string	nu	ID-ul fiscal returnat de AMEF.
`fiscalDate`	string	nu	Data fiscală returnată de AMEF.
`customerCif`	string	nu	CIF client, 2–20 caractere, fără spații la capete.
`qrCode`	string	nu	Date QR code, ≤ 2048 caractere.
`source`	string	nu	Una dintre `api`, `local`, `portal`. Implicit `api`.

Răspuns (`201 Created`)

{
  "receipt": {
    "id": "rec_abc123",
    "deviceId": "dev_pos_01",
    "type": "sale",
    "items": [
      { "name": "Paine alba 500g", "quantity": 2, "price": 5.49, "vatGroup": "VAT2", "department": 1 }
    ],
    "payments": [{ "method": "cash", "amount": 10.98 }],
    "total": 10.98,
    "vatBreakdown": [{ "group": "VAT2", "rate": 9, "base": 10.07, "amount": 0.91 }],
    "operatorId": "casier_01",
    "orgId": "acme_corp",
    "fiscalId": "AMEF-000123",
    "fiscalDate": "2026-04-09",
    "source": "api",
    "createdAt": "2026-04-09T08:10:00.000Z"
  }
}

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/receipts \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-attempt-1" \
  -d '{
    "deviceId": "dev_pos_01",
    "type": "sale",
    "items": [
      { "name": "Paine alba 500g", "quantity": 2, "price": 5.49, "vatGroup": "VAT2", "department": 1 }
    ],
    "payments": [{ "method": "cash", "amount": 10.98 }],
    "total": 10.98,
    "vatBreakdown": [{ "group": "VAT2", "rate": 9, "base": 10.07, "amount": 0.91 }],
    "operatorId": "casier_01",
    "fiscalId": "AMEF-000123",
    "fiscalDate": "2026-04-09"
  }'

Coduri de eroare

VALIDATION_ERROR (400) — corpul cererii este invalid (câmpuri lipsă, grupă TVA invalidă etc.).
NOT_FOUND (404) — deviceId nu există în organizația ta.
UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

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

GET /api/v1/receipts

Listează bonurile organizației cu paginare prin cursor și un set de filtre opționale. Bonurile sunt returnate în ordine descrescătoare a datei, implicit.

Scope auth: receipts

Parametri query

Parametru	Tip	Implicit	Note
`deviceId`	string	—	Filtrează după dispozitiv.
`type`	string	—	Una dintre `sale`, `refund`, `storno`.
`operatorId`	string	—	Filtrează după operator.
`minTotal`	number	—	Limită inferioară inclusivă pe `total`.
`maxTotal`	number	—	Limită superioară inclusivă pe `total`. Trebuie să fie ≥ `minTotal`.
`startDate`	string	—	Timestamp ISO 8601; bonuri cu `createdAt >= startDate`.
`endDate`	string	—	Timestamp ISO 8601; bonuri cu `createdAt <= endDate`.
`sortBy`	string	`createdAt`	`createdAt` sau `total`. Ignorat când `startDate`/`endDate` este setat (sortare după `createdAt`).
`sortOrder`	string	`desc`	`asc` sau `desc`.
`limit`	integer	`50`	Mărime pagină, `1`–`100`.
`startAfter`	string	—	Cursor — trimite valoarea `lastId` din răspunsul precedent.

Când combini un filtru pe interval de total (minTotal / maxTotal) cu sortare, serverul sortează întâi după total (ca să satisfacă regula Firestore pentru range-query), apoi după createdAt desc ca tiebreaker.

Răspuns (`200 OK`)

{
  "receipts": [
    {
      "id": "rec_abc123",
      "deviceId": "dev_pos_01",
      "type": "sale",
      "total": 10.98,
      "operatorId": "casier_01",
      "orgId": "acme_corp",
      "createdAt": "2026-04-09T08:10:00.000Z"
    }
  ],
  "hasMore": true,
  "lastId": "rec_abc123"
}

Exemplu

curl "https://api.e-bon.ro/api/v1/receipts?deviceId=dev_pos_01&limit=20" \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Apoi, pentru a aduce pagina următoare:

curl "https://api.e-bon.ro/api/v1/receipts?deviceId=dev_pos_01&limit=20&startAfter=rec_abc123" \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Coduri de eroare

VALIDATION_ERROR (400) — query invalid (de ex. minTotal > maxTotal, limit > 100).
UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

GET /api/v1/receipts/{receiptId}

Returnează un singur bon după ID.

Scope auth: receipts

Parametri cale

Parametru	Tip	Note
`receiptId`	string	ID-ul documentului bon.

Răspuns (`200 OK`)

{
  "receipt": {
    "id": "rec_abc123",
    "deviceId": "dev_pos_01",
    "type": "sale",
    "items": [
      { "name": "Paine alba 500g", "quantity": 2, "price": 5.49, "vatGroup": "VAT2", "department": 1 }
    ],
    "payments": [{ "method": "cash", "amount": 10.98 }],
    "total": 10.98,
    "vatBreakdown": [{ "group": "VAT2", "rate": 9, "base": 10.07, "amount": 0.91 }],
    "operatorId": "casier_01",
    "orgId": "acme_corp",
    "fiscalId": "AMEF-000123",
    "fiscalDate": "2026-04-09",
    "createdAt": "2026-04-09T08:10:00.000Z"
  }
}

Exemplu

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

Coduri de eroare

NOT_FOUND (404) — nu există un bon cu acel ID în organizația ta.
UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

Vezi și

Comenzi pentru dispozitive — emite o comandă print_receipt înainte să stochezi bonul aici.
Rapoarte — rapoarte live de pe dispozitiv: citiri MF/EJ, tipăriri X/Z/periodice, export arhivă ANAF.
Prezentare API — URL de bază, plic de eroare, limite de rată, idempotență, paginare.
Depanare — rețete pe simptom când bonurile eșuează la tipărire, expiră sau declanșează respingeri ANAF.

Trasare și jurnalizare a cererilor

Cum să urmărești un singur apel HTTP de la clientul tău până la e-bon — turul antetului X-Request-Id, forma plicului de eroare, rețete client gata făcute și o listă de raport de bug care transformă investigațiile de minute în secunde.

Rapoarte

Endpoint-uri de rapoarte live de pe dispozitiv — citește memoria fiscală (istoric Z) și jurnalul electronic, tipărește rapoarte X/Z/periodice și exportă arhiva lunară ANAF, direct de pe AMEF.