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)

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 = 1065255097;  // 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 = 1065255097;  // 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 = 1065255097;  // 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 = 1064116437;  // 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 = 1065255097;  // 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 = 1064116437;  // 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 = 1064116437;  // 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 = 741342700; // 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)

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/login
- 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
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)
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ă.

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>';
?>

Poate fi descărcate direct și în format PDF:

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

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

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 = 1064116437;
  $currency_id = 183;
  $invoice_series_id = 1061104533; // 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.

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 = 1065255097;  // 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 = 1064116437;
$currency_id = 183;
$invoice_series_id = 1061104533; // 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 = 1064116437;
  $currency_id = 183;
  $invoice_series_id = 1061104533; // 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
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.2. Factură proformă

Nume model: proforma_invoice

Pot fi descărcate direct și în format PDF:

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

(vezi factură )

7.3. Aviz

Nume model: notice

Pot fi descărcate direct și în format PDF:

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

(vezi factură )

7.4. Chitanță

Nume model: receipt

Pot fi descărcate direct și în format PDF:

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

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 = 1065255097; // 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

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

8. Callback la înregistrarea unei plăți online

După înregistrarea unei plăți online se trimite o structură de date cu detaliile facturii și a plății pe această adresă prin HTTP POST la adresa specificată în câmpul Callback URL al formularui de editare a parametrilor funcției de plată online.

Exemplu de cod php pentru procesarea requestului HTTP POST trimis:

  <?php
  // write post parameters to file - sample code for processing the callback after successfull payment
  $file_name_json = 'factureaza_callback_post_content.json';
  $document_as_json = file_get_contents('php://input');

  $fp_json = fopen($file_name_json, 'wt') or die('Could not open file! Make sure you have permission to create the file ' . $file_name_json);
  fwrite($fp_json, $document_as_json) or die('Could not write to file! Make sure you have write permission for the file ' . $file_name_json);
  fclose($fp_json);
?>

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

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.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

8. Callback la înregistrarea unei plăți online

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