Skip to main content

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

{
  "evento": "envio_codigo_rastreio",
  "data_hora": "20/05/2024 17:20:15",
  "rastreamentos": [
    {
      "tipo_origem": "pedido",
      "id_origem": 789456,
      "numero_pedido": "12345",
      "codigo_rastreamento": "BR123456789BR",
      "url_rastreamento": "https://rastreamento.correios.com.br/app/index.php?objeto=BR123456789BR",
      "transportadora": "Correios",
      "servico": "SEDEX",
      "data_envio": "20/05/2024",
      "previsao_entrega": "23/05/2024",
      "volumes": 1,
      "peso_total": 0.5,
      "valor_frete": 25.50,
      "observacoes": "Envio expresso"
    }
  ]
}

Campos da Notificação

CampoTipoDescrição
eventostringSempre “envio_codigo_rastreio”
data_horastringData e hora do evento (dd/mm/yyyy hh:mm:ss)
rastreamentos[]arrayLista de rastreamentos criados
rastreamentos[].tipo_origemstring”pedido” ou “nota_fiscal”
rastreamentos[].id_origemintID do pedido ou nota fiscal
rastreamentos[].numero_pedidostringNúmero do pedido
rastreamentos[].codigo_rastreamentostringCódigo de rastreamento
rastreamentos[].url_rastreamentostringURL para rastreamento
rastreamentos[].transportadorastringNome da transportadora
rastreamentos[].servicostringTipo de serviço (SEDEX, PAC, etc.)
rastreamentos[].data_enviostringData de envio (dd/mm/yyyy)
rastreamentos[].previsao_entregastringPrevisão de entrega (dd/mm/yyyy)
rastreamentos[].volumesintQuantidade de volumes
rastreamentos[].peso_totaldecimalPeso total em kg
rastreamentos[].valor_fretedecimalValor do frete
rastreamentos[].observacoesstringObservações do envio

Exemplo de Implementação

PHP

<?php
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data['evento'] === 'envio_codigo_rastreio') {
    foreach ($data['rastreamentos'] as $rastreamento) {
        $tipo = $rastreamento['tipo_origem'];
        $id = $rastreamento['id_origem'];
        $codigo = $rastreamento['codigo_rastreamento'];

        // Atualiza o rastreamento no sistema local
        atualizarRastreamento($tipo, $id, $codigo);

        // Envia e-mail para o cliente
        enviarEmailRastreamento(
            $rastreamento['numero_pedido'],
            $rastreamento['codigo_rastreamento'],
            $rastreamento['url_rastreamento']
        );

        // Atualiza status do pedido
        atualizarStatusPedido($id, 'enviado');

        echo "Rastreamento {$codigo} processado\n";
    }

    http_response_code(200);
    echo json_encode(['status' => 'processado']);
}
?>

Python

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/rastreamento', methods=['POST'])
def webhook_rastreamento():
    data = request.get_json()

    if data.get('evento') == 'envio_codigo_rastreio':
        for rastreamento in data.get('rastreamentos', []):
            tipo = rastreamento['tipo_origem']
            id_origem = rastreamento['id_origem']
            codigo = rastreamento['codigo_rastreamento']

            # Atualiza banco de dados
            atualizar_rastreamento(tipo, id_origem, codigo)

            # Envia notificação push
            enviar_notificacao_cliente(
                rastreamento['numero_pedido'],
                f"Seu pedido foi enviado! Código: {codigo}"
            )

            # Envia SMS
            enviar_sms_rastreamento(
                rastreamento['numero_pedido'],
                codigo,
                rastreamento['url_rastreamento']
            )

        return jsonify({'status': 'processado'}), 200

    return jsonify({'status': 'erro'}), 400

Node.js

const express = require('express');
const nodemailer = require('nodemailer');
const app = express();

app.use(express.json());

app.post('/webhook/rastreamento', async (req, res) => {
    const data = req.body;

    if (data.evento === 'envio_codigo_rastreio') {
        for (const rastreamento of data.rastreamentos) {
            const { tipo_origem, id_origem, codigo_rastreamento, url_rastreamento } = rastreamento;

            // Atualiza no banco
            await atualizarRastreamento(tipo_origem, id_origem, codigo_rastreamento);

            // Envia e-mail
            await enviarEmailCliente({
                pedido: rastreamento.numero_pedido,
                codigo: codigo_rastreamento,
                url: url_rastreamento,
                transportadora: rastreamento.transportadora,
                previsao: rastreamento.previsao_entrega
            });

            // Atualiza status
            await atualizarStatus(id_origem, 'Em Transporte');

            console.log(`Rastreamento ${codigo_rastreamento} processado`);
        }

        res.status(200).json({ status: 'processado' });
    } else {
        res.status(400).json({ status: 'erro' });
    }
});

app.listen(3000);

Configuração

Para ativar este webhook:
  1. Acesse Configurações > Integrações > Webhooks
  2. Clique em Novo Webhook
  3. Selecione o evento Envio de Código de Rastreio
  4. Informe a URL do seu endpoint
  5. 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_entrega pode ser nulo se não informado