Homologação

A homologação é a etapa final de validação da sua integração com a Abbiamo antes de entrar em produção. Consiste em uma reunião guiada onde os 5 fluxos operacionais da integração são simulados em ambiente de testes para garantir que tudo está funcionando corretamente.

Pré-requisitos (antes da reunião)

Dois pontos são obrigatórios antes de agendar a reunião de homologação. Se algum deles não estiver cumprido, a reunião será reagendada.

1. Webhooks cadastrados

Você deve ter cadastrado os dois webhooks abaixo via API antes da reunião. Sem eles, não é possível receber pedidos nem cancelamentos.

Webhook	Descrição	Documentação
`delivery_request`	Recebe o pedido quando a Abbiamo solicita a coleta	ver payload
`cancellation_request`	Recebe o cancelamento quando o embarcador cancela o pedido	ver payload

→ Como cadastrar webhooks

2. Evidência de teste realizado no dia

Você deve enviar ao menos uma evidência de que testou sua integração no dia da reunião — print, log, registro de chamada de endpoint ou similar.

Preparação do ambiente de testes

Com os pré-requisitos confirmados, verifique se seu ambiente de testes está operacional e com pedidos disponíveis para simular os fluxos. Serão usados 5 pedidos — um por fluxo.

Os 5 fluxos validados

A referência oficial dos fluxos está em: Carrier Homologation

Fluxo 1 — Padrão (Standard)

O fluxo esperado na grande maioria das entregas. Um pedido é enviado e percorre todos os status obrigatórios.

Status obrigatórios (na ordem operacional):

Status	Endpoint
Transportadora confirmou	`/confirmed`
Em rota	`/start-delivery`
Sucesso na entrega	`/successful`
Falha na entrega	`/failed`
Falha na solicitação	`/order-failed`
Devolvido	`/returned`

Fluxo 2 — Nova Requisição (New Request)

Utilizado quando a Abbiamo precisa cancelar a entrega e fazer uma nova solicitação para o mesmo pedido.

Quem cancela: a Abbiamo, pelo dashboard.

Sua integração deve ser capaz de receber o cancelamento e aceitar um novo delivery_request para o mesmo pedido sem erros.

Fluxo 3 — Cancelamento (Cancellation)

Utilizado quando a transportadora perde ou extravia o pedido.

Quem cancela: a própria transportadora.

A sequência obrigatória é:

/failed  →  /canceled

Fluxo 4 — Devolução (Return)

Fluxo de retorno do item ao remetente após falha na entrega.

/failed  →  /returning-delivery  →  /returned

Fluxo 5 — Segunda Tentativa (Second Attempt)

Nova tentativa de entrega após falha na primeira.

/failed  →  /start-delivery  →  /successful

Validações técnicas

Durante a execução dos fluxos, os seguintes pontos são verificados:

1. Campo `event_at` com precisão de milissegundos

Todas as atualizações de status devem incluir event_at com hora, minuto, segundo e milissegundos.

✅ Correto	❌ Incorreto
`2024-01-15T14:30:45.123Z`	`2024-01-15T14:30:45Z`

Se dois eventos chegarem dentro do mesmo segundo sem precisão de milissegundos, a ordenação fica ambígua e ocorre erro.

2. Cada endpoint chamado apenas uma vez por evento

Cada endpoint de atualização de status deve ser chamado uma única vez por evento. Chamadas duplicadas (2× ou mais no mesmo endpoint para o mesmo pedido) indicam problema de retry sem idempotência na implementação.

3. Fluxo de status em ordem operacional

Os status devem ser enviados na sequência lógica da operação. Enviar /successful antes de /start-delivery, por exemplo, gera inconsistência no rastreio do cliente final.

Checklist

Antes da reunião

Webhook delivery_request cadastrado e testado
Webhook cancellation_request cadastrado e testado
Evidência de teste realizado no dia enviada para a Abbiamo
Ambiente de testes com pedidos disponíveis

Durante a reunião

Fluxo 1 (Padrão): /confirmed chamado dentro de 30 min após envio
Fluxo 1 (Padrão): todos os status obrigatórios atualizados na ordem correta
Fluxo 2 (Nova Requisição): Abbiamo cancelou pelo dashboard; novo delivery_request aceito sem erros
Fluxo 3 (Cancelamento): transportadora enviou /failed + /canceled
Fluxo 4 (Devolução): sequência /failed → /returning-delivery → /returned validada
Fluxo 5 (Segunda Tentativa): sequência /failed → /start-delivery → /successful validada
event_at com milissegundos em todas as atualizações
Nenhum endpoint chamado mais de uma vez por evento