API gratuit pentru facturile firmei tale și RO e-Factura

Pentru cine

Pentru firma ta: facturile firmelor la care ai acces în contul tău Chappa, emise de programele tale. Magazinul online emite factura la fiecare comandă plătită și o trimite în RO e-Factura; ERP-ul ia facturile primite de la furnizori; contabilitatea primește un webhook la fiecare factură validată de ANAF.

Este gratuit: fără abonament, fără plată pe factură și fără limită de facturi. O cheie face cel mult 300 de cereri pe minut.

Dacă vrei ca utilizatorii aplicației tale să își facă facturile pentru firmele lor, în aplicația ta, ai nevoie de integrare, nu de acest API.

Ce face

Facturi, proforme și stornări cu numerele din seriile firmei, TVA calculat pe linii, valută cu cursul BNR al zilei, client din agendă sau scris direct pe factură.
RO e-Factura: trimiterea în SPV prin conexiunea ANAF a firmei, răspunsul ANAF (validată sau respinsă, cu erorile), XML-ul UBL CIUS-RO și arhiva semnată de ANAF.
Încasări și chitanțe: plăți pe facturi, chitanțe pentru o factură sau la liber, starea plății fiecărei facturi.
PDF-uri cu sigla firmei, pentru facturi, chitanțe și facturile primite, plus trimiterea lor pe email.
Clienți și produse, legate de id-urile din programul tău prin ref.
Facturile primite de la furnizori în SPV, cu liniile, XML-ul și PDF-ul lor.
Webhookuri când se emite o factură, când ANAF o validează sau o respinge, când se încasează, când vine o factură de la un furnizor.

API-ul folosește aceleași reguli ca aplicația: o factură emisă prin API arată, se numerotează și se trimite exact ca una emisă din aplicație, și apare acolo imediat.

Prima cerere

1. Cheia. În aplicație, la API și webhookuri, faci o cheie nouă: îi dai un nume, alegi firmele și, pentru fiecare, ce are voie să facă. Cheia (chf_…) se arată o singură dată; pune-o în configurarea serverului tău.

Dialogul Cheie API nouă din Chappa Facturare: numele cheii și, pentru o firmă, permisiuni pe documente, încasări, clienți, produse și facturi primite, plus emitere și trimitere în RO e-Factura — Cheie nouă: firmele ei și, pentru fiecare, ce are voie să facă.

2. Verifici cheia și afli id-urile firmelor:

curl https://facturare.chappa.ro/api/v1/me \
  -H "Authorization: Bearer $CHAPPA_KEY"

3. Emiți o factură și o trimiți în RO e-Factura, într-o singură cerere:

curl https://facturare.chappa.ro/api/v1/companies/7/documents \
  -H "Authorization: Bearer $CHAPPA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: comanda-1042" \
  -d '{
    "client": { "name": "Beta Construct SRL", "cui": "RO18547290",
                "address": "Str. Fabricii 12", "city": "Sector 3", "county": "București" },
    "lines": [{ "name": "Abonament lunar", "quantity": 1, "unit_price": 250, "vat_percent": 21 }],
    "external_ref": "comanda-1042",
    "issue": true,
    "submit": true
  }'

Răspunsul (201) este factura întreagă: numărul, totalurile, scadența și efactura.status. Idempotency-Key face cererea sigură de repetat: dacă nu primești răspunsul și o trimiți din nou, primești aceeași factură, nu una nouă.

4. Afli răspunsul ANAF prin webhookul efactura.accepted (sau efactura.rejected, cu erorile), de obicei în câteva minute. Fără webhook, citești factura din nou cu GET /companies/7/documents/{id}.

Adresa și formatul

Adresa: https://facturare.chappa.ro/api/v1, doar HTTPS.
Autentificarea: antetul Authorization: Bearer chf_… la fiecare cerere.
Cereri și răspunsuri JSON (UTF-8), câmpuri în snake_case, date AAAA-LL-ZZ în ora României.
Erorile ca application/problem+json, cu un code stabil.
Doar de pe server: cheia nu are ce căuta într-un browser sau într-o aplicație de telefon, iar API-ul nu răspunde cererilor cross-origin din browser.

Toate regulile comune (paginare, idempotență, erori, limite, versiuni) sunt la convenții.

Un flux obișnuit

Un magazin online, la o comandă plătită cu cardul:

POST /companies/7/documents cu clientul, liniile, "payment_method": "card", "collected": true, issue și submit. Factura iese încasată și pleacă spre ANAF.
POST /companies/7/documents/812/email trimite PDF-ul clientului, cu un mesaj al tău.
Webhookul efactura.accepted confirmă validarea; păstrezi în comandă upload_index.
La un retur, POST /companies/7/documents/812/storno cu liniile returnate.

Firmele neverificate

O firmă adăugată de tine în aplicație este a ta până când cineva dovedește drepturile SPV pe codul ei fiscal, conectând-o la ANAF. Până atunci API-ul emite facturi, chitanțe și PDF-uri pentru ea, dar nu trimite în RO e-Factura, nu citește facturile primite și nu trimite emailuri: aceste cereri răspund company_not_verified. După conectare, aceeași cheie continuă, cu același id de firmă. Detaliile, inclusiv ce se întâmplă când firma există deja verificată, sunt la chei și permisiuni.

Contractul OpenAPI

Toate endpointurile și obiectele sunt descrise în openapi.json (OpenAPI 3.1): îl imporți în Postman, Insomnia sau Bruno, sau îți generezi un client în limbajul tău. Referința din paginile acestea este făcută din același fișier.