Cadastrar rastreio

Acrescenta um código de rastreio ao pedido.

POST/v1/pedidos/{id}/rastreios

Quando usar

Quando o envio é emitido pelo parceiro (fora da OTL) e o código precisa aparecer no pedido. Um pedido aceita vários códigos — envio em mais de um volume, ou troca de transportadora.

Corpo

Parâmetro	Tipo	Padrão	Descrição
`id` obrigatório	texto	—	O identificador do pedido, no caminho.
`codigo` obrigatório	texto	—	Pelo menos 5 caracteres. Espaços são removidos e as letras viram maiúsculas.
`transportadora`	texto	—	Nome livre, até 60 caracteres.

Exemplo

curl -X POST "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "codigo": "AA123456789BR",
  "transportadora": "Correios"
}'

curl -X POST "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "codigo": "AA123456789BR",
  "transportadora": "Correios"
}'

const resposta = await fetch('https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "codigo": "AA123456789BR",
    "transportadora": "Correios"
  }),
});

if (!resposta.ok) {
  const { erro } = await resposta.json();
  throw new Error(`${erro.codigo}: ${erro.mensagem} (${erro.requestId})`);
}
const dados = await resposta.json();

const resposta = await fetch('https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "codigo": "AA123456789BR",
    "transportadora": "Correios"
  }),
});

if (!resposta.ok) {
  const { erro } = await resposta.json();
  throw new Error(`${erro.codigo}: ${erro.mensagem} (${erro.requestId})`);
}
const dados = await resposta.json();

<?php
$ch = curl_init('https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_prod_SEU_TOKEN',
    'Idempotency-Key: 7f3c1b9e-pedido-ml-123',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'codigo' => 'AA123456789BR',
    'transportadora' => 'Correios',
]));

$corpo = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception($corpo['erro']['codigo'] . ': ' . $corpo['erro']['mensagem']);
}

<?php
$ch = curl_init('https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key: 7f3c1b9e-pedido-ml-123',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'codigo' => 'AA123456789BR',
    'transportadora' => 'Correios',
]));

$corpo = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception($corpo['erro']['codigo'] . ': ' . $corpo['erro']['mensagem']);
}

import requests

resposta = requests.post(
    "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "codigo": "AA123456789BR",
        "transportadora": "Correios"
    },
    timeout=30,
)

if not resposta.ok:
    erro = resposta.json()["erro"]
    raise RuntimeError(f'{erro["codigo"]}: {erro["mensagem"]} ({erro["requestId"]})')
dados = resposta.json()

import requests

resposta = requests.post(
    "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/rastreios",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "codigo": "AA123456789BR",
        "transportadora": "Correios"
    },
    timeout=30,
)

if not resposta.ok:
    erro = resposta.json()["erro"]
    raise RuntimeError(f'{erro["codigo"]}: {erro["mensagem"]} ({erro["requestId"]})')
dados = resposta.json()

Testar agora no ambiente de testes

A chamada é feita de verdade, do seu navegador para a API de testes (https://api-sandbox.otlshoes.com.br/v1). Use um token otl_sbx_…: ele fica só nesta aba, e some ao fechá-la. Token de produção não é aceito aqui.

Token de testePOSTIdempotency-KeyCorpo (JSON)

Resposta

201 Created, com o rastreio criado:

{
  "id": "cmg8n9q4t0001",
  "codigo": "AA123456789BR",
  "transportadora": "Correios",
  "validado": false,
  "cadastradoPeloParceiro": true,
  "criadoEm": "2026-09-22T14:03:00-03:00"
}

Regras que não se leem no JSON

O código sai normalizado: aa123 456789 br vira AA123456789BR. É assim que a API detecta o código repetido.
O rastreio nasce com validado: false. Quem valida é a equipe OTL — e, depois de validado, o parceiro não consegue mais removê-lo.
Cadastrar um rastreio move o atualizadoEm do pedido: ele volta a aparecer em Listar pedidos com atualizadoDesde.
Cadastrar o código não muda o status do pedido.

Erros possíveis

HTTP	`codigo`	Quando
400	`VALIDACAO`	`codigo` ausente ou com menos de 5 caracteres
404	`NAO_ENCONTRADO`	O pedido não existe — ou é de outro parceiro
409	`CONFLITO`	Este código já está cadastrado neste pedido
403	`ESCOPO_INSUFICIENTE`	A integração não tem `pedidos:escrever`

Ver também

Remover rastreio