Pornire rapidă API

De la zero la primul apel REST în **5 minute** — presupune că aveți deja cont utilizator cu drepturi API sau token creat din interfață.

Pregătire

Cerință	Unde obțineți
URL instanță	`https://flowscmc.ro` (sau TLD al organizației)
Credențiale	Cont utilizator sau token pre-generat din UI
ID companie	`GET /api/companies` după autentificare
Client HTTP	curl, Postman, Playground

1. Obțineți token Bearer


POST /api/auth/token
Content-Type: application/json
Accept: application/json

{
  "email": "integrator@exemplu.com",
  "password": "********",
  "abilities": ["articles:read", "stock:read", "sales-orders:read"],
  "device_name": "erp-prod-1"
}

Răspuns 200:


{
  "token": "1|xxxxxxxxxxxxxxxx",
  "abilities": ["articles:read", "stock:read", "sales-orders:read"]
}

Producție: preferați token creat din Administrare → Token-uri API cu abilities setate explicit, nu parola utilizatorului în script.

Exemplu curl


curl -sS -X POST "https://flowscmc.ro/api/auth/token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email":"user@firma.ro","password":"***","abilities":["stock:read"],"device_name":"curl-test"}'

2. Listați companiile accesibile


GET /api/companies
Authorization: Bearer 1|xxxxxxxx
Accept: application/json

Răspuns (exemplu):


{
  "data": [
    { "id": 42, "name": "ACME Logistics SRL", "code": "ACME-001" }
  ]
}

Notați id — îl folosiți la fiecare request de date ca X-Company-Id.

3. Apelați o resursă — listă articole


GET /api/articles?page=1
Authorization: Bearer 1|xxxxxxxx
X-Company-Id: 42
Accept: application/json

4. Apelați stoc


GET /api/stock
Authorization: Bearer 1|xxxxxxxx
X-Company-Id: 42
Accept: application/json

5. Revocați token (opțional)


POST /api/auth/revoke
Authorization: Bearer 1|xxxxxxxx

Util la rotație credențiale sau decommission integrare.

Headers — cheat sheet

Header	Obligatoriu	Exemplu
Authorization	da*	Bearer 1\	abc...
X-Company-Id	da (date)	42
Accept	recomandat	application/json
Content-Type	POST/PATCH	application/json
Idempotency-Key	POST critice	uuid v4
X-Three-Pl-Id	uneori	1

\* Except /api/auth/token, /api/health

Checklist integrator

[ ] Token cu abilities minime — nu *
[ ] X-Company-Id pe fiecare request de date
[ ] Gestionare 429 — retry cu backoff exponențial
[ ] Idempotency-Key pe POST SO/PO
[ ] Webhooks pentru evenimente — evitați polling la 5 secunde
[ ] Logging fără token în plain text
[ ] Timeout client ≥ 30s pentru operații batch

Health check (fără autentificare)


GET /api/health

Verifică: baza de date, cache, coadă joburi, spațiu disc. Util pentru monitoring extern.

Erori la primul apel

Răspuns	Verificați
401 Unauthorized	Token lipsă/invalid/expirat
403 Forbidden	Ability lipsă pe token
422 Unprocessable	X-Company-Id lipsă sau invalid
429 Too Many Requests	Reduceți frecvența

Următorii pași

Nivel	Resursă
Arhitectură completă	Ghid integrator
Referință endpoints	REST v1 · REST v2
Evenimente async	Webhooks
Query flexibil	GraphQL
Test interactiv	Playground
Exemple curl	Exemple requesturi

Exemplu flux complet (pseudo-cod)


1. token = POST /api/auth/token
2. companies = GET /api/companies (Bearer token)
3. companyId = companies[0].id
4. stock = GET /api/stock (Bearer + X-Company-Id: companyId)
5. IF stock[sku].available >= qty:
     POST /api/sales-orders { lines: [...] }
     SUBSCRIBE webhook sales_order.status_changed
6. ON webhook status=LIVRAT → update ERP

Detalii business: Workflow depozit.