Pular para o conteúdo principal

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​

CampoSignificado
codes[]Uma entrada por código de barras que você enviou
totalCodesQuantos voltaram
truncatedtrue quando o teto de códigos foi atingido — filtre por orderRef
daysAfterCompletionPor quanto tempo um código concluído continua aparecendo
serverUtcRelógio do servidor, para comparar com o seu

Por código:

CampoSignificado
barcodeO código que você enviou. Sempre a raiz do lote, nunca uma fração interna
lotQuantityQuantidade pedida. Imutável — não muda quando o lote é fracionado
statusResumo: a situação da primeira etapa que ainda não fechou
quantityDoneUnidades que cumpriram o roteiro inteiro
stages[]O roteiro, em ordem

Por etapa:

CampoSignificado
sequencePosição no roteiro
service · machineNameA operação e onde ela roda
startedAtQuando a primeira unidade entrou. null se nenhuma entrou
finishedAtPreenchida só quando o lote inteiro passou
scheduledForO 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 · quantityWaitingAs três quantidades. Sempre somam lotQuantity
batchIdO 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çãoSignificado
WAITINGNão começou, está programada e no prazo
LATENã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
UNSCHEDULEDNão começou, e ainda não tem programação, com o prazo da peça no futuro
IN_PROGRESSTem unidade na máquina agora
PARTIALParte do lote passou, e o resto não está em máquina nenhuma
DONETerminou
OUTSOURCEDEnviada a um fornecedor externo
SHIPPEDExpedida
CANCELLEDCancelada

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. É LATE quando 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 é UNSCHEDULED enquanto o prazo da peça não venceu, e LATE depois. É 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 sai UNSCHEDULED. Não é problema: é "na fila, ainda sem hora".
  • O prazo da peça é o mais cedo entre a DueDate que 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 UNSCHEDULED até essa rodada, mesmo com a DueDate já vencida.
  • O lote dividido: LATE se 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 de IN_PROGRESS, PARTIAL ou OUTSOURCED; UNSCHEDULED só se nenhuma parte que não começou tem programação; WAITING no 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âmetroEfeitoExemplo
orderRefSó aquele pedido?orderRef=0001
daysAfterCompletionPor quantos dias códigos concluídos continuam aparecendo?daysAfterCompletion=3
codeLimitTeto 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.