> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.erp.olist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook - Envio de Código de Rastreio

> Receba notificações quando códigos de rastreamento forem adicionados a pedidos.

## 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

```json theme={null}
{
  "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

| 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

```php theme={null}
<?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

```python theme={null}
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

```javascript theme={null}
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