Stările pe care le vezi în bonuri, dispozitive și webhook-uri

Când citești un răspuns API, primești un webhook sau te uiți la un ecran din portal, vei întâlni câmpuri de stare cu un set fix de valori. Această pagină listează fiecare valoare pe care o poți întâlni, ce înseamnă în termeni de business și când o setează e-bon.

Urmărește starea unei comenzi de bon

Când trimiți un bon sau orice altă comandă fiscală către un dispozitiv, e-bon atribuie o stare comenzii și o actualizează pe măsură ce dispozitivul o preia și răspunde.

Ciclul de viață tipic:

   POST /api/v1/devices/:deviceId/commands
                  │
                  ▼
           ┌──────────┐
           │ pending  │
           └────┬─────┘
                │ pornește livrarea
                ▼
           ┌──────────┐    dispozitivul confirmă succesul    ┌────────────┐
           │   sent   │ ──────────────────────────────────▶  │ completed  │ (final)
           └────┬─────┘                                      └────────────┘
                │ dispozitivul întoarce o eroare
                ▼
           ┌──────────┐
           │  failed  │ (final)
           └──────────┘

   Așteptarea push expiră (60 s) sau supraveghetorul de siguranță preia
   o comandă rămasă în pending/sent peste 180 s:
                       ┌──────────┐
                       │ timeout  │ (final)
                       └──────────┘

Odată ce o comandă ajunge în completed, failed sau timeout, e-bon nu o mai modifică.

Unde apare:

• Răspunsurile API la GET /api/v1/commands/:id și GET /api/v1/devices/:deviceId/commands/:id, pe câmpul status.
• Plicurile de webhook command.completed, command.failed și command.timeout — vezi Evenimente de webhook.
• Coloana Dispozitive → Activitate din portal.

Pentru fluxul complet de livrare (conexiune activă plus fallback prin push), vezi Fluxul de emitere a bonului. Pentru catalogul tipurilor de comandă, vezi Tipuri de comandă.

Citește starea de conectivitate a dispozitivului

Fiecare AMEF înregistrat în e-bon poartă o stare de conectivitate care reflectă dacă cloud-ul îl poate atinge în acest moment.

Dispozitivul comută între online și offline pe toată durata de viață a înregistrării sale; nu există stare finală.

Unde apare:

• Răspunsurile API la GET /api/v1/devices și GET /api/v1/devices/:id, pe câmpul status.
• Plicurile de webhook device.online și device.offline.
• Ecusonul de stare de pe cardul dispozitivului din portal (roșu/gri).

Citește starea livrării unui webhook

Fiecare eveniment de webhook pe care e-bon îl trimite către endpoint-ul tău creează o înregistrare de livrare cu propria sa stare. Poți inspecta livrările pentru a-ți depana integrarea.

Ciclul de viață:

   dispatch
     │
     ▼
  ┌──────────┐  încercarea 1 reușește (2xx)   ┌──────────┐
  │ pending  │ ───────────────────────────▶   │ success  │ (final)
  └────┬─────┘                                └──────────┘
       │ încercarea eșuează
       ▼
  ┌──────────┐  o încercare ulterioară reușește   ┌──────────┐
  │ pending  │ ─────────────────────────────────▶ │ success  │ (final)
  │  reluări │
  └────┬─────┘
       │ încercarea 5 tot eșuează
       ▼
  ┌──────────┐
  │  failed  │ (final)
  └──────────┘

După un răspuns non-2xx livrarea rămâne pending și este reluată după programul [60 s, 5 min, 30 min, 2 h, 12 h]. Se fac maximum 5 încercări. Dacă un webhook acumulează 20 de livrări eșuate consecutiv, este dezactivat automat și un administrator trebuie să-l reactiveze din portal.

Unde apare:

• Răspunsul API la GET /api/v1/webhooks/:id/deliveries, pe câmpul status.
• Panoul Setări → Webhook-uri → livrări din portal.
• Webhook-ul părinte expune și lastDeliveryStatus (success sau failed), actualizat la fiecare rezultat final.

Pentru contractul de reluări, regula de auto-dezactivare și cum se capturează corpul răspunsului, vezi Evenimente webhook.

Citește severitatea alertelor de dispozitiv

Când un dispozitiv este într-o stare care necesită atenție (hârtie aproape terminată, capac deschis, raport Z restant etc.), e-bon atașează o severitate fiecărei alerte.

Alertele sunt calculate la momentul citirii pornind de la starea curentă a dispozitivului — nu sunt stocate. Când un dispozitiv are mai multe alerte, cea mai mare severitate câștigă culoarea ecusonului din portal (eroarea bate avertismentul).

Unde apare:

• Răspunsurile API la GET /api/v1/devices/alerts și GET /api/v1/devices/:id/alerts, pe câmpul severity al fiecărei alerte.
• Culoarea ecusonului de pe cardul dispozitivului din portal.

Pentru regulile și pragurile din spatele fiecărui tip de alertă, vezi Alerte din portal.

Urmărește starea unui raport ANAF

Rapoartele Jurnal Electronic (JE) poartă o stare de acceptare ANAF care reflectă ce s-a întâmplat după ce administratorul a depus fișierul pe ANAF SPV.

   JE generat (stare absentă sau 'pending')
                 │
                 ▼
       ┌──────────────────┐
       │     pending      │
       └────────┬─────────┘
                │ administratorul depune pe SPV, apoi face PATCH la raport:
                ├────────────▶ ┌──────────┐
                │              │ accepted │
                │              └──────────┘
                ├────────────▶ ┌──────────┐
                │              │ rejected │
                │              └──────────┘
                └────────────▶ ┌──────────┐
                               │  error   │
                               └──────────┘

Unde apare:

• Răspunsurile API la GET /api/v1/reports/je și GET /api/v1/reports/je/:id, pe câmpul anafStatus.
• Coloana Rapoarte → Stare ANAF din portal.

Pentru procesul de depunere SPV și fundalul legal, vezi Raportare ANAF.

Identifică tipurile de bon

Fiecare bon poartă un tip care indică natura sa legală. Tipul este setat la emiterea bonului și nu se mai schimbă.

Unde apare:

• Răspunsurile API pentru resursele de bon, pe câmpul Receipt.type.
• Coloana Bonuri → Tip din portal.

Identifică rolurile de utilizator

Fiecare utilizator aparține unei organizații cu unul din trei roluri. Schimbările de rol sunt aplicate direct de un administrator sau de proprietar — nu există un flux de tranziție.

Unde apare:

• Rolul apare ca un claim pe fiecare cerere autentificată și în câmpul User.role pe endpoint-urile de listare a membrilor și de utilizator curent.
• Coloana Setări → Organizație → Membri din portal.

Pentru cum fiecare rol controlează API-ul și pentru matricea RBAC completă, vezi Autentificare și autorizare.

Identifică planurile de abonament

Fiecare organizație este pe unul din trei niveluri de abonament. Planul controlează plafoanele de dispozitive, debitul API și accesul la funcționalitățile plătite.

Unde apare:

• Răspunsurile API, pe câmpul Organization.plan.
• Setări → Abonament din portal.

Impunerea nivelului este aplicată la fiecare cerere API pentru a controla funcționalitățile plătite — vezi Autentificare și autorizare.

Unde mergi mai departe

• API Comenzi — plicul de cerere și contractul de polling pentru comenzi de bon.
• Evenimente de webhook — lista completă de plicuri, inclusiv command.completed, command.failed, command.timeout, device.online și device.offline.
• Portal — Dispozitive — unde apar starea dispozitivului și severitățile de alertă în interfață.
• Portal — Alerte — regulile de derivare din spatele fiecărei alerte.
• Fluxul de emitere a bonului — ciclul complet al unei comenzi, inclusiv fallback-ul conexiune activă / push.
• Evenimente webhook — ciclul complet de livrare și contractul de reluări.
• Autentificare și autorizare — porțile pentru roluri și impunerea nivelului de abonament.
• Raportare ANAF — fluxul stării ANAF condus de administrator.
• Glosar — vocabularul fiscal românesc referit aici (storno, AMEF, raport Z etc.).
• Tipuri de comandă — catalogul per tip care folosește ciclul de viață al stării unei comenzi.