Convenții

Adresa și autentificarea

Toate cererile merg la https://facturare.chappa.ro/api/v1, cu antetul Authorization: Bearer chf_…. Fără cheie, sau cu una revocată, răspunsul este 401 invalid_api_key. Cheile și permisiunile au pagina lor.

Formatul

• JSON în UTF-8, câmpuri în snake_case. Un câmp fără valoare este null, nu lipsește.
• Datele calendaristice: AAAA-LL-ZZ, în ora României. Momentele: RFC 3339 cu fus orar, de exemplu 2026-10-09T14:02:11+03:00.
• Sumele: numere, cu două zecimale la totaluri; prețurile unitare și cantitățile pot avea patru.
• Monedele: coduri ISO 4217 (RON, EUR); țările: ISO 3166-1 (RO).
• Id-urile sunt numere întregi, cu două excepții: facturile primite (id-ul mesajului din SPV) și evenimentele (evt_…).
• Câmpurile pe care nu le cunoaștem sunt o eroare (400 unknown_field): o greșeală de scriere nu trece neobservată.

Paginarea

Listele dau cele mai noi înregistrări primele, câte limit (1–100, implicit 25). Pagina următoare o ceri cu starting_after egal cu next_cursor din pagina de acum, cât timp has_more este true:

let after = null, all = [];
do {
  const url = `/api/v1/companies/7/documents?limit=100${after ? `&starting_after=${after}` : ''}`;
  const page = await api(url);
  all.push(...page.data);
  after = page.next_cursor;
} while (after);

Cursorul nu se strică dacă între timp apar înregistrări noi: nu sari peste nimic și nu primești nimic de două ori.

Idempotency-Key

La POST, PATCH și PUT poți trimite antetul Idempotency-Key, un id unic al operației (id-ul comenzii, un UUID). Dacă repeți cererea în 24 de ore cu aceeași cheie și același corp, primești răspunsul primei cereri, cu antetul Idempotent-Replayed: true, fără ca operația să se mai execute: o factură nu se emite de două ori pentru că s-a pierdut un răspuns.

• Aceeași cheie cu alt corp sau pe altă adresă: 422 idempotency_key_reused.
• Cât timp prima cerere încă rulează: 409 idempotency_in_progress.
• Erorile noastre (5xx) nu se păstrează: repetă cererea cu aceeași cheie.
• Cheile sunt ale cheii API: două chei API diferite nu se încurcă între ele.

Erorile

Orice eroare vine cu codul HTTP potrivit și un corp application/problem+json (RFC 9457). Decizia în programul tău o iei după code, care rămâne același; detail este pentru oameni și se poate schimba.

{
  "type": "https://facturare.chappa.ro/dezvoltatori/api-firma/conventii#erori-missing-permission",
  "title": "Permisiune lipsă",
  "status": 403,
  "code": "missing_permission",
  "detail": "Cheia nu are permisiunea „documents:submit” pe această firmă.",
  "request_id": "req_4f1c09a2b7e3d610",
  "permission": "documents:submit"
}

Limitele

O cheie face cel mult 300 de cereri pe minut. Fiecare răspuns spune cât mai ai:

Peste limită primești 429 rate_limited, cu Retry-After în secunde. Dacă ai de emis multe facturi deodată, trimite-le pe rând sau câteva în paralel, nu sute simultan.

Versiunile

/v1 nu se strică: putem adăuga oricând câmpuri noi în răspunsuri, endpointuri noi, tipuri noi de evenimente și valori noi în listele de stări, așa că programul tău trebuie să ignore ce nu cunoaște. O schimbare care ar strica un program existent vine într-o versiune nouă, /v2, anunțată din timp, cu /v1 păstrat în paralel.

Id-ul cererii

Fiecare răspuns are antetul X-Request-Id (și erorile, câmpul request_id). Dacă ne scrii despre o cerere, trimite-ni-l: găsim exact ce s-a întâmplat.

OpenAPI

Contractul complet, cu toate endpointurile și obiectele, este la /api/v1/openapi.json (OpenAPI 3.1), fără autentificare. Permisiunea cerută de fiecare operație este în descrierea ei și în x-permissions.

Obiectele comune

Obiectul Problem

Orice eroare, ca application/problem+json (RFC 9457).

Obiectul List

O pagină dintr-o listă, cea mai nouă înregistrare prima.

Obiectul Deleted

Răspunsul unei ștergeri.