Situação da produção
Onde está cada peça, agora.
GET /api/v1/integration/production-status
curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
https://seu-servidor/api/v1/integration/production-status
Resposta
{
"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"
}
Campos
| Campo | Significado |
|---|---|
codes[] | Uma entrada por código de barras que você enviou |
totalCodes | Quantos voltaram |
truncated | true quando o teto de códigos foi atingido — filtre por orderRef |
daysAfterCompletion | Por quanto tempo um código concluído continua aparecendo |
serverUtc | Relógio do servidor, para comparar com o seu |
Por código:
| Campo | Significado |
|---|---|
barcode | O código que você enviou. Sempre a raiz do lote, nunca uma fração interna |
lotQuantity | Quantidade pedida. Imutável — não muda quando o lote é fracionado |
status | Resumo: a situação da primeira etapa que ainda não fechou |
quantityDone | Unidades que cumpriram o roteiro inteiro |
stages[] | O roteiro, em ordem |
Por etapa:
| Campo | Significado |
|---|---|
sequence | Posição no roteiro |
service · machineName | A operação e onde ela roda |
startedAt | Quando a primeira unidade entrou. null se nenhuma entrou |
finishedAt | Preenchida só quando o lote inteiro passou |
scheduledFor | O início programado mais cedo entre as partes do lote que têm programação (início e fim programados), em UTC. null enquanto nenhuma tem. Só informativo: a situação não sai dele |
quantityCompleted · quantityInProgress · quantityWaiting | As três quantidades. Sempre somam lotQuantity |
batchId | O lote físico (fornada, chapa) por onde as unidades passaram, quando houver |
É um retrato, não um log
Esta é a parte para entender antes de escrever qualquer código contra este endpoint.
A resposta é o estado completo atual, não uma lista do que aconteceu desde a última vez que você perguntou. Não há cursor, não há offset, e não há confirmação para devolver.
O que decorre disso:
- Sobrescreva o que você tinha. Não acumule, não faça merge. A resposta já é o retrato inteiro.
- Perder um ciclo não custa nada. Seu leitor ficou fora do ar por uma hora? A próxima chamada traz o estado atual. Nada ficou na fila e nada se perdeu.
- Consultar é idempotente. Ler duas vezes não muda nada do nosso lado.
Um log teria sido mais fácil para nós construirmos e bem mais difícil para você consumir — você precisaria controlar o que já tinha visto, e um evento perdido deixaria você errado para sempre. Retrato não tem como desalinhar.
As três quantidades
Uma peça pedida com lotQuantity > 1 pode estar dividida entre etapas — parte cortada, parte ainda esperando. No exemplo acima, a segunda etapa tem 2 prontas, 1 dentro do forno e 1 aguardando.
Sem a do meio, "está na máquina" e "ainda não começou" apareceriam as duas como zero de progresso — que é exatamente a pergunta sobre a qual o PCP liga.
As situações de uma etapa
| Situação | Significado |
|---|---|
WAITING | Não começou, está programada e no prazo |
LATE | Não começou, e está atrasada: a etapa programada vai terminar depois da data em que precisa estar pronta (ou o relógio já passou dela); a não programada, com o prazo da peça já vencido |
UNSCHEDULED | Não começou, e ainda não tem programação, com o prazo da peça no futuro |
IN_PROGRESS | Tem unidade na máquina agora |
PARTIAL | Parte do lote passou, e o resto não está em máquina nenhuma |
DONE | Terminou |
OUTSOURCED | Enviada a um fornecedor externo |
SHIPPED | Expedida |
CANCELLED | Cancelada |
LATE e PARTIAL têm nome próprio de propósito. As duas se esconderiam atrás de WAITING, e as duas são as que geram telefonema.
Como se decide entre WAITING, LATE e UNSCHEDULED
É a mesma régua que a fábrica usa por dentro, aplicada no instante da consulta:
- A etapa programada tem uma data em que precisa estar pronta: o prazo da peça menos o que ainda falta do roteiro depois dela. É
LATEquando o fim programado — ou o agora, se ele já passou do fim sem a etapa começar — vem depois dessa data. O início programado no passado não basta, sozinho. - A etapa ainda sem programação é
UNSCHEDULEDenquanto o prazo da peça não venceu, eLATEdepois. É o estado normal de quem espera: a fábrica programa em detalhe só as próximas horas (até 24, conforme a configuração da fábrica), e a peça entra no detalhe quando chega a vez dela. A etapa que o planejador não programa (montagem, expedição, serviço no terceiro ainda não enviado) também saiUNSCHEDULED. Não é problema: é "na fila, ainda sem hora". - O prazo da peça é o mais cedo entre a
DueDateque você mandou, a saída da carga em que ela está e — quando a carga tem janela reservada na doca — a hora-limite de carregar. A lâmina de um laminado ou insulado fica com o prazo da unidade quando ele vem antes do dela. - O prazo da etapa sem programação é o que o planejador gravou na última rodada (normalmente de segundos a minutos atrás). A peça recém-chegada, ou a etapa recém-criada (uma reposta, uma divisão de lote), sai
UNSCHEDULEDaté essa rodada, mesmo com aDueDatejá vencida. - O lote dividido:
LATEse qualquer parte que não começou está atrasada — mesmo com outra parte na máquina, já passada ou no terceiro: a parte atrasada não se esconde atrás deIN_PROGRESS,PARTIALouOUTSOURCED;UNSCHEDULEDsó se nenhuma parte que não começou tem programação;WAITINGno resto. - Não há situação "em risco" no contrato: o que a fábrica chama de risco por dentro sai como
WAITING.
UNSCHEDULED entrou junto com esta régua, na versão indicada no changelog. Antes, LATE era "o início programado passou" e saía 3 h cedo, e o scheduledFor mostrava um instante 3 h antes do real (a hora local da fábrica ia com o Z). Se você somava 3 h ao scheduledFor para compensar, pare. Trate situação desconhecida como informativa, não como erro.
O código é sempre o que você mandou
O que você usou como barcode é o que volta. Não traduzimos, não prefixamos, e não substituímos por um id interno.
Se uma peça foi dividida durante a produção — um lote cortado em parte, uma peça quebrada reposta — as frações são consolidadas de volta sob o código que você conhece. Nossos identificadores internos continuam internos.
Filtros
| Parâmetro | Efeito | Exemplo |
|---|---|---|
orderRef | Só aquele pedido | ?orderRef=0001 |
daysAfterCompletion | Por quantos dias códigos concluídos continuam aparecendo | ?daysAfterCompletion=3 |
codeLimit | Teto de códigos retornados | ?codeLimit=500 |
curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
"https://seu-servidor/api/v1/integration/production-status?orderRef=0001"
Códigos concluídos continuam aparecendo por alguns dias de propósito, para um leitor que ficou fora do ar por um ciclo não perder o fechamento de um pedido.
Quando truncated voltar true, você bateu no teto. Filtre por orderRef em vez de aumentá-lo.
O que isso não cobre
Reporta o que o chão de fábrica registrou. Não é documento fiscal, não é confirmação de entrega, e não reporta nada que aconteça depois da expedição.