Webservice ANAF — API-urile SPV / e-Factura

Webservice-urile ANAF sunt API-urile prin care o aplicație comunică direct cu sistemele ANAF — SPV și e-Factura — fără interfața web. Cu ele poți lista mesajele primite, descărca fișierul unei facturi și îl poți transforma în PDF oficial, totul automat.

Pe scurt, un webservice este o „ușă de serviciu” a ANAF prin care intră programele, nu oamenii. În loc să te loghezi în SPV și să apeși butoane, o aplicație trimite cereri standardizate către aceste API-uri și primește înapoi liste de mesaje, fișiere XML sau PDF-uri. Accesul nu este liber: orice apel trebuie autorizat prin OAuth cu certificat digital calificat. Așa funcționează, în culise, orice aplicație care preia automat facturile din e-Factura — inclusiv eFacturaSPV.

Ce poți face cu webservice-urile e-Factura

Pentru facturile primite, fluxul se sprijină pe câteva apeluri esențiale, folosite de regulă unul după altul:

• listaMesajeFactura — întoarce lista mesajelor din SPV pentru un CUI: facturi primite, recipise și erori, fiecare cu un ID de încărcare;
• descarcare — preia, după acel ID, arhiva ZIP care conține XML-ul facturii (originalul legal);
• transformare/FACT1 — convertește XML-ul în PDF-ul oficial, identic cu cel din interfața SPV;
• upload și stareMesaj — pentru partea de emitere: trimiți o factură și verifici dacă a fost validată sau respinsă.

Fiecare element din lista returnată este, practic, un mesaj ANAF: o factură, o recipisă de confirmare sau o eroare de validare. Aplicația parcurge lista, alege ce o interesează (de exemplu facturile primite, pe filtrul P) și descarcă fiecare fișier în parte.

Cum se face accesul: OAuth cu certificat

Webservice-urile ANAF nu se apelează cu user și parolă. Autentificarea se face prin OAuth 2.0: te identifici o singură dată cu certificatul digital calificat (de regulă tokenul SPV) pe site-ul ANAF, iar ANAF emite un token de acces (valabil 90 de zile) și unul de reînnoire (valabil 365 de zile). De atunci înainte, aplicația trimite tokenul la fiecare apel, iar ANAF știe în numele cărui CUI lucrează.

Asta înseamnă că tokenul fizic se folosește o singură dată, la autorizare. După aceea totul rulează în fundal, fără ca stick-ul USB să mai fie conectat — exact modelul „autorizezi o dată, rulează singur”. Lista CUI-urilor pentru care ai dreptul să apelezi webservice-urile vine chiar în răspunsul ANAF, nu o ghicești tu.

Cum le folosește o aplicație ca eFacturaSPV

În spatele preluării automate stă exact acest lanț de apeluri. eFacturaSPV apelează periodic listaMesajeFactura, identifică facturile primite de la furnizori, descarcă XML-ul fiecăreia cu descarcare, îl trece prin transformare/FACT1 ca să obțină PDF-ul oficial și apoi arhivează ambele fișiere în Google Drive-ul tău, organizate pe luni (foldere YYYY.MM), deduplicate. Tu nu vezi niciun apel API — vezi doar arhiva care se umple singură.

De ce contează webservice-urile pentru arhiva ta

Aici se întâlnesc API-urile ANAF cu o realitate inconfortabilă: ești obligat să păstrezi facturile 5 ani, dar ANAF le ține descărcabile din SPV doar aproximativ 60 de zile. După acest interval, webservice-ul descarcare nu mai întoarce fișierul, iar singura cale rămâne repostarea manuală din interfața SPV.

Tocmai de aceea contează ca o aplicație să apeleze webservice-urile constant și la timp. Prin preluarea automată din SPV, fiecare factură primită este descărcată și transformată în PDF oficial înainte să iasă din fereastra de 60 de zile — astfel încât arhiva ta din Drive să fie completă, nu dependentă de cât timp mai ține ANAF fișierul disponibil.

← Înapoi la dicționarul e-Factura