Descrição
Este webhook é acionado automaticamente sempre que um código de rastreamento for adicionado ou atualizado em um pedido ou nota fiscal.Quando é Acionado
- Cadastro de código de rastreamento em pedido
- Cadastro de código de rastreamento em nota fiscal
- Atualização de código de rastreamento existente
- Adição de dados de transportadora
Estrutura da Notificação
Campos da Notificação
| Campo | Tipo | Descrição |
|---|---|---|
| evento | string | Sempre “envio_codigo_rastreio” |
| data_hora | string | Data e hora do evento (dd/mm/yyyy hh:mm:ss) |
| rastreamentos[] | array | Lista de rastreamentos criados |
| rastreamentos[].tipo_origem | string | ”pedido” ou “nota_fiscal” |
| rastreamentos[].id_origem | int | ID do pedido ou nota fiscal |
| rastreamentos[].numero_pedido | string | Número do pedido |
| rastreamentos[].codigo_rastreamento | string | Código de rastreamento |
| rastreamentos[].url_rastreamento | string | URL para rastreamento |
| rastreamentos[].transportadora | string | Nome da transportadora |
| rastreamentos[].servico | string | Tipo de serviço (SEDEX, PAC, etc.) |
| rastreamentos[].data_envio | string | Data de envio (dd/mm/yyyy) |
| rastreamentos[].previsao_entrega | string | Previsão de entrega (dd/mm/yyyy) |
| rastreamentos[].volumes | int | Quantidade de volumes |
| rastreamentos[].peso_total | decimal | Peso total em kg |
| rastreamentos[].valor_frete | decimal | Valor do frete |
| rastreamentos[].observacoes | string | Observações do envio |
Exemplo de Implementação
PHP
Python
Node.js
Configuração
Para ativar este webhook:- Acesse Configurações > Integrações > Webhooks
- Clique em Novo Webhook
- Selecione o evento Envio de Código de Rastreio
- Informe a URL do seu endpoint
- Salve as configurações
Casos de Uso
- Notificação automática ao cliente: Envie e-mail/SMS com código de rastreamento
- Atualização de status: Mude o status do pedido automaticamente
- Dashboard de entregas: Atualize painéis em tempo real
- Integração com marketplaces: Envie informações de rastreamento para plataformas externas
- Sistema de logística: Integre com sistemas de gestão de entregas
Boas Práticas
- Valide o código: Verifique o formato do código de rastreamento antes de processar
- E-mail transacional: Use templates profissionais para notificar clientes
- Rastreamento automático: Implemente polling para atualizar status da entrega
- Notificações múltiplas: Envie via e-mail, SMS e notificação push
- Log de envios: Registre todas as notificações enviadas aos clientes
Formato de Códigos por Transportadora
Correios
- Formato: 13 caracteres (ex: BR123456789BR)
- Padrão: 2 letras + 9 números + 2 letras
Transportadoras Privadas
- Variável: Cada transportadora tem seu próprio formato
- Exemplos:
- Jadlog: 15 dígitos numéricos
- Total Express: Alfanumérico variável
- Azul Cargo: Alfanumérico com 11-13 caracteres
Observações
- A URL de rastreamento pode não estar disponível para todas as transportadoras
- Múltiplos volumes podem gerar múltiplos códigos de rastreamento
- O webhook é enviado imediatamente após o cadastro do código
- Alterações no código de rastreamento geram nova notificação
- O campo
previsao_entregapode ser nulo se não informado
