Prezentare arhitectură
Această pagină îți oferă imaginea de ansamblu asupra modului în care funcționează e-bon. Citește-o o dată înainte să integrezi casa de marcat cu API-ul, înainte să configurezi un webhook sau înainte să investighezi de ce un eveniment a sosit mai târziu decât te așteptai.
Dacă vrei pașii practici de pornire, începe cu Primii pași.
Cunoaște cele patru piese
Orice instalare e-bon este formată din aceleași patru piese, care comunică între ele:
Casa de marcat sau browserul
Cloud-ul e-bon
api.e-bon.ro și Portalul de la app.e-bon.ro. Primește cererile tale, păstrează bonurile și rapoartele și rutează comenzile către dispozitivul potrivit.Aplicația mobilă e-bon
Imprimantă fiscală (AMEF)
O reprezentare simplificată a felului în care se leagă:
Casa de marcat ─── HTTPS ──▶ Cloud-ul e-bon
sau browserul │
│ canal în timp real
▼
Aplicația mobilă e-bon
│
│ Bluetooth / USB / Serial / TCP
▼
Imprimantă fiscală (AMEF)
│
│ raport Z de final de zi
▼
ANAF
Urmărește un bon de la vânzare până la ANAF
Când casierul sau casa ta de marcat emite un bon, acesta este drumul pe care îl parcurge:
Casa de marcat trimite cererea
Casa de marcat trimite o cerere HTTPS semnată către API-ul e-bon, cu produsele, prețurile, modalitatea de plată și dispozitivul pe care trebuie să se tipărească.
Cloud-ul acceptă și salvează comanda
e-bon validează cererea, o salvează ca o comandă în așteptare și răspunde imediat casei de marcat cu 201 Created, ca să nu blocheze fluxul de la casă.
Cloud-ul rutează comanda către dispozitivul potrivit
Comanda este trimisă către aplicația mobilă e-bon de pe telefonul sau tableta de lângă imprimanta fiscală pe care ai țintit-o.
Aplicația mobilă pilotează imprimanta
Aplicația alege driverul corect pentru modelul tău de imprimantă, codifică cererea și o trimite prin Bluetooth, USB, Serial sau TCP. Imprimanta tipărește bonul fiscal și actualizează memoria fiscală.
Rezultatul revine în cloud
Aplicația trimite confirmarea imprimantei înapoi la e-bon. Bonul este acum permanent în contul tău, vizibil în Portal și disponibil prin API.
Webhook-urile anunță celelalte sisteme
Dacă ai webhook-uri configurate, e-bon livrează un eveniment receipt.created către fiecare abonat care l-a cerut.
Raportul Z de final de zi pleacă spre ANAF
La finalul fiecărei zile de lucru, aplicația mobilă declanșează raportul Z pe imprimantă, iar totalurile sunt raportate către ANAF la termenul cerut de lege.
Cum ajung actualizările în timp real la dispozitive
Cloud-ul comunică cu aplicația mobilă printr-o conexiune persistentă WebSocket. Cât timp aplicația este online, comenzile și confirmările circulă instant în ambele sensuri, iar Portalul se actualizează fără sondaj.
Când conexiunea WebSocket nu este activă — de exemplu, dispozitivul Android este în repaus, are rețea instabilă sau este pus pe fundal — e-bon recurge la o notificare push (FCM) care trezește aplicația. Aplicația se reconectează, drenează comenzile rămase în coadă și raportează rezultatul.
Cum ajung webhook-urile la celelalte sisteme
Webhook-urile sunt modul prin care împingi evenimentele e-bon în propriile tale sisteme — programul de contabilitate, platforma de facturare, dashboard-ul propriu, sistemul de alertare — fără să interoghezi API-ul nostru.
Te abonezi la tipuri de evenimente
În Portal, înregistrezi un URL al tău și alegi ce tipuri de evenimente te interesează (de exemplu, receipt.created, report.z.created, device.alert).
e-bon semnează și trimite fiecare eveniment
Când se întâmplă ceva, e-bon construiește plicul evenimentului, îl semnează cu cheia ta secretă folosind HMAC SHA-256 și îl trimite prin POST către URL-ul tău, cu un timeout de 10 secunde.
Livrările eșuate sunt reîncercate cu backoff
Dacă endpoint-ul tău răspunde non-2xx, expiră sau este inaccesibil, e-bon reîncearcă cu backoff exponențial:
Endpoint-urile care eșuează constant sunt dezactivate automat
Dacă același webhook eșuează de 20 de ori la rând, e-bon îl dezactivează automat și te anunță. Îl poți reactiva din Portal după ce ai reparat capătul receptor.
Unde mergi mai departe
client.webhooks
Referință pentru WebhooksResource — gestionează abonamentele webhook, rotește secretele de semnare, declanșează livrări de test și inspectează istoricul livrărilor, oglindind /api/v1/org/webhooks.
Alerte pentru dispozitive
Înțelege cele cinci alerte pe care e-bon le ridică pentru AMEF-urile tale — hârtie pe terminate, capac deschis, memorie fiscală aproape plină, raport Z întârziat și dispozitiv deconectat — unde apar în Portal și cum le citești din API.