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

Mergi la Dezvoltatori din meniul lateral (sau accesează direct /dezvoltatori).
In tab-ul API Keys, apasă Cheie nouă.
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.
Apasă Creează.
Copiază cheia imediat — este afișată o singură data și nu poate fi recuperata ulterior.

Cheia API are formatul sf_live_ urmat de 48 de caractere hexazecimale. Doar primele 16 caractere (prefix-ul) sunt vizibile după creare — restul este stocat criptat și nu mai poate fi afișat.

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/v1/invoices

Permisiuni (Scopes)

Scope	Ce permite
`read`	Listare și vizualizare facturi, clienti, produse, plăți
`write`	Creare, editare, ștergere facturi, clienti, produse + trimitere e-Factura

O cheie cu doar read nu poate crea sau modifică resurse.
O cheie cu write include implicit și permisiunile read.
Alege permisiunile minime necesare pentru integrarea ta (principiul least privilege).

Revocare și ștergere

Revocare

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

Ștergere

Apasă iconita de ștergere pe o cheie revocată sau activă.
Cheia este eliminată complet — nu mai apare în lista.
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ă.