Anaf v1 / Interop (CII / Factur-X)

Factură → PDF Factur-X

Body = XML (brut sau base64), UBL CIUS-RO sau CII — se recunoaşte după rădăcină. Întoarce PDF brut;
cu ?format=base64, un envelope {data, meta} cu PDF-ul codat, pentru clienţii care nu pot citi
binar. ?profil= alege nivelul declarat în metadate (implicit en16931).

POST

https://oneapi.ro/api/anaf/v1/interop/facturx-build

Corpul cererii

Corpul cererii e documentul întreg, trimis brut (Content-Type: application/xml) — nu un obiect cu câmpuri.

Din factură UBL

efactura.xml application/xml · 4,0 KB — se trimite ca atare, în corpul cererii.

Profil BASIC

efactura.xml application/xml · 4,0 KB — se trimite ca atare, în corpul cererii.

Dintr-o notă de credit

efactura-stornare.xml application/xml · 3,6 KB — se trimite ca atare, în corpul cererii.

Parametri de interogare

NumeTipDescriereValori acceptate

profilopțional text Nivelul declarat în metadate: minimum, basicwl, basic, en16931 (implicit), extended. ex. basic

formatopțional text Lipsă = PDF brut. base64 = envelope {data, meta} cu PDF-ul codat. ex. base64

Cum se comportă

Documentul se poate trimite şi ca fişier: multipart/form-data cu câmpul fisier (curl -F fisier=@document.xml), în locul corpului brut.
Primeşte o factură în UBL CIUS-RO (rădăcină Invoice/CreditNote) sau în CII (CrossIndustryInvoice) — se recunoaşte singură — şi întoarce un PDF Factur-X: macheta citibilă de om ŞI XML-ul facturii în acelaşi fişier. Asta e forma pe care o cer Franţa (Factur-X) şi Germania (ZUGFeRD), şi care circulă tot mai mult în B2B european.
⚠️ Factur-X încorporează CII, nu UBL — nu sunt interschimbabile. Dacă trimiţi UBL, convertim pentru încorporare; dacă trimiţi CII, îl păstrăm EXACT aşa (o conversie dus-întors ar putea pierde câmpuri fără corespondent în UBL) şi convertim doar o copie pentru machetă.
Macheta e aceeaşi cu cea de la /efactura/render — acelaşi şablon, deliberat: două machete ar însemna două facturi care arată altfel pentru acelaşi document, iar cea din Factur-X e cea pe care o vede clientul final.
⚠️ profil e ce DECLARĂM în metadate, nu ce am verificat. Verificarea unui profil Factur-X cere Schematronul lui, pe care nu îl avem. Validăm structura (XSD-ul oficial CII D16B, la conversie); potrivirea cu profilul rămâne afirmaţia ta. Dacă nu eşti sigur, basic e afirmaţia mai prudentă.
Răspunsul normal e PDF brut, cu profilul şi numele ataşamentului în antetele X-Facturx-Profil şi X-Facturx-Atasament. Cu ?format=base64 primeşti envelope-ul obişnuit {data, meta}, pentru clienţii care nu pot citi binar.
Zero retenție. Nici XML-ul primit, nici PDF-ul produs nu ating discul: încorporarea se face din memorie, iar fişierele de lucru ale randării stau în /dev/shm (RAM). Nimic nu se loghează.

La ce folosește

Trimiterea unei facturi româneşti către un partener francez sau german care aşteaptă Factur-X/ZUGFeRD.
Un singur fişier pe care îl poate citi şi omul din contabilitate şi sistemul care-l importă, fără să trimiţi două ataşamente.
Arhivare: PDF/A-3 e format de arhivare pe termen lung, cu datele structurate înăuntru.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere

standard Ce s-a produs: Factur-X 1.0 / PDF/A-3B.

intrare Formatul recunoscut în corp: CIUS-RO sau CII.

profil Profilul scris în metadate, în forma cerută de specificaţie (ex. EN 16931).

atasament Numele fişierului încorporat — mereu factur-x.xml, fixat de specificaţie: un cititor conform caută exact numele ăsta.

pdf PDF-ul, codat base64 (doar cu ?format=base64).

Exemple de răspuns

body: @efactura.xml

POSThttps://oneapi.ro/api/anaf/v1/interop/facturx-build

Răspunsul e un document binar, nu JSON: application/pdf, 54,3 KB în acest exemplu.

Descarcă documentul întors de acest exemplu

body: @efactura.xml

POSThttps://oneapi.ro/api/anaf/v1/interop/facturx-build?profil=basic

Răspunsul e un document binar, nu JSON: application/pdf, 54,3 KB în acest exemplu.

Descarcă documentul întors de acest exemplu

body: @efactura-stornare.xml

POSThttps://oneapi.ro/api/anaf/v1/interop/facturx-build

Răspunsul e un document binar, nu JSON: application/pdf, 53,9 KB în acest exemplu.

Descarcă documentul întors de acest exemplu

Coduri de eroare

Cod	Slug	Când apare
401	neautentificat	Token lipsă, invalid, expirat sau revocat.
403	feature_indisponibil	Planul curent nu include funcţia de care ţine ruta.
422	xml_invalid	Corpul nu e nici UBL (`Invoice`/`CreditNote`) nici CII (`CrossIndustryInvoice`), XML invalid, sau `profil` necunoscut.
429	cota_depasita	Cota lunară a planului a fost depăşită (vezi `Retry-After`).

Erorile modulului Anaf au acelaşi plic ca restul platformei, cu două câmpuri în plus: {eroare: {cod, mesaj, camp, request_id}}. eroare.cod e stabil şi e cel după care ramifici în cod; la validare (422) codul e specific cazului: xml_invalid, xml_nu_e_factura, unitate_necunoscuta, luna_invalida ş.a. camp arată câmpul vinovat, când se poate identifica.

{
    "eroare": {
        "cod": "xml_invalid",
        "mesaj": "Corpul nu e nici UBL (Invoice/CreditNote) nici CII (CrossIndustryInvoice), XML invalid, sau profil necunoscut.",
        "camp": "profil",
        "request_id": "0199c1f0-6e1a-7c3d-9b2f-4a8e5d1c7b04"
    }
}