Integrare API ANAF e-Factura: ghid tehnic 2026, cu exemple de cod

Pe scurt: integrarea cu API-ul ANAF e-Factura are 5 pași: autentificare OAuth 2.0 cu certificat digital calificat, generarea facturii în XML UBL 2.1 (CIUS-RO), trimiterea prin API-ul SPV, verificarea statusului și descărcarea răspunsului semnat de ANAF. O integrare costă €2.500–€15.000 și durează de regulă 1–2 săptămâni. e-Factura e obligatorie pentru B2B din 2024 și pentru B2C din 2025. Mai jos: endpoint-urile, exemple de cod și cele 7 capcane care pică integrarea în producție, din proiectele pe care le-am livrat.

Cadru legal scurt

• OUG 120/2021 + Legea 296/2023: sistemul național RO e-Factura
• 1 iulie 2024: obligatoriu pentru tranzacții B2B în RON
• 1 ianuarie 2025: extins la B2C
• Sancțiuni: 1.000-10.000 RON per factură netransmisă

API ANAF e-Factura: endpoint-urile principale

Toate apelurile e-Factura pornesc de la https://api.anaf.ro, cu /test/ în cale pentru mediul de test și /prod/ pentru producție. Autentificarea trece prin serverul OAuth logincert.anaf.ro.

Cele 5 etape ale integrării

Etapa 1: autentificare OAuth 2.0

ANAF SPV folosește certificat digital calificat pentru autentificare API. Pașii:

1. Obțineți un certificat digital calificat (DigiSign, certSIGN, Trans Sped), €50-€150/an
2. Vă înregistrați în SPV (Spațiul Privat Virtual) cu certificatul
3. Generați un token de acces care expiră (refresh la 90 de zile)
4. Endpoint OAuth: https://logincert.anaf.ro/anaf-oauth2/v1/authorize

OAuth ANAF: cum obțineți token-ul

Înregistrați aplicația în SPV, cu un URL de callback, și primiți un client_id și un client_secret. Utilizatorul care are certificatul deschide URL-ul de autorizare, se autentifică, iar ANAF îl trimite înapoi la callback cu un cod. Aplicația dumneavoastră schimbă codul pe token-uri la endpoint-ul /token. De aici încolo, fiecare apel trimite header-ul Authorization: Bearer <token>, iar token-ul se reînnoiește automat cu refresh token-ul, înainte să expire.

Etapa 2: generare XML UBL 2.1

Factura trebuie generată în format XML conform standardului UBL 2.1 cu extensii ANAF (CIUS-RO). Structură:

• Header: număr factură, dată emitere, valută
• Supplier: CIF emitent, adresă, conturi bancare
• Customer: CUI/CNP destinatar, adresă
• Linii: produs/serviciu, cantitate, preț unitar, TVA
• Totaluri: subtotal, TVA pe fiecare cotă aplicată, total

Capcană tipică: caracterele române cu diacritice trebuie UTF-8 corect, nu ANSI. Datele în format ISO 8601 (2026-05-04), nu DD/MM/YYYY.

XML e-Factura: structura minimă (exemplu de cod)

Scheletul de mai jos arată ordinea elementelor de nivel superior. Blocurile marcate cu «…» conțin datele de identificare, adresele, TVA-ul și liniile facturii.

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">
  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:efactura.mfinante.ro:CIUS-RO:1.0.1</cbc:CustomizationID>
  <cbc:ID>FCT-2026-0001</cbc:ID>
  <cbc:IssueDate>2026-09-23</cbc:IssueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>RON</cbc:DocumentCurrencyCode>
  <cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty>…</cac:AccountingCustomerParty>
  <cac:TaxTotal>…</cac:TaxTotal>
  <cac:LegalMonetaryTotal>…</cac:LegalMonetaryTotal>
  <cac:InvoiceLine>…</cac:InvoiceLine>
</Invoice>

Etapa 3: trimitere prin API

Endpoint: POST https://api.anaf.ro/test/FCTEL/rest/upload (sandbox) sau https://api.anaf.ro/prod/FCTEL/rest/upload (producție).

Headers obligatorii: Authorization: Bearer <token>, Content-Type: application/xml.

Răspuns: index_incarcare unic per factură. Stocați-l: îl folosiți pentru verificarea statusului.

Exemplu de apel în mediul de test, cu curl:

curl -X POST "https://api.anaf.ro/test/FCTEL/rest/upload?standard=UBL&cif=12345678" -H "Authorization: Bearer $ANAF_TOKEN" -H "Content-Type: application/xml" --data-binary @factura.xml

Etapa 4: verificare status

Factura nu e procesată instant. Trece prin validări la ANAF (poate dura 1-30 de minute). Trebuie să interogați periodic statusul:

Endpoint: GET /stareMesaj?id_incarcare=<index>. Status posibile: nok (eroare validare), ok (validat), in prelucrare (în curs).

curl "https://api.anaf.ro/test/FCTEL/rest/stareMesaj?id_incarcare=<index_incarcare>" -H "Authorization: Bearer $ANAF_TOKEN"

Etapa 5: descărcare semnătură ANAF

După validare, ANAF returnează ZIP cu factura semnată digital. Trebuie stocată: e dovada legală că ați trimis-o.

SPV API: ce mai puteți face prin API

API-ul e-Factura folosește aceeași autentificare ca Spațiul Privat Virtual: certificatul calificat și drepturile pe CIF pe care le aveți deja în SPV. Pe lângă trimiterea facturilor, prin listaMesajeFactura vedeți și facturile primite de la furnizori, pe care le descărcați apoi cu descarcare. Interogarea periodică a listei (maxim 60 de zile în urmă) e modul simplu de a importa automat facturile de achiziție în contabilitate.

7 capcane care vă pică integrarea în producție

1. Token expirat fără avertisment: token-urile OAuth expiră silent. Implementați refresh automat la 80% din durata de viață.
2. Rate limiting nedocumentat: 60 de request-uri/minut per certificat. La un burst peste prag, primiți 429 fără explicație.
3. Schema XML strictă: un câmp lipsă = respingere totală, nu mesaj specific. Validați local cu schema XSD înainte să trimiteți.
4. Mentenanță programată: ANAF face mentenanță, de obicei dimineața. Implementați retry cu exponential backoff (5min, 30min, 2h, 6h).
5. Anularea facturii: nu ștergeți, ci transmiteți o factură de stornare cu referință la cea anulată. Logică separată de business.
6. Numerotarea conformă: factura trebuie să respecte numerotarea dumneavoastră secvențială. ANAF nu generează numere, dumneavoastră le furnizați.
7. Versiuni de schemă: ANAF actualizează periodic specificațiile, iar integrarea se poate rupe fără avertisment. Urmăriți anunțurile ANAF.

Stack tehnic recomandat

• Backend: Node.js sau PHP, cu librării bune pentru manipulare XML și criptografie
• Queue: BullMQ sau RabbitMQ, esențial pentru retry logic
• Storage: S3 sau local pentru ZIP-urile semnate (retention legal 5-10 ani)
• Monitoring: Sentry pentru erori, dashboard custom pentru rata de succes
• Validation: librărie XSD pentru validare locală pre-trimitere

Integrare API: e-Factura e rar singura

În proiectele reale, e-Factura e doar una dintre integrări. Același flux de facturare trebuie legat de magazinul online, de ERP, de procesatorul de plăți sau de curier, iar fiecare legătură are nevoie de aceleași lucruri: autentificare, retry, validare și monitoring. Dacă aveți de conectat mai multe sisteme, vedeți serviciul nostru de integrări API pentru ERP, CRM, plăți și magazine online. Pentru noțiunile de bază, avem ghiduri despre ce este un API REST și ce este un webhook.

Cost dezvoltare integrare

• Integrare simplă (B2C, volume mic, fără storno): €2.500 – €4.000
• Integrare standard (B2B + B2C, retry, dashboard admin): €4.000 – €7.000
• Integrare enterprise (volume mari, multi-companie, audit logs): €7.000 – €15.000

Plus mentenanță lunară €100-€500 pentru update-uri ANAF + monitoring. Vedeți și prețurile orientative pentru alte tipuri de proiecte.

Întrebări frecvente

Cât costă o integrare API ANAF e-Factura?

Între €2.500 și €15.000, după complexitate: €2.500–€4.000 pentru o integrare simplă, €4.000–€7.000 pentru B2B + B2C cu retry și dashboard, €7.000–€15.000 pentru volume mari și mai multe firme. Mentenanța costă €100–€500 pe lună.

Cât durează integrarea cu API-ul ANAF?

De regulă 1–2 săptămâni pentru o integrare cu retry logic, dashboard admin și monitoring.

Ce certificat îmi trebuie pentru API-ul ANAF?

Un certificat digital calificat (DigiSign, certSIGN, Trans Sped), care costă €50–€150 pe an și e înregistrat în SPV.

Există un mediu de test pentru e-Factura?

Da. Endpoint-urile de test au /test/ în cale, de exemplu https://api.anaf.ro/test/FCTEL/rest/upload, iar cele de producție au /prod/.

Ce fac dacă factura primește statusul nok?

Descărcați răspunsul ANAF cu endpoint-ul descarcare, citiți erorile de validare, corectați XML-ul, îl validați local cu schema XSD și îl retrimiteți.