Cum generezi API keys pentru integrari externe

Pentru a integra SoftFactura cu alte aplicații (ERP, CRM, e-commerce, automatizări), ai nevoie de o cheie API (API key). Cheia se generează din panoul Dezvoltatori și se folosește pentru autentificarea cererilor către API-ul public SoftFactura.

Generare API key

1. Mergi la Dezvoltatori din meniul lateral (sau accesează direct /dezvoltatori).
2. In tab-ul API Keys, apasă Cheie nouă.
3. Completează:
   • Nume — un nume descriptiv pentru a identifica integrarea (ex: „ERP Saga", „WooCommerce sync", „Automatizare facturi").
   • Permisiuni (scopes) — alege read (doar citire), write (citire și scriere) sau ambele. Costuri de achiziție (costs:read) se bifează separat, doar dacă integrarea are nevoie de ele.
4. Apasă Creează.
5. Copiază cheia imediat — este afișată o singură data și nu poate fi recuperata ulterior.

Utilizare în cereri API

Include cheia în header-ul Authorization al fiecărei cereri:

Authorization: Bearer sf_live_a1b2c3d4e5f6...

Exemplu cURL:

curl -H "Authorization: Bearer sf_live_a1b2c3d4e5f6..." \
     https://api.softfactura.ro/public/v1/invoices

Permisiuni (Scopes)

Scope	Ce permite
read	Listare și vizualizare facturi emise, clienti, produse, plăți (facturile primite de la furnizori nu se văd prin API)
write	Creare, editare, ștergere facturi, clienti, produse + trimitere e-Factura
costs:read	Costul ultimei achiziții pe produs (GET /products/costs). Nu e inclus în read sau write — se acordă separat

• O cheie cu doar read nu poate crea sau modifică resurse.
• O cheie cu write include implicit și permisiunile read.
• costs:read nu vine cu nicio altă permisiune: o cheie cu read sau write nu poate citi GET /products/costs.
• Alege permisiunile minime necesare pentru integrarea ta (principiul least privilege).

Revocare și ștergere

Revocare

1. În lista API Keys, apasă iconita de revocare pe cheia dorită.
2. Cheia devine inactivă imediat — toate cererile viitoare cu această cheie vor primi eroare 401.
3. Cheia revocată rămâne vizibilă în lista pentru audit.

Ștergere

1. Apasă iconita de ștergere pe o cheie revocată sau activă.
2. Cheia este eliminată complet — nu mai apare în lista.
3. Această acțiune este ireversibilă.

Bune practici de securitate

• Nu include cheia API în codul sursa al aplicatiei — folosește variabile de mediu (environment variables).
• Nu partaja cheia prin email sau chat neencriptat — folosește un manager de parole sau un vault securizat.
• Roteste cheile periodic — creează o cheie nouă, actualizează integrarea, apoi revoce cheia veche.
• Creează chei separate pentru fiecare integrare — dacă o integrare este compromisă, revoci doar cheia respectivă fără a afecta celelalte.
• Monitorizează utilizarea — verifică câmpul „Ultima utilizare" din lista API Keys pentru a detecta chei inactive sau utilizare suspectă.