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

# Rastreio Unificado & Notificações

> Entenda as 3 camadas de rastreamento e como configurar a página de rastreio personalizada com a sua marca.

Um dos maiores desafios logísticos é manter o cliente informado sem sobrecarregar a central de SAC. O BulkRoute resolve isso com o motor de rastreamento em 3 camadas.

## As 3 Camadas de Atualização

### 1. Webhook Inbound (Push)

Transportadoras modernas enviam atualizações push imediatas para o BulkRoute:

* Lalamove, Kombex, DHL, FedEx

O BulkRoute valida a assinatura HMAC de cada webhook, normaliza o status e dispara o webhook outbound para o seu sistema.

### 2. Polling Periódico Inteligente

Para transportadoras que não emitem webhooks (Braspress, Jadlog, SSW, Correios):

* Cron job automático consulta o status a cada **15 minutos**
* Só consulta shipments ativos (PICKED\_UP até OUT\_FOR\_DELIVERY)
* Limite de concorrência por carrier para não estourar rate limit
* Desativável via variável de ambiente `TRACKING_POLL_ENABLED=false`

### 3. App do Motorista (Frota Própria)

O motorista atualiza os eventos em tempo real direto do celular:

* Saída para entrega
* Tentativa frustrada com foto e motivo
* Entrega concluída com assinatura digital
* Geolocalização GPS de cada evento

## Status Padronizados

Todos os eventos de todos os carriers são normalizados para um único padrão:

| Status BulkRoute   | Descrição                          | Cor          |
| :----------------- | :--------------------------------- | :----------- |
| `PENDING`          | Aguardando processamento inicial   | Cinza        |
| `PROCESSING`       | Envio criado, aguardando coleta    | Azul         |
| `PICKED_UP`        | Carga coletada na expedição        | Azul         |
| `IN_TRANSIT`       | Em transferência entre filiais/CDs | Amarelo      |
| `OUT_FOR_DELIVERY` | Em rota final de entrega           | Laranja      |
| `DELIVERED`        | Entrega finalizada com sucesso     | Verde        |
| `FAILED`           | Tentativa frustrada / ocorrência   | Vermelho     |
| `RETURNED`         | Devolução em andamento             | Roxo         |
| `CANCELLED`        | Envio cancelado                    | Cinza escuro |

## Página de Rastreio com a sua Marca (Branded Tracking)

Em vez de direcionar seu cliente para sites genéricos das transportadoras, envie o link de rastreamento do BulkRoute:

```
https://www.bulkroute.com.br/tracking/BRFMSF5NRT9S0M
```

A página exibe:

* **Logotipo da sua empresa** (light e dark mode)
* **Cores da sua marca** (cor primária e de destaque)
* **CSS customizado** (opcional — para personalização avançada)
* **Título da página** (ex: "Rastreio - Cliente X")
* **Rodapé customizado** com link para seu site
* **Linha do tempo visual** limpa e descomplicada

### Como configurar

1. Acesse **Configurações da Empresa** > **Branding**
2. Faça upload do seu logo (light e dark mode)
3. Defina a cor primária (HEX ou OKLCH)
4. Defina a cor de destaque
5. (Opcional) Cole seu CSS customizado
6. Defina o título da página e rodapé
7. Use o **Preview** para ver como vai ficar antes de publicar

### Domínio próprio (Enterprise)

Clientes Enterprise podem usar seu próprio domínio para a página de rastreio:

```
https://rastreio.suaempresa.com.br/tracking/BRFMSF5NRT9S0M
```

Para configurar:

1. Crie um CNAME `rastreio.suaempresa.com.br` → `saas.bulkroute.com.br`
2. Entre em contato com o suporte para ativar o Cloudflare for SaaS
3. Configure o domínio customizado no painel de Branding

## Notificações Proativas ao Cliente Final

O BulkRoute envia notificações automáticas ao destinatário em eventos-chave:

| Evento             | Canal                   | Quando                                    |
| :----------------- | :---------------------- | :---------------------------------------- |
| `PICKED_UP`        | WhatsApp / SMS / E-mail | Carga coletada                            |
| `OUT_FOR_DELIVERY` | WhatsApp / SMS / E-mail | Saiu para entrega                         |
| `DELIVERED`        | WhatsApp / SMS / E-mail | Entrega concluída + link de avaliação NPS |
| `EXCEPTION`        | WhatsApp / SMS / E-mail | Ocorrência ou tentativa frustrada         |
| `RESCHEDULED`      | WhatsApp / SMS / E-mail | Reagendamento confirmado                  |

### Configurar canais

1. Acesse **Configurações** > **Notificações**
2. Ative os canais disponíveis:
   * **WhatsApp** (usa provider integrado)
   * **SMS** (Twilio)
   * **E-mail** (AWS SES)
3. Edite os templates por evento (suporta i18n pt-BR e en)
4. Defina o **rate limit** por destinatário (padrão: 5/dia)

### Opt-out

O destinatário pode cancelar as notificações:

* Responde "SAIR" no WhatsApp/SMS
* Clica em "Cancelar notificações" no e-mail
* O sistema respeita a preferência e não envia mais

## NPS pós-entrega

24 horas após `DELIVERED`, o BulkRoute envia automaticamente:

* Link de avaliação (1-10)
* Campo de feedback opcional
* O resultado fica disponível no dashboard de NPS

## Webhook Outbound (para seu sistema)

Sempre que o status muda, o BulkRoute envia um `POST` para a URL que você configurou:

```json theme={null}
{
  "event": "shipment.status_updated",
  "timestamp": "2026-09-06T18:30:00Z",
  "data": {
    "shipmentId": "shp_987654321",
    "trackingCode": "BR123456789BR",
    "carrierCode": "braspress",
    "previousStatus": "IN_TRANSIT",
    "currentStatus": "DELIVERED",
    "occurredAt": "2026-09-06T18:28:45Z"
  }
}
```

Cada requisição inclui o header `X-BulkRoute-Signature` com HMAC-SHA256 para validação. Veja [Webhooks](/api-reference/webhooks) para detalhes.