# 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](https://abbiamo.readme.io/reference/deliveries) | | `cancellation_request` | Recebe o cancelamento quando o embarcador cancela o pedido | [ver payload](https://abbiamo.readme.io/reference/cancellation) | → [Como cadastrar webhooks](https://abbiamo.readme.io/reference/list-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. **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](https://abbiamo.readme.io/reference/homologation) **Note:** 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 → /canceled ``` **Note:** Este 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 → /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 --- ## Referências - [Carrier Homologation — API Reference](https://abbiamo.readme.io/reference/homologation) - [Delivery Request — payload completo](https://abbiamo.readme.io/reference/deliveries) - [Cancellation Request — payload completo](https://abbiamo.readme.io/reference/cancellation) - [Gerenciar webhooks](https://abbiamo.readme.io/reference/list-webhooks)