Documentație Webhook eFactura

Acest webhook oferă notificări în timp real pentru diverse evenimente din sistemul eFactura SPV ANAF, procesate prin intermediul aplicației InsideApp. Sistemul webhook eFactura este disponibil EXCLUSIV pentru clienții de tip Reseller.

Sistemul de Reseller - Integrare Completă

Sistemul de Reseller vă permite implementarea întregului proces de facturare și arhiva SPV direct în aplicația dumneavoastră, indiferent de limbajul de programare utilizat.

Acces complet la Arhiva SPV

Accesați toate facturile din sistemul SPV ANAF, nu doar cele din ultimele 60 de zile, oferind o vizibilitate completă asupra istoricului de facturare.

Management dinamic al firmelor

Creați și adăugați mai multe firme în contul de reseller într-un mod dinamic, fără a depinde de interfața InsideApp. Toate acțiunile se realizează prin API InsideApp.

Compatibilitate universală

Integrarea funcționează cu orice limbaj de programare, oferind flexibilitate maximă în dezvoltarea soluțiilor personalizate.

Pentru detalii complete despre API: doc.iapp.ro

Important

Toate request-urile webhook sunt trimise prin metoda POST cu Content-Type: application/json

Obligatoriu - Format Răspuns JSON

Pentru ca sistemul InsideApp să poată procesa corect notificările, endpoint-ul webhook declarat TREBUIE să returneze EXCLUSIV răspunsuri în format JSON. Orice alt format de răspuns (HTML, text simplu, XML etc.) va genera erori în procesarea automată și nu va putea fi interpretat de sistemul nostru.

Configurarea sistemului Webhook

Pentru a putea primi notificări webhook, este necesar să configurați URL-ul de destinație prin API-ul InsideApp. Această configurare se realizează pentru fiecare firmă din contul de reseller.

Verificarea setărilor curente

Pentru a vedea configurația actuală a webhook-urilor pentru o firmă:

POST /e-factura/setari-view

Acest endpoint vă permite să vizualizați toate setările curente ale firmei, inclusiv URL-ul webhook configurat.

Configurarea URL-ului webhook

Pentru a activa, modifica sau dezactiva webhook-urile:

POST /e-factura/setari-update

Folosiți câmpul webhook_url pentru a configura destinația notificărilor.

Reguli pentru webhook_url

Activare: Setați un URL valid format https://example.ro/...
Dezactivare: Setați câmpul ca empty pentru a opri notificările
Format obligatoriu: URL-ul trebuie să înceapă cu https://
Același URL: Poate fi folosit pentru toate firmele din contul reseller

Notificări în timp real - Nu retroactiv

Important: Webhook-urile se trimit doar din momentul activării și pe perioada cât este setat un URL valid. Nu se trimit notificări pentru evenimente care au avut loc înainte de activare.

Configurare per firmă

Pentru fiecare firmă din contul de reseller este necesar să fie activat accesul webhook dacă se doresc notificări. Fiecare firmă poate avea propriul URL sau se poate folosi același URL pentru toate.

Identificarea firmei

Request-ul de webhook trimite id_firma în payload-ul JSON, permițând identificarea exactă a firmei pentru care s-a generat notificarea, chiar dacă folosiți același URL pentru multiple firme.

Scenarii de răspuns disponibile:

Reîmprospătare Token - Succes

Acest webhook este trimis când un token a fost reîmprospătat cu succes.

Structura răspunsului JSON

{
    "type": "renew",
    "status": "success",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Token nou generat automat",
    "expires_in": 3600,
    "last_day": "2025-02-08 15:30:45",
    "response_time": "2025-02-08 14:30:45"
}

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("renew")
`status`	string	Statusul operației ("success")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv al operației
`expires_in`	integer	Durata de viață a token-ului în secunde
`last_day`	datetime	Data și ora expirării token-ului
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru monitorizare reîmprospătare

Token-ul a fost reîmprospătat cu succes automat. Opțional, poți folosi API-ul InsideApp pentru monitorizare:

Verifică toate încercările de autorizare (opțional)

Pentru a vedea toate încercările de autorizare/reînnoire și valabilitatea noii perioade:

POST /e-factura/autorizare-lista

Acest endpoint îți oferă o listă completă cu toate încercările de autorizare și reînnoire, inclusiv valabilitatea pentru noua perioadă reînnoită.

Funcție opțională pentru monitoring și audit
Vezi istoricul complet al autorizărilor
Verifică valabilitatea noii perioade reînnoite
Util pentru raportare și tracking

Workflow pentru reîmprospătare cu succes

Primești webhook cu reînnoire reușită

✅ Token reînnoit automat - nu sunt acțiuni necesare

Opțional: verifică cu /autorizare-lista

Notă: Token-ul este deja reînnoit cu succes. Verificarea listei de autorizări este opțională pentru audit și monitorizare.

Reîmprospătare Token - Eroare

Acest webhook este trimis când reîmprospătarea unui token a eșuat.

Structura răspunsului JSON

{
    "type": "renew",
    "status": "error",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Eroare la reimprospatarea token-ului! - Error: invalid_grant - Description: The provided authorization grant is invalid",
    "error": "invalid_grant",
    "error_description": "The provided authorization grant is invalid",
    "response_time": "2025-02-08 14:30:45"
}

Acțiune necesară - Reînnoire manuală: Când primiți această notificare, este necesară reînnoirea manuală a autorizării SPV. Utilizați API-ul pentru a genera un nou link de autorizare și trimiteți-l clientului pentru completarea procesului.

Motive posibile pentru care reînnoirea automată nu a funcționat:

• Semnătura fizică a clientului a expirat - certificatul digital utilizat pentru autentificare a ajuns la expirare

• Semnătura nu a putut fi reînnoită automat la ANAF - sistemul ANAF a întâmpinat probleme în procesul de reînnoire automată

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("renew")
`status`	string	Statusul operației ("error")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv al erorii
`error`	string	Codul de eroare returnat de server
`error_description`	string	Descrierea detaliată a erorii
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru gestionarea erorii de reînnoire

În cazul în care reînnoirea automată a eșuat, trebuie realizată manual autorizarea prin API-ul InsideApp:

Verifică toate încercările de autorizare

Folosește endpoint-ul pentru a vedea toate încercările de autorizare și reînnoire:

POST /e-factura/autorizare-lista

Acest endpoint îți oferă o listă completă cu toate încercările de autorizare și reînnoire, permițându-ți să analizezi istoricul și să identifici problemele.

Generează nou link de autorizare

Pentru a reînnoi manual autorizarea SPV:

POST /e-factura/autorizare

Acest endpoint va genera un nou link de autorizare care trebuie trimis utilizatorului pentru a reînnoi manual autorizarea SPV.

Se generează un link unic de autorizare
Link-ul trebuie trimis utilizatorului final
Utilizatorul va completa procesul de autorizare SPV
După completare, token-ul va fi reînnoit automat

Workflow pentru eroarea de reînnoire

Primești webhook cu eroare reînnoire

Apelezi /autorizare-lista pentru istoric

Generezi nou link cu /autorizare

Trimiți link-ul către utilizator

Important: Reînnoirea manuală necesită intervenția utilizatorului final pentru completarea procesului de autorizare SPV prin link-ul generat.

Trimitere Automată B2B - Succes

Notificare când facturile B2B au fost trimise automat în sistemul RO e-Factura.

Structura răspunsului JSON

{
    "type": "notify_send_b2b",
    "status": "success",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Facturile (INV-001, INV-002, INV-003) au fost trimise automat în sistemul RO e-Factura.",
    "response_time": "2025-02-08 14:30:45"
}

Notă: Mesajul se adaptează automat în funcție de numărul de facturi trimise:
• Pentru o singură factură: "Factura (INV-001) a fost trimisă automat..."
• Pentru mai multe facturi: "Facturile (INV-001, INV-002) au fost trimise automat..."

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("notify_send_b2b")
`status`	string	Statusul operației ("success")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv cu lista facturilor trimise
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru confirmări Auto Send B2B

Facturile B2B au fost trimise automat cu succes. Opțional, poți folosi API-ul InsideApp pentru a vizualiza confirmările:

Vizualizează confirmarea de încărcare (opțional)

Pentru a vedea confirmarea de încărcare și indexul pentru facturile B2B trimise:

POST /e-factura/upload-status

Acest endpoint îți oferă confirmarea încărcării și indexul de încărcare/descărcare pentru facturile B2B trimise automat.

Funcție opțională pentru monitoring
Confirmă că factura a fost procesată cu succes
Oferă index de încărcare și descărcare
Util pentru audit și tracking

Workflow pentru Auto Send B2B

Primești webhook B2B trimis cu succes

✅ Factura este deja în sistem - nu sunt acțiuni necesare

Opțional: verifică cu /upload-status

Notă: Facturile B2B sunt deja trimise cu succes. Verificarea statusului este opțională pentru audit și monitoring.

Trimitere Automată B2C - Succes

Notificare când facturile B2C au fost trimise automat în sistemul RO e-Factura.

Structura răspunsului JSON

{
    "type": "notify_send_b2c",
    "status": "success",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Factura (INV-B2C-001) a fost trimisă automat în sistemul RO e-Factura.",
    "response_time": "2025-02-08 14:30:45"
}

Notă: Similar cu B2B, mesajul se adaptează în funcție de numărul de facturi trimise.

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("notify_send_b2c")
`status`	string	Statusul operației ("success")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv cu factura trimisă B2C
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru confirmări Auto Send B2C

Facturile B2C au fost trimise automat cu succes. Opțional, poți folosi API-ul InsideApp pentru a vizualiza confirmările:

Vizualizează confirmarea de încărcare (opțional)

Pentru a vedea confirmarea de încărcare și indexul pentru facturile B2C trimise:

POST /e-factura/upload-status

Acest endpoint îți oferă confirmarea încărcării și indexul de încărcare/descărcare pentru facturile B2C trimise automat.

Funcție opțională pentru monitoring
Confirmă că factura a fost procesată cu succes
Oferă index de încărcare și descărcare
Util pentru audit și tracking

Workflow pentru Auto Send B2C

Primești webhook B2C trimis cu succes

✅ Factura este deja în sistem - nu sunt acțiuni necesare

Opțional: verifică cu /upload-status

Notă: Facturile B2C sunt deja trimise cu succes. Verificarea statusului este opțională pentru audit și monitoring.

Notificare Furnizori

Notificare când ați primit una sau mai multe facturi în ANAF SPV de la furnizori.

Structura răspunsului JSON

{
    "type": "notify_furnizori",
    "status": "success",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Ai primit una sau mai multe facturi în ANAF SPV.",
    "response_time": "2025-02-08 14:30:45"
}

Utilizare: Această notificare vă permite să știți imediat când aveți facturi noi de la furnizori în sistemul ANAF SPV, putând astfel să le procesați rapid.

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("notify_furnizori")
`status`	string	Statusul operației ("success")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul de notificare despre facturile primite
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru gestionarea facturilor de la furnizori

Dacă folosești API-ul InsideApp, poți automatiza gestionarea facturilor de la furnizori prin următoarele endpoint-uri:

Vezi lista tuturor facturilor primite

Folosește endpoint-ul pentru a obține lista completă cu toate facturile de la furnizori:

POST /e-factura/furnizori

Acest endpoint îți oferă acces la toate facturile primite de la furnizori, cu posibilitatea de filtrare și sortare după diverse criterii.

Vizualizare detalii pe factură individuală

Pentru a vedea detaliile complete ale unei facturi specifice:

POST /e-factura/view-furnizori

Acest endpoint îți permite să accesezi toate detaliile unei facturi individuale, inclusiv informațiile complete despre furnizor, produse și servicii.

Descarcă factura (opțional)

Pentru a descărca documentul original al facturii:

POST /e-factura/descarca-furnizori

Acest endpoint îți permite să descarci documentul original al facturii în format PDF sau XML, pentru arhivare sau procesare offline.

Funcție opțională pentru arhivare locală
Suportă formatele PDF și XML
Ideal pentru backup și conformitate

Workflow recomandat pentru facturile de la furnizori

Primești webhook notificare furnizori

Apelezi /furnizori pentru listă completă

Folosești /view-furnizori pentru detalii

Opțional: /descarca-furnizori pentru PDF

Timeout Factură - Eroare

Notificare când au trecut 36 de ore fără răspuns la o factură trimisă în sistemul RO e-Factura.

Structura răspunsului JSON

{
    "type": "notify_send_timeout",
    "status": "error",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Au trecut 36 de ore fără răspuns la factura trimisă. Te rugăm să reîncerci trimiterea.",
    "serie": "INV",
    "numar": "001234",
    "response_time": "2025-02-08 14:30:45"
}

Important: Această notificare este trimisă automat după 36 de ore de la trimiterea unei facturi dacă nu s-a primit confirmare de la ANAF. Este recomandat să reîncercați trimiterea facturii.

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("notify_send_timeout")
`status`	string	Statusul operației ("error")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv despre timeout-ul facturii
`serie`	string	Seria facturii pentru care s-a depășit timeout-ul
`numar`	string	Numărul facturii pentru care s-a depășit timeout-ul
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru gestionarea timeout-ului

Dacă folosești API-ul InsideApp, poți automatiza gestionarea timeout-urilor prin următoarele endpoint-uri:

Verifică statusul și detaliile erorii

Folosește endpoint-ul pentru a obține informații detaliate despre timeout-ul facturii:

POST /e-factura/upload-status

Acest endpoint îți oferă informații complete despre statusul facturii și motivul timeout-ului, permițându-ți să afișezi aceste informații în interfața aplicației tale.

Retrimite factura

După verificarea statusului, retrimite factura pentru a relua procesul:

POST /e-factura/trimite-factura-spv

Acest endpoint îți permite să retrimiți factura în sistemul ANAF SPV, reîncepând procesul de validare și procesare.

Workflow recomandat pentru timeout

Primești webhook cu timeout

Apelezi /upload-status pentru verificare

Retrimiți cu /trimite-factura-spv

Eroare Factură

Notificare când s-a primit un mesaj de eroare de la ANAF pentru o factură trimisă.

Structura răspunsului JSON

{
    "type": "notify_send_error",
    "status": "error",
    "id_firma": "69fi378428iru3423e243edawdw",
    "message": "Ai primit mesaj de eroare la factura trimisă (INV 001234). Te rugăm să verifici mesajele pentru mai multe detalii.",
    "serie": "INV",
    "numar": "001234",
    "response_time": "2025-02-08 14:30:45"
}

Acțiune necesară: Când primiți această notificare, verificați mesajele din contul InsideApp pentru detaliile complete ale erorii și corectați factura înainte de a o retrimite.

Descrierea câmpurilor

Câmp	Tip	Descriere
`type`	string	Tipul evenimentului ("notify_send_error")
`status`	string	Statusul operației ("error")
`id_firma`	string	ID-ul firmei encodat
`message`	string	Mesajul descriptiv despre eroarea facturii
`serie`	string	Seria facturii care a generat eroarea
`numar`	string	Numărul facturii care a generat eroarea
`response_time`	datetime	Data și ora când s-a generat notificarea

Integrare API pentru gestionarea erorilor

Dacă folosești API-ul InsideApp, poți automatiza gestionarea erorilor prin următoarele endpoint-uri:

Verifică statusul și detaliile erorii

Folosește endpoint-ul pentru a obține informații detaliate despre eroarea primită:

POST /e-factura/upload-status

Acest endpoint îți oferă informații complete despre statusul facturii și detaliile erorii, permițându-ți să afișezi aceste informații în interfața aplicației tale.

Corectează factura

Pe baza informațiilor primite, îndrumă utilizatorul să corecteze erorile identificate în factură.

Verifică câmpurile obligatorii
Validează formatele datelor
Corectează informațiile despre cumpărător/furnizor

Retrimite factura corectată

După corectarea erorilor, retrimite factura folosind:

POST /e-factura/trimite-factura-spv

Acest endpoint îți permite să retrimiți factura corectată în sistemul ANAF SPV, asigurându-te că toate erorile au fost rezolvate.

Workflow recomandat

Primești webhook cu eroare

Apelezi /upload-status pentru detalii

Corectezi factura pe baza erorilor

Retrimiți cu /trimite-factura-spv

Ghid de implementare

Configurarea endpoint-ului

Configurați un endpoint care să accepte request-uri POST și să proceseze payload-ul JSON.

// Exemplu PHP
$input = file_get_contents('php://input');
$data = json_decode($input, true);

// Procesați datele în funcție de tip
switch($data['type']) {
    case 'renew':
        // Procesați reîmprospătarea token-ului
        break;
    case 'notify_send_b2b':
        // Procesați trimiterea B2B
        break;
    // ... alte cazuri
}

Validarea request-urilor

Verificați că request-urile provin de la InsideApp prin validarea semnăturii sau IP-ului.

// Verificați content-type
if ($_SERVER['CONTENT_TYPE'] !== 'application/json') {
    http_response_code(400);
    exit('Invalid content type');
}

// Validați structura JSON
if (!isset($data['type']) || !isset($data['status'])) {
    http_response_code(400);
    exit('Invalid payload');
}

Răspunsul webhook-ului

Returnați un răspuns HTTP 200 pentru a confirma primirea cu succes a notificării.

// Procesați datele
// ...

// Returnați confirmarea
http_response_code(200);
echo json_encode([
    'status' => 'received',
    'timestamp' => date('Y-m-d H:i:s')
]);

Bune practici

Timeout: Răspundeți în maximum 10 de secunde
Idempotență: Gestionați posibilitatea de a primi același webhook de mai multe ori
Logging: Înregistrați toate webhook-urile primite pentru debugging
Securitate: Validați întotdeauna sursa request-urilor
Error handling: Implementați gestionarea erorilor pentru stabilitate

Monitorizare și management Webhooks

Accesați toate instrumentele pentru managementul webhook-urilor în panoul de control InsideApp

Monitorizare în timp real

Vizualizați toate request-urile webhook trimise în timp real

Istoricul complet al webhook-urilor
Statusuri de livrare (success/error)
Timpul de răspuns al endpoint-urilor
Detalii complete JSON pentru fiecare request

Simulare Webhooks pentru testare

Testați implementarea webhook-urilor cu date fictive

Creați request-uri webhook cu date simulate
Testați toate tipurile de scenarii disponibile
Verificați compatibilitatea endpoint-urilor
Debug și validare implementare

Retrimite Webhooks

Retrimiți webhook-urile eșuate sau pentru testare suplimentară

Retrimiteți orice webhook din istoric
Util pentru debug-ul erorilor
Testare după modificări în endpoint
Urmărirea statusului de retrimiere

Cum să accesați:

Conectați-vă la my.iapp.ro → Reseller → eFactura Webhooks

Cerințe de acces:

Cont InsideApp de tip Reseller activ și configurat

Contact și suport

Ai întrebări despre webhook-urile InsideApp? Vrei să devii reseller sau ai nevoie de ajutor?

Vrei să devii reseller InsideApp?

Dorești să activezi opțiunile de webhook pentru aplicația ta și să oferi servicii eFactura clienților tăi?

Ești deja reseller dar ai nevoie de ajutor?

Echipa noastră de suport este disponibilă pentru a te ajuta cu implementarea și configurarea webhook-urilor.

Contactează-ne:

Pagina oficială de contact