Integrare API RO e-Factura: ghid tehnic pentru dezvoltatori (OAuth, XML, 2026)

API-ul RO e-Factura este interfata REST expusa de ANAF prin care o aplicatie software poate trimite, valida si descarca facturi electronice fara interventie manuala in SPV. Integrarea se bazeaza pe autentificare OAuth 2.0 cu certificat digital calificat si pe schimbul de fisiere XML in format UBL, validate automat de sistemul ANAF inainte de a fi considerate transmise cu succes.

Pentru orice dezvoltator care lucreaza la un ERP, un sistem de facturare sau un modul de integrare pentru un client, intelegerea corecta a fluxului OAuth si a endpoint-urilor disponibile reduce semnificativ timpul de implementare si numarul de erori intalnite in productie.

Acest ghid acopera pasii tehnici principali: inregistrarea aplicatiei OAuth, fluxul de autorizare, endpoint-urile API pentru upload/validare/descarcare si cele mai frecvente erori intalnite de dezvoltatori la prima integrare.

Ce este API-ul RO e-Factura si cui i se adreseaza

API-ul RO e-Factura este un serviciu web REST pus la dispozitie de ANAF, care permite transmiterea programatica a facturilor electronice catre Sistemul national privind factura electronica (RO e-Factura), fara a folosi interfata web a SPV pas cu pas.

Este destinat in principal:

dezvoltatorilor care construiesc sau intretin ERP-uri si aplicatii de facturare;
furnizorilor de software financiar-contabil care ofera integrare directa cu SPV;
echipelor tehnice interne ale firmelor cu volum mare de facturi, care nu isi permit incarcare manuala.

Pentru firmele care emit un numar mic de facturi, incarcarea manuala din interfata SPV ramane o optiune valabila; API-ul devine relevant abia atunci cand volumul sau frecventa facturilor justifica automatizarea.

Ce ai nevoie inainte sa incepi integrarea

Inainte de a scrie prima linie de cod pentru integrare, ai nevoie de cateva elemente confirmate si functionale:

un certificat digital calificat, valabil, asociat firmei sau persoanei care are drept in SPV;
acces activ in SPV pentru CUI-ul firmei pentru care se face integrarea;
o aplicatie OAuth inregistrata pe portalul ANAF, cu client_id si client_secret proprii;
un callback URL (redirect URI) valid, gazduit pe un domeniu pe care il controlezi;
acces la mediul de test ANAF, pentru validarea fluxului inainte de a trece pe productie.

Inregistrarea aplicatiei OAuth se face din portalul ANAF, sectiunea dedicata inregistrarii aplicatiilor pentru API-uri (accesibila din contul de servicii online ANAF). Completezi numele aplicatiei si callback URL-ul, iar sistemul iti genereaza client_id si client_secret, necesare la fiecare pas ulterior de autorizare.

Cum functioneaza autentificarea OAuth 2.0 in API-ul ANAF

Autentificarea foloseste fluxul standard OAuth 2.0 de tip authorization code, adaptat la specificul certificatului digital folosit de SPV:

Aplicatia redirectioneaza utilizatorul (sau procesul automat, daca certificatul e instalat pe server) catre URL-ul de autorizare ANAF, cu client_id si redirect_uri in parametri.
Utilizatorul se autentifica cu certificatul digital calificat asociat contului SPV.
ANAF redirectioneaza catre callback URL impreuna cu un cod de autorizare temporar.
Aplicatia schimba acest cod, prin cerere server-to-server, pentru un access_token si un refresh_token, folosind client_id si client_secret.
access_token-ul se trimite in header-ul Authorization: Bearer la fiecare cerere catre endpoint-urile API.

Un aspect important pentru dezvoltatori: access_token-ul are o durata de viata limitata, iar refresh_token-ul permite obtinerea unui nou token fara reluarea intregului flux de autorizare cu certificat. Duratele exacte de valabilitate pot fi ajustate de ANAF in timp; verifica mereu documentatia oficiala OAuth publicata pe anaf.ro inainte de a hardcoda aceste valori in aplicatie.

Endpoint-uri principale ale API-ului e-Factura

API-ul expune un set de endpoint-uri REST distincte pentru fiecare etapa a ciclului de viata al unei facturi electronice. Structura de baza este similara intre mediul de test si cel de productie, diferind doar domeniul/prefixul de mediu folosit in URL.

Endpoint (functie)	Rol	Observatii tehnice
`/upload`	Trimite o factura XML spre validare si inregistrare in SPV	Necesita `cif` ca parametru si corpul cererii in format XML
`/stareMesaj`	Verifica statusul procesarii unui mesaj trimis anterior	Se apeleaza cu `id_incarcare` primit la upload
`/descarcare`	Descarca arhiva (ZIP) cu factura si raspunsul ANAF	Contine XML-ul original, semnatura si eventualele erori de validare
`/listaMesajeFactura`	Listeaza mesajele/facturile disponibile pentru un CIF, intr-un interval	Util pentru sincronizare periodica si paginare
`/validare/{tip}`	Valideaza structura XML fara a o trimite oficial	Recomandat inainte de upload, in etapa de testare
`/transformare/{tip}`	Converteste XML-ul facturii intr-un format lizibil (PDF)	Util pentru afisarea facturii catre utilizatorul final

Toate cererile catre aceste endpoint-uri necesita header-ul de autorizare cu access_token-ul valid, obtinut prin fluxul OAuth descris mai sus. Numele exact al domeniilor pentru mediul de test si cel de productie se pot schimba in timp; confirma-le mereu din documentatia tehnica oficiala inainte de a le folosi intr-un sistem live.

Cum trimiti si validezi o factura XML pas cu pas

Un flux tipic de trimitere a unei facturi prin API arata astfel:

Generezi factura in format XML UBL 2.1, conform specificatiei CIUS-RO folosite de sistemul RO e-Factura.
Ruleaza intern o validare XSD/schematron (sau apelezi endpoint-ul de validare) inainte de trimitere, pentru a prinde erorile de structura devreme.
Trimiti XML-ul catre endpoint-ul de upload, folosind access_token-ul curent si CIF-ul corect al emitentului.
Retii id_incarcare-ul primit ca raspuns si il folosesti pentru a verifica periodic statusul procesarii.
Cand statusul indica finalizare, descarci arhiva de raspuns pentru a confirma acceptarea si a pastra dovada in sistemul propriu.
Salveaza local atat XML-ul trimis, cat si raspunsul ANAF, pentru audit si eventuale contestatii.

Checklist minim inainte de a trece integrarea pe productie:

flux OAuth testat integral in mediul de test ANAF, inclusiv reimprospatarea tokenului;
validare XML automata inainte de fiecare upload, nu doar la prima factura;
gestionare explicita a starilor "in procesare", "validat cu erori" si "acceptat";
logging al fiecarui id_incarcare si al raspunsului asociat;
alertare interna daca un upload ramane blocat in status "in procesare" un timp neobisnuit de lung.

Erori frecvente in integrarea API si cum le previi

Majoritatea problemelor raportate de dezvoltatori la integrarea API-ului e-Factura se incadreaza in cateva categorii recurente:

Eroare 401 (Unauthorized) — apare cel mai des cand access_token-ul a expirat sau nu a fost reimprospatat corect prin refresh_token. Solutie: implementeaza reimprospatarea automata a tokenului inainte de expirare, nu doar la primirea erorii.
XML invalid structural — cauzat de campuri obligatorii lipsa, namespace-uri incorecte sau encoding gresit al fisierului. Solutie: ruleaza validarea XSD/schematron local, inainte de trimitere, nu doar dupa raspunsul ANAF.
Erori de validare de tip regula de business (schematron) — factura este structural corecta, dar incalca o regula CIUS-RO (de exemplu corelatii intre totaluri si linii de factura). Solutie: pastreaza actualizat setul de reguli de validare folosit intern, in pas cu versiunile publicate de ANAF.
Confuzie intre mediul de test si cel de productie — facturi trimise din greseala pe mediul gresit, sau credentiale OAuth generate pentru un mediu si folosite in celalalt. Solutie: separa explicit configuratia (client_id, client_secret, URL-uri) pe medii, in variabile de mediu distincte.
Certificat digital expirat sau revocat — blocheaza intregul flux OAuth, chiar daca aplicatia in sine este configurata corect. Solutie: monitorizeaza intern data de expirare a certificatului folosit pentru autorizare.

API direct vs. solutie software cu integrare deja facuta

Nu orice firma trebuie sa construiasca propria integrare cu API-ul e-Factura. Alegerea depinde de volumul de facturi, resursele tehnice disponibile si cat de personalizat trebuie sa fie fluxul.

Criteriu	Integrare API proprie	Software cu integrare gata facuta
Efort tehnic initial	Ridicat (OAuth, validare XML, tratare erori)	Redus (configurare, nu dezvoltare)
Control asupra fluxului	Total, inclusiv reguli custom de business	Limitat la ce ofera furnizorul
Mentenanta pe termen lung	In sarcina echipei proprii, la fiecare schimbare ANAF	In sarcina furnizorului de software
Recomandat pentru	Volume mari, ERP-uri proprii, cerinte specifice	Firme fara echipa tehnica dedicata sau volum mic-mediu

Daca ai deja un sistem intern (ERP, platforma de facturare proprie) si volum suficient de mare cat sa justifice mentenanta continua, integrarea API directa are sens pe termen lung. Daca obiectivul este doar conformare rapida, o solutie software existenta, cu integrare deja validata de ANAF, reduce riscul si timpul de implementare.

Bune practici de securitate si mentenanta

Nu stoca client_secret sau refresh_token in cod sursa; foloseste variabile de mediu sau un vault dedicat.
Limiteaza accesul la certificatul digital folosit pentru autorizare doar la procesele care chiar au nevoie de el.
Pastreaza loguri separate pentru fiecare upload (XML trimis, raspuns ANAF, timestamp), utile atat pentru debugging, cat si pentru audit.
Verifica periodic anunturile ANAF privind modificari de schema XML sau reguli de validare, deoarece specificatia CIUS-RO se actualizeaza in timp.
Testeaza orice modificare a integrarii in mediul de test ANAF inainte de a o pune in productie.

Intrebari frecvente despre integrarea API RO e-Factura

Ce este API-ul RO e-Factura, pe scurt?

Este interfata REST oficiala prin care o aplicatie poate trimite, valida si descarca facturi electronice direct in Sistemul national privind factura electronica, fara a folosi manual interfata web SPV.

Am nevoie de certificat digital pentru a folosi API-ul?

Da. Autorizarea OAuth se bazeaza pe certificatul digital calificat asociat contului SPV al firmei; fara acest certificat, fluxul de autorizare nu poate fi finalizat.

Ce format de fisier accepta API-ul pentru facturi?

Facturile se transmit in format XML, conform specificatiei UBL 2.1 folosite de sistemul RO e-Factura (profilul CIUS-RO). Alte formate nu sunt acceptate direct la endpoint-ul de upload.

De ce primesc eroare 401 Unauthorized la trimiterea facturii?

Cel mai frecvent motiv este un access_token expirat sau reimprospatat incorect. Verifica implementarea fluxului de refresh_token si asigura-te ca tokenul folosit corespunde mediului (test sau productie) catre care faci cererea.

Pot testa integrarea inainte de a o folosi cu facturi reale?

Da, ANAF pune la dispozitie un mediu de test separat de mediul de productie, recomandat pentru validarea completa a fluxului OAuth si a trimiterii XML inainte de a trece la facturi reale.

Trebuie sa construiesc propria integrare API sau pot folosi un software existent?

Depinde de volumul de facturi si de resursele tehnice disponibile. Pentru volume mari si cerinte specifice, integrarea proprie ofera control total; pentru conformare rapida, un software cu integrare deja facuta reduce timpul si riscul de implementare.

Concluzie

Integrarea cu API-ul RO e-Factura presupune un flux OAuth 2.0 bazat pe certificat digital, endpoint-uri dedicate pentru upload, validare si descarcare, si o disciplina tehnica clara privind tratarea erorilor si separarea mediilor de test si productie. Cu un flux testat corect si validare XML facuta inainte de trimitere, majoritatea problemelor frecvente (erori 401, XML invalid) pot fi evitate din start.

Daca ai nevoie de ajutor pentru integrarea API-ului RO e-Factura in sistemul tau software, sau vrei o solutie personalizata compatibila cu SPV, echipa HappyWeb poate prelua implementarea tehnica. Contacteaza-ne pentru a discuta cerintele proiectului tau.

Surse

Imagine generata cu AI, folosita in scop ilustrativ.