WMS Agile — API Reference

Autenticazione

JWT Bearer Token + API Key per tutti gli endpoint

Headers richiesti

X-API-Key: {your-api-key}

Authorization: Bearer {jwt-token}

Gli endpoint pubblici (health check, tracking, webhook) non richiedono autenticazione. Tutti gli altri richiedono almeno l'API Key.

Ottenere il JWT — POST /api/auth/login

Request

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded
X-API-Key: wms-demo-api-key-2026-secure

email=admin%40example.it&password=Password123%21

Response

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "user": {
      "id": 1,
      "email": "admin@example.it",
      "role": "admin",
      "tenant_id": 1
    }
  }
}

Importante: il login usa application/x-www-form-urlencoded (NON JSON). Il token JWT si trova nel campo access_token. Il carattere ! nella password va URL-encoded come %21.

Formato risposta standard

// Successo
{ "success": true, "data": { ... } }

// Errore
{ "success": false, "error": "Messaggio errore", "code": 400 }

Rate Limiting

Limite

100 req / min

Per

API Key

Header risposta

X-RateLimit-Remaining

Reset

X-RateLimit-Reset

Auth Service

:3081 Utenti, ruoli, sessioni, tenant, JWT

Method	Path	Auth	Descrizione
POST	/api/auth/login	Nessuna	Login utente. Body form-urlencoded: `email`, `password`
POST	/api/auth/logout	JWT	Invalida sessione corrente
GET	/api/auth/me	JWT	Profilo utente autenticato
GET	/api/auth/users	JWT + Admin	Lista utenti del tenant
POST	/api/auth/users	JWT + Admin	Crea nuovo utente
PUT	/api/auth/users/{id}	JWT + Admin	Aggiorna utente
DELETE	/api/auth/users/{id}	JWT + Admin	Disattiva utente (soft delete)
GET	/api/auth/tenants	API Key	Lista tenant — solo superadmin
POST	/api/auth/tenants	API Key	Crea nuovo tenant
GET	/api/auth/health	Nessuna	Health check servizio

Esempio — Crea utente

POST /api/auth/users
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "email":      "user@example.it",
  "password":   "Secure2026!",
  "role":       "operator",
  "first_name": "Mario",
  "last_name":  "Rossi"
}

Inventory Service

:3082 Prodotti, SKU, stock, lotti, seriali, ubicazioni, forecast

Query params comuni su tutti gli endpoint paginati: page, limit, search. Il tenant_id è estratto automaticamente dal JWT.

Method	Path	Auth	Descrizione	Parametri chiave
GET	/api/inventory/products	JWT	Lista prodotti con filtri	search, category, status
POST	/api/inventory/products	JWT	Crea prodotto/SKU	sku, name, category, uom
GET	/api/inventory/products/{id}	JWT	Dettaglio prodotto + stock aggregato	—
PUT	/api/inventory/products/{id}	JWT	Aggiorna prodotto	—
GET	/api/inventory/stock	JWT	Stock levels per bin	product_id, bin_code, zone_id
GET	/api/inventory/lots	JWT	Lista lotti con scadenza e quantità	product_id, expiry_before
POST	/api/inventory/lots	JWT	Crea lotto (FEFO automatico)	product_id, lot_number, expiry_date, qty
GET	/api/inventory/forecast	JWT	Dashboard forecast ROP per tutti i prodotti	—
POST	/api/inventory/forecast/calculate	JWT	Ricalcola ROP con parametri personalizzati	lead_time_days, service_level
GET	/api/movements	JWT	Lista movimenti stock (ingresso, uscita, trasferimento, rettifica)	limit, offset, movement_type
POST	/api/stock/movement	JWT	Registra nuovo movimento stock	movement_type, sku, from_bin_code, to_bin_code, quantity, lot_number, reason
GET	/api/cycle-counts	JWT	Lista inventari ciclici (conteggi pianificati e completati)	status, zone_id, limit
POST	/api/cycle-counts	JWT	Crea nuovo inventario ciclico (totale, parziale, spot)	type (full/partial/spot), zone_id, bin_code, scheduled_date
GET	/api/inventory/packaging	JWT	Configurazioni UOM e imballaggi	—
GET	/api/inventory/health	Nessuna	Health check servizio	—

Warehouse Service

:3083 Struttura magazzino, zone, bin, missioni, alert, slotting, NCR, yard

Method	Path	Auth	Descrizione	Note
GET	/api/warehouse/warehouses	JWT	Lista magazzini del tenant	—
POST	/api/warehouse/warehouses	JWT	Crea magazzino	name, code, address
GET	/api/warehouse/zones	JWT	Zone del magazzino	tipi: storage, picking, receiving, shipping, quarantine
POST	/api/warehouse/zones	JWT	Crea zona	name, zone_type, warehouse_id
GET	/api/warehouse/bins	JWT	Lista bin/scaffali	zone_id, status, bin_code
GET	/api/warehouse/missions	JWT	Missioni attive/completate	tipi: picking, putaway, replenishment, transfer
POST	/api/warehouse/missions	JWT	Crea missione manuale	type, assigned_to, tasks[]
PUT	/api/warehouse/missions/{id}/complete	JWT	Completa missione	—
GET	/api/warehouse/alerts	JWT	Alert attivi	severity: info / warning / critical / emergency
POST	/api/warehouse/alerts/{id}/resolve	JWT	Risolvi alert	—
GET	/api/warehouse/slotting/proposals	JWT	Proposte slotting ABC (riassegnazione bin)	—
POST	/api/warehouse/slotting/apply	JWT	Applica proposta slotting	proposal_id
GET	/api/warehouse/ncr	JWT	Non conformità (NCR) aperte	severity: info/warning/critical/blocking
POST	/api/warehouse/ncr	JWT	Crea NCR	description, severity, entity_type, entity_id
GET	/api/warehouse/yard	JWT	Stato banchine e trailer	—
GET	/api/warehouse/operators	JWT	Lista operatori in turno	shift, role
GET	/api/warehouse/health	Nessuna	Health check servizio	—

Inbound Service

:3084 Ordini ingresso, ricevimento, quality check, put-away, webhook e-commerce

Method	Path	Auth	Descrizione	Parametri chiave
GET	/api/inbound/orders	JWT	Lista ordini inbound	stati: expected, partial, received, completed
POST	/api/inbound/orders	JWT	Crea ordine inbound (Purchase Order)	supplier_id, expected_date, lines[]
GET	/api/inbound/orders/{id}	JWT	Dettaglio ordine + righe + stato ricevimento	—
POST	/api/inbound/orders/{id}/receive	JWT	Avvia ricevimento merce	lines[]{product_id, qty_received, lot_number}
POST	/api/inbound/orders/{id}/quality-check	JWT	Registra quality check	result: pass/fail, notes
POST	/api/inbound/orders/{id}/putaway	JWT	Conferma put-away bin	lines[]{lpn, bin_code}
GET	/api/inbound/lpn	JWT	Lista LPN (License Plate Numbers)	status, bin_code
POST	/api/inbound/webhook/ecommerce	HMAC	Webhook WooCommerce / Shopify / Magento	order_id, items[], source
GET	/api/inbound/health	Nessuna	Health check servizio	—

Esempio — Webhook e-commerce (WooCommerce)

POST /api/inbound/webhook/ecommerce
X-API-Key: wms-demo-api-key-2026-secure
X-WC-Webhook-Signature: sha256=abc123...
Content-Type: application/json

{
  "order_id": "WC-1234",
  "items": [
    { "sku": "SKU-001", "qty": 10 },
    { "sku": "SKU-042", "qty": 5  }
  ],
  "source": "woocommerce"
}

Outbound Service

:3085 Ordini uscita, wave picking, packing, shipping, LPN/SSCC GS1, TMS

Method	Path	Auth	Descrizione	Note
GET	/api/outbound/orders	JWT	Lista ordini outbound	stati: new, wave, picking, packing, shipped
POST	/api/outbound/orders	JWT	Crea ordine di spedizione	customer_id, lines[], carrier_id, priority
POST	/api/outbound/wave	JWT	Crea wave picking (ottimizza percorsi)	order_ids[], strategy: zone/cluster/batch
GET	/api/outbound/wave/{id}/picks	JWT	Lista picking task per wave	—
POST	/api/outbound/wave/{id}/picks/{task_id}/confirm	JWT	Conferma pick singolo	qty_picked, bin_code
POST	/api/outbound/orders/{id}/pack	JWT	Avvia packing + genera LPN	—
POST	/api/outbound/orders/{id}/ship	JWT	Spedisce + genera SSCC GS1 + tracking	carrier_id, tracking_number
GET	/api/outbound/sscc/{code}	Pubblico	Tracking pubblico SSCC (portale tracking)	—
GET	/api/outbound/carriers	JWT	Carrier configurati (BRT, NCR, etc.)	—
GET	/api/outbound/health	Nessuna	Health check servizio	—

SSCC GS1: formato 00 + 0 + azienda (9 cifre) + item ref (8 cifre) + check digit (1 cifra) = 20 cifre totali. Il portale tracking pubblico e' raggiungibile a wms.agile.software/tracking/?n=TRK-...

Customers API

:3083 wms_warehouse_db

Anagrafica clienti: CRUD completo con tipo, SLA, priorita e corriere default.

Method	Endpoint	Descrizione
GET	/api/customers	Lista clienti (filtri: search, customer_type, is_active, limit, offset)
POST	/api/customers	Crea cliente (code, name, customer_type, priority, sla_hours, default_carrier_code, contatti)
GET	/api/customers/{id}	Dettaglio cliente
PUT	/api/customers/{id}	Aggiorna cliente
DELETE	/api/customers/{id}	Elimina cliente (soft delete)

Tipi cliente: gdo, horeca, ecommerce, retail, pharma_retail, pharma_dist, hospital, distributor, marketplace, export, catering, other

Suppliers API

:3083 wms_warehouse_db

Anagrafica fornitori: CRUD con lead time, affidabilita e associazione prodotti.

Method	Endpoint	Descrizione
GET	/api/suppliers	Lista fornitori (filtri: search, category, is_active, limit, offset)
POST	/api/suppliers	Crea fornitore (code, name, category, lead_days_default, reliability_score, country, contatti)
GET	/api/suppliers/{id}	Dettaglio fornitore
PUT	/api/suppliers/{id}	Aggiorna fornitore
DELETE	/api/suppliers/{id}	Elimina fornitore (soft delete)

reliability_score: valore 0.00-1.00 (es. 0.95 = 95% consegne puntuali). Usato dal simulatore per eventi supplier_delay.

Carriers API

:3083 wms_warehouse_db

Anagrafica corrieri: CRUD con tariffe, SLA, certificazioni GDP e Cold Chain.

Method	Endpoint	Descrizione
GET	/api/carriers	Lista corrieri (filtri: search, is_active)
POST	/api/carriers	Crea corriere (code, name, service_type, sla_hours, base_cost, cost_per_kg, max_weight_kg, gdp_certified, cold_capable)
GET	/api/carriers/{id}	Dettaglio corriere
PUT	/api/carriers/{id}	Aggiorna corriere
DELETE	/api/carriers/{id}	Elimina corriere (soft delete)

Calcolo costo: base_cost + (peso_kg x cost_per_kg). Certificazioni: gdp_certified (pharma), cold_capable (refrigerato). service_type: standard, express, premium, economy, ftl, ltl

Report Service

:3086 Dashboard KPI, analytics, audit trail, labour management, export CSV

Method	Path	Auth	Descrizione	Parametri chiave
GET	/api/report/dashboard	JWT	KPI principali: missioni, stock, ordini, performance	—
GET	/api/report/kpi	JWT	KPI dettagliati per periodo	period: today, week, month, custom; date_from, date_to
GET	/api/report/labour	JWT	Shift report operatori: ore lavorate, produttivita, OEE	operator_id, date
GET	/api/report/audit	JWT	Audit log filtrato	user, action, entity, date_from, date_to
GET	/api/report/forecast-summary	JWT	Riepilogo forecast e prodotti critici	—
GET	/api/report/inbound-performance	JWT	Performance ricevimento (lead time, errori, fornitori)	period, supplier_id
GET	/api/report/outbound-performance	JWT	Performance spedizione (SLA, carrier, errori picking)	period, carrier_id
GET	/api/report/export/csv	JWT	Export dati in CSV	entity: products, stock, orders, missions
GET	/api/report/health	Nessuna	Health check servizio	—

AI Service

:3087 Chat Claude con function calling, SSE streaming, RAG documentale, alert realtime

Method	Path	Auth	Descrizione
POST	/api/ai/chat	JWT	Chat AI con SSE streaming. Body: `{"message":"...","context":{},"stream":true}`
GET	/api/ai/settings	JWT + Admin	Configurazione AI per tenant (modello, tools abilitati, RAG)
PUT	/api/ai/settings	JWT + Admin	Aggiorna config AI (Anthropic API key, modello, prompt)
POST	/api/ai/ingest	JWT + Admin	Ingest documenti per RAG (PDF, TXT, HTML)
GET	/api/realtime/stream	JWT	SSE stream realtime: alert proattivi, missioni, stock critici
GET	/api/ai/health	Nessuna	Health check servizio

SSE Response format — /api/ai/chat

data: {"type":"token","content":"Ciao"}

data: {"type":"token","content":", ho analizzato lo stock..."}

data: {"type":"tool_use","tool":"get_stock_levels","result":{...}}

data: {"type":"done","usage":{"input_tokens":120,"output_tokens":85}}

Per SSE, impostare Accept: text/event-stream e gestire la connessione con EventSource o fetch in streaming. Il nginx gateway ha proxy_buffering off e timeout 120s.

AI Tools disponibili (20+)

get_stock_levels get_missions create_mission get_alerts get_forecast get_inbound_orders create_inbound_order get_outbound_orders ship_order get_kpi_dashboard get_operators get_yard_status get_audit_log get_network_orders create_network_order get_lots get_slotting_proposals get_bins get_zones get_products

Network Service — Rete Filiera™

:3090 Procure-to-Pay completo: ordini tra partner, EDI X12/EDIFACT, notifiche

Riferimenti ordine: formato NET-YYYYMMDD-NNNN (es: NET-20260228-0042). Il flusso stati e immutabile e registrato come log di eventi.

sent confirmed delayed shipped received invoiced

Method	Path	Auth	Descrizione
GET	/api/network/partners	JWT	Lista partner (supplier, carrier, 3PL, client)
POST	/api/network/partners	JWT	Registra nuovo partner nella rete
GET	/api/network/orders	JWT	Ordini di acquisto/vendita nella rete (filtro per ruolo buyer/seller)
POST	/api/network/orders	JWT	Crea ordine di acquisto verso partner
PUT	/api/network/orders/{ref}/confirm	JWT	Partner (seller) conferma ordine ricevuto
PUT	/api/network/orders/{ref}/ship	JWT	Partner aggiorna stato a shipped
PUT	/api/network/orders/{ref}/receive	JWT	Buyer conferma ricezione merce
GET	/api/network/events	JWT	Timeline eventi ordine (immutable log)
GET	/api/network/notifications	JWT	Notifiche in-app per il tenant corrente
GET	/api/network/edi/inbound	JWT	Messaggi EDI ricevuti (X12 / EDIFACT)
POST	/api/network/edi/send	JWT	Invia messaggio EDI a partner
GET	/api/network/health	Nessuna	Health check servizio

Codici Errore HTTP

Risposta standard: {"success":false,"error":"...","code":NNN}

Codice	Significato	Causa comune
200	OK	Operazione eseguita con successo
201	Created	Risorsa creata correttamente
400	Bad Request	Body malformato o parametri obbligatori mancanti
401	Unauthorized	JWT mancante/scaduto o API Key non valida
403	Forbidden	Ruolo non autorizzato per questa azione
404	Not Found	Risorsa non trovata o appartiene a tenant diverso
409	Conflict	Risorsa gia esistente (slug, codice duplicato)
422	Unprocessable	Validazione fallita (stock insufficiente, quantita negativa, etc.)
429	Too Many Requests	Rate limit superato (100 req/min per API Key). Attendere reset.
500	Internal Server Error	Errore interno del server. Consultare i log o contattare il supporto.

Multi-tenancy

Isolamento completo dei dati per tenant

Come funziona

Ogni endpoint filtra automaticamente i dati per il tenant_id derivato dal JWT. Non e' necessario passare tenant_id nelle query: l'API lo estrae internamente dal token di autenticazione. Tutte le tabelle del database contengono una colonna tenant_id e tutte le query la usano in WHERE.

Superadmin: puo' passare ?tenant_id=X per operare su tenant specifici. Questa funzione e' riservata esclusivamente agli account con ruolo superadmin.

Operatore / Supervisor Vede solo i dati del proprio tenant

Admin tenant Gestisce utenti e config del proprio tenant

Superadmin Accesso cross-tenant via ?tenant_id=X

Architettura 4PL Multi-tenant

WMS Agile supporta la modalita' 4PL (Fourth Party Logistics): un unico operatore logistico puo' gestire magazzini per conto di piu' clienti (tenant) nella stessa istanza. Ogni tenant ha la propria vista isolata di prodotti, stock, ordini e reportistica. La Rete Filiera™ (network-ms) permette invece la comunicazione strutturata tra tenant diversi attraverso il flusso Procure-to-Pay.

Postman Collection

Collection preconfigurata con tutti gli 8 servizi e relativi esempi

WMS Agile — Postman Collection v1.0

Include tutti gli 8 microservizi con autenticazione pre-impostata, variabili d'ambiente per i base URL, e un esempio funzionante per ogni endpoint. Importa il file JSON in Postman o in qualsiasi client OpenAPI 3.0.

Scarica Collection JSON

Quickstart — curl

1. Login e ottieni il JWT

# Login
TOKEN=$(curl -s -X POST https://wms.agile.software/api/auth/login \
  -H "X-API-Key: wms-demo-api-key-2026-secure" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=admin%40logitech-wh.it&password=Admin2026%21" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['access_token'])")

echo "Token: $TOKEN"

2. Chiamata autenticata — lista prodotti

curl -s https://wms.agile.software/api/inventory/products \
  -H "X-API-Key: wms-demo-api-key-2026-secure" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

3. Chat AI in streaming

curl -s -N -X POST https://wms.agile.software/api/ai/chat \
  -H "X-API-Key: wms-demo-api-key-2026-secure" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Quanti prodotti in stock critico?","stream":true}'

WMS AgileAPI Reference

Autenticazione

Headers richiesti

Ottenere il JWT — POST /api/auth/login

Formato risposta standard

Rate Limiting

Auth Service

Inventory Service

Warehouse Service

Inbound Service

Outbound Service

Customers API

Suppliers API

Carriers API

Report Service

AI Service

Network Service — Rete Filiera™

Codici Errore HTTP

Multi-tenancy

Come funziona

Architettura 4PL Multi-tenant

Postman Collection

WMS Agile — Postman Collection v1.0

Quickstart — curl

WMS Agile
API Reference