Integrare e-Factura cu API-ul ANAF: ce livrăm și cum decurge

Cele mai multe pagini care vând „integrare e-Factura" nu-ți spun ce primești. Spun că e complicat, că ei se pricep și că poți cere o ofertă.

Pagina asta e opusul: îți arată exact ce construim, în ce ordine, ce depinde de tine și unde sunt limitele. Dacă după ce o citești ajungi la concluzia că nu ai nevoie de noi, e un rezultat bun — înseamnă că ai economisit un call.

Partea tehnică generală — ce e RO_CIUS, cum arată XML-ul, care sunt cele trei arhitecturi posibile — e detaliată în ghidul de integrare ERP cu e-Factura și ANAF. Aici vorbim despre livrare.

Ce înseamnă „integrare directă cu API-ul ANAF"

ANAF expune două moduri de autentificare pentru serviciile RO e-Factura: prezentarea certificatului digital la fiecare apel (pe webserviceapl.anaf.ro) sau OAuth2 (pe api.anaf.ro). Noi construim pe al doilea.

Motivul e practic. Cu OAuth2, certificatul calificat e folosit o singură dată, la înregistrarea aplicației în portalul ANAF și la obținerea token-ului. După aceea, serverele tale vorbesc cu ANAF pe bază de token — nu ai nevoie de certificatul fizic instalat pe fiecare mașină care trimite facturi. La un singur server e o diferență minoră. La o infrastructură cu mai multe medii și deployment automat, e diferența dintre „merge" și „nu se poate".

Token-ul de acces e valabil 90 de zile, cel de refresh 365. Reînnoirea automată face parte din livrare, nu e o notă de subsol — o integrare fără ea se oprește tăcut într-o dimineață, la trei luni după lansare.

Ce livrăm, concret

Nouă componente. Toate ajung în repository-ul tău.

1. Generator RO_CIUS. Mapare din modelul tău de date (parteneri, articole, cote de TVA, unități de măsură) în XML UBL 2.1 conform profilului RO_CIUS. Nu un template — o mapare scrisă pe nomenclatoarele tale reale.

2. Validare locală înainte de trimitere. Rulăm artefactele Schematron publicate de Ministerul Finanțelor în propriul tău proces. O factură invalidă e prinsă la tine, în milisecunde, nu descoperită prin respingere după ce a consumat cotă de apeluri.

3. Autentificare OAuth2 cu reînnoire automată. Flow-ul complet către logincert.anaf.ro, stocare securizată a token-urilor și refresh programat înainte de expirare, cu alertă dacă eșuează.

4. Upload B2B și B2C. Ambele endpoint-uri, /upload și /uploadb2c, cu parametrii corecți pentru cazurile speciale: cumpărător din afara României, autofactură, document depus de organul de executare.

5. Idempotență pe trimitere. Cheie unică per factură, verificată înainte de fiecare apel. Un retry după un timeout nu poate produce o factură duplicată în sistemul național — pentru că duplicatul nu se șterge, se stornează.

6. Reconciliere pe listă. Job programat care interoghează lista de mesaje și potrivește răspunsurile după id_solicitare, în loc să întrebe de fiecare factură în parte. Pentru volume mari folosim varianta cu paginație, care are o cotă zilnică semnificativ mai mare.

7. Recepție facturi de la furnizori. Partea uitată de jumătate din integrări. Nu doar emiți — primești. O factură de la furnizor care nu ajunge la tine prin sistem îți poate afecta deducerea de TVA.

8. Arhivare pe 10 ani. XML-urile semnate, stocate la tine, cu index interogabil. SPV nu e arhiva ta.

9. Monitorizare și rapoarte. Alertă pe expirarea token-ului, alertă pe job-ul de reconciliere oprit, raport zilnic cu facturile fără recipisă. Fără stratul ăsta ai automatizat trimiterea, nu certitudinea.

Cum decurge, pe faze

Faza care decide durata proiectului e prima, nu ultima. O firmă cu un nomenclator curat și un singur flux de facturare e alt proiect decât una cu trei surse de facturi și cote de TVA istorice amestecate.

Ce ne dai tu

Ca să nu existe surprize:

• Certificat digital calificat pentru persoana care are drept în SPV pentru CUI-ul tău. Nu îl putem obține noi în numele tău.
• Acces la modelul de date — schema, sau un export reprezentativ.
• Un set de facturi reale din istoric, inclusiv cazurile urâte: storno, reduceri, TVA la încasare, clienți fără CUI.
• O persoană care poate răspunde la întrebări fiscale. Contabilul tău, de regulă. Noi scriem integrarea; el confirmă că maparea cotelor reflectă realitatea firmei.

Ultimul punct e cel mai important și cel mai des subestimat. Cele mai multe respingeri la validare nu sunt bug-uri de cod. Sunt decizii fiscale prost transferate în date.

Ce nu facem

La fel de util:

• Nu vindem un program de facturare. Dacă nu ai deja un sistem care emite facturi, integrarea nu are ce integra. Îți trebuie întâi acela.
• Nu preluăm răspunderea fiscală. Construim fluxul; corectitudinea datelor fiscale rămâne a ta și a contabilului tău.
• Nu ne interpunem între tine și ANAF. Nu există un serviciu BaseTech prin care să treacă facturile tale. Codul rulează la tine, token-urile sunt ale tale. Dacă mâine nu mai lucrăm împreună, fluxul merge mai departe.

Punctul ăsta din urmă e diferența reală față de un middleware SaaS. Un middleware e mai rapid de pornit și e o alegere rezonabilă pentru multe firme. Dar introduce o dependență externă permanentă în lanțul tău fiscal, și un abonament care nu se termină. Integrarea directă costă mai mult la început și zero după.

Când are sens integrarea directă (și când nu)

Fii sincer cu răspunsurile: Are sens dacă: ai deja un ERP sau o aplicație proprie care emite facturi · volumul e peste câteva sute pe lună · ai particularități pe care un conector standard nu le acoperă · vrei ca fluxul fiscal să nu depindă de un furnizor terț · ai sau poți contracta pe cineva care să întrețină codul.

Nu are sens dacă: ai sub o sută de facturi pe lună și un program de facturare cu conector inclus · nu ai nicio echipă tehnică și nici buget de mentenanță · fluxul tău de facturare urmează să se schimbe complet în următoarele luni.

Pentru cazul cu volume mari și magazin online, unde problema nu e conectarea, ci debitul, am scris separat despre automatizarea e-Facturii la volum — cozi, limite de apel și cazul B2C fără CNP.

Iar dacă vrei să știi dinainte ce se strică cel mai des în implementările existente, greșelile frecvente la e-Factura sunt exact lista de verificare pe care o folosim noi la discovery.

Cât costă

Depinde de complexitatea mapării, nu de numărul de facturi. Un flux simplu, cu un singur tip de document și nomenclatoare curate, e un proiect de câteva zile. Trei surse de facturi, storno automat și mai multe CUI-uri e altceva.

Integrarea se face de obicei ca parte dintr-un proiect mai mare de sistem ERP la comandă, iar bugetul se construiește pe module. Poți vedea intervalele și ce le mișcă în estimarea de cost pentru un ERP, sau ne scrii cu situația ta concretă și îți spunem în care dintre cele două categorii de mai sus te încadrezi — inclusiv dacă răspunsul e „nu ai nevoie de noi".

Întrebări frecvente

Certificatul trebuie să fie pe numele firmei sau al unei persoane?

Certificatul e emis pe o persoană fizică, iar acea persoană trebuie să aibă drept în SPV pentru CUI-ul firmei. Token-urile OAuth sunt legate de seria certificatului folosit.

Ce se întâmplă când ANAF schimbă specificația?

Artefactele de validare au versiuni, iar Ministerul publică modificările. Pentru că generatorul și validarea rulează la tine, actualizarea e o schimbare de cod pe care o poate face echipa ta sau noi, printr-un contract de mentenanță. Nu depinzi de calendarul unui vendor.

Putem integra și e-Transport sau SAF-T pe același mecanism?

Autentificarea OAuth2 e comună — același token deschide și celelalte servicii pentru care certificatul are drepturi. Logica de business diferă, dar infrastructura de autentificare se refolosește. Vezi și RO e-Transport și SAF-T (D406).

Cât durează până intrăm în producție?

Partea de cod e rareori bottleneck-ul. Obținerea certificatului și acordarea drepturilor în SPV pot dura mai mult decât integrarea în sine. Începe cu ele.

Codul rămâne al nostru?

Da. Repository-ul tău, licența ta. Nu păstrăm o copie de care depinzi.