Criar Logística Reversa

POST que dispara a coleta reversa nos Correios e persiste o resultado no banco do time.

Endpoint

POST/api/public/logistica-reversa

Auth10/min por IP

Body (JSON)

Omita orderId para uma LR avulsa (a API gera um ID interno lr_avulso_* que não é exposto nas consultas).

Campo	Tipo	Obrig.	Descrição
`credentialId`	uuid	sim	ID de uma credencial Correios LR do seu time. Use GET /credenciais para listar.
`tipo`	enum	sim	`A` = agendada, `C` = coleta domiciliar, `CA` = coleta na agência.
`servicoEnvio`	enum	sim	`pac` ou `sedex`. Deve haver código de serviço (5 dígitos) cadastrado para a opção escolhida na credencial.
`remetente`	object	sim	Dados do remetente da etiqueta reversa (cliente final). Veja schema abaixo.
`orderId`	string	não	ID do pedido do time. Se informado, o pedido precisa existir, ter `trackingCode` e estar em status `shipped` ou `delivered`.
`valorDeclarado`	number	não	Valor declarado em reais (0 a 10000). Opcional.
`descricao`	string	não	Texto livre, até 255 caracteres.
`objDesc`	string	não	Descrição do objeto coletado (até 255 caracteres). Default: "Devolução".

Schema do remetente

Todos os campos são obrigatórios. CEP só os 8 dígitos. DDD com 2 dígitos. Telefone com 8-9 dígitos.

Campo	Tipo	Obrig.	Descrição
`remetente.nome`	string	sim	Nome completo.
`remetente.logradouro`	string	sim	Rua/Avenida.
`remetente.numero`	string	sim	Número do endereço.
`remetente.complemento`	string	sim	Pode ser string vazia ("").
`remetente.bairro`	string	sim	Bairro.
`remetente.cidade`	string	sim	Cidade.
`remetente.uf`	string(2)	sim	UF, sigla com 2 letras.
`remetente.cep`	string(8)	sim	Apenas dígitos.
`remetente.ddd`	string(2)	sim	DDD do telefone.
`remetente.telefone`	string	sim	Telefone, 8-9 dígitos sem máscara.
`remetente.email`	string	sim	E-mail válido.

Exemplo de body

{
  "credentialId": "9a2c1f80-1234-4abc-9def-000000000001",
  "tipo": "A",
  "servicoEnvio": "pac",
  "valorDeclarado": 89.90,
  "descricao": "Devolução tamanho",
  "objDesc": "Tênis tamanho 41",
  "orderId": "ord_123456",
  "remetente": {
    "nome": "Maria Silva",
    "logradouro": "Rua das Flores",
    "numero": "100",
    "complemento": "Apto 12",
    "bairro": "Centro",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "01310100",
    "ddd": "11",
    "telefone": "987654321",
    "email": "[email protected]"
  }
}

Resposta de Sucesso (201)

{
  "ok": true,
  "id": "lr_uuid_interno",
  "idCliente": "lr1a2b3c4d5e6f...",
  "orderId": "ord_123456",
  "numeroPedido": "1234567890",
  "numeroEtiqueta": "AA123456789BR",
  "prazoValidade": "2026-05-18T00:00:00.000Z",
  "createdAt": "2026-04-18T12:00:00.000Z"
}

Para LR avulsa, o campo orderId retornado começa com lr_avulso_ — esse valor é interno e não aparece nas listagens (é mascarado como null).

Erros comuns

Veja a tabela completa de códigos. Os mais frequentes:

422 correios — Correios rejeitou (telefone, CEP, código de serviço errado).
404 credential — credentialId não pertence ao time.
404 order — pedido não enviado/entregue ou sem código de rastreio.
429 limit — cota mensal estourada.

Exemplos

cURL

curl -X POST "https://seurastreio.com.br/api/public/logistica-reversa" \
  -H "Authorization: Bearer sr_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialId": "9a2c1f80-1234-4abc-9def-000000000001",
    "tipo": "A",
    "servicoEnvio": "pac",
    "remetente": {
      "nome": "Maria Silva",
      "logradouro": "Rua das Flores",
      "numero": "100",
      "complemento": "",
      "bairro": "Centro",
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01310100",
      "ddd": "11",
      "telefone": "987654321",
      "email": "[email protected]"
    }
  }'

JavaScript

const res = await fetch("https://seurastreio.com.br/api/public/logistica-reversa", {
  method: "POST",
  headers: {
    Authorization: "Bearer sr_live_sua_chave_aqui",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    credentialId: "9a2c1f80-1234-4abc-9def-000000000001",
    tipo: "A",
    servicoEnvio: "pac",
    remetente: {
      nome: "Maria Silva",
      logradouro: "Rua das Flores",
      numero: "100",
      complemento: "",
      bairro: "Centro",
      cidade: "São Paulo",
      uf: "SP",
      cep: "01310100",
      ddd: "11",
      telefone: "987654321",
      email: "[email protected]",
    },
  }),
});
if (!res.ok) {
  const err = await res.json();
  console.error(err.code, err.message);
}
const data = await res.json();
console.log(data.numeroEtiqueta);

Python

import requests

payload = {
    "credentialId": "9a2c1f80-1234-4abc-9def-000000000001",
    "tipo": "A",
    "servicoEnvio": "pac",
    "remetente": {
        "nome": "Maria Silva",
        "logradouro": "Rua das Flores",
        "numero": "100",
        "complemento": "",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "uf": "SP",
        "cep": "01310100",
        "ddd": "11",
        "telefone": "987654321",
        "email": "[email protected]",
    },
}

r = requests.post(
    "https://seurastreio.com.br/api/public/logistica-reversa",
    headers={"Authorization": "Bearer sr_live_sua_chave_aqui"},
    json=payload,
)
print(r.status_code, r.json())

Cada chamada com sucesso conta para a cota mensal de logística reversa do time. Veja seu uso atual em Dashboard → Time.