Stato della produzione
Dove si trova ogni pezzo, adesso.
GET /api/v1/integration/production-status
curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://vostro-server/api/v1/integration/production-status
Risposta
{
"codes": [
{
"barcode": "ABC-001",
"lotQuantity": 4,
"orderRef": "0001",
"status": "IN_PROGRESS",
"quantityDone": 0,
"stages": [
{
"sequence": 1,
"service": "SERVICE_A",
"machineName": "MACHINE 01",
"status": "DONE",
"startedAt": "2026-09-18T11:02:00Z",
"finishedAt": "2026-09-18T11:47:00Z",
"scheduledFor": "2026-09-18T08:00:00Z",
"quantityCompleted": 4,
"quantityInProgress": 0,
"quantityWaiting": 0,
"batchId": 101
},
{
"sequence": 2,
"service": "SERVICE_B",
"machineName": "MACHINE 02",
"status": "PARTIAL",
"startedAt": "2026-09-18T13:20:00Z",
"finishedAt": null,
"scheduledFor": "2026-09-18T13:00:00Z",
"quantityCompleted": 2,
"quantityInProgress": 1,
"quantityWaiting": 1,
"batchId": 102
},
{
"sequence": 3,
"service": "SERVICE_C",
"machineName": "MACHINE 03",
"status": "WAITING",
"startedAt": null,
"finishedAt": null,
"scheduledFor": "2026-09-19T09:00:00Z",
"quantityCompleted": 0,
"quantityInProgress": 0,
"quantityWaiting": 4,
"batchId": null
}
]
}
],
"totalCodes": 1,
"truncated": false,
"daysAfterCompletion": 7,
"serverUtc": "2026-09-18T14:02:11Z"
}
Campi
| Campo | Significato |
|---|---|
codes[] | Una voce per ogni codice a barre che avete inviato |
totalCodes | Quanti ne sono tornati |
truncated | true quando è stato raggiunto il tetto dei codici — filtrate per orderRef |
daysAfterCompletion | Per quanto tempo un codice concluso continua a comparire |
serverUtc | Orologio del server, da confrontare con il vostro |
Per codice:
| Campo | Significato |
|---|---|
barcode | Il codice che avete inviato. Sempre la radice del lotto, mai una frazione interna |
lotQuantity | Quantità ordinata. Immutabile — non cambia quando il lotto viene frazionato |
status | Sintesi: lo stato della prima fase non ancora chiusa |
quantityDone | Unità che hanno completato l'intero ciclo |
stages[] | Il ciclo di lavorazione, in ordine |
Per fase:
| Campo | Significato |
|---|---|
sequence | Posizione nel ciclo |
service · machineName | La lavorazione e dove viene eseguita |
startedAt | Quando è entrata la prima unità. null se nessuna è entrata |
finishedAt | Valorizzata solo quando l'intero lotto è passato |
scheduledFor | L'inizio programmato più presto tra le parti del lotto che hanno una programmazione (inizio e fine programmati), in UTC. null finché nessuna ne ha. Solo informativo: la situazione non deriva da esso |
quantityCompleted · quantityInProgress · quantityWaiting | Le tre quantità. Sommano sempre a lotQuantity |
batchId | Il lotto fisico (infornata, lastra) attraverso cui sono passate le unità, quando esiste |
È una fotografia, non un registro
È la cosa da capire prima di scrivere qualsiasi codice contro questo endpoint.
La risposta è lo stato completo attuale, non un elenco di ciò che è accaduto dall'ultima volta che avete chiesto. Non c'è cursore, non c'è offset, e non c'è conferma da rimandare.
Ne consegue che:
- Sovrascrivete ciò che avevate. Non accodate, non fate merge. La risposta è già il quadro intero.
- Saltare un ciclo non costa nulla. Il vostro lettore è rimasto fermo un'ora? La chiamata successiva dà lo stato attuale. Nulla si è accodato e nulla si è perso.
- Interrogare è idempotente. Leggere due volte non cambia nulla da parte nostra.
Un registro sarebbe stato più facile da costruire per noi e molto più difficile da consumare per voi — dovreste tenere traccia di ciò che avete già visto, e un evento perso vi lascerebbe sbagliati per sempre. Una fotografia non può disallinearsi.
Le tre quantità
Un pezzo ordinato con lotQuantity > 1 può essere diviso fra le fasi — parte tagliata, parte ancora in attesa. Nell'esempio sopra, la seconda fase ha 2 concluse, 1 in macchina e 1 in attesa.
Senza quella di mezzo, "è in macchina" e "non è ancora iniziata" apparirebbero entrambe come zero avanzamento — che è esattamente la domanda per cui la programmazione telefona.
Gli stati di una fase
| Stato | Significato |
|---|---|
WAITING | Non iniziata, programmata e nei tempi |
LATE | Non iniziata, e in ritardo: la fase programmata finirà dopo la data in cui deve essere pronta (o l'orologio l'ha già superata); la fase non programmata, con la scadenza del pezzo già passata |
UNSCHEDULED | Non iniziata, e non ancora programmata, con la scadenza del pezzo ancora davanti |
IN_PROGRESS | Unità in macchina adesso |
PARTIAL | Parte del lotto è passata, e il resto non è in nessuna macchina |
DONE | Terminata |
OUTSOURCED | Inviata a un fornitore esterno (conto terzi) |
SHIPPED | Spedita |
CANCELLED | Annullata |
LATE e PARTIAL hanno un nome proprio di proposito. Entrambe si nasconderebbero dietro WAITING, ed entrambe sono quelle che generano una telefonata.
Come si decide tra WAITING, LATE e UNSCHEDULED
È la stessa regola che lo stabilimento usa internamente, applicata nel momento della richiesta:
- Una fase programmata ha una data entro cui deve essere pronta: la scadenza del pezzo meno ciò che resta del ciclo dopo di essa. È
LATEquando la fine programmata — o adesso, se adesso ha già superato la fine programmata senza che la fase sia iniziata — viene dopo quella data. Un inizio programmato nel passato non basta da solo. - Una fase ancora senza programmazione è
UNSCHEDULEDfinché la scadenza del pezzo è davanti, eLATEdopo. È lo stato normale del lavoro in attesa: lo stabilimento programma in dettaglio solo le prossime ore (fino a 24, secondo la configurazione dello stabilimento), e il pezzo entra nel dettaglio quando arriva il suo turno. Anche le fasi che il pianificatore non programma (assemblaggio, spedizione, lavorazione presso un fornitore non ancora inviata) risultanoUNSCHEDULED. Non è un problema: significa "in coda, ancora senza orario". - La scadenza del pezzo è la più vicina tra la
DueDateinviata, la partenza del carico in cui si trova e — quando il carico ha una finestra prenotata alla baia — l'ora limite entro cui finire il carico. La lastra di un laminato o di una vetrocamera prende la scadenza dell'unità quando viene prima della propria. - La scadenza di una fase senza programmazione è quella che il pianificatore ha scritto nella sua ultima esecuzione (di solito da pochi secondi a pochi minuti prima). Un pezzo appena arrivato, o una fase appena creata (una sostituzione, una divisione del lotto), risulta
UNSCHEDULEDfino a quell'esecuzione, anche con laDueDategià passata. - Un lotto diviso:
LATEse una qualsiasi parte non iniziata è in ritardo — anche mentre un'altra parte è in macchina, è già passata o è presso il fornitore: la parte in ritardo non si nasconde dietroIN_PROGRESS,PARTIALoOUTSOURCED;UNSCHEDULEDsolo se nessuna parte non iniziata ha una programmazione;WAITINGnegli altri casi. - Il contratto non ha la situazione "a rischio": ciò che lo stabilimento chiama a rischio internamente risulta
WAITING.
UNSCHEDULED è stata aggiunta insieme a questa regola, nella versione indicata nel changelog. Prima, LATE significava "l'inizio programmato è passato" e usciva 3 ore in anticipo, e scheduledFor mostrava un istante 3 ore prima di quello reale (l'ora locale dello stabilimento veniva inviata con la Z). Se sommavate 3 ore a scheduledFor per compensare, smettete. Trattate le situazioni sconosciute come informative, non come errori.
Il codice è sempre quello che avete inviato
Ciò che avete usato come barcode è ciò che torna. Non lo traduciamo, non lo prefissiamo e non lo sostituiamo con un identificativo interno.
Se un pezzo è stato diviso durante la produzione — un lotto tagliato in parte, un pezzo rotto e rimpiazzato — le frazioni vengono riconsolidate sotto il codice che conoscete. I nostri identificativi interni restano interni.
Filtri
| Parametro | Effetto | Esempio |
|---|---|---|
orderRef | Solo quell'ordine | ?orderRef=0001 |
daysAfterCompletion | Per quanti giorni i codici conclusi continuano a comparire | ?daysAfterCompletion=3 |
codeLimit | Tetto al numero di codici restituiti | ?codeLimit=500 |
curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
"https://vostro-server/api/v1/integration/production-status?orderRef=0001"
I codici conclusi continuano a comparire per qualche giorno di proposito, così che un lettore rimasto fermo per un ciclo non perda la chiusura di un ordine.
Quando truncated torna true, avete raggiunto il tetto. Filtrate per orderRef invece di alzarlo.
Cosa questo non copre
Riporta ciò che il reparto ha registrato. Non è un documento fiscale, non è una conferma di consegna, e non riporta nulla di ciò che accade dopo la spedizione.