Înregistrează-te și copiază prima cheie API

Creează o organizație în Portalul Cloud (app.e-bon.ro) cu emailul de business. CUI-ul este preluat automat din ANAF — confirmă-l, alege o parolă, iar organizația este provizionată pe planul gratuit fără card.

După ce ajungi în dashboard, deschide Setări → Chei API (calea: /portal/api-keys), apasă Creează cheie, dă-i o etichetă de tipul Dezvoltare locală — ghid rapid, alege cel puțin permisiunile devices:read și commands și copiază cheia. Cheia completă este afișată o singură dată — păstreaz-o într-un manager de parole sau într-un fișier .env pe care nu îl comiți.

Cheile API au forma:

ebon_live_<orgId>_<32-hex>

Pentru restul paginii, exportă cheia o singură dată și reutilizeaz-o:

export EBON_API_KEY="ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Ghidul complet din Portal — inclusiv rotația, dezactivarea și urmărirea ultimei utilizări — se află la Portal › Chei API.

Fă primul apel — listează dispozitivele

Cel mai mic apel end-to-end pe care îl poți face este GET /api/v1/devices. Validează cheia, întoarce dispozitivele înregistrate în organizație și funcționează și pe o organizație goală (primești înapoi []).

curl

curl https://api.e-bon.ro/api/v1/devices \
  -H "Authorization: Bearer $EBON_API_KEY"

Node — @e-bon/sdk

Mai întâi instalează SDK-ul în proiect:

pnpm add @e-bon/sdk

Apoi:

import { EBonClient } from '@e-bon/sdk';

const client = new EBonClient({
  baseUrl: 'https://api.e-bon.ro',
  apiKey: process.env.EBON_API_KEY!,
});

const devices = await client.devices.list();
console.log(devices);

Un răspuns reușit este un array JSON plat (fără înveliș):

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

Dacă încă nu ai asociat o casă de marcat, array-ul va fi gol — este în regulă pentru pasul următor, dar vei avea nevoie de cel puțin un dispozitiv online (un AMEF real sau un dispozitiv de dezvoltare conectat la un simulator de imprimantă) înainte ca prima comandă print_receipt să poată fi finalizată cu succes. Ghidul de integrare acoperă fluxul de asociere în portal și în aplicația E-BON pentru Android.

Alege un deviceId din răspuns (sau înregistrează unul mai întâi) și exportă-l pentru pasul următor:

export EBON_DEVICE_ID="dev_pos_01"

Trimite prima comandă fiscală

API-ul de comenzi fiscale este asincron: POST /api/v1/commands pune comanda în coadă, întoarce 201 cu status: "pending" și o trimite dispozitivului prin WebSocket în fundal. Apoi fie faci polling pe GET /api/v1/commands/{commandId}, fie — preferabil — te abonezi la evenimentele command.* (pasul următor).

Cel mai mic payload print_receipt valid este un singur articol plătit cash:

curl

curl -X POST https://api.e-bon.ro/api/v1/commands \
  -H "Authorization: Bearer $EBON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$(date +%s)" \
  -d '{
    "deviceId": "'"$EBON_DEVICE_ID"'",
    "type": "print_receipt",
    "payload": {
      "items": [
        { "name": "Item A", "price": 10, "quantity": 1, "vatRate": 21 }
      ],
      "payments": [
        { "type": "cash", "amount": 10 }
      ]
    }
  }'

Node — @e-bon/sdk

const command = await client.commands.send({
  deviceId: process.env.EBON_DEVICE_ID!,
  type: 'print_receipt',
  payload: {
    items: [{ name: 'Item A', price: 10, quantity: 1, vatRate: 21 }],
    payments: [{ type: 'cash', amount: 10 }],
  },
});

console.log(command.id, command.status); // → "cmd_…", "pending"

Primești înapoi un 201 Created cu înregistrarea pusă în coadă:

{
  "id": "cmd_abc123",
  "deviceId": "dev_pos_01",
  "type": "print_receipt",
  "payload": {
    "items": [{ "name": "Item A", "price": 10, "quantity": 1, "vatRate": 21 }],
    "payments": [{ "type": "cash", "amount": 10 }]
  },
  "orgId": "acme_corp",
  "status": "pending",
  "apiKeyId": "apikey_abc",
  "deviceOnline": true,
  "createdAt": "2026-04-09T08:10:00.000Z",
  "updatedAt": "2026-04-09T08:10:00.000Z"
}

Schemele de payload pentru fiecare type, limita commandRateLimit (50 / 10 min) și semantica antetului Idempotency-Key sunt documentate pe pagina Comenzi.

Abonează-te la primul eveniment

Polling-ul funcționează, dar calea în timp real este mai simplă: deschizi un singur subscriber WebSocket, asculți command.completed și command.failed și rezolvi fiecare comandă dintr-un singur handler.

curl — nu există o cale curl pentru stream-ul de evenimente; canalul este un WebSocket. Fie sari direct la fragmentul Node de mai jos, fie, în timp ce aștepți, fă polling pe înregistrarea comenzii:

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

Node — @e-bon/sdk

import { EBonClient } from '@e-bon/sdk';

const client = new EBonClient({
  baseUrl: 'https://api.e-bon.ro',
  apiKey: process.env.EBON_API_KEY!,
});

const events = client.events.subscribe();

events.on('command.completed', (data) => {
  // data: { commandId, deviceId, type, result, timestamp }
  console.log(`✓ ${data.type} ${data.commandId} pe ${data.deviceId} ok`);
});

events.on('command.failed', (data) => {
  // data: { commandId, deviceId, type, error, errorCode, retryable, timestamp, fiscalError }
  console.error(
    `✗ ${data.type} ${data.commandId} a eșuat: ${data.errorCode} — ${data.error} (retryable=${data.retryable})`,
  );
});

// La oprire:
// events.close();

errorCode este una dintre constantele ErrorCode — valori uzuale includ E300 (memorie fiscală plină), E304 (eroare hardware fiscal), E400 (validare — payload invalid), E500 (timeout — comandă), E900 (necunoscută). Catalogul complet și semantica retryable sunt documentate pe API › Webhook-uri și SDK › Evenimente.

Subscriber-ul se reconectează automat cu backoff exponențial, deci îl poți lăsa pornit pe toată durata de viață a worker-ului tău.

Continuă integrarea

Ai bucla end-to-end: cheie → listare → comandă → eveniment. Restul API-ului e-bon este o variație pe aceeași formă.