Documentație API e-Factura — proforme și facturi din sistemul tău, printr-un apel.

Verifică dacă cheia API e validă.

Seriile de facturare configurate pentru firmă, pentru a alege una la creare (sau lași serverul să aleagă prima serie configurată).

Următorul număr disponibil pentru o serie (informativ — numărul real se alocă automat, atomic, la creare).

Caută clienți după nume sau CIF. Se poate folosi și ?cif=. Potrivirea este parțială (conține textul căutat), iar răspunsul are cel mult 25 de rezultate. Fără q sau cif răspunsul este 422.

Creează un client nou, sau — dacă există deja un client cu același CIF la firma ta — returnează clientul existent (fără duplicat). Singurul câmp obligatoriu pentru un client nou e name.

Dacă ai deja client.id dintr-un apel anterior, îl poți trimite direct: {"client":{"id":"kL9mN2pQ7rS1"}}.

Caută o firmă după CUI și returnează datele ei, ca să precompletezi clientul (de exemplu când cumpărătorul a introdus doar CUI-ul în formularul de comandă). Nu creează nimic în contul tău — pentru asta trimiți apoi datele la POST /api/v2/clients. Merge cu o cheie completă sau de căutare de server (de pe serverul tău) și cu o cheie de căutare din browser.

Ordinea căutării: (1) baza noastră de date — registrul firmelor din România (importat de la ONRC) plus răspunsurile ANAF salvate la căutările anterioare; dacă avem firma și statusul ei TVA a fost verificat în ultimele 90 de zile, răspundem imediat, fără ANAF ("source":"local"). (2) Altfel ANAF, cu până la 3 încercări, iar răspunsul se salvează pentru data viitoare ("source":"anaf"). (3) Dacă ANAF nu răspunde, întoarcem ce avem local, chiar dacă e vechi; 503 primești doar când nu avem nimic nici local.

{cui}: doar cifre, cu sau fără prefixul RO, cel mult 10 cifre. Cheile răspunsului sunt aceleași cu câmpurile de la POST /api/v2/clients (name, cif, reg_com, address, city, subdivision, country, phone), deci le poți trimite direct, adăugând email etc. Pentru București, orașul vine ca SECTOR1…SECTOR6.

vat_payer e true / false, sau null dacă ANAF nu a răspuns și nu avem un status TVA salvat — null nu înseamnă „neplătitor”. Când ANAF nu răspunde, dar firma există în baza noastră de firme, răspundem cu datele de acolo (denumire, adresă, județ, nr. de înregistrare), cu vat_payer: null și un warning — statusul TVA trebuie atunci verificat separat. checked_on e momentul ultimei verificări la ANAF: datele sunt ținute în cache și reverificate automat după 90 de zile sau când lipsește statusul TVA; ?refresh=1 forțează reinterogarea ANAF (ignorat pentru cheile din browser). source: local = răspuns din baza noastră, anaf = ANAF a fost interogat pentru această cerere.

Erori: 404 CUI negăsit; 422 CUI cu format greșit sau firmă radiată; 503 ANAF nu răspunde și firma nu există nici în baza noastră (se întâmplă des — completează datele manual sau reîncearcă); 429 peste 60 de căutări pe minut (plus limitele cheilor de căutare); 403 pentru o cheie din browser folosită de pe un domeniu nepermis.

De pe serverul tău (recomandat când site-ul are backend): browserul apelează endpoint-ul tău, serverul tău verifică dacă cererea e legitimă și ne apelează cu o cheie secretă (dh_ sau dhls_). Limitează singur căutările pe vizitator — toate cererile ajung la noi de pe IP-ul serverului tău.

Din browser, cu o cheie dhpk_:

Creează o proformă nouă. Câmpuri acceptate în corpul cererii (aceleași și la POST /api/v2/invoices):

Datele proformei, respectiv PDF-ul ei (generat la creare și păstrat pe server; dacă lipsește, se regenerează la cerere).

Linkul pdf_url din răspunsuri e semnat și valabil 30 de zile — îl poți pune direct într-un email sau în contul clientului, fără header de autentificare. PDF-urile nu pot fi afișate în <iframe> de pe alt domeniu (X-Frame-Options: SAMEORIGIN) — deschide-le în tab nou. Doar rutele /pdf acceptă link semnat; restul endpointurilor (inclusiv /xml) cer header-ul Authorization.

Transformă o proformă existentă în factură (de exemplu după confirmarea plății comenzii). O proformă poate fi convertită o singură dată.

Corpul cererii e opțional ({} e valid); câmpuri acceptate: date, series, payby, send_spv. Răspunsul are aceeași structură ca POST /api/v2/invoices, plus converted_from_proforma_id.

Creează direct o factură (fără să treacă prin proformă).

Starea curentă a facturii, inclusiv statusul real al trimiterii în SPV, respectiv PDF-ul ei.

Listează facturile emise, pentru reconciliere din magazin — util dacă sistemul tău a pierdut ID-urile. Fiecare element din items are exact aceeași structură ca GET /api/v2/invoices/{id}.

XML-ul UBL 2.1 exact așa cum a fost (sau ar fi) trimis la ANAF — pentru contabilitățile care arhivează documentul original, nu PDF-ul randat. Dacă XML-ul nu a fost încă generat, se generează la cerere.

Trimite în SPV o factură deja creată: fie ca reîncercare după o urcare eșuată (token ANAF expirat, ANAF indisponibil), fie ca trimitere ulterioară a unei facturi create fără send_spv.

Răspunsul 202 vine imediat și înseamnă „pus la trimis”, nu „acceptat de ANAF” — rezultatul real ajunge prin webhook sau la următorul GET /api/v2/invoices/{id}. Endpointul refuză cu 409 dacă factura e deja acceptată de ANAF sau dacă există deja o încărcare în curs. Dacă a fost respinsă, reîncercarea se face explicit, cu ?force=1, după corectarea datelor.

Înregistrează o adresă la care îți trimitem un POST semnat la fiecare schimbare, respectiv listează webhook-urile existente cu starea ultimei livrări (last_status, last_error, fail_count) și lista completă de evenimente disponibile (câmpul available_events).

Șterge webhook-ul și livrările lui aflate în coadă (răspuns {"ok":true}), respectiv trimite o livrare de probă sincron și returnează codul HTTP primit de la tine ({"ok":true,"http_status":200,"error":null}) — așa depanezi o integrare fără să aștepți un eveniment real.

Detalii complete — evenimente, structura livrării, verificarea semnăturii, reîncercări — în secțiunea 07.

secret e afișat o singură dată, ca și cheia API — cu el verifici semnătura fiecărei livrări, deci salvează-l în configurarea integrării. Dacă îl pierzi, reînregistrezi același URL: secretul se rotește și primești unul nou. Câmpul events e opțional; dacă lipsește (sau nu conține niciun eveniment valid), primești toate evenimentele — numele necunoscute sunt ignorate.