Ghid integrator ERP / WMS

Ghid complet pentru echipele tehnice care conectează **ERP sau e-commerce** la flowSCMC: arhitectură, securitate, pattern-uri recomandate și capcane de evitat.

Arhitectura integrării


┌─────────────┐     HTTPS REST/GraphQL     ┌──────────────────┐
│  ERP / shop │ ◄──────────────────────► │    flowSCMC      │
│  e-commerce │     Webhooks (outbound)   │  (multi-tenant)  │
└─────────────┘ ◄─────────────────────── └──────────────────┘
                      HMAC signed

Direcție	Mecanism	Caz tipic
Inbound (spre flowSCMC)	REST v1/v2, GraphQL	Creare SO, sync articole, citire stoc
Outbound (din flowSCMC)	Webhooks HMAC	Notificare livrare, stoc scăzut
Inbound dedicat	`/api/integrations/etsm/*`	Transport eTSM

Principii de design

1. Multi-tenant — context obligatoriu

Fiecare request de date trebuie să specifice compania:


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

Fără X-Company-Id → 422 sau date goale. Token-ul poate avea acces la mai multe companii — listați cu GET /api/companies.

2. Permisiuni minime (abilities)

La emitere token, solicitați doar ce folosiți:


{
  "email": "integrator@firma.ro",
  "password": "***",
  "abilities": ["articles:read", "stock:read", "sales-orders:write"],
  "device_name": "erp-prod-main"
}

Evitați * în producție. Revocați token-uri vechi: POST /api/auth/revoke.

3. Idempotency pe operații critice

Pentru POST care creează documente, trimiteți header:


Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Reîncercarea cu aceeași cheie nu dublează comanda.

4. Rate limit și retry

Limită tipică: ~60 req/min per companie
Răspuns 429 — backoff exponențial (1s, 2s, 4s… max 60s)
Nu faceți polling agresiv — preferați webhooks

Pattern-uri recomandate

Sync articole (ERP → flowSCMC)

Pas	Acțiune
1	`GET /api/articles/sync?since={iso8601}` — delta
2	Pentru fiecare articol nou/modificat: `POST /api/articles` sau `PATCH /api/articles/by-code/{code}`
3	Stocați maparea `erp_id ↔ flowscmc_id` în baza dvs.

Comandă vânzare (ERP → depozit)

Pas	Acțiune
1	Verificați stoc: `GET /api/stock?article_code=SKU-001`
2	Creați SO: `POST /api/sales-orders` (v1) sau `POST /api/v2/sales-orders`
3	Abonați webhook `sales_order.status_changed` pentru livrare
4	La `LIVRAT` — confirmați în ERP facturare/expediere

Stoc (flowSCMC → ERP)

Opțiune	Când
Webhook `stock.updated`	Timp real, volum mic-mediu
Polling `GET /api/v2/stock` cu cursor	Batch noaptea, volume mari
GraphQL `stockConnection`	Interogări flexibile per depozit/SKU

Versiuni API — ce alegeți

Necesitate	Recomandare
CRUD complet, PO, recepții	REST v1
Listări mari, cursor, ambalaje	REST v2
Frontend custom, query unic	GraphQL
Notificări evenimente	Webhooks

Descoperire automată: GET /api și GET /api/v2/meta.

Securitate

Regulă	Detaliu
TLS obligatoriu	`https://flowscmc.{tld}`
Token în header	Nu în URL query string
Webhook secret	Verificați `X-Webhook-Signature: sha256=…` — Playground
Medii separate	Token staging ≠ producție
Rotație	Re-emiteți token la schimbare personal

Testare

Pornire rapidă — token + primul GET
Playground — test REST fără Postman
Health: GET /api/health (fără auth)
OpenAPI: /openapi-v2.json pe acest site

Erori și depanare

Cod	Cauză frecventă	Remediere
401	Token invalid/expirat	Re-auth sau token nou
403	Ability lipsă	Extindeți abilities token
422	Validare — companie, câmp	Citiți `errors` JSON
429	Rate limit	Backoff, reduceți frecvența
409	Conflict status / stoc	Verificați workflow document

Detalii: Erori & rate limit.

Integrări predefinite

Sistem	Documentație
eTSM transport	Integrări inbound
Verificare QR aviz/recepție	Verificare QR

Checklist go-live

[ ] Token producție cu abilities minime
[ ] X-Company-Id pe toate request-urile de date
[ ] Webhooks configurate + verificare semnătură
[ ] Idempotency-Key pe POST SO/PO
[ ] Monitorizare 429 și alerte
[ ] Runbook: revocare token compromis
[ ] Contact suport cu valori exemplu, fără token real în ticket