Começar pela edição e pelo fluxo
Manhattan é uma família de soluções; não existe um único contrato de integração aplicável a todas as instalações. Identifique produto, versão, extensões, interfaces disponíveis e responsabilidades já executadas pelo WMS/WES. A documentação de Manhattan Active descreve orquestração de automação, mas isso não comprova que uma instalação específica exponha determinado endpoint.
Mapeie os fluxos de recebimento, armazenagem, separação e expedição separadamente. Para cada um, determine quem cria a tarefa, quem pode alterá-la e qual evidência permite concluí-la. A integração ABNET WCS deve respeitar esse contrato, em vez de reproduzir regras de estoque em uma segunda camada.
Referência técnica: Manhattan — Integrated Automation & Robotics.
Mensagens com identidade estável
Defina identificadores de tarefa, unidade de carga, mensagem e correlação. Documente campos obrigatórios, unidades, enumerações, timezone e compatibilidade de versões. Uma alteração de prioridade não deve ser interpretada como uma nova tarefa, e uma retransmissão não deve criar outro movimento.
Um acknowledgement de transporte confirma recepção no nível definido pelo protocolo. O aceite de negócio indica que a solicitação foi validada; a conclusão exige evidência física. Armazene o estado da publicação de eventos para recuperar confirmações após quedas de conexão.
Retry e filas de exceção
Retry é apropriado para falhas transitórias, com limite, espaçamento e controle de volume. Um destino inválido exige correção, não repetição infinita. Uma fila de exceções precisa de responsável, diagnóstico e procedimento de reenvio que preserve identidade e rastreabilidade.
Defina também como consultar tarefas abertas e reconciliar resultados. Comparar apenas quantidade de mensagens não encontra uma confirmação associada à carga errada. Use uma relação por tarefa entre estado no WMS, estado no WCS e posição física conhecida.
Exemplo: confirmação depois do timeout
O WCS entrega C31 e envia o evento E91. O WMS processa E91, mas a resposta se perde. O reenvio deve ser reconhecido como repetição de E91, sem um novo lançamento. Se uma atualização de tarefa chegar depois da conclusão, o contrato deve determinar rejeição ou compensação, nunca reabrir silenciosamente o movimento.
No aceite, inclua indisponibilidade prolongada, eventos fora de ordem e recuperação de filas. Especifique os limites de latência e vazão a partir do fluxo contratado; números de demonstração não substituem o dimensionamento do ambiente real.
Antes da API: fechar a fronteira funcional
Registre produto e versão Manhattan, extensões, autenticação, limites de tráfego e ambientes disponíveis. Para cada fluxo, descreva o evento que cria a tarefa, a autoridade sobre destino e o ponto físico que permite concluí-la. A mesma operação pode atravessar WMS, WES, WCS e controle local sem que cada sigla corresponda a um servidor separado.
O documento de interface deve incluir sequência nominal, cancelamento, alteração de prioridade, execução parcial e retomada. Defina responsáveis pelas duas pontas e como validar uma mudança de contrato. Uma conexão tecnicamente ativa ainda pode transportar uma interpretação incorreta de destino ou unidade de carga.
Contrato ilustrativo: mensagem não é tarefa
O JSON abaixo é um exemplo didático criado para explicar o contrato. Não é uma API oficial da Manhattan nem um formato publicado do ABNET WCS. Os nomes e valores devem ser mapeados para a interface realmente disponibilizada no projeto.
messageId identifica uma entrega lógica de mensagem; taskId identifica a operação física; taskVersion distingue alterações autorizadas. correlationId liga comandos e eventos da mesma cadeia. A chave de deduplicação deve incluir o escopo necessário, como origem e instalação, para evitar colisões entre emissores.
{
"schemaVersion": "example-1",
"messageId": "MSG-0091",
"taskId": "T42",
"taskVersion": 1,
"correlationId": "FLOW-018",
"loadId": "C18",
"source": "IN-01",
"destination": "S3",
"intent": "MOVE"
}| Elemento | Regra a especificar | Falha evitada |
|---|---|---|
| Identidade e escopo | Unicidade, retenção e comportamento após reinício | Reexecutar mensagem antiga depois de perder o histórico. |
| Versão da tarefa | Aceitar atualização apenas na versão e fase permitidas | Prioridade antiga sobrescrever decisão recente. |
| Carga e endereços | Validar existência, formato e mapeamento | Mover a carga correta para o endereço errado. |
| Resultado | Separar recebido, aceito, executando e concluído | Confirmar estoque antes da entrega física. |
Três confirmações diferentes no mesmo fluxo
Recepção de transporte, aceite de negócio e conclusão física devem ser distinguíveis nos logs e na interface. Um retorno de transporte pode acontecer antes de o consumidor validar o destino. Da mesma forma, uma tarefa aceita pode aguardar capacidade sem que exista falha de comunicação.
Manhattan → WCS
Solicitar T42; identificar carga, destino e versão.
Canal → emissor
Confirmar recepção conforme o protocolo, sem inferir execução.
WCS → Manhattan
Aceitar após validação e registro, ou rejeitar com motivo.
WCS ↔ equipamento
Reservar, enviar comando e acompanhar a carga.
WCS → Manhattan
Publicar entrega comprovada com identidade de evento estável.
Manhattan → integração
Confirmar processamento ou permitir reconciliação do resultado.
Se a última resposta se perder, repetir o evento não pode repetir o lançamento de estoque. A retenção de deduplicação deve cobrir a janela de replay prevista no projeto.
Ordenação, timeout e fila de exceções
Ordene operações que dependem umas das outras, por exemplo atualizações da mesma tarefa. Não imponha uma fila global se tarefas independentes puderem avançar em paralelo. Ao receber uma versão futura sem a anterior, o contrato deve prever espera, consulta de estado ou rejeição diagnosticável; um timestamp sozinho não resolve a ordem causal.
Para falhas transitórias, limite tentativas e use espaçamento progressivo com variação para evitar reenvios sincronizados. Uma rejeição de conteúdo vai para correção, não para retry infinito. A fila de exceções precisa de dono, contexto e reenvio auditável. Corrigir conteúdo mantendo a mesma chave pode ser interpretado como repetição; defina como uma versão corrigida recebe identidade válida.
| Ocorrência | Ação de referência | O que não fazer |
|---|---|---|
| Resposta perdida após aceite | Consultar T42 ou repetir a mesma solicitação de modo idempotente | Criar T43 apenas porque houve timeout. |
| Destino inválido | Rejeitar com código e contexto; corrigir pelo fluxo autorizado | Repetir indefinidamente o mesmo conteúdo. |
| Cancelamento após movimento | Avaliar ponto de compromisso e ação compensatória | Apagar a tarefa enquanto a carga continua em trânsito. |
| Conclusão recebida duas vezes | Retornar o resultado já aplicado | Lançar uma segunda movimentação de estoque. |
Matriz mínima de aceite da integração
O teste deve provar integridade de negócio e execução, não apenas conectividade. Use tarefas identificáveis, estado inicial conhecido e registros correlacionados dos dois sistemas. Os valores de carga e tempo de recuperação devem vir dos requisitos operacionais acordados.
Ao encerrar cada cenário, concilie três conjuntos: tarefas aceitas, cargas fisicamente entregues e resultados registrados no WMS. Toda diferença deve estar explicada por rejeição, cancelamento ou exceção aberta. Um painel sem alarmes não substitui essa conciliação.
| Cenário | Resultado esperado | Evidência |
|---|---|---|
| Duplicar solicitação | Uma tarefa física, resposta coerente às repetições | taskId, deduplicação e trajetória da carga. |
| Perder confirmação final | Notificação recuperada sem nova execução | Evento original e um resultado no WMS. |
| Inverter atualizações | Não aplicar versão antiga sobre a nova | Versões recebidas, decisão e estado final. |
| Reiniciar durante execução | Recuperar ou bloquear para conciliação | Estado persistido, observação física e decisão de retomada. |
| Interromper e restaurar o canal | Drenar backlog dentro do limite acordado | Idade das filas, vazão útil e tarefas sem resultado. |
Critérios para verificar no projeto
- Confirmar edição, interface e autoridade de cada sistema.
- Perder a resposta após o processamento e verificar deduplicação.
- Conciliar tarefas abertas após interrupção prolongada.
Os exemplos descrevem decisões de engenharia e cenários de teste. Interfaces, limites e recursos implantados são definidos no escopo de cada projeto.