Correios

Os Correios são a maior transportadora do Brasil. Quando a loja usa a integração Correios 2.0, cada seller (lojista) tem o seu próprio contrato (cartão de postagem), sem herdar o da loja. O pedido é dividido em volumes (pacotes físicos), e cada volume ganha uma pré-postagem: um registro no sistema dos Correios que gera o código de rastreio e a etiqueta (PDF) para colar na caixa. A pré-postagem vale por poucos dias; se vence sem a caixa ser postada, é preciso renová-la. Estas rotas fazem tudo isso pela API.

Como funciona

1. Cadastre as credenciais
   PUT /config com o cartão de postagem, login e senha da API; teste com POST /test.
2. Cadastre caixas (opcional)
   Para o empacotamento usar suas caixas reais.
3. Receba o pedido
   O checkout cria os volumes com o serviço escolhido.
4. Emita
   POST /volumes/{volumeId}/preposting devolve o rastreio.
5. Baixe a etiqueta
   GET /postings/{postingId}/documents/label, ou um lote com vários volumes.
6. Acompanhe
   GET /orders/{orderId}/tracking-events e, se preciso, POST /volumes/{volumeId}/tracking/refresh.

Estados da emissão

Conceitos-chave

Volume, emissão e rastreio

Um volume é um pacote físico. Um pedido grande vira vários volumes, dimensionados com as caixas de embalagem cadastradas. Cada volume tem uma emissão atual e um histórico de emissões anteriores. O rastreio (eventos do SRO, o sistema de rastreamento dos Correios) é puxado automaticamente e pode ser atualizado à mão uma vez por minuto.

Privilégios

Credenciais e caixas: leitura com vendor_settings (ou um dos privilégios de leitura de configurações); gravação com vendor_settings. Emitir, renovar, cancelar, baixar documentos e atualizar rastreio: vendor_orders, vendor_manage_orders ou vendor_manage_fulfillments. Consultas de volumes, operação e rastreio: qualquer privilégio de pedidos. O dono da conta sempre passa.

Endpoints

Erros comuns

1. Esquecer as credenciais. Sem cartão de postagem do seller, o checkout não oferece Correios e a emissão falha.
2. Emitir duas vezes. Se o volume já tem emissão, a resposta é 409 O volume já possui uma emissão. Use consultar ou renovar.
3. Renovar o que já foi postado. Objeto posted não pode ser reemitido.
4. Cancelar e emitir de novo sem renovar. Após cancelar, só renovar (ação humana explícita) destrava.
5. Atualizar o rastreio mais de uma vez por minuto. 429 com Retry-After.
6. Mandar rate_calculation R sem código de serviço. Veja Formas de envio.
7. Contar com a etiqueta para sempre. A pré-postagem vence: confira validity_expires_at.

Próximos passos