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

# Configurando os Correios (CWS API)

> Conecte seu contrato dos Correios via nova API CWS para SEDEX, PAC e Mini Envios.

O BulkRoute utiliza a API moderna dos Correios (CWS / REST) com autenticação baseada em cartão de postagem corporativo.

## Credenciais Necessárias

1. **Usuário do Portal Meu Correios** (geralmente o e-mail ou CNPJ).
2. **Código de Acesso da API** (gerado no portal CWS).
3. **Cartão de Postagem** (número com 10 dígitos).
4. **Número do Contrato**.

### Como obter

1. Acesse o [Portal Meu Correios](https://www.correios.com.br/meu-correios)
2. Vá em **Serviços** > **API Correios**
3. Solicite o acesso à API CWS para seu contrato
4. Gere o **código de acesso** e anote o **cartão de postagem**
5. Tenha em mãos o número do seu contrato (encontrado no documento contratual)

## Configuração no BulkRoute

1. No painel BulkRoute, selecione **Transportadoras** > **Correios**.
2. Preencha os campos com suas credenciais CWS.
3. Ative os serviços desejados:

| Código  | Serviço        | Prazo típico    |
| :------ | :------------- | :-------------- |
| `03220` | SEDEX Contrato | 1-3 dias úteis  |
| `03298` | PAC Contrato   | 3-10 dias úteis |
| `04227` | Mini Envios    | 5-15 dias úteis |
| `03204` | SEDEX 10       | 1 dia útil      |
| `03205` | SEDEX 12       | 1 dia útil      |
| `03206` | SEDEX Hoje     | Mesmo dia       |

4. Clique em **Testar Conexão** para validar se o cartão de postagem está ativo e com saldo/limite liberado.
5. Salve as configurações.

## Cubagem nos Correios

Os Correios usam fator de cubagem **6000** (cm³ → kg), diferente das transportadoras rodoviárias (fator 300):

```
Peso cubado = (Comprimento × Largura × Altura) ÷ 6000
```

O BulkRoute calcula automaticamente e compara com o peso real — a cobrança é pelo **maior**.

### Exemplo

Pacote 40×30×30 cm, 2 kg real:

* Peso cubado: `(40 × 30 × 30) ÷ 6000 = 6 kg`
* Correios cobra por **6 kg** (peso cubado)

Pacote 20×15×10 cm, 3 kg real:

* Peso cubado: `(20 × 15 × 10) ÷ 6000 = 0,5 kg`
* Correios cobra por **3 kg** (peso real)

## Limites dos Correios

| Serviço     | Peso máx. | Dimensão máx.       | Valor máx. |
| :---------- | :-------- | :------------------ | :--------- |
| SEDEX       | 30 kg     | 100 cm (maior lado) | R\$ 10.000 |
| PAC         | 30 kg     | 100 cm (maior lado) | R\$ 3.000  |
| Mini Envios | 2 kg      | 30×20×10 cm         | R\$ 500    |

<Warning>
  O BulkRoute valida automaticamente esses limites nas cotações. Se um item exceder o limite, o Correios é descartado da cotação e o log explica o motivo.
</Warning>

## Etiquetas

Os Correios fornecem etiqueta própria via API. O BulkRoute gera automaticamente no formato:

* **PDF A4** (4 etiquetas por folha — padrão SARA)
* **ZPL 100×150mm** (impressora térmica — formato compatível com SARA)

A etiqueta inclui:

* Código de rastreio (SSCC)
* Código de barras 128
* QR Code de validação
* Dados do remetente e destinatário
* Serviço contratado (SEDEX/PAC/Mini)

## Rastreamento

O BulkRoute rastreia via a API CWS de rastreio:

* **Polling a cada 15 minutos** (os Correios não enviam webhook)
* Eventos normalizados para o padrão BulkRoute
* Status `DELIVERED` confirmado via evento "Entrega Efetuada"

### Eventos comuns dos Correios

| Evento Correios      | Status BulkRoute   |
| :------------------- | :----------------- |
| Objeto postado       | `PROCESSING`       |
| Em trânsito          | `IN_TRANSIT`       |
| Saiu para entrega    | `OUT_FOR_DELIVERY` |
| Entrega efetuada     | `DELIVERED`        |
| Tentativa de entrega | `FAILED`           |
| Objeto devolvido     | `RETURNED`         |

## Troubleshooting

| Problema               | Causa                         | Solução                             |
| :--------------------- | :---------------------------- | :---------------------------------- |
| `401 Unauthorized`     | Código de acesso inválido     | Verificar credenciais no portal CWS |
| `403 Forbidden`        | Cartão de postagem sem saldo  | Recarregar cartão nos Correios      |
| `422 Validation Error` | Item excede limite do serviço | Verificar peso/dimensões            |
| Cotação vazia          | Serviço não ativo no contrato | Ativar serviço no BulkRoute         |
| Tracking não atualiza  | API CWS instável              | Aguardar próximo ciclo de polling   |