Integrare API ANAF e-Factura — ghid tehnic 2026
Din 2024, e-Factura este obligatorie pentru facturile B2B în România; din 2025, și pentru B2C. Integrarea cu API-ul ANAF SPV este fezabilă tehnic, însă prezintă capcane operaționale frecvente. Acest ghid documentează cerințele, fluxul de implementare și erorile tipice în producție.
Cadru legal scurt
- OUG 120/2021 + Legea 296/2023 — sistem 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ă
Cele 5 etape ale integrării
Etapa 1 — Autentificare OAuth 2.0
ANAF SPV folosește certificat digital calificat pentru autentificare API. Pașii:
- Obții certificat digital calificat (DigiSign, certSIGN, Trans Sped) — €50-€150/an
- Te înregistrezi pe SPV (Serviciu Persoane Virtuale) cu certificatul
- Generezi un token de acces care expiră — refresh la 90 zile
- Endpoint OAuth:
https://logincert.anaf.ro/anaf-oauth2/v1/authorize
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 cote (5%, 9%, 19%), 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.
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ă. Stochează-l — îl folosești pentru status check.
Etapa 4 — Verificare status
Factura nu e procesată instant. Trece prin validări la ANAF (poate dura 1-30 minute). Trebuie să interoghezi periodic statusul:
Endpoint: GET /stareMesaj?id_incarcare=<index>. Status posibile: nok (eroare validare), ok (validat), in prelucrare (în curs).
Etapa 5 — Descărcare semnătură ANAF
După validare, ANAF returnează ZIP cu factura semnată digital. Trebuie stocată — ăsta e dovada legală că ai trimis-o.
7 capcane care eșuează integrarea în prod
- Token expirat fără warning — token-urile OAuth expiră silent. Implementează refresh automat la 80% din lifetime.
- Rate limiting nedocumentat — 60 request/minut per certificat. La burst > prag, primești 429 fără explicație.
- Schema XML strictă — un câmp lipsă = respingere totală, nu mesaj specific. Validează local cu schema XSD înainte să trimiți.
- Mentenanță programată — ANAF face mentenanță, de obicei dimineața. Implementează retry cu exponential backoff (5min, 30min, 2h, 6h).
- Anularea facturii — nu ștergi, transmiți factură de stornare cu referință la cea anulată. Logică separată de business.
- Numerotarea conformă — factura trebuie să respecte numerotarea ta secvențială. ANAF nu generează numere, tu le furnizezi.
- Versiuni schema — ANAF actualizează periodic specificațiile. Build-ul tău rupe-se silent. Monitor pentru email-uri de la ANAF.
Stack tehnic recomandat
- Backend: Node.js sau PHP — au 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
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.