Prezentare generală SDK

@e-bon/sdk este clientul TypeScript oficial pentru API-ul REST e-bon și pentru WebSocket-ul de evenimente. Este aceeași librărie folosită intern de Portalul e-bon și este modul recomandat de a comunica cu https://api.e-bon.ro din orice runtime TypeScript sau JavaScript modern (Node 22+, Deno, Bun, browsere moderne).

Ce îți oferă SDK-ul peste un fetch brut:

• Un EBonClient tipat, cu un accesor pentru fiecare resursă (devices, commands, receipts, …).
• Tratarea automată a antetului de autentificare — pasezi o cheie API sau un JWT o singură dată și uiți de el.
• O excepție reală EBonApiError cu status, code, details și retryAfter, ca să poți ramifica în funcție de plicul de eroare fără să parsezi singur JSON.
• O excepție FiscalError pentru eșecurile de comandă fiscală, cu un câmp retryable precalculat.
• Un EventSubscriber care împachetează WebSocket-ul de evenimente cu reconectare automată și payload-uri de eveniment tipate.

SDK-ul este o mapare subțire și fidelă peste API-ul HTTP documentat. Tot ce face el se poate face și cu curl — vezi Prezentare generală API pentru referința la nivel de protocol.

Instalare

pnpm add @e-bon/sdk

Pachetul se instalează și cu npm install @e-bon/sdk sau yarn add @e-bon/sdk. Are o singură dependență de runtime (@e-bon/types) și vine cu declarații TypeScript incluse.

Instanțierea clientului

EBonClient este singurul punct de intrare. Primește un obiect EBonClientOptions cu unul din două moduri de autentificare — niciodată ambele în același timp.

Cu o cheie API (parteneri POS, integrări de server)

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

const client = new EBonClient({
  baseUrl: 'https://api.e-bon.ro',
  apiKey: 'ebon_live_<orgId>_<32-hex>',
});

SDK-ul trimite cheia ca antet X-API-Key la fiecare cerere. Acesta este modul pe care îl vrei pentru orice back-end nesupravegheat.

Cu un JWT (sesiuni Portal, aplicația mobilă)

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

const client = new EBonClient({
  baseUrl: 'https://api.e-bon.ro',
  token: 'eyJ...',
});

SDK-ul trimite token-ul ca antet Authorization: Bearer <token>. După o reînnoire, împinge noul token de acces în același client fără să îl recreezi:

client.setToken('eyJ...token-de-acces-nou');

Configurează celelalte opțiuni

Dacă nu pasezi nici apiKey, nici token, fiecare cerere va eșua cu 401 UNAUTHORIZED. Dacă lipsește baseUrl, constructorul aruncă sincron.

Accesează resursele

EBonClient expune zece accesoare de resurse tipate. Fiecare acoperă o felie din /api/v1/* și returnează obiecte TypeScript simple, sprijinite pe tipurile din @e-bon/types.

Fiecare accesor este construit o singură dată când instanțiezi EBonClient; sunt referințe stabile pe care le poți păstra în siguranță pe un obiect cu durată lungă de viață.

Tratează erorile

Fiecare apel HTTP trece prin același handler și expune erorile sub forma a două clase concrete:

• EBonApiError — împachetează orice răspuns HTTP non-2xx. Conține status, code (corespunde catalogului de erori HTTP), message, details și, pe 429, retryAfter (secunde).
• FiscalError — apare când o comandă fiscală eșuează la imprimantă. Conține code (enumerarea ErrorCode), message, retryable, commandId și deviceId.

Câmpul retryable de pe FiscalError este precalculat din mulțimea RETRYABLE_ERRORS din @e-bon/types, deci poți ramifica direct:

import { FiscalError, isRetryable } from '@e-bon/sdk';

try {
  await client.commands.send({ deviceId, type: 'print_receipt', payload });
} catch (err) {
  if (err instanceof FiscalError && err.retryable) {
    // Sigur de retrimis cu același Idempotency-Key
  } else {
    throw err;
  }
}

Catalogul complet de coduri de eroare, modelul de retry și forma lui EBonApiError se află pe pagina Erori.

Abonează-te la evenimente în timp real

EBonClient poartă un mic accesor events care îți întoarce un EventSubscriber conectat la WebSocket-ul de evenimente folosind aceleași credențiale ca și clientul HTTP:

const events = client.events.subscribe();
events.on('receipt.created', (data) => console.log('bon', data.receiptId));
events.on('command.failed', (data) => console.error('eșec', data.fiscalError));
events.close();

Subscriber-ul se reconectează automat cu backoff exponențial. Catalogul complet de evenimente, tipurile de payload și semantica reconectării sunt documentate pe pagina Evenimente.

Unde mergi mai departe

• Pornire rapidă — instalare, obținerea unei chei API, instanțierea clientului și emiterea primului bon.
• Evenimente — EventSubscriber, EventMap tipat și reconectare automată.
• Erori — FiscalError, EBonApiError și modelul recomandat de reîncercare.
• Prezentare generală API — referința REST la nivel de protocol pe care este construit SDK-ul.
• Bonuri, Comenzi, Aparate — referințe HTTP per resursă cu schemele de cerere și răspuns.