Lista principalelor endpoint-uri API publice

API-ul public SoftFactura urmeaza convențiile REST și returnează răspunsuri JSON. Toate endpoint-urile necesită autentificare cu cheia API, transmisă fie în header-ul X-Api-Key, fie ca Authorization: Bearer sf_live_....

URL de baza: https://api.softfactura.ro/public/v1

Facturi

Metoda	Endpoint	Descriere	Scope necesar
GET	/invoices	Lista facturi (paginată)	read
GET	/invoices/:id	Detalii factura	read
POST	/invoices	Creează factura nouă	write
PATCH	/invoices/:id	Actualizează factura	write
GET	/invoices/:id/pdf	Descarcă PDF factura	read
POST	/invoices/:id/send-email	Trimite factura pe email către client	write
GET	/invoices/:id/efactura/status	Status e-Factura ANAF pentru factura	read
POST	/invoices/:id/shipment	Generează AWB pentru factura (necesită modulul Curieri)	write

Legarea liniilor de produse + descărcarea stocului

Câmpuri opționale la POST /invoices (DOAR la creare — la PATCH sunt respinse cu field_not_supported_on_update, pentru că update-ul înlocuiește liniile fără legare de produse):

• lines[].product_id — leagă linia de un produs EXISTENT din catalog (UUID — string; vezi GET /products și /products/lookup). Produsul trebuie să aparțină firmei și să fie activ, altfel cererea e respinsă (invalid_product_id pentru UUID malformat sau tip greșit, product_not_found, product_inactive). Descrierea, prețul și TVA rămân cele trimise pe linie.
• lines[].code — cod produs (SKU): dacă firma are activată salvarea automată a produselor noi, linia e potrivită după cod cu catalogul (sau produsul e creat automat).
• descarca_stoc (pe document, default false) — dacă true, factura emisă descarcă stocul produselor gestionate, exact ca emiterea din aplicație, inclusiv verificările pre-emitere: stoc insuficient sau vânzare sub cost răspund 400 (below_cost). Cere modulul Stoc activ (stock_module_required) și, pe cheia API, scope-ul stock:read (verificările expun niveluri de stoc — 403 insufficient_scope altfel). Descărcarea propriu-zisă rulează asincron, imediat după emitere — confirmarea se vede în mișcările de stoc, nu în răspunsul HTTP. Ignorat pentru proforme.
• allow_below_cost (pe document, doar împreună cu descarca_stoc: true) — confirmă explicit vânzarea sub costul de achiziție (echivalentul confirmării din aplicație); fără el, liniile cu preț ≤ cost sunt respinse cu below_cost.

Creare factura — exemplu

POST /public/v1/invoices
{
  "client_id": "cl_abc123",
  "type": "factura",
  "currency": "RON",
  "issue_date": "2026-07-02",
  "due_date": "2026-08-01",
  "auto_submit_efactura": true,
  "lines": [
    {
      "description": "Servicii consultanta IT",
      "quantity": 10,
      "unit_price": 500,
      "vat_rate": 21
    }
  ]
}

Parametri de filtrare

• ?status=issued — filtrează după status (draft, issued, paid, cancelled).
• ?from=2026-01-01&to=2026-03-31 — interval de date.
• ?page=2&limit=50 — paginare (default: page 1, limit 20).

Clienti

Metoda	Endpoint	Descriere	Scope necesar
GET	/clients	Lista clienti	read
GET	/clients/:id	Detalii client	read
POST	/clients	Creează client nou	write
PATCH	/clients/:id	Actualizează client	write
DELETE	/clients/:id	Șterge client	write
GET	/clients/lookup/anaf/:cui	Preia datele firmei de la ANAF, după CUI	read
GET	/clients/lookup/vies/:vat	Verificare TVA intracomunitar (VIES)	read

Parametri de filtrare

• ?search=firma — caută după nume, CUI sau email.
• ?type=pj — filtrează după tip (pj = persoana juridica, pf = persoana fizica).

Produse (read-only)

Metoda	Endpoint	Descriere	Scope necesar
GET	/products	Lista produselor ACTIVE (paginată: ?page= / ?limit=, default 20, max 100; ?search= pe nume/cod/barcode/cod furnizor)	read
GET	/products/lookup?code=SKU123	Găsire exactă după cod intern / barcode / cod furnizor (doar produse active; found: false fără match)	read
GET	/products/:id	Detalii produs — întoarce și produsele dezactivate, cu is_active: false (utile la reconciliere); produsele șterse răspund 404 product_not_found	read

Stoc

Metoda	Endpoint	Descriere	Scope necesar
GET	/stock?code=SKU123	Stocul curent pentru un produs, după cod	read
GET	/stock/all	Stocul curent pentru toate produsele	read

Informații cont

Metoda	Endpoint	Descriere	Scope necesar
GET	/account	Informații firma și abonament	read

Calcul TVA

Metoda	Endpoint	Descriere	Scope necesar
POST	/tax/calculate	Calcul automat cota TVA pe baza tipului de client, țară și produs	read

Format răspuns

Toate răspunsurile urmeaza un format consistent:

{
  "data": { ... },
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Erorile returnează:

{
  "error": {
    "type": "validation_error",
    "code": "missing_client_id",
    "message": "client_id is required",
    "field": "client_id"
  },
  "meta": {
    "request_id": "req_24e4cae10b0846ffb261b40d",
    "api_version": "v1"
  }
}

Coduri HTTP

Cod	Semnificație
200	Succes
201	Resursa creată cu succes
400	Date invalide (verificare parametri)
401	Cheie API invalida sau lipsa
403	Permisiuni insuficiente (scope lipsa)
404	Resursa nu exista
429	Rate limit depășit
500	Eroare server