Documentație acces API factureaza.ro

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

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)

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.

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

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:

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

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: TVA (standard)
- 2: TVA inclus
- 3: TVA scutit cu drept de deducere
- 4: TVA scutit făra drept de deducere
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”

Date legate de expediție

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’
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]

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

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

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

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

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

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

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

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

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

Aplicaţie de facturare online

Documentație acces API factureaza.ro

Resurse și URL-uri

Autentificare

Rezultate și erori

Câmpuri și tipuri de date

Operațiuni de scriere

Exemple scriere

Modele

Factura

Datele emitentului

Datele clientului

Moneda facturii

Datele documentului

Date legate de expediție

Alte câmpuri

Flaguri

Pozițiile de pe factură

Pozițiile de discount

Stările facturii

Exemple editare facturi

Factură proforma

Aviz

Chitanță

Datele emitentului

Plată

Serii documente

Client

Date fiscale

Adresă

Date bancare

Date de contact

Fișa clientului

Abonamente (facturi recurente)

Produs

Moneda

Țara

Datele contului

Punct de lucru

Informații utile

Resurse

Contact

Despre noi

Aplicaţie de facturare online

Managementul unităţilor de cazare