Comenzi

API-ul de comenzi este suprafața publică a modelului de coadă de comenzi din e-bon. Un POS sau o integrare de back-office trimite o comandă fiscală (print_receipt, x_report, cash_in, set_datetime, …) către e-bon prin REST; serverul persistă comanda, o trimite în fundal către dispozitivul corespunzător prin WebSocket și returnează imediat o înregistrare cu status pending, ca apelantul HTTP să nu fie blocat de round-trip-ul cu dispozitivul. Apoi integrarea face polling pe GET /api/v1/commands/{commandId} până când comanda ajunge într-un status terminal (completed, failed, timeout) sau se abonează la evenimentele command.completed / command.failed / command.timeout pe canalul de Webhook-uri.

Toate endpoint-urile din acest grup sunt sub /api/v1/commands și au o singură permisiune de cheie API: commands. Acceptă și un JWT din Portal prin middleware-ul de autentificare combinată. Vezi Autentificare › Alege permisiunile pentru catalogul complet de permisiuni.

Plicul de eroare, regulile de idempotență și limitele de rată folosite mai jos sunt documentate o singură dată pe Prezentare API; pe această pagină listăm doar codurile de eroare specifice fiecărui endpoint.

POST /api/v1/commands

Pune în coadă o comandă fiscală către un dispozitiv din organizația ta. Comanda este trimisă către dispozitiv prin WebSocket asincron; răspunsul este returnat imediat cu status: "pending".

• Permisiune cheie API: commands
• Idempotență: acceptă antetul Idempotency-Key (rejucările returnează răspunsul 201 original fără retrimitere).
• Limită de rată: ruta trece prin middleware-ul dedicat commandRateLimit (50 / 10 min implicit), peste limita globală. Vezi Limite de rată.

Corpul cererii

Răspuns (201 Created)

{
  "id": "cmd_abc123",
  "deviceId": "dev_pos_01",
  "type": "print_receipt",
  "payload": { "items": [], "payments": [] },
  "orgId": "acme_corp",
  "status": "pending",
  "apiKeyId": "apikey_abc",
  "deviceOnline": true,
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:00.000Z"
}

deviceOnline este o fotografie a conectivității WebSocket din momentul în care comanda a fost pusă în coadă — false nu blochează comanda (rămâne pending și e trimisă imediat ce dispozitivul se reconectează), dar este un semnal util de avertizare în loguri.

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/commands \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-attempt-1" \
  -d '{
    "deviceId": "dev_pos_01",
    "type": "x_report",
    "payload": {}
  }'

Coduri de eroare

• VALIDATION_ERROR (400) — corpul nu a trecut validarea Zod sau payload nu a trecut verificarea schemei specifice lui type (details listează { path, message } pentru fiecare câmp).
• NOT_FOUND (404) — deviceId nu există în organizația ta.
• RATE_LIMIT_EXCEEDED (429) — s-a atins limita de rată pentru comenzi.
• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

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

GET /api/v1/commands

Listează comenzile organizației, cele mai noi primele după createdAt. Filtrele opționale restrâng setul de rezultate; răspunsul este un array JSON plat (fără plic).

• Permisiune cheie API: commands

Parametri query

Răspuns (200 OK)

[
  {
    "id": "cmd_abc123",
    "deviceId": "dev_pos_01",
    "type": "print_receipt",
    "status": "completed",
    "payload": { "items": [], "payments": [] },
    "result": { "success": true, "fiscalId": "AMEF-000123" },
    "orgId": "acme_corp",
    "apiKeyId": "apikey_abc",
    "createdAt": "2026-04-09T08:10:00.000Z",
    "updatedAt": "2026-04-09T08:10:02.500Z"
  }
]

Exemplu

curl "https://api.e-bon.ro/api/v1/commands?deviceId=dev_pos_01&status=failed&limit=20" \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Coduri de eroare

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

GET /api/v1/commands/{commandId}

Returnează o singură comandă după ID. Folosește acest endpoint pentru a face polling pe finalizare după POST /api/v1/commands.

• Permisiune cheie API: commands

Parametri de cale

Răspuns (200 OK)

{
  "id": "cmd_abc123",
  "deviceId": "dev_pos_01",
  "type": "print_receipt",
  "status": "completed",
  "payload": { "items": [], "payments": [] },
  "result": {
    "success": true,
    "fiscalId": "AMEF-000123",
    "data": { "receiptNumber": "0000123" }
  },
  "orgId": "acme_corp",
  "apiKeyId": "apikey_abc",
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:02.500Z"
}

Când comanda este într-un status terminal de eșec, result.success este false, iar error / errorCode / errorMessage sunt populate. Valoarea errorCode este una dintre codurile de eroare fiscale / pe aparat.

Exemplu

curl https://api.e-bon.ro/api/v1/commands/cmd_abc123 \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Coduri de eroare

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

POST /api/v1/commands/{commandId}/cancel

Anulează o comandă care este încă în status pending sau sent. Statusul comenzii este mutat la failed, cu error: "Cancelled by API" și errorCode: "Unknown". Comenzile aflate deja în processing, completed, failed sau timeout nu pot fi anulate — odată ce dispozitivul preia comanda, doar dispozitivul decide rezultatul.

• Permisiune cheie API: commands
• Efect lateral: actualizează înregistrarea comenzii. Nu trimite un mesaj de anulare către dispozitiv — dacă dispozitivul a primit deja comanda prin WebSocket, o poate finaliza; statusul anulat este pur și simplu un marker server-side pentru apelantul API.

Parametri de cale

Răspuns (200 OK)

{
  "id": "cmd_abc123",
  "deviceId": "dev_pos_01",
  "type": "print_receipt",
  "status": "failed",
  "payload": { "items": [], "payments": [] },
  "error": "Cancelled by API",
  "errorCode": "Unknown",
  "errorMessage": "Cancelled by API",
  "orgId": "acme_corp",
  "apiKeyId": "apikey_abc",
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:01.000Z"
}

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/commands/cmd_abc123/cancel \
  -H "Authorization: Bearer ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Coduri de eroare

• NOT_FOUND (404) — nu există nicio comandă cu acel ID în organizația ta.
• CONFLICT (409) — comanda nu mai poate fi anulată (statusul curent este unul dintre processing, completed, failed, timeout). Mesajul de eroare include statusul curent.
• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

Vezi și

• Dispozitive — scurtături de comenzi pe dispozitiv (POST /api/v1/devices/{deviceId}/commands și wrapper-ele tipate pentru sold de numerar, antet/subsol, cote TVA, storno etc.).
• Webhook-uri — abonează-te la evenimentele command.completed, command.failed și command.timeout în loc de polling.
• Autentificare — formatul cheilor API, permisiuni și fluxul de login JWT.
• Prezentare API — URL de bază, plic de eroare, limite de rată, idempotență, paginare.
• Depanare › Timeout-uri de comenzi și sweep-ul de 180s — ce înseamnă efectiv command.timeout și cum reîncerci idempotent.