API de Logística Reversa

Solicite coleta reversa nos Correios e acompanhe o ciclo de vida de cada solicitação.

Visão Geral

A API permite criar logísticas reversas (LR) atreladas a pedidos do seu time ou avulsas (sem orderId), listar todas as LRs e consultar uma específica pelo id ou pelo numeroPedido retornado pelos Correios.

Pré-requisitos

Antes de criar uma LR via API, é necessário cadastrar uma credencial Correios LR no dashboard com:

Usuário e senha de logística reversa fornecidos pelos Correios.
Código administrativo, cartão de postagem e endereço de destinatário (snapshot).
Código de serviço PAC e/ou SEDEX (5 dígitos) — depende do contrato com os Correios.

Liste suas credenciais via GET /credenciais para descobrir o credentialId que vai no body do POST.

Autenticação

Bearer token no header Authorization. Todas as rotas exigem chave de API válida.

Authorization: Bearer sr_live_sua_chave_aqui

Endpoints disponíveis

GET /credenciais — lista credenciais Correios do time.
POST / — cria nova solicitação.
GET / — lista solicitações com paginação por cursor.
GET /[id] — consulta detalhe + histórico Correios.

Limites do Plano

Cada plano define um limite mensal único de logísticas reversas, somando criações via dashboard e via API. O contador reinicia a cada novo período de billing do time.

Comportamento ao atingir o limite

Ao atingir o teto, o POST responde 429 Too Many Requests com:

{
  "ok": false,
  "code": "limit",
  "message": "Limite mensal de logística reversa atingido (5/5). Faça upgrade do plano ou aguarde o próximo período.",
  "current": 5,
  "max": 5
}

Códigos de Erro

O campo code nas respostas de erro indica a categoria do problema:

code	HTTP	Significado
`unauthorized`	401	Chave de API ausente ou inválida.
`validation`	400	Body inválido (zod) ou contatos do remetente/destinatário inconsistentes.
`workspace_locked`	403	Workspace do time bloqueado (sub. expirada / pagamento pendente).
`order`	404	Pedido referenciado não pertence ao time, sem código de rastreio, ou status incompatível.
`credential`	404	Credencial não pertence ao time ou código de serviço PAC/SEDEX ausente.
`correios`	422	Erro de negócio retornado pelos Correios (mensagem original em `message`).
`limit`	429	Cota mensal de LR esgotada. Inclui `current` e `max`.

Próximo: veja a página de criação para o body completo do POST e exemplos prontos.