Homologação

Como não há ambiente de testes, a validação acontece em produção, com loja e pedidos de teste combinados com a RaptorX. Antes de ir ao ar, confirme cada item.

Cuidado

Avise a RaptorX antes de começar. Cada entrega criada é real e pode acionar um entregador.

Credenciais e acesso

• Recebi a URL base, o clientId e o clientSecret, e guardei o segredo em um cofre.
• Obtenho o token com client_credentials e o renovo antes de 1 hora ou ao receber 401.
• Enviei à RaptorX o Merchant ID e a URL de webhook corretos de cada loja.

Criação e pedido pronto

• Envio orderId estável e orderDisplayId para cada pedido.
• Sempre envio o telefone do destinatário.
• Envio latitude e longitude do endereço de entrega.
• Mapeei as formas de pagamento (ONLINE, PIX, CASH, cartão, vale) e o troco corretamente.
• Repito a criação em caso de timeout e confirmo que não duplica (mesmo deliveryId).
• Guardo o deliveryId da resposta e o uso em readyForPickup, consulta e cancelamento.
• Chamo readyForPickup quando o pedido fica pronto.

Webhook

• O endpoint é HTTPS, público e não redireciona.
• Valido X-App-Signature sobre o corpo bruto, com comparação em tempo constante.
• Respondo 2xx em poucos segundos e processo o resto depois.
• Trato eventos duplicados e fora de ordem sem retroceder o status.
• Trato todos os tipos de evento: PENDING, ACCEPTED, PICKUP_ONGOING, ORDER_PICKED, DELIVERY_ONGOING, ARRIVED_AT_CUSTOMER, ORDER_DELIVERED, DELIVERY_FINISHED, CANCELLED, REJECTED, RETURNING_TO_MERCHANT e RETURNED_TO_MERCHANT.

Cancelamento e erros

• Testei o cancelamento de uma entrega de teste (a loja precisa da permissão habilitada pela RaptorX).
• Trato 403, 409 e 422 do cancelamento mostrando uma mensagem útil ao lojista.
• Trato 429, 5xx e timeouts com nova tentativa e espera crescente.
• Não uso a disponibilidade como cotação ou verificação de cobertura: ela sempre retorna available: true.

Antes de liberar para as lojas

• Fiz o fluxo completo (criar, pronto, aceitar, retirar, entregar) com a RaptorX acompanhando.
• Combinei com a RaptorX o contato para suporte e como tratar entregas que não são aceitas.