Validarea conținutului comenzilor

Fiecare comandă trimisă către API-ul e-bon este validată înainte de a ajunge la dispozitiv. Dacă conținutul nu trece validarea, cererea este respinsă cu HTTP 400 și o listă structurată de erori la nivel de câmp — nicio comandă nu este pusă în așteptare, niciun bon fiscal nu este tipărit.

Această pagină documentează regulile, ca să poți construi cereri care trec din prima.

Validează după constantele fiscale din România

Trei seturi fixe de valori sunt aplicate pe comenzile legate de bonuri.

Grupe de TVA

Câmpul vatGroup de pe fiecare articol trebuie să fie una dintre grupele TVA ale dispozitivului:

Procentul efectiv al fiecărei grupe nu este validat după o listă națională fixă — se rezolvă din tabela de cote a imprimantei, pe care e-bon o citește live de pe dispozitiv (get_vat_rates / get_vat_capabilities). Cotele nu sunt niciodată hardcodate.

Orice altă valoare este respinsă cu:

vatGroup must be one of: VAT1..VAT16, exempt

Tipuri de plată

Fiecare intrare din payments[] trebuie să declare un type din acest set:

Mesaj de respingere:

type must be one of: 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

Motive de stornare

La emiterea unui bon de stornare, reason trebuie să fie unul dintre:

Mesaj de respingere:

reason must be one of: operator-error, refund, tax-base-reduction

Echilibrează articolele cu plățile

Pentru bonurile care includ atât items, cât și payments, totalurile trebuie să coincidă:

sum(items[i].quantity * items[i].price)  ==  sum(payments[i].amount)

Ambele părți sunt rotunjite la 2 zecimale. O diferență de până la ±0,01 RON este tolerată pentru a absorbi rotunjirile de virgulă mobilă — nu este o marjă de discount.

Dacă totalurile nu coincid, cererea este respinsă cu un mesaj de forma:

Payment total (99.99) does not match items total (100.00)

Aplică regulile per tip de comandă

Comenzile de mai jos transportă conținut care este validat câmp cu câmp. Comenzile care nu apar aici fie nu primesc conținut, fie au forma fixată de schema cererii.

print_receipt

Cel mai pretențios conținut. Combină validarea articolelor, validarea plăților și verificarea de echilibru articole-vs-plăți.

void_receipt

cash_in / cash_out

Ambele comenzi folosesc același validator.

set_datetime

non_fiscal_receipt

set_logo

set_vat_rates

set_header_footer

Tablourile vide sunt acceptate.

set_operator

print_reversal_receipt

print_receipt vs print_reversal_receipt

Interpretează răspunsul de eroare la validare

Când conținutul nu trece validarea, API-ul returnează HTTP 400 cu acest corp:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid command payload",
    "details": [
      { "field": "items[0].vatGroup", "message": "vatGroup must be one of: VAT1..VAT16, exempt" },
      { "field": "payments", "message": "Payment total (99.99) does not match items total (100.00)" }
    ]
  }
}

details enumeră fiecare câmp care a eșuat, în ordinea verificării. Pentru a localiza eroarea în propria interfață, mapează pe field + code, nu pe textul message — mesajele sunt doar în engleză și pot evolua.

Endpoint-ul dedicat de stornare folosește aceeași formă, dar message-ul de la nivel superior este "Invalid reversal receipt payload" în loc de "Invalid command payload".

Mai departe

• Referință: Tipuri de comenzi — catalogul complet al formelor de conținut per tip de comandă.
• Referință: Coduri de eroare — catalogul complet ErrorCode, inclusiv VALIDATION_ERROR.
• API: Comenzi — contractul POST /api/v1/commands.
• API: Dispozitive — endpoint-urile de comandă per dispozitiv, inclusiv ruta de stornare.
• API: Erori — forma de pe fir a fiecărui răspuns de eroare.