Referință API

Dispozitive

Endpoint-uri REST pentru gestionarea dispozitivelor fiscale (AMEF) — CRUD, claim/release, status live, alerte și setul complet de comenzi (sold de casă, dată/oră, sigle, cote TVA, antet/subsol, operatori, anulare, storno etc.).

Dispozitive

API-ul de dispozitive este cea mai largă suprafață din e-bon. Se împarte în două straturi, ambele montate sub /api/v1/devices:

CRUD & introspecție — înregistrează, actualizează și șterge dispozitive, le listează, citește status și alerte. Aceste endpoint-uri citesc/scriu în înregistrarea dispozitivului din Firestore și în gateway-ul WebSocket din memorie.
Comenzi & operațiuni live — preluare/eliberare control (claim/release), trimitere de comenzi fiscale (set_datetime, print_duplicate, non_fiscal_receipt, set_logo, configurări TVA/antet/subsol/operator, anulări, stornări…) și citire de date live de pe dispozitiv. Pentru majoritatea rutelor de comandă, platforma transmite cererea spre dispozitiv prin WebSocket și așteaptă răspunsul acestuia înainte de a răspunde.

Fiecare endpoint își declară mai jos propriul scope. Cele patru scope-uri folosite în acest grup sunt devices:read, devices:write, commands și receipts — vezi Autentificare › Alege permisiunile pentru catalogul complet. Plicul de eroare, limitele de rată și regulile de autentificare sunt documentate o singură dată pe Prezentarea API-ului.

Endpoint-urile de tip comandă live (sold de casă, set datetime, print duplicate, non-fiscal, sigla, cote TVA, antet/subsol, operator, info, last-receipt, void, storno) cer ca dispozitivul să fie online prin WebSocket și să aibă un controller atribuit. Dacă vreuna din condiții nu e îndeplinită, cererea eșuează cu 503 SERVICE_UNAVAILABLE.

CRUD

POST /api/v1/devices

Înregistrează un dispozitiv fiscal nou pe organizație.

Scope auth: devices:write
Verificare plan: cererea este verificată față de limita de dispozitive a planului tău înainte de validarea corpului; dacă organizația ta a atins deja limita de dispozitive, cererea este respinsă cu 403.

Corpul cererii

Câmp	Tip	Obligatoriu	Note
`name`	string	da	1–255 caractere.
`protocol`	string	da	Una dintre `datecs_compact`, `datecs_professional`, `datecs_extended`, `daisy`, `daisy_ro`, `eltrade`, `incotex`, `tremol`, `tremol_v2`, `custom`, `mfje`.
`transport`	string	da	Una dintre `tcp`, `bluetooth`, `serial`, `usb`.
`locationId`	string	da	Locația de care aparține dispozitivul (≥ 1 caracter).
`connectionParams`	object	da	Fie `{ host: string, port: number (1–65535) }` (TCP), fie `{ address: string }` (bluetooth/serial/usb).

Răspuns (`201 Created`)

{
  "id": "dev_pos_01",
  "name": "Tejghea POS 1",
  "protocol": "datecs_compact",
  "transport": "tcp",
  "locationId": "loc_main",
  "connectionParams": { "host": "192.168.1.50", "port": 9100 },
  "orgId": "acme_corp",
  "status": "offline",
  "controllerId": null,
  "controllerName": null,
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:00.000Z"
}

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/devices \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tejghea POS 1",
    "protocol": "datecs_compact",
    "transport": "tcp",
    "locationId": "loc_main",
    "connectionParams": { "host": "192.168.1.50", "port": 9100 }
  }'

Parametru	Tip	Note
`status`	string	Una dintre `online`, `offline`, `busy`, `error`.
`locationId`	string	Filtrează după locație.

Câmp	Tip	Obligatoriu	Note
`type`	string	da	Una dintre: `print_receipt`, `void_receipt`, `x_report`, `z_report`, `cash_in`, `cash_out`, `get_status`, `get_cash_amount`, `set_datetime`, `print_duplicate`, `non_fiscal_receipt`, `set_logo`, `delete_logo`, `raw_command`, `open_drawer` (plus tipurile mai specifice listate în rutele dedicate de mai jos).
`payload`	object	da	Payload specific comenzii. Pre-validat pe server.

Câmp	Tip	Obligatoriu	Note
`lines`	string	da	Cel puțin o linie. Fiecare linie ≤ 48 caractere.
`header`	string	nu	Antet opțional, tipărit bold/centrat în partea de sus. ≤ 48 caractere.

Câmp	Tip	Obligatoriu	Note
`header`	string	da	Până la 10 linii, fiecare ≤ 48 caractere.
`footer`	string	da	Până la 10 linii, fiecare ≤ 48 caractere.