Listar pedidos

Os pedidos do parceiro, com itens, destinatário e o resultado de cada venda.

Quando usar

Para espelhar os pedidos no seu sistema e acompanhar o andamento de cada um. Aparecem todos os pedidos do parceiro — os feitos no painel e os criados por integração.

Parâmetros

Exemplo

curl "https://api.otlshoes.com.br/v1/pedidos?status=ENVIADO&limite=50" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN"

curl "https://api-sandbox.otlshoes.com.br/v1/pedidos?status=ENVIADO&limite=50" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN"

const resposta = await fetch('https://api.otlshoes.com.br/v1/pedidos?status=ENVIADO&limite=50', {
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
  },
});

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?status=ENVIADO&limite=50', {
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
  },
});

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?status=ENVIADO&limite=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_prod_SEU_TOKEN',
]);

$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?status=ENVIADO&limite=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_sbx_SEU_TOKEN',
]);

$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.get(
    "https://api.otlshoes.com.br/v1/pedidos",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
    },
    params={
        "status": "ENVIADO",
        "limite": "50"
    },
    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.get(
    "https://api-sandbox.otlshoes.com.br/v1/pedidos",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
    },
    params={
        "status": "ENVIADO",
        "limite": "50"
    },
    timeout=30,
)

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

Resposta

{
  "dados": [
    {
      "id": "cmg8k1p2a0007",
      "numero": 12,
      "status": "ENVIADO",
      "total": "279.80",
      "origem": "API",
      "referenciaExterna": "PED-778",
      "enviarPara": "CLIENTE",
      "clienteId": "cmg7h2k9x0003",
      "destinatario": {
        "nome": "Maria da Silva",
        "telefone": "5551999990000",
        "endereco": {
          "cep": "90000000",
          "rua": "Rua das Flores",
          "numero": "10",
          "complemento": "ap 2",
          "bairro": "Centro",
          "cidade": "Porto Alegre",
          "uf": "RS"
        }
      },
      "observacao": "Entregar à tarde",
      "itens": [
        {
          "id": "cmg8k1p2a0008",
          "sku": "320",
          "titulo": "Tênis Adidas Forum Low Branco",
          "imagem": "https://cdn.otlshoes.com.br/otl-catalog/320.webp",
          "numeracao": "38",
          "skuVariacao": "320U",
          "quantidade": 2,
          "precoAtacado": "139.90",
          "total": "279.80",
          "valorVenda": "259.90",
          "valorVendaEm": "2026-09-21T09:00:00-03:00"
        }
      ],
      "resultado": {
        "faturamento": "519.80",
        "custo": "279.80",
        "despesas": "10.00",
        "lucroBruto": "240.00",
        "lucro": "230.00",
        "margemPercentual": 44.25,
        "itens": 2,
        "itensSemVenda": 0
      },
      "criadoEm": "2026-09-20T09:15:00-03:00",
      "atualizadoEm": "2026-09-22T14:03:00-03:00"
    }
  ],
  "paginacao": {
    "proximoCursor": "eyJvIjoicmVjZW50ZXMiLCJ2IjoiMjAyNi0wOS0yMFQxMjoxNTowMC4wMDBaIiwiaWQiOiJjbWc4azFwMmEwMDA3In0",
    "temMais": true
  },
  "resumo": {
    "faturamento": "519.80",
    "custo": "279.80",
    "despesas": "10.00",
    "lucroBruto": "240.00",
    "lucro": "230.00",
    "margemPercentual": 44.25,
    "itens": 2,
    "itensSemVenda": 0,
    "pedidos": 1
  }
}

Status do pedido

Resultado

O resultado é a conta do parceiro naquele pedido — a mesma que ele vê no painel.

Regras que não se leem no JSON

• A ordem é do pedido mais recente para o mais antigo. Com atualizadoDesde, passa a ser da alteração mais antiga para a mais nova — a ordem certa para sincronizar. O cursor de uma ordem não serve na outra.
• O resumo só soma pedido pago (PAGO, EM_SEPARACAO, ENVIADO, ENTREGUE). Pedido aguardando pagamento, cancelado ou estornado aparece em dados, mas não no resumo. Filtrar por status=CANCELADO devolve os pedidos e um resumo zerado.
• atualizadoEm anda com tudo que muda no pedido: status, observação, rastreio, anexo, despesa e valor de venda. Sincronizar por atualizadoDesde é suficiente para não perder um rastreio novo.
• A lista não traz despesas, rastreios nem anexos: eles estão em Detalhar pedido.

Erros possíveis

Ver também

• Detalhar pedido
• Saldo