Informar valor de venda

Registra por quanto o parceiro vendeu um item do pedido.

PATCH/v1/pedidos/{id}/itens/{itemId}/valor-venda

Quando usar

Quando o seu sistema sabe o preço da venda ao cliente final e ele não foi enviado na criação do pedido — ou mudou depois. É esse valor que alimenta o resultado (faturamento, lucro e margem do parceiro).

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`id` obrigatório	texto	—	O identificador do pedido, no caminho.
`itemId` obrigatório	texto	—	O `id` do item (`itens[].id` do pedido), no caminho.
`valorVenda` obrigatório	dinheiro ou null	—	No corpo. O valor por par, não o total do item. `null` apaga o valor informado.

Exemplo

curl -X PATCH "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/itens/cmg8k1p2a0008/valor-venda" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "valorVenda": "259.90"
}'

curl -X PATCH "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/itens/cmg8k1p2a0008/valor-venda" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "valorVenda": "259.90"
}'

const resposta = await fetch('https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/itens/cmg8k1p2a0008/valor-venda', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer otl_prod_SEU_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "valorVenda": "259.90"
  }),
});

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/itens/cmg8k1p2a0008/valor-venda', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "valorVenda": "259.90"
  }),
});

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/itens/cmg8k1p2a0008/valor-venda');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_prod_SEU_TOKEN',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'valorVenda' => '259.90',
]));

$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/itens/cmg8k1p2a0008/valor-venda');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer otl_sbx_SEU_TOKEN',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'valorVenda' => '259.90',
]));

$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.patch(
    "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/itens/cmg8k1p2a0008/valor-venda",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
    },
    json={
        "valorVenda": "259.90"
    },
    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.patch(
    "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/itens/cmg8k1p2a0008/valor-venda",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
    },
    json={
        "valorVenda": "259.90"
    },
    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 testePATCHCorpo (JSON)

Resposta

200 OK, com o pedido inteiro — o valor de um item muda o resultado do pedido. O formato é o de Detalhar pedido.

{
  "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"
    }
  ]
}

Regras que não se leem no JSON

É por par. Um item com quantidade: 2 vendido a R$ 259,90 cada recebe "259.90", e entra no faturamento como R$ 519,80.
O valor pode ser alterado quantas vezes for preciso, em qualquer status do pedido.
A equipe OTL também vê este valor. As despesas, não.

Erros possíveis

HTTP	`codigo`	Quando
400	`VALIDACAO`	`valorVenda` ausente, negativo ou fora do formato `"259.90"`
404	`NAO_ENCONTRADO`	O pedido não existe (ou é de outro parceiro), ou o item não é deste pedido
403	`ESCOPO_INSUFICIENTE`	A integração não tem `pedidos:escrever`