Autentificare

Fiecare cerere către API trebuie să includă un Bearer token în antetul Authorization. Este singura metodă acceptată: antetul X-API-Key și parametrul ?api_key= în adresă nu funcționează.

Formatul token-ului

Tokenurile sunt restricționate la un singur tenant și au forma <slug-tenant>.<cheie>:

tenant.7c4a8d09ca3762af61e59520943dc26494f8941b

• Partea dinaintea punctului (aici tenant) este slug-ul tenantului tău — același care apare în subdomeniu (tenant.notsowms.ro). Îi indică platformei către ce bază de date să direcționeze cererea, încă dinainte ca cheia să fie validată.
• 7c4a8d09... este secretul propriu-zis. Tratează-l ca pe o parolă — oricine are tokenul complet poate acționa în limitele cheii.

Trimiterea token-ului

GET /api/v1/products HTTP/1.1
Host: tenant.notsowms.ro
Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b
Accept: application/json

curl:

curl https://tenant.notsowms.ro/api/v1/products \
  -H "Authorization: Bearer tenant.7c4a8d09ca3762af61e59520943dc26494f8941b" \
  -H "Accept: application/json"

Emiterea unei chei

Cheile se gestionează din interfața WMS, Setări → API & Webhooks → Chei API. Doar un administrator poate emite, roti sau revizui chei, iar emiterea necesită modulul API & Webhooks activ. Fiecare cheie nouă are, toate alese explicit (nimic nu este preselectat):

• Nume — etichetă descriptivă (ex. integrare eMag, sync-erp-intern).
• Proprietar — ce reprezintă cheia:
  • Tenant: nu este legată de un client; poate primi orice capabilitate din catalog.
  • Stoc propriu: limitată la stocul propriu al depozitului (clientul „stoc propriu” este stabilit de platformă).
  • Client: limitată la un singur client extern. Un client extern poate primi doar comenzi (citire și creare), produse, stoc (doar citire) și avize de expediție (ASN). Proprietarii de tip stoc propriu și client necesită modulul 3PL.
• Utilizator responsabil — utilizatorul activ căruia i se atribuie comenzile și mișcările de stoc făcute cu cheia.
• Depozite — toate depozitele (destinația se trimite explicit în cerere) sau un singur depozit fixat. O cheie fixată refuză un X-Warehouse-Id sau un warehouse_id diferit de depozitul ei și nu poate primi capabilități care nu sunt limitate la depozit (furnizori, curieri, facturi, service).
• Capabilități — o listă explicită de permisiuni de forma resursă:acțiune (ex. orders:read, products:write). Nu există acces complet și nu există wildcard. Acțiunea este read pentru GET/HEAD și write pentru celelalte metode. O cerere către o resursă neacoperită primește 403 cu {"error":"Missing capability: orders:write"}.
• Expirare — obligatorie. Implicit 90 de zile, cel mult 365 de zile de la emitere. Nu există chei fără termen.

După salvare, tokenul complet (<slug-tenant>.<cheie>) este afișat o singură dată, în fereastra de confirmare. Stochează-l imediat în managerul tău de secrete. Platforma păstrează doar un hash SHA-256 și nu îl poate recupera: o cheie pierdută se rotește sau se înlocuiește.

Excepții la nivel de client

Fixarea pe un depozit limitează comenzile, stocul, locațiile și zonele la acel depozit. Produsele și avizele de expediție (products:*, asns:*) aparțin clientului și acoperă toate depozitele lui, deci o cheie fixată pe un depozit le accesează în continuare la nivel de client. Interfața cere o confirmare explicită, pe fiecare astfel de capabilitate, înainte de emitere.

Valabilitate

O cheie activă nu este neapărat utilizabilă. Cheia încetează să funcționeze la primul dintre:

• data de expirare;
• termenul de revizuire, pentru o cheie veche revizuită (vezi mai jos);
• revocarea;
• indisponibilitatea utilizatorului responsabil, a clientului sau a depozitului fixat (cererile sunt refuzate, cheia nu se modifică).

Lista de chei afișează termenul efectiv, nu doar statusul.

Rotație

Rotația înlocuiește o cheie cu una nouă, fără întrerupere bruscă:

1. Din lista de chei, alege Rotește. Cheia nouă primește exact aceeași autoritate (sau una mai restrânsă, niciodată mai largă) și o expirare proprie.
2. Setezi suprapunerea: implicit 15 minute, între 0 și 1440 de minute. Cât ține suprapunerea, ambele chei funcționează; după aceea, cheia veche se oprește. Termenul cheii vechi nu se prelungește niciodată, doar se scurtează.
3. Muți integrările pe noul token, afișat o singură dată.

O cheie are un singur succesor, definitiv: chiar dacă succesorul este revocat sau expiră, cheia veche nu mai poate fi rotită din nou. Linia de rotație (înlocuiește / înlocuită de) este vizibilă în detaliile cheii.

Revocare

Revocarea este imediată și definitivă. Cheia nu se șterge: rămâne în listă, cu data, autorul, motivul și istoricul cererilor, ca dovadă. Revocarea funcționează și dacă modulul API & Webhooks nu mai este activ, astfel încât o cheie existentă să poată fi oprită oricând. Utilizatorii care nu sunt administratori văd și pot revoca doar cheile emise de ei sau atribuite lor.

Migrarea cheilor vechi

Cheile create înainte de autoritatea explicită sunt chei vechi (deseori cu permisiuni * sau nesetate și fără expirare). Trecerea se face în trei pași, din Inventar și migrare:

1. Pregătire: cheile vechi nerevizuite continuă să funcționeze cu comportamentul lor original; cheile noi și cele revizuite sunt deja stricte.
2. Revizuire: un administrator dă fiecărei chei veche o autoritate explicită (proprietar, utilizator responsabil, depozite, capabilități), un motiv și un termen de revizuire de cel mult 30 de zile. Revizuirea poate doar restrânge ce putea cheia veche, niciodată extinde, și nu prelungește expirarea originală. După termen, cheia este refuzată până la o nouă revizuire; o cheie deja înlocuită prin rotație nu se mai poate reînnoi. Valorile originale rămân în inventar ca dovadă, nu ca autoritate.
3. Mod strict: o simulare listează fiecare cheie care ar bloca trecerea. Activarea este distinctă, definitivă și recalculează blocajele chiar în acel moment; după ea, o cheie veche nerevizuită este refuzată cu api_key_review_required.

Raportul de migrare și aprobarea

Pentru fiecare tenant se poate genera un raport de migrare, doar în citire (nu modifică nicio cheie și nu conține tokenuri, hash-uri sau previzualizări de chei):

php artisan api-keys:inventory --tenant=<slug>                         # sumar și tabel în consolă
php artisan api-keys:inventory --tenant=<slug> --json                  # același conținut, mașină-lizibil
php artisan api-keys:inventory --tenant=<slug> --report=raport-<slug>.md

Sumarul numără cheile pe categorii (categoriile se pot suprapune): total, legacy_unreviewed (fără autoritate canonică), wildcard (toate capabilitățile sau nesetate), client_missing (cheie veche fără client sau cu client lipsă), needs_review (de revizuit înainte de modul strict), issued (emise cu autoritate explicită) și revoked_or_expired. Opțiunea --report scrie un document Markdown cu tenantul, faza, aceste numere, câte un rând pentru fiecare cheie (stări și modificări de comportament) și un tabel gol Revizuit de / Data / Decizie.

Raportul se parcurge împreună cu responsabilii integrărilor, iar tabelul de aprobare se completează de omul care decide: cine a revizuit raportul, când, și decizia (de exemplu, „se revizuiesc cheile marcate, apoi se trece la modul strict”). Abia după această aprobare se face simularea și activarea modului strict.

Erori legate de autentificare

Status	Body	Cauză
401	{"error":"API key missing. Use Authorization: Bearer <key>"}	Lipsește antetul Authorization cu Bearer token.
401	{"error":"Invalid API key."}	Token fără forma <tenant>.<cheie>, tenant necunoscut sau cheie necunoscută. Nu se dau detalii despre motiv.
403	{"error":"Account suspended."}	Tenantul este suspendat din panoul central de admin.
403	{"error":"API key is inactive."}	Cheia este inactivă.
403	{"error":"API key has been revoked."}	Cheia a fost revocată.
403	{"error":"API key has expired."}	Data de expirare a trecut.
403	{"error":"API key requires administrator review.","code":"api_key_review_required"}	Cheie veche nerevizuită după trecerea la modul strict, sau termenul de revizuire a expirat.
403	{"error":"API key owner is not available.","code":"api_key_principal_unavailable"}	Utilizatorul responsabil este inactiv sau a fost șters.
403	{"error":"Client API access is not available.","code":"api_key_client_unavailable"}	Clientul cheii este inactiv sau lipsește, sau funcția 3PL nu este activă.
403	{"error":"API key warehouse is not available.","code":"api_key_warehouse_unavailable"}	Depozitul fixat este inactiv, șters sau filtrul pe depozite este oprit.
403	{"error":"This API key is pinned to a different warehouse.","code":"api_key_warehouse_mismatch"}	Cererea indică alt depozit decât cel fixat.
403	{"error":"Missing capability: orders:write"}	Endpoint-ul cere o capabilitate pe care cheia nu o are.
403	{"error":"This resource is not available to client API keys."}	O cheie de client a cerut o resursă în afara celor permise clienților externi.
403	{"error":"…","code":"client_order_operation_forbidden"}	O cheie de client poate doar crea și citi comenzi; schimbarea statusului, ștergerea și anularea se fac de depozit.
403	{"error":"…","code":"api_key_state_unavailable"} / "api_key_authority_invalid"	Starea credențialelor sau autoritatea cheii nu poate fi verificată: cererea este refuzată.
404	{"error":"Unknown or inactive warehouse."}	X-Warehouse-Id indică un depozit inexistent sau inactiv.

Jurnalizare

Fiecare cerere autentificată este înregistrată cu metoda, calea, statusul răspunsului și durata; cheia, tokenul și hash-ul lor sunt șterse din ce se păstrează. Poți audita traficul unei chei, împreună cu istoricul de administrare (emitere, revizuire, rotație, revocare), din detaliile cheii în aceeași pagină de Setări.