Abbiamo DocsHomologação
O que é a homologação de transportadora, o que preparar antes da reunião e quais fluxos serão validados
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 |
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.
Testes de dias anteriores não são aceitos
O objetivo é garantir que a integração está funcional no momento da reunião, não apenas que funcionou em algum ponto no passado. Problemas de ambiente, credenciais ou configuração podem surgir entre sessões.
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
Nem todos os status são obrigatórios. Se sua transportadora não implementou os opcionais, isso não bloqueia a homologação — desde que os obrigatórios estejam corretos.
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 |
Prazo de confirmação
Após o envio do pedido, você tem até 30 minutos para chamar /confirmed. Se o prazo expirar, ocorre timeout automático — essa é a primeira validação do fluxo.
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 → /canceledEste fluxo é diferente do Fluxo 2: aqui quem inicia o cancelamento é a transportadora, não a Abbiamo.
Fluxo 4 — Devolução (Return)
Fluxo de retorno do item ao remetente após falha na entrega.
/failed → /returning-delivery → /returnedFluxo 5 — Segunda Tentativa (Second Attempt)
Nova tentativa de entrega após falha na primeira.
/failed → /start-delivery → /successfulValidaçõ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_requestcadastrado e testado - Webhook
cancellation_requestcadastrado 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):
/confirmedchamado 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_requestaceito sem erros - Fluxo 3 (Cancelamento): transportadora enviou
/failed+/canceled - Fluxo 4 (Devolução): sequência
/failed → /returning-delivery → /returnedvalidada - Fluxo 5 (Segunda Tentativa): sequência
/failed → /start-delivery → /successfulvalidada -
event_atcom milissegundos em todas as atualizações - Nenhum endpoint chamado mais de uma vez por evento