API pentru dezvoltatori

1. Adresa și autentificarea

Fiecare firmă are propriul subdomeniu, iar API-ul răspunde DOAR pe el:

https://<firma>.depozio.ro/api/v1

Autentificarea e un token Bearer, generat din panou: Setări → Sincronizare API → „Emite token nou”. Token-ul se vede o singură dată, la emitere. Îi alegi scope-urile și termenul de expirare (inclusiv „fără expirare”), iar data expirării se vede în tabelul de token-uri — nu moare nimic pe nespuse.

Scope-uri disponibile:

2. Antete

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json          # pe POST
Idempotency-Key: <UUID v4>              # opțional, recomandat pe POST

Idempotency-Key e un UUID per request (nu per comandă). Același key în 24 de ore întoarce exact răspunsul anterior, deci poți relua în siguranță după un timeout. Două detalii care contează: se memorează doar răspunsurile 2xx (un retry după 422 cu payload corectat se procesează normal), iar același key cu alt corp întoarce 409 idempotency_key_conflict.

3. Endpoint-uri

Comenzi

Produse

Stoc

Retururi

Puncte de livrare

Formatul complet al fiecărui corp (câmpuri, validări, exemple) e în specificația pe care ți-o trimitem la cerere — scrie-ne de pe pagina de contact.

4. Webhook-uri către tine

Configurezi o adresă HTTPS în panou, iar Depozio îți trimite acolo un POST semnat (HMAC-SHA256 pe corpul brut, în antetul de semnătură) la fiecare eveniment:

• order.status_changed
• order.shipped
• order.delivered
• order.returned
• return.status_changed
• stock.threshold_alert
• stock.insufficient
• order.blocked

Livrările se reîncearcă, iar fiecare încercare se vede în panou, cu răspunsul primit — deci un webhook picat nu e o presupunere, e un rând pe care îl poți retrimite.

5. Erori

Orice eroare are aceeași formă, cu un cod stabil pe care poți ramifica:

{
  "status": "error",
  "error": "validation_failed",
  "message": "...",
  "errors": { "items.0.sku": ["..."] }
}

Coduri uzuale: unauthenticated, missing_ability, validation_failed, missing_skus, order_not_found, order_in_progress, rate_limited, tenant_suspended. Mesajele sunt în engleză și sunt pentru dezvoltator, nu pentru utilizatorul final.

6. Versionare, stabilitate, CORS

API-ul e server-to-server: token-ul nu are ce căuta într-un browser, deci nu publicăm antete CORS pentru terți. Cheamă-l din backend-ul tău.

Versiunea trăiește în cale (/api/v1). Ne angajăm ca v1 să rămână stabil cel puțin 12 luni după anunțul unei versiuni noi. Adăugăm câmpuri fără preaviz — clientul tău trebuie să ignore ce nu cunoaște —, dar nu ștergem și nu schimbăm sensul unui câmp existent în v1. Când ceva intră în retragere, răspunsurile poartă antetele Deprecation și Sunset, deci o poți vedea din cod, nu dintr-un email.

7. Limite

Cererile cu token valid intră pe limita standard per token; cele fără token au o limită mai strânsă, per IP. La depășire primești 429 rate_limited cu antetul Retry-After — respectă-l, nu relua imediat.