factureaza.ro
tu ce facturezi azi

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.

Comma

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/[model-plural].xml (HTTP GET) DETALII https://factureaza.ro/api/[model-plural]/[id].xml (HTTP GET) ȘTERGERE https://factureaza.ro/api/[model-plural]/[id].xml (HTTP DELETE) MODIFICARE https://factureaza.ro/api/[model-plural]/[id].xml (HTTP PUT) CREARE https://factureaza.ro/api/[model-plural].xml (HTTP POST)

Exemple folosind curl:

LISTARE curl -i -u [api_key]:x https://factureaza.ro/api/clients.xml DETALII curl -i -u [api_key]:x https://factureaza.ro/api/clients/1.xml ȘTERGERE curl -i -X DELETE -u [api_key]:x https://factureaza.ro/api/clients/1.xml MODIFICARE curl -i -X PUT -F "client[name]=Cubus" -u [api_key]:x https://factureaza.ro/api/clients/1.xml CREARE curl -i -X POST -d "client[name]=Cubus" -d "client[uid]=999999" -u [api_key]:x https://factureaza.ro/api/clients.xml

Exemple folosind php:

Listare facturi

Detalii factură

Schimbare stare factură

Modificare factură

Listare clienți

Adăugare client

Căutare clienți

Detalii client

Modificare client

Ștergere produs

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

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/clients/1.xml -u [api_key]:x \
  -d '<?xml version="1.0" encoding="UTF-8"?>
  <client>
    <name>Cubus</name>
    <uid>999999</uid>
  </client>'

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

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

Adăugare produs (xml):

  curl -H 'Content-Type: application/xml'
  -X POST https://factureaza.ro/api/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/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):

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

DESCĂRCARE PDF https://factureaza.ro/api/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:

  1. fără TVA
  2. TVA (standard)
  3. TVA inclus
  4. TVA scutit cu drept de deducere (s.c.d.d.)
  5. TVA scutit făra drept de deducere (s.f.d.d.)
  6. TVA taxare inversă
  7. TVA neinclus în baza de impozitare (n.î.b.i.)
  8. Regimul marjei - agenții de turism (r.m.a.t.)
  9. Regimul marjei - bunuri second-hand (r.m.b.s.h.)
  10. Regimul marjei - opere de artă (r.m.o.a.)
  11. 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ă

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.

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/[hashcode]

note - Note interne

account_company_pays_vat_on_payment - TVA la încasare

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/[model-plural]/[id]/mark_draft.xml - pentru starea ciornă

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

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

https://factureaza.ro/api/[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, body:

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

Trimitere factură pe email (fragment php):

7.1.11. Exemple editare facturi

Adăugare factură (xml)

  curl -i -H 'Content-Type: application/xml' \
  -X POST https://factureaza.ro/api/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):

Modificare factură (xml)

  curl -i -H 'Content-Type: application/xml' \
  -X PUT https://factureaza.ro/api/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/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/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:

7.2. Factură proforma

Nume model: proforma_invoice

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

DESCĂRCARE PDF https://factureaza.ro/api/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/notices/[id].pdf (HTTP GET)

(vezi factură )

7.4. Chitanță

Nume model: invoice

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

DESCĂRCARE PDF https://factureaza.ro/api/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):

7.5.1. Căutare plăți

Accesibilă la adresa /api/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ă:

7.6. Serii documente

Nume model: polimorfic, și anume:

  • facturi, accesibile la /api/invoice_series
  • proforme, accesibile la /api/proforma_invoice_series
  • avize, accesibile la /api/notice_series
  • chitanțe, accesibile la /api/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:

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/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:

7.7.2. Fișa clientului

Accesibilă la adresa /api/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/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 plată după dată:

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/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 - dentificator 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: