Program de facturare online integrat cu e-Factura & e-Transport

Prețuri Ajutor

Documentație API

API (Application Programming Interface)
îți pune la dispoziție resursele

În continuare vei regăsi tot ce este necesar pentru integrarea software-ului tău.

1. Resurse și URL-uri

API-ul factureaza.ro este un API de tip REST, utilizând verbele HTTP corespunzătoare operației invocate.

API-ul este accesibil doar prin HTTPS.

Sunt accesibile următoarele operații pentru modelele de mai jos:

LISTARE https://factureaza.ro/api/v1/[model-plural].xml (HTTP GET) DETALII https://factureaza.ro/api/v1/[model-plural]/[id].xml (HTTP GET) ȘTERGERE https://factureaza.ro/api/v1/[model-plural]/[id].xml (HTTP DELETE) MODIFICARE https://factureaza.ro/api/v1/[model-plural]/[id].xml (HTTP PUT) CREARE https://factureaza.ro/api/v1/[model-plural].xml (HTTP POST)

LISTARE întoarce doar un rezumat al fiecărei înregistrări. Toate câmpurile descrise în capitolul 7 se obțin cu DETALII, pentru un document anume.

Pentru facturi, proforme și avize rezumatul conține id series document_date total currency due_date document_state client_id client_name share_url total_due exchange_rate reversed_document_id

La acestea se adaugă încasările și plățile asociate documentului. exchange_rate și reversed_document_id apar doar la documentele care au o valoare pentru ele, iar total_due doar la documentele care se încasează.

Pentru chitanțe rezumatul conține id series document_date amount currency invoice_id client_id client_name

LISTAREA și CĂUTAREA returnează rezultatele paginat: fără parametri de paginare primești prima pagină. Listele de referință (țări, monede) se returnează întregi.

page — pagina cerută, numerotată de la 1
per_page — câte înregistrări pe pagină; implicit 100, maximum 500

Antetele răspunsului descriu paginarea: X-Total-Count, numărul total de înregistrări, X-Total-Pages, numărul total de pagini, X-Page, pagina curentă și X-Per-Page, mărimea ei. Cât timp există o pagină următoare, antetul Link îi poartă adresa.

Exemple folosind curl:

LISTARE curl -i -u [api_key]:x https://factureaza.ro/api/v1/clients.xml DETALII curl -i -u [api_key]:x https://factureaza.ro/api/v1/clients/1.xml ȘTERGERE curl -i -X DELETE -u [api_key]:x https://factureaza.ro/api/v1/clients/1.xml MODIFICARE curl -i -X PUT -F "client[name]=FirmaMea" -u [api_key]:x https://factureaza.ro/api/v1/clients/1.xml

CREARE curl -i -X POST -d "client[name]=FirmaMea" -d "client[uid]=999999" -u [api_key]:x https://factureaza.ro/api/v1/clients.xml

Exemple folosind php:

Listare facturi

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'invoices.xml';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Detalii factură

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $invoice_id = 1065257565;  // your invoice id here
  $url = BASE_URL . 'invoices/' . $invoice_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Schimbare stare factură

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $invoice_id = 1065257565;  // your invoice id here
  $url = BASE_URL . 'invoices/' . $invoice_id . '/mark_closed.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([]));

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Modificare factură

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $invoice_id = 1065257565;  // your invoice id here
  $changes = array("invoice" =>
    array(
      "lower_annotation" => 'Explicații noi',
      "upper_annotation" => 'Note de antet',
      "note" => "Note interne noi",
      "document_positions" => array (
        1 => array (
    'description' => 'cartof',
    'unit' => 'kg',
    'unit_count' => '4',
    'input_currency_price' => '0.74',
    'vat' => 10
    ),
      2 => array (
    'description' => 'varză de Bruxelles',
    'unit' => 'g',
    'unit_count' => '250',
    'input_currency_price' => '51',
    'vat' => 19
    )
      )
      )
      );
  $url = BASE_URL . 'invoices/' . $invoice_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($changes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 200) {
    echo 'Updated successfully';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

Modificare date client + factură asociată

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $client_id = 1064116436;  // your client id here
  $changes = array("client" => array("name" => 'Nume client schimbat', "city" => "Nume oras nou"));
  $url = BASE_URL . 'clients/' . $client_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($changes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);
  if ($httpCode == 200) {
    echo 'Client updated successfully<br/>';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }


  $invoice_id = 1065257565;  // a invoice for the above client
  $changes = array("invoice" =>
    array(
      "update_client_data" => "1",
      "note" => "client data updated"
      )
    );
  $url = BASE_URL . 'invoices/' . $invoice_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($changes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 200) {
    echo 'Invoice updated successfully';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

Listare clienți

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'clients.xml';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Adăugare client

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $attributes = array(
    "client" => array(
      "name" => 'Firma mea preferata',
      "uid" => '3987985',
      "tax_id" => 1,
      "registration_id" => "J39/44/1990",
      "city" => "Nume oras client",
      "address" => "strada Buldozerului nr. 221",
      "country_id" => "167"
      )
    );
  $url = BASE_URL . 'clients.xml';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($attributes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch); // returns the newly created client in xml format
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
      // transform the client data from xml to a array
          $client_data = json_decode(json_encode(simplexml_load_string($result)), TRUE);
    echo 'Client created successfully. Client id: ' . $client_data['id'];
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

Căutare clienți

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'clients/search.xml?field=uid&value=16751764';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Detalii client

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $client_id = 1064116436;  // your client id here
    $url = BASE_URL . 'clients/' . $client_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Modificare client

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $client_id = 1064116436;  // your client id here
  $changes = array("client" => array("name" => 'Nume client nou', "city" => "Nume oras nou"));
  $url = BASE_URL . 'clients/' . $client_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($changes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 200) {
    echo 'Updated successfully';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

Ștergere produs

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $product_id = 741342701; // your product id here
  $url = BASE_URL . 'products/' . $product_id . '.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 200) {
    echo 'Deleted successfully';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . '</pre>';
  }
?>

Facturile, proformele, avizele și chitanțele pot fi descărcate direct în format PDF, specificând în URL formatul respectiv:

DESCĂRCARE PDF https://factureaza.ro/api/v1/[model-plural]/[id].pdf (HTTP GET)

Descărcarea PDF este un apel API obișnuit și necesită autentificare, exact ca toate celelalte apeluri (vezi autentificare ).

DESCĂRCARE PDF curl -i -u [api_key]:x -o factura.pdf https://factureaza.ro/api/v1/invoices/1.pdf

Un apel fără date de autentificare primește 401 Unauthorized, iar apelurile repetate fără autentificare duc la blocarea temporară a adresei IP.

2. Sistem sandbox pentru testarea API

Pentru testarea funcțiilor API-ul factureaza.ro am realizat un sistem sandbox.

Acesta este disponibil la adresa: https://sandbox.factureaza.ro
Cheia API: 72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965
Datele de acces:
- Adresa login: https://sandbox.factureaza.ro/users/sign_in
- Nume cont: sandbox
- Nume utilizator: dan.popescu
- Parola: dAn.p0pescu

3. Autentificare

Cheia API este definită per utilizator și se poate (re)genera din contul tău factureaza.ro, la punctul “Contul meu” -> “Cheie API”

Sunt disponibile două metode de autentificare:

HTTP Authentication (se va folosi cheia API ca username, parola fiind ignorată)
Parametru api_key adăugat fiecărui request.

4. Rezultate și erori

Resursele sunt returnate în format xml. Rezultatul unui request semnalează prin status-ul HTTP returnat:

200 Success (după un request GET, PUT, sau DELETE reușit)
201 Created (după un request POST reușit)
400 Resource Invalid (request formatat greșit)
401 Unauthorized (cheia API lipsește sau nu este validă)
403 Forbidden (cheia API este validă, dar abonamentul sau starea contului nu permit operațiunea — de ex. limita de documente a fost atinsă)
404 Resource Not Found
405 Method Not Allowed (Verbul HTTP folosit nu este acceptat pentru această resursă)
422 Unprocessable Entity (Request-ul a fost sintactic corect, dar modificările cerute nu sunt valide)
429 Too Many Requests (Limita de cereri API a abonamentului a fost depășită)
500 Application Error (Eroare în sistem)

Pentru cereri corecte sintactic, dar care nu îndeplinesc criteriile de validare ale sistemului, erorile vor fi returnate in corpul răspunsului sub forma:

  <errors>
  <error>Mesaj eroare</error>
  <error>Alt mesaj eroare</error>
  ...
</errors>

După adăugarea unei înregistrări, in header-ul `Location’ al răspunsului va fi returnat URL-ul la care noua înregistare este disponibilă.

4.1. Limite de cereri și header-ele de răspuns

Numărul de cereri API incluse pe oră, pe zi și pe lună calendaristică depinde de tipul de abonament — limitele curente sunt afișate pe pagina de prețuri. Ele sunt comune tuturor canalelor de acces: API v1 (REST), API GraphQL și conectorul AI / MCP.

Ca să îți poți doza cererile fără să aștepți un răspuns 429, fiecare răspuns îți spune unde te afli față de limite. Pentru fiecare fereastră de timp limitată se returnează trei header-e:

X-RateLimit-Limit-Hour (respectiv -Day și -Month ) — numărul de cereri incluse în fereastră
X-RateLimit-Remaining-Hour — câte cereri mai ai la dispoziție în fereastră
X-RateLimit-Reset-Hour — momentul în care fereastra eliberează următoarea cerere, ca timestamp Unix (secunde, UTC)

  X-RateLimit-Limit-Hour: 250
X-RateLimit-Remaining-Hour: 243
X-RateLimit-Reset-Hour: 1756111013
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 812
X-RateLimit-Reset-Day: 1756158613
X-RateLimit-Limit-Month: 5000
X-RateLimit-Remaining-Month: 3140
X-RateLimit-Reset-Month: 1756674000

Ferestrele „pe oră” și „pe zi” sunt glisante: se numără cererile din ultimele 60 de minute, respectiv din ultimele 24 de ore, deci cota se eliberează treptat, pe măsură ce cererile vechi ies din fereastră — header-ul Reset indică momentul în care se eliberează prima cerere, nu momentul în care se eliberează toată cota. Fereastra „pe lună” este luna calendaristică și se resetează integral la 00:00, în prima zi a lunii următoare.

Dacă abonamentul tău nu are limită pe o anumită fereastră, header-ele acelei ferestre lipsesc din răspuns. Valorile sunt orientative — sub trafic paralel se pot actualiza cu o mică întârziere — deci folosește-le pentru dozarea cererilor, nu ca evidență contabilă exactă.

Răspunsul 429 conține în plus header-ul Retry-After cu numărul de secunde după care poți relua cererile.

Independent de limitele abonamentului, există și o protecție per adresă IP împotriva abuzurilor; un ritm normal de integrare nu ajunge la acel prag.

5. Câmpuri și tipuri de date

Toate modelele conțin următoarele câmpuri:

id - identificatorul unic al înregistrării
created_at - data și ora creării înregistrării
updated_at - data și ora actualizării înregistrării

Câmpurile marcate cu (R) sunt read-only; ele se calculează de sistem pe baza celorlalte date.

Tipuri de date:

formatul pentru dată este AAAA-LL-ZZ
valori boolean vor fi reprezentate cu true / false
se folosesc identificatori (id) numerici

6. Operațiuni de scriere

Câmpurile marcate cu * sunt obligatorii

Modelele agregate vor fi specificate prin identificator. Exemplu: se va specifica currency_id pentru moneda.

Datele pot fi trimise ca xml sau trimise ca parametrii in request-ul HTTP. în ambele cazuri, se va specifica totdeauna și numele modelului.

La operațiuni de actualizare (POST) nu e necesară decât trimiterea câmpurilor actualizate.

6.1. Exemple scriere

Modificare nume client (xml):

  curl -H 'Content-Type: application/xml'
  -X PUT https://factureaza.ro/api/v1/clients/1.xml -u [api_key]:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <client>
    <name>Denumire Client</name>
    <uid>999999</uid>
  </client>'

Modificare nume client (application/x-www-form-urlencoded):

  curl -X PUT https://factureaza.ro/api/v1/clients/1.xml -u [api_key]:x \
  -d 'client[name]=NumeClient&client[uid]=999999'

Adăugare produs (xml):

  curl -H 'Content-Type: application/xml'
  -X POST https://factureaza.ro/api/v1/products.xml -u [api_key]:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <product>
    <description>abonament factureaza.ro</description>
    <price>12</price>
    <currency_id>1</currency_id>
  </product>'

După adăugarea unei înregistrări, in header-ul `Location’ al răspunsului va fi returnat URL-ul la care noua înregistare este disponibilă, iar în body va fi returnată toată înregistrarea

  HTTP/1.1 201 Created
...
Location: https://factureaza.ro/api/v1/products/741342701
...

<?xml version="1.0" encoding="UTF-8"?>
<product>
  <code></code>
  <created_at type="datetime">2011-05-19T14:53:41+03:00</created_at>
  <description>abonament factureaza.ro standard</description>
  <id type="integer">741342701</id>
  <price type="decimal">12.0</price>
  ...
</product>

7. Modele

7.1. Factura

Nume model: invoice

Listare facturi (fragment php):

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'invoices.xml';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

Facturile pot fi descărcate direct și în format PDF, folosind aceleași date de autentificare ca la orice alt apel API:

DESCĂRCARE PDF https://factureaza.ro/api/v1/invoices/[id].pdf (HTTP GET) DESCĂRCARE PDF curl -i -u [api_key]:x -o factura.pdf https://factureaza.ro/api/v1/invoices/1.pdf

7.1.1. Datele emitentului

account_banks (R) Conturile bancare ale emitentului documentului, de forma:

  <account_banks>
  <bank>
    <name>Banca Transilvania</name>
    <bic>1000000</bic>
    <accounts>
      <account>
        <iban>RO99BTRL000000000000</iban>
        <currency>EUR</currency>
      </account>
      ... more accounts ...
    </accounts>
  </bank>
  ... more banks ...
</account_banks>

account_xxx (R) - datele emitentului; vezi și datele contului ; la scriere se preiau automat din datele contului

branch_office_id - identificatorul punctului de lucru

branch_office_data (R) - datele punctului de lucru (vezi puncte de lucru )

7.1.2. Datele clientului

client_id * (RW) - identificatorul clientului

client_xxx (R) - toate datele unui client; (vezi clienți ); la scriere se preiau automat din client

7.1.3. Moneda facturii

currency_id * - moneda care apare pe factură

input_currency_id - moneda în care se introduc sumele de pe factură

exchange_rate - cursul de schimb, obligatoriu pentru documente cu sumele introduse în alte monede (ex: 4.6 pe EUR/RON)

Documentele factureaza.ro pot fi emise în orice monedă. Există trei cazuri:

Sumele se introduc și se afișează în RON
- se va specifica doar currency_id
Sumele se introduc într-o monedă externă și se afișează în moneda externă și în RON
- se va specifica doar la currency_id fiind moneda externă
Sumele se introduc într-o monedă externă și se afișează doar în RON
- se specifică RON ca currency_id și moneda externa ca input_currency_id

7.1.4. Datele documentului

total (R) - total factură

total_due (R) - rest de plată

document_date * - data documentului

document_series_id * - seria din care face parte acest document

document_series_counter * - numărul de ordine al documentului în cadrul seriei

vat_type * - tipul de TVA aplicabil:

fără TVA
TVA (standard)
TVA inclus
TVA scutit cu drept de deducere (s.c.d.d.)
TVA scutit făra drept de deducere (s.f.d.d.)
TVA taxare inversă
TVA neinclus în baza de impozitare (n.î.b.i.)
Regimul marjei - agenții de turism (r.m.a.t.)
Regimul marjei - bunuri second-hand (r.m.b.s.h.)
Regimul marjei - opere de artă (r.m.o.a.)
Regimul marjei - obiecte de colecție şi antichităţi (r.m.o.c.a.)

due_days - numărul de zile după care factura devine scadentă

due_date (R) - data scadenței (calculată din due_days)

document_state - starea documentului; valori posibile: “draft”, “open”, “closed”, “cancelled”

source_document_id - documentul din care a rezultat prezentul document in urma operațiunii de copiere sau generare din alt document

reversed_document_id - in cazul facturilor de stornare: documentul(factura) stornată

input_currency_reversing - in cazul facturilor de stornare: valoarea care se stornează din factura stornată. Util atunci când o factură include atât poziţii de stornare cât şi alte poziţii

Prezența lui reversed_document_id este singurul semnal sigur că un document este o factură de stornare. Câmpul este returnat atât de DETALII cât și de LISTARE, acolo doar la facturile de stornare. Vezi 7.1.13. Facturi de stornare.

Exemplu creare factură de stornare parţială

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');
  /* adapt there variables to your needs*/
  $client_id = 1064116436;
  $currency_id = 183;
  $invoice_series_id = 1061105577; // IDul seriei - NU PREFIXUL !!!!!
  $document_series_counter = rand(1000,10000);
  $url = BASE_URL . 'invoices.xml';
  $ch = curl_init();
  $data = array("invoice" =>
    array(
      "client_id" => $client_id,
      "currency_id" => $currency_id,
      "document_date" => '2014-10-20',
      "document_series_id" => $invoice_series_id,
      "document_series_counter" => $document_series_counter,
      "vat_type" => 1,
      "delegate_id" => 525664463,
      "display_transport_data" => 1,
      "source_document_id" => 1065254081,
      "reversed_document_id" => 1065254081,
      'input_currency_reversing' => 100,
      "document_positions" => array (
        1 => array (
    'description' => 'STORNARE partiala alta factura',
    'unit' => 'luni',
    'unit_count' => '12',
    'price' => '-12',
    'product_code' => '66XXH663496H',
    'vat' => 19
    ),
      )
      )
    );


  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
            // transform the invoice data from xml to a array
    $invoice_data = json_decode(json_encode(simplexml_load_string($result)), TRUE);
    echo 'Invoice created successfully. Invoice id: ' . $invoice_data['id'];
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

7.1.5. Date legate de expediție

display_transport_data - include datele privind expediţia pe factură

delegate_id

delegate_cnp (R)

delegate_first_name (R)

delegate_identity_document (R)

delegate_identity_document_issue_date (R)

delegate_identity_document_issued_by (R)

delegate_identity_document_number (R)

delegate_identity_document_series (R)

delegate_last_name (R)

expedition_time - data și ora expediției

7.1.6. Alte câmpuri

late_fees_cycle - ciclul de calcul al penalităților; valori posibile: [d,m] daily/monthly

late_fees_percentage - procentul penalizare aplicabil per ciclu

locale - limba documentului (codul ISO), implicit este ‘ro’

hide_domestic_translations - nu include traducerile în limba română pentru facturile în limbi străine

lower_annotation - notele adiționale, observații etc.

upper_annotation - notele de antet, apar în partea de sus a documentului.

delivery_date - Data livrării

advance_date - Data plății avansului

means_of_transport - mijlocul de transport

means_of_transport_number - informații de înmatriculare ale mijlocului de transport

notice_date - data avizului

notice_number - numărul avizului

user_id (R) - utilizatorul emitent

hashcode (R) - cod care poate fi folosit pentru shareing-ul read only al documentului la URL-ul https://factureaza.ro/vizualizare/%5Bhashcode%5D

note - Note interne

account_company_pays_vat_on_payment - TVA la încasare

update_account_data - Preia modificările firmei Dvs. în factură (dacă s-au schimbat de la data emiterii facturii)

update_client_data - Preia modificările clientului în factură (dacă s-au schimbat de la data emiterii facturii)

update_user_data - Preia modificările utilizatorului/emitentului în factură (dacă s-au schimbat de la data emiterii facturii)

7.1.7. Flaguri

flag_downloaded_pdf - documentul a fost descărcat în format PDF

flag_filed - documentul a fost înregistrat în contabilitate

flag_sent_by_email - documentul a fost trimis prin email

flag_sent_by_fax - documentul a fost trimis prin fax

flag_sent_by_postal_mail - documentul a fost trimis prin poștă

7.1.8. Pozițiile de pe factură

Factura va conține una sau mai multe poziții facturate cu următoarele câmpuri:

description* - descrierea produsului/serviciului

unit * - unitatea de măsura

unit_count * - numărul unităților

product_code - codul intern al produsului

vat - valoarea TVA în procente

position - ordinea în document

input_currency_price** - prețul unitar fără TVA în moneda secundară

input_currency_total** - prețul total cu TVA în moneda secundară

price** - prețul unitar fără TVA în moneda principală

total** - prețul total cu TVA în moneda principală

** se specifica fie prețul unitar fie prețul total și doar pentru o singură monedă. Vezi și detalii despre moneda facturii.

discount_rate - reducere procentuală (0-100) aplicată poziției; se aplică oricărei poziții, indiferent dacă este definită prin preț unitar sau prin valoare totală. Este reprezentată intern ca o poziție de discount separată, afișată imediat sub această linie (în PDF, e-Factura, exporturi), dar nu apare ca poziție distinctă în acest răspuns API - rămâne pe câmpul discount_rate al liniei native. O reducere nouă este luată în calcul doar dacă opțiunea de reduceri pe linie este activată - setarea proprie a facturii, dacă a fost vreodată salvată (se poate seta doar din formularul de editare al facturii, bifa "Activează reducerile pe linie pentru acest document", nu și prin acest API), altfel valoarea implicită din Setări cont > Valori implicite > Facturare. Dacă opțiunea este dezactivată, valoarea trimisă este ignorată - dar o valoare în afara intervalului 0-100 sau nenumerică este întotdeauna respinsă printr-o eroare de validare, indiferent de această opțiune. O reducere deja existentă pe o poziție poate fi oricând modificată sau ștearsă, indiferent de această opțiune.

Pozițiile de discount

discount_rate * - discount în procente

type - se specifica valoarea “DiscountPosition”

Pentru poziții de discount, câmpurile price, total, unit, unit_count nu se specifică!

Exemplu:

  <document_position>
  <type>DiscountPosition</type>
  <description>Discount conform contract (20.0%)</description>
  <discount_rate>20.0</discount_rate>
</document_position>

7.1.9. Stările facturii

Stările facturii nu se pot schimba direct, ci prin request PUT la:

https://factureaza.ro/api/v1/[model-plural]/[id]/mark_draft.xml - pentru starea ciornă

https://factureaza.ro/api/v1/[model-plural]/[id]/mark_open.xml - pentru starea emis

https://factureaza.ro/api/v1/[model-plural]/[id]/mark_closed.xml - pentru starea închis

https://factureaza.ro/api/v1/[model-plural]/[id]/mark_cancelled.xml - pentru starea anulat

7.1.10. Trimitere factură pe email

Trimiterea unei facturi pe email se face prin request PUT la url-ul de mai jos, specificând parametri: to, bcc, cc (se poate specifica un singur parametru bcc sau cc cu lista de e-mail-uri către care se va trimite mail-ul prin metoda specificată), body:

https://factureaza.ro/api/v1/[model-plural]/[id]/email.xml

Trimitere factură pe email (fragment php):

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $invoice_id = 1065257565;  // your invoice id here
  $url = BASE_URL . 'invoices/' . $invoice_id . '/email.xml' ;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $body = "Draga client \n\nTe rog plătește factura atașată.\n\nMersi frumos\nEchipa";
  $email_params = array('to'=>['clientul4@client.ro', 'contabilitatea-clientul@client.ro'],
    'bcc'=>['office@la-mine.ro', 'contabilitate@la-mine.ro'],
    'body'=> $body);
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($email_params));
  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

7.1.11. Exemple editare facturi

Adăugare factură (xml)

  curl -i -H 'Content-Type: application/xml' \
  -X POST https://factureaza.ro/api/v1/invoices.xml -u [api_key]:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <invoice>
    <client_id>100</client_id>
    <currency_id>200</currency_id>
    <document_date>2011-05-20</document_date>
    <document_series_id>300</document_series_id>
    <document_series_counter>10</document_series_counter>
    <vat_type>1</vat_type>
    <document_positions>
      <document_position>
        <description>ABONAMENT BASIC</description>
        <unit>luni</unit>
        <unit_count>12</unit_count>
        <price>12</price>
        <vat>24</vat>
      </document_position>
      <document_position>
        <type>DiscountPosition</type>
        <description>Reducere pentru plata in avans</description>
        <discount_rate>10</discount_rate>
      </document_position>
    </document_positions>
  </invoice>'

Adăugare factură (fragment php):

  <?php
//set BASE_URL to https://factureaza.ro/api/v1/ for production
define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
//replace with the api key provided in the backend
define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

/* adapt there variables to your needs*/
$client_id = 1064116436;
$currency_id = 183;
$invoice_series_id = 1061105577; // IDul seriei - NU PREFIXUL !!!!!
$document_series_counter = rand(1000,10000);

$url = BASE_URL . 'invoices.xml';
$ch = curl_init();

$data = array("invoice" =>
  array(
    "client_id" => $client_id,
    "currency_id" => $currency_id,
    "document_date" => '2014-05-20',
    "document_series_id" => $invoice_series_id,
    "document_series_counter" => $document_series_counter,
    "vat_type" => 1,
    "delegate_id" => 525664463,
    "display_transport_data" => 1,
    "document_positions" => array (
      1 => array (
  'description' => 'ABONAMENT BASIC',
  'unit' => 'luni',
  'unit_count' => '12',
  'price' => '12',
  'product_code' => '66XXH663496H',
  'vat' => 19
  ),
    2 => array (
  'type' => 'DiscountPosition',
  'description' => 'Reducere pentru plata in avans',
  'discount_rate' => '12'
  )
    )
    )
    );


  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
          // transform the invoice data from xml to a array
    $invoice_data = json_decode(json_encode(simplexml_load_string($result)), TRUE);
    echo 'Invoice created successfully. Invoice id: ' . $invoice_data['id'];
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }

?>

//alternative for XML-lovers:

<?php
  //set BASE_URL to https://factureaza.ro/api/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  /* adapt there variables to your needs*/
  $client_id = 1064116436;
  $currency_id = 183;
  $invoice_series_id = 1061105577; // IDul seriei - NU PREFIXUL !!!!!
  $document_series_counter = rand(1000,10000);

  $url = BASE_URL . 'invoices.xml';
  $ch = curl_init();
  $postdata = '<?xml version="1.0" encoding="UTF-8"?>
    <invoice>
      <client_id>' . $client_id . '</client_id>
      <currency_id>' . $currency_id . '</currency_id>
      <document_date>2014-05-20</document_date>
      <document_series_id>' . $invoice_series_id . '</document_series_id>
      <document_series_counter>' . $document_series_counter . '</document_series_counter>
      <vat_type>1</vat_type>
      <delegate_id>525664463</delegate_id>
      <display_transport_data>1</display_transport_data>
      <document_positions>
        <document_position>
          <description>ABONAMENT BASIC</description>
          <unit>luni</unit>
          <unit_count>12</unit_count>
          <price>12</price>
          <product_code>66XXH663496H</product_code>
          <vat>24</vat>
        </document_position>
        <document_position>
          <type>DiscountPosition</type>
          <description>Reducere pentru plata in avans</description>
          <discount_rate>10</discount_rate>
        </document_position>
      </document_positions>
    </invoice>';

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
          // transform the invoice data from xml to a array
    $invoice_data = json_decode(json_encode(simplexml_load_string($result)), TRUE);
    echo 'Invoice created successfully. Invoice id: ' . $invoice_data['id'];
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }

?>

Modificare factură (xml)

  curl -i -H 'Content-Type: application/xml' \
  -X PUT https://factureaza.ro/api/v1/invoices/1065253716.xml -u 123:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <invoice>
    <due_days>10</due_days>
  </invoice>'

Modificare poziții (xml) toate pozițiile trebuie specificate, nu doar cele actualizate.

  curl -i -H 'Content-Type: application/xml' \
  -X PUT https://factureaza.ro/api/v1/invoices/100.xml -u [api_key]:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <invoice>
    <document_positions>
      <document_position>
        <description>ABONAMENT STANDARD</description>
        <unit>luni</unit>
        <unit_count>12</unit_count>
        <price>35</price>
        <vat>24</vat>
      </document_position>
      <document_position>
        <type>DiscountPosition</type>
        <description>Reducere pentru plata in avans</description>
        <discount_rate>10</discount_rate>
      </document_position>
    </document_positions>
  </invoice>'

7.1.12. Căutare facturi

Accesibilă la adresa /api/v1/invoices/search.xml?field=[key]&value=[val] (HTTP GET).

Semnificația parametrilor:

key: reprezintă unul din câmpurile: document_state client_id document_series_id document_date document_series_counter created_at updated_at vat_type cached_total reversed_document_id
val: termenul de căutare

Exemplu de cod php pentru căutare factură după data creării:

  <?php
  //set BASE_URL to https://factureaza.ro/api/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'invoices/search.xml?field=created_at&value=2014.06.06';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

7.1.13. Facturi de stornare

O factură de stornare este o factură obișnuită. Singura diferență o fac două câmpuri: reversed_document_id, id-ul facturii stornate, și input_currency_reversing, valoarea stornată din ea.

reversed_document_id este returnat atât de DETALII cât și de LISTARE, unde apare doar la facturile de stornare — el este semnalul după care le recunoști într-o listare.

Pentru a nu le prelua deloc, listarea acceptă un parametru dedicat:

LISTARE FĂRĂ STORNĂRI https://factureaza.ro/api/v1/invoices.xml?reversing=false (HTTP GET) LISTARE DOAR STORNĂRI https://factureaza.ro/api/v1/invoices.xml?reversing=true (HTTP GET)

Valorile acceptate:

false 0 no — toate facturile, fără cele de stornare
true 1 yes — doar facturile de stornare

Funcția php http_build_query transformă true/false în 1/0, de aceea sunt acceptate ambele scrieri. Fără acest parametru listarea rămâne neschimbată, cu toate facturile. O valoare pe care nu o recunoaștem întoarce 400, ca să nu primești din greșeală lista nefiltrată.

Parametrul se aplică la fel și celorlalte modele de documente (proforme, avize, chitanțe), unde însă nu există stornări.

Exemplu de cod php: facturile emise și rămase de încasat, fără stornări

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'invoices.xml?' . http_build_query(array('reversing' => 'false'));
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  curl_close($ch);

  $invoices = simplexml_load_string($result);
  foreach ($invoices->invoice as $invoice) {
    // emisa (nu ciorna, nu anulata) si cu rest de plata
    if ($invoice['document_state'] == 'open' && (float)$invoice['total_due'] > 0) {
      echo $invoice['series'] . ' - ' . $invoice['total_due'] . ' ' . $invoice['currency'] . "\n";
    }
  }
?>

Pentru drumul invers — ce stornare anulează o factură anume — folosește căutarea descrisă la 7.1.12:

CĂUTARE STORNĂRI https://factureaza.ro/api/v1/invoices/search.xml?field=reversed_document_id&value=[id_factura_stornata] (HTTP GET)

7.2. Factură proformă

Nume model: proforma_invoice

Pot fi descărcate direct și în format PDF, folosind aceleași date de autentificare ca la orice alt apel API:

DESCĂRCARE PDF https://factureaza.ro/api/v1/proforma_invoices/[id].pdf (HTTP GET) DESCĂRCARE PDF curl -i -u [api_key]:x -o proforma.pdf https://factureaza.ro/api/v1/proforma_invoices/1.pdf

(vezi factură )

7.3. Aviz

Nume model: notice

Pot fi descărcate direct și în format PDF, folosind aceleași date de autentificare ca la orice alt apel API:

DESCĂRCARE PDF https://factureaza.ro/api/v1/notices/[id].pdf (HTTP GET) DESCĂRCARE PDF curl -i -u [api_key]:x -o aviz.pdf https://factureaza.ro/api/v1/notices/1.pdf

(vezi factură )

7.4. Chitanță

Nume model: receipt

Pot fi descărcate direct și în format PDF, folosind aceleași date de autentificare ca la orice alt apel API:

DESCĂRCARE PDF https://factureaza.ro/api/v1/receipts/[id].pdf (HTTP GET) DESCĂRCARE PDF curl -i -u [api_key]:x -o chitanta.pdf https://factureaza.ro/api/v1/receipts/1.pdf

vezi factură , precum și următoarele câmpuri adiționale:

receipt_amount* - suma încasată în RON

amount (R) - suma încasată calculată în moneda facturii aferente;

ex: pentru 100 RON încasați pe o factură în RON va returna 100
ex: pentru 100 RON încasați pentru o factură în EUR va returna suma in EUR (cca 25)

invoice_id - identificatorul facturii aferente acestei chitanțe

invoice_date - data facturii aferente acestei chitanțe

invoice_number - numărul facturii aferente acestei chitanțe

Datele emitentului

user_cnp user_first_name user_id user_identity_document user_identity_document_issue_date user_identity_document_issued_by user_identity_document_number user_identity_document_series user_last_name

7.5. Plată

Nume model: payment

amount * - suma achitată

currency_id - idenfiticatorul monedei plății

currency (agregat, R) - moneda plății

payment_date * - data plății

description - descriere

invoice_id ** - identificatorul facturii aferente

proforma_invoice_id ** - identificatorul proformei aferente

** Se va specifica cel puțin unul dintre câmpurile invoice_id și proforma_invoice_id

Adăugare plată la o factură (fragment php):

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $currency_id = 183;
  $invoice_id = 1065257565; // your invoice id here

  $attributes = array(
    "payment" => array(
      "amount" => '1001.11',
      "currency_id" => $currency_id,
      "payment_date" => '2015-02-20',
      "description" => 'prin ordin de plata - Banca Transilvania',
      "invoice_id" => $invoice_id
      )
    );
  $url = BASE_URL . 'payments.xml';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($attributes));
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
    echo 'Created successfully';
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

7.5.1. Căutare plăți

Accesibilă la adresa /api/v1/payments/search.xml?field=[key]&value=[val] (HTTP GET).

Semnificația parametrilor:

key : reprezintă unul din câmpurile: payment_date proforma_invoice_id invoice_id description created_at updated_at
val: termenul de căutare

Exemplu de cod php pentru căutare plată după dată:

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'payments/search.xml?field=payment_date&value=2014.06.06';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

7.6. Serii documente

Nume model: polimorfic, și anume:

facturi, accesibile la /api/v1/invoice_series
proforme, accesibile la /api/v1/proforma_invoice_series
avize, accesibile la /api/v1/notice_series
chitanțe, accesibile la /api/v1/receipt_series

Câmpuri:

counter_current - numărul ultimului document generat pe baza acestei serii
prefix - prefixul numerelor generate
suffix - sufixul numerelor generate
sepparator - separatorul folosit la generarea numerelor
year - anul valabilității seriei

Creare serie facturi proforme - fragment php:

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'proforma_invoice_series.xml';
  $ch = curl_init();
  $postdata_with_suffix = '<?xml version="1.0"?>
    <proforma_invoice_series>
      <counter_start>100</counter_start>
      <counter_current>100</counter_current>
      <prefix>PREFIXUSS</prefix>
      <sepparator>-</sepparator>
      <suffix>SUPREFIXUS</suffix>
      <year>2021</year>
    </proforma_invoice_series>';

  $postdata_without_suffix = '<?xml version="1.0"?>
    <proforma_invoice_series>
      <counter_start>100</counter_start>
      <counter_current>100</counter_current>
      <prefix>PREFIXUSS</prefix>
      <sepparator>-</sepparator>
      <year>2021</year>
    </proforma_invoice_series>';


  # a little bit of randomness :)
  $postdata = (mt_rand(0, 10) > 4) ? $postdata_without_suffix : $postdata_with_suffix;

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_POSTFIELDS, $postdata);
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/xml'));
  $result = curl_exec($ch);
  $header = curl_getinfo($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode == 201) {
            // transform the invoice data from xml to a array
    $invoice_data = json_decode(json_encode(simplexml_load_string($result)), TRUE);
    echo 'Proforma Invoice Series created successfully. Series id: ' . $invoice_data['id'];
  } else {
    echo  '<pre> Error occured: ' . $httpCode . ':' . $result . '</pre>';
  }
?>

7.7. Client

Nume model: client; permite scrierea (adăugare, modificare, ștergere). Vezi instrucțiunile pentru scriere.

name * - Numele clientului

is_company - Indică dacă clientul este persoană juridică

Date fiscale

registration_id - numărul de înregistrare la registrul comerțului

tax_id - identificator TVA (RO pentru plătitori TVA din România)

uid ** - identificator fiscal (CIF pentru România)

Adresă

address * - adresa clientului

address_2 - adresa clientului (cont.)

city * - orașul

zip - codul poștal

state - regiunea administrativă (județ, land etc.)

country_id * - identificatorul țării

country (agregat, R) - țara

Date bancare

bank_iban - codul iban al contului clientului

bank_name - numele băncii

Date de contact

email fax homepage telephone

** Obligatoriu doar în cazul clienților persoane juridice

7.7.1. Căutare clienți

Accesibilă la adresa /api/v1/clients/search.xml?field=[key]&value=[val] (HTTP GET)

Semnificația parametrilor:

key: reprezintă unul din câmpurile: name uid email created_at updated_at
val: termenul de căutare

Exemplu de cod php pentru căutare client după CIF:

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'clients/search.xml?field=uid&value=13548146';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

7.7.2. Fișa clientului

Accesibilă la adresa /api/v1/clients/[id]/sheet.xml.

Conține:

lista facturilor cu plățile aferente
sumele restante defalcate pe monedă
abonamentele (facturi recurente) la care este trecut acest client se vor afișa doar abonamentele care încă sunt active pentru acest client

Exemplu sume restante:

  <dues>
  <due currency="EUR" amount="100"/>
  <due currency="RON" amount="200"/>
  ...
</dues>

Abonamente (facturi recurente)

Toate câmpurile sunt read-only.

payment_start_at (R) - data de la care a început abonamentul pentru acest abonat

payment_end_at (R) - data pâna la care este activ abonamentul

covered_until (R) - data până la care s-au emis facturile pentru acest abonat

schedule_unit (R) - unitatea unui ciclu abonamentului (d - zi, w - săptamânp, m - month, y - an)

schedule_unit_count (R) - numărul de unități ale unui ciclu

price (R) - prețul pe ciclu al abonamentului

currency (R) - moneda

recurrent_name (R) - numele abonamentului

Atenție: Prețul este pentru un ciclu de facturare întreg. Astfel, dacă facturarea se face trimestrial (schedule_unit = m și schedule_unit_count = 3) și prețul este 100, atunci prețul per lună este 100 / 3 = 33

Exemplu listă abonamente (facturi recurente):

  <recurrent_jobs>
  <recurrent_job schedule_unit_count="1" payment_end_at="" schedule_unit="m" price="1.19" payment_start_at="2011-01-01"
  recurrent_name="standard" currency="RON" covered_until="" id="1"/>
  ...
</recurrent_jobs>

7.8. Produs

Nume model: product; permite scrierea (adăugare, modificare, ștergere). Vezi instrucțiunile pentru scriere.

code - codul intern folosit de utilizator pentru acest produs

description* - descrierea produsului

quantity - cantitatea implicită

unit - număr unități

price - preț

vat - cota TVA

currency_id * - identificatorul monedei

currency (agregat, R) - moneda

disabled - produs dezactivat (nu mai apare în sugestiile de produse din aplicație)

7.8.1. Căutare produse

Accesibilă la adresa /api/v1/products/search.xml?field=[key]&value=[val] (HTTP GET).

Semnificația parametrilor:

key: reprezintă unul din câmpurile: code description price created_at updated_at
val: termenul de căutare

Exemplu de cod php pentru căutare produs după descriere:

  <?php
  //set BASE_URL to https://factureaza.ro/api/v1/ for production
  define('BASE_URL', 'https://sandbox.factureaza.ro/api/v1/');
  //replace with the api key provided in the backend
  define('API_KEY', '72543f4dc00474bc40a27916d172eb93339fae894ec7a6f2dceb4751d965');

  $url = BASE_URL . 'products/search.xml?field=description&value=cartofi%20albi100';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_USERPWD, API_KEY . ":x");
  curl_setopt($ch, CURLOPT_URL, $url );
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  $result = curl_exec($ch);
  curl_close($ch);
  echo  '<pre>' . htmlentities($result) . '</pre>';
?>

7.9. Moneda

Nume model: currency

iso_name - codul ISO al monedei

7.10. Țara

Nume model: country

name - numele țării

iso - codul ISO al țării

7.11. Datele contului

Nume model: account (singular!)

Accesibile la adresa /api/v1/account.xml , doar pentru citire.

name - numele contului

disabled - activ / inactiv

disabling_reason - motivul dezactivării

total_open - total de plată

total_overdue - total scadent

branch_offices - lista a punctelor de lucru

company_vat_id - Cod TVA (pentru operațiuni intracomunitare)

company_euid - Identificator Unic la Nivel European (EUID)

Câmpuri identice cu ale unui client :

company_name company_uid company_registration_id company_tax_id company_address_1 company_address_2 company_state company_city company_country_id company_zip company_web company_phone company_fax company_email

7.12. Punct de lucru

Nume model: branch_office

name address_1 address_2 state city zip phone fax

Documentație API

API (Application Programming Interface) îți pune la dispoziție resursele

În continuare vei regăsi tot ce este necesar pentru integrarea software-ului tău.

1. Resurse și URL-uri

Listare facturi

Detalii factură

Schimbare stare factură

Modificare factură

Modificare date client + factură asociată

Listare clienți

Adăugare client

Căutare clienți

Detalii client

Modificare client

Ștergere produs

2. Sistem sandbox pentru testarea API

3. Autentificare

4. Rezultate și erori

4.1. Limite de cereri și header-ele de răspuns

5. Câmpuri și tipuri de date

6. Operațiuni de scriere

6.1. Exemple scriere

Modificare nume client (xml):

Modificare nume client (application/x-www-form-urlencoded):

Adăugare produs (xml):

După adăugarea unei înregistrări, in header-ul `Location’ al răspunsului va fi returnat URL-ul la care noua înregistare este disponibilă, iar în body va fi returnată toată înregistrarea

7. Modele

7.1. Factura

7.1.1. Datele emitentului

7.1.2. Datele clientului

7.1.3. Moneda facturii

7.1.4. Datele documentului

Exemplu creare factură de stornare parţială

7.1.5. Date legate de expediție

7.1.6. Alte câmpuri

7.1.7. Flaguri

7.1.8. Pozițiile de pe factură

7.1.9. Stările facturii

7.1.10. Trimitere factură pe email

7.1.11. Exemple editare facturi

7.1.12. Căutare facturi

7.1.13. Facturi de stornare

7.2. Factură proformă

7.3. Aviz

7.4. Chitanță

7.5. Plată

7.5.1. Căutare plăți

7.6. Serii documente

7.7. Client

7.7.1. Căutare clienți

7.7.2. Fișa clientului

7.8. Produs

7.8.1. Căutare produse

7.9. Moneda

7.10. Țara

7.11. Datele contului

7.12. Punct de lucru

Acest site utilizează cookie-uri

Tipuri de cookie-uri

Ce sunt cookie-urile?

API (Application Programming Interface)
îți pune la dispoziție resursele