Criar pedido

Fecha um pedido do parceiro com a OTL, com os itens no corpo da requisição.

POST/v1/pedidos

pedidos:criar Idempotency-Key obrigatória

Este endpoint cria um pedido de verdade

Em produção, o pedido criado gera compromisso de pagamento do parceiro com a OTL. Teste primeiro no sandbox, onde nada é cobrado, e use Simular pedido para conferir sem criar.

Quando usar

Quando uma venda entra no seu sistema (marketplace, loja, ERP) e precisa virar um pedido na OTL. O pedido nasce AGUARDANDO_PAGAMENTO, como os feitos no painel: a OTL confirma o pagamento com o parceiro e o status avança.

Corpo

Parâmetro	Tipo	Padrão	Descrição
`itens` obrigatório	lista	—	De 1 a 100 itens.
`itens[].sku` obrigatório	texto	—	O SKU do produto (`320`), não o da variação.
`itens[].numeracao` obrigatório	texto	—	A numeração do par (`38`).
`itens[].quantidade` obrigatório	número	—	Inteiro, de 1 a 999.
`itens[].valorVenda`	dinheiro	—	Por quanto o parceiro vendeu, por par. Opcional — alimenta o resultado do pedido.
`enviarPara` obrigatório	texto	—	`CLIENTE` (direto ao cliente final) ou `PARCEIRO` (endereço da ficha do parceiro).
`clienteId`	texto	—	Um cliente da agenda. Com `enviarPara: CLIENTE`, envie este campo ou `novoCliente`.
`novoCliente`	objeto	—	O destinatário, com os mesmos campos de Criar cliente.
`salvarCliente`	booleano	false	Com `novoCliente`: `true` também guarda o destinatário na agenda.
`referenciaExterna`	texto	—	O identificador do pedido no seu sistema, até 120 caracteres. Único por parceiro.
`observacao`	texto	—	Observação para a equipe OTL, até 1000 caracteres.

Exemplo

curl -X POST "https://api.otlshoes.com.br/v1/pedidos" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "itens": [
    {
      "sku": "320",
      "numeracao": "38",
      "quantidade": 2,
      "valorVenda": "259.90"
    }
  ],
  "enviarPara": "CLIENTE",
  "clienteId": "cmg7h2k9x0003",
  "referenciaExterna": "PED-778",
  "observacao": "Entregar à tarde"
}'

curl -X POST "https://api-sandbox.otlshoes.com.br/v1/pedidos" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "itens": [
    {
      "sku": "320",
      "numeracao": "38",
      "quantidade": 2,
      "valorVenda": "259.90"
    }
  ],
  "enviarPara": "CLIENTE",
  "clienteId": "cmg7h2k9x0003",
  "referenciaExterna": "PED-778",
  "observacao": "Entregar à tarde"
}'

const resposta = await fetch('https://api.otlshoes.com.br/v1/pedidos', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "itens": [
      {
        "sku": "320",
        "numeracao": "38",
        "quantidade": 2,
        "valorVenda": "259.90"
      }
    ],
    "enviarPara": "CLIENTE",
    "clienteId": "cmg7h2k9x0003",
    "referenciaExterna": "PED-778",
    "observacao": "Entregar à tarde"
  }),
});

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', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "itens": [
      {
        "sku": "320",
        "numeracao": "38",
        "quantidade": 2,
        "valorVenda": "259.90"
      }
    ],
    "enviarPara": "CLIENTE",
    "clienteId": "cmg7h2k9x0003",
    "referenciaExterna": "PED-778",
    "observacao": "Entregar à tarde"
  }),
});

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');
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([
    'itens' => [
        [
            'sku' => '320',
            'numeracao' => '38',
            'quantidade' => 2,
            'valorVenda' => '259.90',
        ],
    ],
    'enviarPara' => 'CLIENTE',
    'clienteId' => 'cmg7h2k9x0003',
    'referenciaExterna' => 'PED-778',
    'observacao' => 'Entregar à tarde',
]));

$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');
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([
    'itens' => [
        [
            'sku' => '320',
            'numeracao' => '38',
            'quantidade' => 2,
            'valorVenda' => '259.90',
        ],
    ],
    'enviarPara' => 'CLIENTE',
    'clienteId' => 'cmg7h2k9x0003',
    'referenciaExterna' => 'PED-778',
    'observacao' => 'Entregar à tarde',
]));

$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",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "itens": [
            {
                "sku": "320",
                "numeracao": "38",
                "quantidade": 2,
                "valorVenda": "259.90"
            }
        ],
        "enviarPara": "CLIENTE",
        "clienteId": "cmg7h2k9x0003",
        "referenciaExterna": "PED-778",
        "observacao": "Entregar à tarde"
    },
    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",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "itens": [
            {
                "sku": "320",
                "numeracao": "38",
                "quantidade": 2,
                "valorVenda": "259.90"
            }
        ],
        "enviarPara": "CLIENTE",
        "clienteId": "cmg7h2k9x0003",
        "referenciaExterna": "PED-778",
        "observacao": "Entregar à tarde"
    },
    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 pedido completo — o mesmo formato de Detalhar pedido. Um pedido recém-criado vem com status: "AGUARDANDO_PAGAMENTO" e as listas despesas, rastreios e anexos vazias.

{
  "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",
  "despesas": [
    {
      "id": "cmg8m3d1e0002",
      "descricao": "Embalagem",
      "valor": "10.00",
      "criadoEm": "2026-09-21T09:05:00-03:00"
    }
  ],
  "rastreios": [
    {
      "id": "cmg8n9q4t0001",
      "codigo": "AA123456789BR",
      "transportadora": "Correios",
      "validado": true,
      "cadastradoPeloParceiro": false,
      "criadoEm": "2026-09-22T14:03:00-03:00"
    }
  ],
  "anexos": [
    {
      "id": "cmg8k5z7u0004",
      "tipo": "COMPROVANTE",
      "nomeArquivo": "comprovante-pix.pdf",
      "tipoArquivo": "application/pdf",
      "tamanhoBytes": 51234,
      "validado": true,
      "enviadoPeloParceiro": true,
      "criadoEm": "2026-09-20T09:20:00-03:00"
    }
  ]
}

Como não criar o pedido duas vezes

Duas proteções, e vale usar as duas:

Idempotency-Key (obrigatória). Gere uma chave por pedido e, se a chamada falhar por rede ou timeout, repita com a mesma chave: você recebe o pedido que já foi criado, não um segundo. Veja Idempotência.
referenciaExterna. Se a mesma venda for enviada de novo com outra chave (um reprocessamento, um job que rodou duas vezes), a API responde 409 REFERENCIA_EXTERNA_DUPLICADA e devolve em pedido o id e o numero do pedido que já existe.

Regras que não se leem no JSON

O preço é o de atacado do momento da criação, e fica congelado no pedido. Não se envia preço: o total é calculado pela OTL.
O estoque é conferido na criação, não reservado antes. Entre uma consulta de estoque e o pedido, outro parceiro pode ter comprado o par.
Ou o pedido inteiro é criado, ou nada é. Um item indisponível recusa o pedido todo.
A ficha do parceiro precisa estar completa (fichaCompleta em Conta).
Pedido para o próprio parceiro pode ter mínimo de pares, definido pela OTL. Pedido para cliente final não tem mínimo.
O carrinho do parceiro no painel não é usado nem alterado.
Sem salvarCliente, o novoCliente fica só no pedido (clienteId: null).
O pedido aparece para a equipe OTL marcado como criado por integração.
Não há cancelamento pela API: o parceiro fala com a equipe OTL.

Erros possíveis

HTTP	`codigo`	Quando
400	`IDEMPOTENCY_KEY_OBRIGATORIA`	Faltou o cabeçalho `Idempotency-Key`
400	`VALIDACAO`	Campo ausente ou inválido. `detalhes` traz todos, com o caminho (`itens[1].quantidade`, `novoCliente.endereco.cep`). `clienteId` que não é da agenda do parceiro também cai aqui
400	`PROFILE_INCOMPLETE`	A ficha cadastral do parceiro está incompleta
400	`MIN_ITEMS_NOT_MET`	`enviarPara: PARCEIRO` com menos pares que o mínimo
403	`ESCOPO_INSUFICIENTE`	A integração não tem `pedidos:criar`
409	`REFERENCIA_EXTERNA_DUPLICADA`	Já existe pedido com esta `referenciaExterna`. Veja `pedido` na resposta
409	`REQUISICAO_EM_ANDAMENTO`	A primeira chamada com esta chave ainda não terminou
422	`ITENS_INDISPONIVEIS`	Um ou mais itens não podem ser vendidos. Veja abaixo
422	`IDEMPOTENCY_KEY_REUTILIZADA`	A mesma chave já foi usada com outro corpo
429	`LIMITE_EXCEDIDO`	Além do limite geral, esta rota aceita 30 chamadas por minuto

Itens indisponíveis

O erro lista todos os itens com problema, cada um com o indice no corpo enviado:

{
  "erro": {
    "codigo": "ITENS_INDISPONIVEIS",
    "mensagem": "Um ou mais itens não podem ser vendidos agora.",
    "itens": [
      { "indice": 0, "sku": "320", "numeracao": "38", "motivo": "ESTOQUE_INSUFICIENTE", "disponivel": 1 },
      { "indice": 2, "sku": "415", "numeracao": "40", "motivo": "SEM_ESTOQUE", "disponivel": 0 }
    ]
  }
}

`motivo`	Significado
`PRODUTO_NAO_ENCONTRADO`	Não existe produto com este SKU
`PRODUTO_INATIVO`	O produto saiu do catálogo
`NUMERACAO_INEXISTENTE`	O produto não tem esta numeração
`SEM_ESTOQUE`	Estoque zerado nesta numeração
`ESTOQUE_INSUFICIENTE`	Há menos pares do que a quantidade pedida — `disponivel` diz quantos