Chei API

La ce folosește

O cheie API lasă un script sau un server al firmei să citească date fără sesiunea unui om. Cheia aparține firmei, are un rol de firmă, o dată de expirare și se poate revoca oricând, fără să schimbi parola cuiva.

Cheia arată așa: ilk_ urmat de 43 de caractere (32 de octeți aleatori în base64url). Platforma păstrează doar amprenta ei SHA-256, nu cheia. De aceea cheia întreagă se vede o singură dată, în răspunsul la creare.

Cum o trimiți

În antetul Authorization, cu schema Bearer:

curl https://app.ilustromania.com/nucleu/v1/stoc \
  -H "Authorization: Bearer $CHEIE_API"

O cerere cu Bearer ilk_… se judecă doar după cheie: cookie-ul de sesiune din aceeași cerere nu se mai citește. Firma și rolul vin din cheie; antetul X-Firma-Tab poate numi doar firma cheii, altfel răspunsul este 403.

Ce poate face o cheie

Accesul este închis implicit: o cheie trece doar pe rutele dintr-o listă fixă, numai cu metodele din listă. Pe orice altă rută răspunsul este 403 cu {"eroare": "interzis_cu_cheie_api"}.

În referința API, rutele care merg cu o cheie au mențiunea „merge și cu o cheie API”. Lista se lărgește doar cu rutele care decid accesul pe rolul și firma cererii, fără să recitească drepturile contului care a creat cheia; o rută nouă pe listă apare în Noutăți.

Pe lângă listă, mai contează două lucruri:

• Doar citire. O cheie creată cu doarCitire: true (implicit) primește 403 cu {"eroare": "cheie_doar_citire"} la orice metodă în afară de GET și HEAD.
• Rolul nu trece peste cel al creatorului. La fiecare cerere, contul care a creat cheia trebuie să fie încă activ pe firmă și să fie admin sau să aibă chiar rolul cheii. Dacă nu mai este, cheia nu mai merge (401).

Gestionarea cheilor

Cheile se creează, se văd și se revocă doar de un Administrator al firmei, doar din sesiune (cookie). O cerere făcută cu o cheie API pe aceste rute primește 403: o cheie nu poate crea altă cheie.

1. Creează cheia

   Crearebash

   curl -X POST https://app.ilustromania.com/nucleu/v1/chei-api \
     -H "Cookie: __Host-sesiune=$JETON_SESIUNE" \
     -H "Content-Type: application/json" \
     -d '{"nume": "Raport stoc zilnic", "rol": "gestiune", "doarCitire": true, "zile": 90}'

   Câmp	Tip	Obligatoriu	Detalii
   nume	string	da	între 1 și 80 de caractere, fără caractere de control; te ajută să recunoști cheia în listă
   rol	string	da	una din: bucatar, casier, gestiune, patron, marketing, angajat, finante; niciodată admin
   doarCitire	boolean	nu	implicit true; false = cheia poate și scrie, în limita rolului
   zile	integer	nu	după câte zile expiră: între 1 și 365, implicit 90

   Câmpurile necunoscute sunt refuzate (400 cu {"eroare": "corp_invalid"}).

2. Salvează cheia din răspuns

   Răspuns 201json

   {
     "cheie": "ilk_…",
     "detalii": {
       "id": "3f0c2a8e-6b1d-4c3a-9e2f-1a2b3c4d5e6f",
       "nume": "Raport stoc zilnic",
       "prefix": "ilk_Ab12Cd34",
       "rol": "gestiune",
       "doarCitire": true,
       "creataLa": "2026-11-12T09:30:00.000Z",
       "expiraLa": "2027-02-10T09:30:00.000Z",
       "revocataLa": null,
       "ultimaFolosire": null,
       "creataDe": "9b2e4c1a-7d3f-4e8b-a1c2-5f6e7d8c9b0a"
     }
   }

   cheie nu mai apare nicăieri după acest răspuns. În listă rămâne doar prefix (ilk_ și primele 8 caractere), ca să știi despre ce cheie e vorba.

3. Folosește-o, apoi revoc-o când nu mai e nevoie

   Revocarebash

   curl -X POST https://app.ilustromania.com/nucleu/v1/chei-api/$ID_CHEIE/revoca \
     -H "Cookie: __Host-sesiune=$JETON_SESIUNE"

   Răspunsul conține cheia cu revocataLa completat. O cheie deja revocată sau a altei firme dă 404 cu {"eroare": "negasit"}.

Câmpurile din listă

Limite și răspunsuri

• Expirarea este obligatorie: cel mult 365 de zile de la creare. O cheie expirată dă 401; pentru continuitate creezi una nouă înainte de expirare și o schimbi în script.
• Cel mult 20 de chei active pe firmă (nerevocate și neexpirate). A 21-a primește 409 cu {"eroare": "plafon_chei"}.
• Limita de cereri: fiecare cheie are numărătoarea ei, cu aceleași praguri ca o sesiune (vezi Limite); adresa IP se numără și ea.