Prezentare generală SDK

@e-bon/sdk este clientul TypeScript oficial pentru API-ul REST e-bon. Este aceeași librărie folosită intern de Portalul e-bon și este modul recomandat de a comunica cu api.e-bon.ro/docs din orice runtime TypeScript sau JavaScript modern (Node 22+, Deno, Bun, browsere moderne). Actualizările în timp real trăiesc în pachetul standalone @e-bon/realtime.

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.

SDK-ul este doar REST. Pentru actualizări în timp real (bonuri, rezultate de comenzi, status de dispozitiv, alerte), folosește în schimb pachetul standalone @e-bon/realtime — cele două partajează @e-bon/types, dar nu au altă cuplare.

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

Livrarea în timp real trăiește în pachetul standalone @e-bon/realtime — bonurile tipărite, rezultatele comenzilor, schimbările de status al dispozitivelor și alertele derivate curg toate prin canalul său WebSocket. Instalează-l alături de SDK și reutilizează aceleași credențiale:

import { RealtimeClient } from '@e-bon/realtime';

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

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

Catalogul complet de evenimente, tipurile de payload și semantica reconectării sunt documentate sub Realtime › Evenimente.

Unde mergi mai departe

• Pornire rapidă — instalare, obținerea unei chei API, instanțierea clientului și emiterea primului bon.
• Prezentare generală Realtime — clientul WebSocket standalone pentru actualizări live.
• 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.