API
Prezentare generala
Tipul API-ului
apiefactura.ro este de un API tip REST și utilizeaza formatul JSON pentru comunicarea datelor.
Securitate
Toate comunicarile prin intermediul acestui API sunt criptate folosind protocolul HTTPS/SSL pentru asigurarea securitatii. Accesul necriptat prin HTTP nu este permis și este respins automat.
Autentificarea la API se bazeaza pe o combinatie a cheii API a utilizatorului (Apikey) și a parolei API (Apipassword). Mai multe detalii despre autentificare pot fi gasite in sectiunea "Autentificare" a acestei documentatii.
URL de baza
URL-ul de baza pentru efectuarea cererilor catre API-ul apiefactura.ro este:
https://secure.apiefactura.ro/api/
Acest URL trebuie utilizat ca punct de plecare pentru construirea cererilor catre endpoint-urile API-ului.
Endpoint-uri disponibile
API-ul ofera mai multe endpoint-uri (puncte terminale) pentru diferite functionalitati, inclusiv autentificare, gestionarea licentelor, trimiterea și testarea documentelor, precum și obtinerea detaliilor despre documente.
Raspunsuri standard
API-ul furnizeaza raspunsuri standard in format JSON, care contin un camp "status" pentru a indica daca solicitarea a fost un succes sau a intampinat erori, un camp "message" pentru mesaje de clarificare, un camp "errors" pentru a lista eventualele erori și un camp "data" pentru datele returnate (daca exista).
Autentificare
Autentificarea la API-ul apiefactura.ro se realizeaza prin intermediul cheilor API și a parolei API ale utilizatorului. Aceasta este o masura de securitate esentiala pentru a asigura ca doar utilizatorii autorizati pot accesa și utiliza serviciile API-ului.
Pentru a efectua autentificarea, trebuie sa furnizati urmatoarele informatii:
- Apikey (Cheia API): Aceasta este o cheie unica generata pentru utilizator și este folosita pentru a identifica și autentifica solicitarile API. Apikey trebuie inclusa in antetul fiecarei solicitari catre API pentru a indica sursa solicitarii.
- Apipassword (Parola API): Parola API este o alta componenta a autentificarii și trebuie furnizata impreuna cu Apikey pentru a valida solicitarea. Aceasta asigura ca doar utilizatorii cu acces autorizat pot interactiona cu API-ul.
Este important sa mentionam ca autentificarea la API trebuie sa fie securizata și sa respecte cerintele de securitate. Prin urmare, urmatoarele aspecte trebuie avute in vedere:
- Toate solicitarile catre API trebuie sa includa atat Apikey, cat și Apipassword in antetul cererii pentru a fi validate corect.
- Comunicarea cu API-ul trebuie sa se realizeze prin intermediul protocolului HTTPS sau SSL pentru a asigura criptarea datelor și protejarea informatiilor confidentiale.
- In cazul in care autentificarea nu reușește sau una dintre cele doua componente (Apikey sau Apipassword) lipsește sau este incorecta, API-ul va respinge automat solicitarea.
Exemplu de autentificare generic:
curl -X GET "https://secure.apiefactura.ro/api/{endpoint}" -H "Apikey: {Apipassword}" -H "Apipassword: {Apipassword}"
Exemplu de autentificare pentru endpoint-ul testAuth:
curl -X GET "https://secure.apiefactura.ro/api/testAuth" -H "Apikey: {Apipassword}" -H "Apipassword: {Apipassword}"
Structura document
Aceasta este o descriere a campurilor obligatorii și optionale care alcatuiesc o factura, precum și informatii suplimentare pentru fiecare camp.
| Variabila | Obligatoriu | Descriere |
|---|---|---|
| Informatii privind documentul | ||
| number | obligatoriu | Acest camp reprezinta numarul unic al facturii și este esential pentru identificarea acesteia in evidenta financiara. Numarul poate fi format dintr-un prefix, cum ar fi seria. |
| issueDate | obligatoriu | Data emiterii facturii este data in care factura este emisa și transmisa catre client. Aceasta trebuie sa fie in formatul "YYYY-MM-DD" (de exemplu, "2024-01-01"). |
| currency | obligatoriu | Valuta in care este exprimata factura (de exemplu, "RON" pentru Lei Romanești). ISO 4217 |
| dueDate | optional | Data scadentei platii facturii. Acest camp este optional și poate fi utilizat pentru a specifica data limita pana la care clientul trebuie sa efectueze plata. Aceasta trebuie sa fie in formatul "YYYY-MM-DD" (de exemplu, "2024-01-01"). In cazul in care nu se comunica "dueDate", factura va avea data scadenta data emiterii ("issueDate"). |
| iban | optional | Contul bancar (IBAN) al companiei emitente in care se doreste plata. |
| bank | optional | Numele bancii la care este deschis contul bancar al companiei emitente. Trebuie utilizat impreuna cu campul "iban". |
| note | optional | Orice nota sau observatie suplimentara care trebuie inclusa in factura. |
| deliveryDate | optional | Data livrarii bunurilor sau serviciilor pentru care se emite factura. Acest camp este optional, dar necesar in cazul schemei TVA ("vatScheme") K al cel putin un articol. |
| invoiceCode | optional |
Tipul de factura:
"380" (Factura) "381" (Nota de creditare) "384" (Factura corectata) "389" (Autofactura) "751" (Factura informatii in scopuri contabile) Valoarea implicita este "380". |
| Informatii privind emitentul | ||
| obligatoriu | Adresa de e-mail a emitentului facturii, care poate fi utilizata pentru corespondenta și notificari. | |
| name | obligatoriu | Numele complet al companiei emitente a facturii. |
| address | obligatoriu | Adresa companiei emitente. |
| city | obligatoriu | Orașul in care este situat sediul companiei emitente. |
| subdivision | obligatoriu | Judetul/municipiul in care este situat sediul companiei emitente. |
| country | obligatoriu | Tara in care este situata compania emitenta. ISO 3166 |
| regCom | optional | Nr. Inreg. Registrul Comertului al companiei emitente |
| Informatii privind clientul | ||
| clientCui | obligatoriu | Codul Unic de Inregistrare (CUI) al clientului catre care se emite factura. Pentru persoane fizice se poate trimite CNP-ul persoanei fizice sau "0000000000000" |
| clientName | obligatoriu | Numele complet al clientului catre care se emite factura. |
| clientAddress | obligatoriu | Adresa clientului catre care se emite factura. |
| clientSubdivision | obligatoriu | Judetul/municipiul clientului catre care se emite factura. |
| clientCountry | obligatoriu | Tara in care este situat clientul. ISO 3166 |
| clientSubdivision | obligatoriu | Judetul/municipiul clientului catre care se emite factura. |
| clientRegCom | optional | Nr. Inreg. Registrul Comertului al clientului |
| Informatii privind continutul documentului | ||
| items | obligatoriu | Array ce contine articolele documentului |
| Informatii privind un articol | ||
| (items) name | obligatoriu | Numele produsului sau serviciului furnizat, care trebuie inclus in factura. |
| (items) price | obligatoriu | Pretul unitar al produsului sau serviciului. Acesta indica costul unei singure unitati a produsului sau serviciului. |
| (items) name | obligatoriu | Numele produsului sau serviciului furnizat, care trebuie inclus in factura. |
| (items) quantity | obligatoriu | Cantitatea de produse sau servicii furnizate. Acest camp indica numarul de unitati vandute. |
| (items) vatRate | obligatoriu | Rata TVA (Taxa pe Valoarea Adaugata) aplicata produsului sau serviciului. TVA-ul este adesea exprimat ca procent (de exemplu, 19%). |
| (items) vatScheme | obligatoriu | Schema TVA aplicata pentru acest produs sau serviciu. Valori acceptate: "AE", "E", "S", "Z", "G", "O", "K", "L", "M" și "B". UNCL5305 |
| (items) vatexCode | optional | Codul de exceptie de la TVA, daca este aplicabil. Acesta este un camp optional, dar necesar in cazul schemei TVA ("vatScheme") E. |
| (items) classificationList | optional | N/A |
| (items) classificationCode | optional | N/A |
testAuth (testare autentificare)
Acest endpoint are ca scop verificarea starii de autentificare a API-ului și furnizarea informatiilor despre licenta asociata autentificarii.
URL:
https://secure.apiefactura.ro/api/testAuth
Tipul de request:
GET
Variabile necesare:
Nu necesita variabile suplimentare header-ului de autentificare.
Exemplu de cerere:
curl -X GET "https://secure.apiefactura.ro/api/testAuth" -H "Apikey: {Apipassword}" -H "Apipassword: {Apipassword}"
Exemplu de cerere cu raspuns succes:
{
"status": "success",
"message": "API autentification successful.",
"data": {
"license": "{CUI licenta}"
}
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "API autentification failed."
}
getLicense (obtinere licenta)
Acest endpoint permite utilizatorilor sa obtina informatii despre licenta asociata cu autentificarea lor.
URL:
https://secure.apiefactura.ro/api/getLicense
Tipul de request:
GET
Variabile necesare:
Nu necesita variabile suplimentare header-ului de autentificare.
Exemplu de cerere:
curl -X GET "https://secure.apiefactura.ro/api/getLicense" -H "Apikey: {Apipassword}" -H "Apipassword: {Apipassword}"
Exemplu de cerere cu raspuns succes:
{
"status": "success",
"message": "License retrieved.",
"data": {
"id": "{ID-ul companiei in API}",
"cui": "{codul fiscal al companiei}",
"companyName": "{numele companiei}",
"status": "enabled",
"expire": "{data expirarii abonamentului}"
}
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "API autentification failed."
}
testDocument (validare document)
Acest endpoint permite utilizatorilor sa trimita documente pentru a le testa validitatea fara a le incarca in mod efectiv in sistemul API.
URL:
https://secure.apiefactura.ro/api/testDocument
Tipul de request:
POST
Variabile necesare:
Datele documentului sub forma unui obiect JSON (vezi structura document) in corpul cererii.
Exemplu de cerere:
curl -X POST -H "Apikey: {Apikey}" -H "Apipassword: {Apipassword}" -d '{
"documentData": {
"number": "ABC123",
"issueDate": "2025-04-28",
...
}
}' "https://secure.apiefactura.ro/api/testDocument"
Exemplu de cerere cu raspuns succes:
{
"status": "success",
"message": "Document has been validated with apiefactura.ro. Warning: Test endpoint, document has not been uploaded."
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "Test document failed.",
"errors": [
...
]
}
sendDocument (trimitere document)
Acest endpoint permite utilizatorilor sa trimita documente pentru a fi procesate de sistemul API. Documentul va fi validat și incarcat in sistem pentru a fi prelucrat ulterior.
URL:
https://secure.apiefactura.ro/api/sendDocument
Tipul de request:
POST
Variabile necesare:
Datele documentului sub forma unui obiect JSON (vezi structura document) in corpul cererii.
Exemplu de cerere:
curl -X POST -H "Apikey: {Apikey}" -H "Apipassword: {Apipassword}" -d '{
"documentData": {
"number": "ABC123",
"issueDate": "2025-04-28",
...
}
}' "https://secure.apiefactura.ro/api/sendDocument"
Exemplu de cerere cu raspuns succes:
{
"status": "success",
"message": "Document has been validated with apiefactura.ro. Pending upload and RO eFactura confirmation.",
"data": [
"id": "{ID document}",
"status": "{status document}",
"docName": "{nume document}",
"docName": "{nume document}"
]
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "Send document failed.",
"errors": [
...
]
}
Acest endpoint este destinat pentru trimiterea documentelor pentru procesare reala in sistem. Daca dorești doar sa testezi validarea documentelor, te rugam sa folosești functia "testDocument".
getDocument (obtinere document)
Acest endpoint permite utilizatorilor sa obtina detalii despre un document specific, utilizand ID-ul documentului. Se pot returna atat documente comunicate catre RO eFactura (exemplu: facturi emise), cat si documente primite din RO eFactura (exemplu: facturi furnizor).
URL:
https://secure.apiefactura.ro/api/getDocument
Tipul de request:
POST
Variabile necesare:
ID-ul documentului pentru care dorești sa obtii detalii.
Exemplu de cerere:
curl -X POST -H "Apikey: {Apikey}" -H "Apipassword: {Apipassword}" -d '{
"id": "{ID document}"
}' "https://secure.apiefactura.ro/api/getDocument"
Exemplu de cerere cu raspuns succes:
{
"status": "success",
"message": "Document found.",
"data": {
"id": "{ID-ul documentui}",
"type": "{tipul documentului",
"status": "{status document}",
"docName": "{nume document}",
"indexIncarcare ": "{index incarcarcare SPV}",
"indexDescarcare": "{index descarcare SPV}",
"invoiceCode": "{codul documentului}",
"issueDate": "{data emiterii}",
"dueDate": "{data scadenta}",
"totalValue": "{valoare totala}",
"currency": "{moneda}",
"seller": "{denumirea emitentului}",
"sellerInfo": [
... (informatii suplimentare despre emitent)
]
"buyer": "{denumirea cumparatorului}",
"buyerInfo": [
... (informatii suplimentare despre cumparator)
]
"content": [
... (continutul documentului - versiune BETA)
]
}
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "Document not found.",
"errors": [
...
]
}
getDocuments (obtinere lista documente)
Acest endpoint permite utilizatorilor sa obtina o lista de documente, utilizand un ID de start si filtre optionale, cum ar fi tipul documentului. Pot fi returnate atat documente comunicate catre RO eFactura (ex: facturi emise), cat si documente primite (ex: facturi furnizor). Sistemul returneaza maximum 50 de documente per cerere.
URL:
https://secure.apiefactura.ro/api/getDocuments
Tipul de request:
POST
Variabile obligatorii:
start
ID-ul documentului de la care doresti sa incepi listarea documentelor. Toate documentele returnate vor avea un ID mai mare sau egal cu acest ID.
Variabile optionale:
type
Tipul documentelor pe care doresti sa le obtii: outgoing sau incoming.
Exemplu de cerere:
curl -X POST -H "Apikey: {Apikey}" -H "Apipassword: {Apipassword}" -d '{
"start": "1"
}' "https://secure.apiefactura.ro/api/getDocuments"
Exemplu de cerere cu raspuns succes:
{
"errors": [],
"status": "success",
"message": "Documents found.",
"data": [
{
"id": "{ID-ul documentului}",
"type": "{tipul documentului}",
"status": "{status document}",
"docName": "{nume document}",
"createdOn": "{data prezentarii documentului}",
"processedOn": "{data procesarii documentului}"
},
{
"id": "{ID-ul documentului}",
"type": "{tipul documentului}",
"status": "{status document}",
"docName": "{nume document}",
"createdOn": "{data prezentarii documentului}",
"processedOn": "{data procesarii documentului}"
}
...
]
}
Exemplu de cerere cu raspuns eroare:
{
"status": "error",
"message": "No documents found."
}
downloadPdf (obtinere fisier PDF)
Aceasta functionalitate este in teste si va fi disponibila in curand.
downloadZip (obtinere arhiva ZIP)
Aceasta functionalitate este in teste si va fi disponibila in curand.
Status si tip document
In cadrul API-ului apiefactura.ro, documentele sunt identificate și clasificate prin intermediul a doua atribute importante: "status" (stare) și "type" (tip). Aceste doua atribute ofera informatii cruciale despre starea și natura documentului. Iata o descriere detaliata a acestor atribute și a valorilor posibile pentru fiecare:
status (stare document)
Starea documentului reprezinta stadiul actual al unui document in sistem. Aceasta indica in ce faza se afla documentul in procesul sau de manipulare și transmitere. Valorile posibile pentru atributul "status" sunt urmatoarele:
- lobby: documentul a fost receptionat si validat de catre apiefactura.ro, urmand sa fie comunicat catre RO eFactura.
- pending documentul a fost comunicat catre RO eFactura, se asteapta validarea sau invalidarea acestuia.
- validated documentul a fost validat de catre RO eFactura.
- errors documentul a fost invalidat de catre RO eFactura.
type (tip document)
Tipul documentului indica natura specifica a documentului. Acesta ne spune daca documentul este o factura de intrare, o factura de ieșire sau alt tip de document fiscal. Valorile posibile pentru atributul "type" sunt urmatoarele:
- outgoing: documentul reprezinta o factura de ieșire, adica o factura emisa de catre utilizatorul API catre un client.
- incoming: documentul reprezinta o factura de intrare, adica o factura primita de catre utilizatorul API de la un furnizor.