Catalogo API OMS
Indice operativo manuale delle route OMS, con autenticazione, permessi, idempotenza ed errori.
Questo è un catalogo manuale, non una specifica OpenAPI. Riassume le famiglie di route implementate sotto packages/oms/app/api/**; per payload, query e risposta puntuali, l'implementazione resta la fonte di verità.
Gli spec generati da pnpm gen:openapi coprono oggi soltanto Feed Manager web e worker. Non esiste ancora uno spec oms.json, quindi questa pagina non offre schema machine-readable, client generation o playground contrattuale.
Tutti i path seguenti sono relativi all'app OMS e iniziano con /api.
Route operative
| Metodo | Path o famiglia | Scopo |
|---|---|---|
GET, POST | /health, /auth/active-company, /active-project | Health e selezione del contesto condiviso fra applicazioni. |
GET | /connections | Elenca le connessioni cifrate compatibili con il wizard canale. |
GET, POST | /channels | Elenca o crea i canali commerce. La creazione richiede idempotenza e produce un canale inizialmente non attivo. |
GET, PATCH, DELETE | /channels/{id} | Legge, aggiorna o rimuove un canale; una modifica alla configurazione invalida l'health precedente. |
POST | /channels/{id}/test, /channels/{id}/sync | Verifica la connessione o avvia la sincronizzazione. |
GET, POST, PATCH | /channels/{id}/inbound-webhook | Legge, crea, attiva, disattiva o ruota l'endpoint inbound. |
GET, POST | /channels/{id}/inventory-bindings | Elenca o crea i binding inventario. |
PATCH, DELETE | /channels/{id}/inventory-bindings/{bindingId} | Modifica lo stato o elimina un binding inventario. |
GET, PUT | /channels/{id}/inventory-policy | Legge o sostituisce la policy di pubblicazione stock. |
POST | /webhooks/commerce/{endpointId} | Riceve un evento pubblico firmato dal provider commerce. |
GET | /orders, /orders/{id}, /orders/stats, /orders/export | Ricerca, dettaglio, statistiche ed export degli ordini. |
GET | /orders/{id}/documents/{kind} | Genera i documenti operativi collegati all'ordine. |
PATCH, POST | /orders/{id}, /orders/{id}/confirm, /cancel, /ship, /send-supplier | Modifica e transizioni protette dell'ordine. |
POST | /orders/{id}/label, /orders/{id}/tracking/refresh | Richiede un'etichetta o aggiorna il tracking tramite provider. |
GET, POST | /orders/{id}/fulfillment, /fulfillment/steps/{stepId}/scan, /fulfillment/steps/{stepId}/complete | Crea il piano di fulfillment e avanza picking o packing. |
GET, POST, PATCH, DELETE | /customers, /customers/{id} | CRUD dell'anagrafica cliente. |
POST | /customers/import/preview, /customers/import/{batchId}/commit | Valida un CSV e conferma un batch già verificato. |
GET, POST | /warehouses, /inventory | Elenca o configura magazzini e posizioni inventario. |
POST | /inventory/{id}/mutations, /inventory/transfers, /reservations | Registra movimenti ledger, trasferimenti e prenotazioni stock. |
PATCH | /reservations/{id} | Aggiorna lo stato di una prenotazione. |
GET, POST | /stocktakes, /stocktakes/{id}, /counts, /complete | Apre, consulta, conta e chiude un inventario fisico. |
GET | /warehouse-documents, /warehouse-documents/{id}/pdf | Consulta i documenti operativi PZ/WZ/MM e il relativo PDF. |
GET | /shipments, /shipments/{id}, /shipments/export, /shipments/{id}/label | Consulta spedizioni, export ed etichette. |
POST | /shipments/push-store, /shipments/{id}/op, /recover-label | Pubblica al canale o avvia e recupera operazioni corriere. |
GET, POST | /returns, /returns/{id}, /returns/export | Ricerca, crea, consulta ed esporta i resi. |
POST | /returns/{id}/approve, /reject, /receive, /refund, /refund-resolution | Avanza il reso, applica stock e governa il rimborso. |
GET, PATCH | /returns/portal-settings | Legge o modifica la configurazione del portale resi. |
GET, POST | /public/returns/** | Lookup, apertura e consultazione token-scoped senza sessione utente. |
GET, POST, PATCH, DELETE | /automations, /automations/{id} | Gestisce regole versionate; /dry-run, /events e /runs espongono simulazione e storia. |
GET | /analytics/sales, /analytics/channels, /analytics/export | KPI ed export analitici tenant-scoped. |
GET, PUT, DELETE, POST | /projects/{id}/imports/**/order-config | Legge, configura, rimuove e testa l'inoltro ordini ai fornitori. |
POST | /operations/blockers/{id}, /operations/outbox/{id}/retry | Risolve blocker o ritenta un evento eleggibile. |
POST | /operations/carrier-*/**, /operations/marketplace-shipment/** | Registra una decisione di riconciliazione per esiti esterni ambigui. |
Le abbreviazioni come /approve nella tabella si aggiungono al path completo mostrato all'inizio della stessa riga. Non indicano endpoint alla radice.
Le route /api/internal/** sono riservate alla comunicazione server-to-server e non
fanno parte dell'API operatore. Le route NextAuth sotto /api/auth/** seguono invece il
contratto del framework.
Autenticazione e permessi
Salvo le eccezioni pubbliche, una route OMS richiede:
- sessione NextAuth valida;
- company attiva;
- entitlement al modulo OMS;
- accesso in lettura all'area OMS.
Ogni mutazione richiede inoltre l'accesso OMS write. Le operazioni sensibili applicano una capability dedicata, per esempio order.confirm, order.ship, order.cancel, return.receive, return.refund, inventory.configure o automation.configure. Il possesso della capability non supera un'area configurata in sola lettura.
Le route /api/public/returns/** usano company e token del portale. /api/webhooks/commerce/{endpointId} autentica invece la provenienza del provider. Nessuna delle due famiglie usa la sessione browser ordinaria.
La matrice completa ruolo/capability è in Architettura OMS.
Idempotenza e concorrenza
Non tutte le route usano la stessa forma di chiave:
POST /api/channelsrichiede l'header UUIDidempotency-key;POST /api/inventory/{id}/mutationsriceveidempotencyKeynel body e segnala i replay nei metadati;- i rimborsi confrontano il fingerprint normalizzato del comando prima di creare l'effetto marketplace;
- creazioni e scansioni che espongono una chiave client la persistono con il comando logico;
- le automazioni usano
clientRequestId, revisione immutabile e lock token; - le transizioni già completate possono rispondere come replay idempotente.
La stessa chiave va riutilizzata solo per lo stesso payload logico. Un replay equivalente restituisce il risultato già ottenuto; una chiave riusata con dati incompatibili produce un conflitto.
Gli effetti verso provider possono essere asincroni. Una risposta accettata non implica sempre che marketplace o corriere abbiano già terminalizzato l'operazione: stato outbox e blocker sono consultati e riconciliati dal flusso operations. Vedi Outbox e riconciliazione.
Errori
| Status | Significato OMS tipico |
|---|---|
400 / 422 | Input non valido o comando semanticamente non applicabile. |
401 | Sessione assente o credenziale pubblica non valida. |
402 | Modulo OMS non incluso per la company. |
403 | Area, ruolo o capability utente insufficienti. |
404 | Risorsa non visibile nel tenant attivo. |
409 | Stato concorrente, revisione, idempotency key o fingerprint in conflitto. |
429 | Limite di frequenza applicato al flusso pubblico o al provider. |
500 / 502 / 503 | Errore interno, dipendenza remota o servizio temporaneamente non disponibile. |
Le singole route possono usare un sottoinsieme di questi status. Finché non viene generato lo spec OMS, non bisogna dedurre automaticamente payload ed errori ammessi da questa tabella: verificare route, schema Zod e test del comando interessato.
Una firma, un segreto o un endpoint webhook commerce non valido restituisce 401, non
403, perché quella famiglia autentica il provider anziché autorizzare un utente.