Documentație acces API factureaza.ro

Loading

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ă

Listare clienți

Adăugare client

Căutare clienți

Detalii client

Modificare client

Stergere 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)

Sistem sandbox pentru testarea API

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

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:

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

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

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-DD
  • valori boolean vor fi reprezentate cu true / false
  • se folosesc identificatori (id) numerici

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

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>

Modele

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)

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)

Datele clientului

  • client_id * (RW) - identificatorul clientului
  • client_xxx (R) - toate datele unui client; (vezi clienți); la scriere se preiau automat din client

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.2 ptr EUR/RON)

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

  1. Sumele se introduc și se afișează în RON
    • se va specifica doar currency_id
  2. 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ă
  3. 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

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

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

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

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ă

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>

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

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)

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

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:

Factură proforma

Nume model: proforma_invoice

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

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

(vezi factură)

Aviz

Nume model: notice

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

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

(vezi factură)

Chitanță

Nume model: invoice

Poate 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 ptr o factură în RON va returna 100
    • ex: pentru 100 RON încasați ptr 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

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)

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

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

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 țarii
  • country (agregat, R) - țara
Date bancare
  • bank_iban - codul iban al contului clientului
  • bank_name - numele bancii
Date de contact
  • email
  • fax
  • homepage
  • telephone

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

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:

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

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

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

Moneda

Nume model: currency

  • iso_name - codul ISO al monedei

Țara

Nume model: country

  • name - numele țării
  • iso - codul ISO al țării

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

Punct de lucru

Nume model: branch_office

  • name
  • address_1
  • address_2
  • state
  • city
  • zip
  • phone
  • fax

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:

Click pentru ajutor live x ^