Emitir etiqueta

Cria e paga a etiqueta de envio de um pedido, na conta SuperFrete do parceiro.

POST/v1/pedidos/{id}/etiquetas

etiquetas:emitir Idempotency-Key obrigatória

Esta chamada gasta dinheiro do parceiro

Emitir paga a etiqueta na hora: o valor sai da carteira SuperFrete do parceiro. Não existe “criar sem pagar”. Por isso a Idempotency-Key é obrigatória — se a sua chamada der timeout e você repetir com a mesma chave, a etiqueta não é paga duas vezes.

Quando usar

Quando o pedido está pronto para ser enviado e o parceiro quer que a OTL despache com a etiqueta dele. Depois de emitida, ela entra na fila da equipe OTL, que imprime, cola na caixa e despacha.

Corpo

Parâmetro	Tipo	Padrão	Descrição
`id` obrigatório	texto	—	O identificador do pedido, no caminho.
`servico` obrigatório	inteiro	—	O `servico.id` escolhido na cotação: `1` PAC, `2` SEDEX, `17` Mini Envios.
`documentoDestinatario`	texto	—	CPF ou CNPJ do destinatário, com ou sem pontuação. Obrigatório quando o pedido vai para um cliente; dispensado quando vai para o próprio parceiro (usa o CPF da ficha dele).

Exemplo

curl -X POST "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "servico": 1,
  "documentoDestinatario": "529.982.247-25"
}'

curl -X POST "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN" \
  -H "Idempotency-Key: 7f3c1b9e-pedido-ml-123" \
  -H "Content-Type: application/json" \
  -d '{
  "servico": 1,
  "documentoDestinatario": "529.982.247-25"
}'

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

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/etiquetas', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer otl_sbx_SEU_TOKEN',
    'Idempotency-Key': '7f3c1b9e-pedido-ml-123',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "servico": 1,
    "documentoDestinatario": "529.982.247-25"
  }),
});

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/etiquetas');
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([
    'servico' => 1,
    'documentoDestinatario' => '529.982.247-25',
]));

$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/etiquetas');
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([
    'servico' => 1,
    'documentoDestinatario' => '529.982.247-25',
]));

$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/etiquetas",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "servico": 1,
        "documentoDestinatario": "529.982.247-25"
    },
    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/etiquetas",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
        "Idempotency-Key": "7f3c1b9e-pedido-ml-123",
    },
    json={
        "servico": 1,
        "documentoDestinatario": "529.982.247-25"
    },
    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 a etiqueta já paga:

{
  "id": "cmg8p2r5v0003",
  "pedido": {
    "id": "cmg8k1p2a0007",
    "numero": 12
  },
  "servico": {
    "id": 1,
    "nome": "PAC"
  },
  "transportadora": "PAC",
  "valor": "23.72",
  "status": "GERADA",
  "rastreio": "AA123456789BR",
  "emitidaEm": "2026-09-21T11:00:00-03:00",
  "impressaEm": null,
  "despachadaEm": null,
  "canceladaEm": null,
  "atualizadoEm": "2026-09-21T11:00:00-03:00"
}

Campo	Tipo	Descrição
`id`	texto	O identificador da etiqueta.
`pedido`	objeto	O pedido da etiqueta: `id` e `numero`.
`servico`	objeto	`id` e `nome` do serviço escolhido (1 PAC, 2 SEDEX, 17 Mini Envios).
`transportadora`	texto	Quem transporta.
`valor`	dinheiro	Quanto saiu da carteira SuperFrete do parceiro.
`status`	texto	`GERADA` (paga, esperando a OTL imprimir), `IMPRESSA`, `DESPACHADA` ou `CANCELADA`.
`rastreio`	texto	O código de rastreio. `null` enquanto a transportadora não o devolveu.
`emitidaEm`	data	Quando foi emitida e paga.
`impressaEm`	data	Quando a OTL imprimiu. `null` até lá.
`despachadaEm`	data	Quando a caixa saiu. `null` até lá.
`canceladaEm`	data	Quando foi cancelada. `null` se não foi.
`atualizadoEm`	data	A última mudança na etiqueta.

Regras que não se leem no JSON

O documento do destinatário não é guardado. A transportadora exige; a OTL repassa e descarta. Por isso ele é pedido a cada emissão.
A declaração de conteúdo usa o valor de venda de cada item, não o que o parceiro pagou à OTL — ela vai colada na caixa, e o cliente final lê. Item sem valor de venda bloqueia a emissão: informe em Valor de venda.
Um pedido tem no máximo uma etiqueta ativa. Para trocar, cancele a atual.
O rastreio entra no pedido sozinho: aparece em rastreio e também na lista de rastreios do pedido. Se a transportadora ainda não o devolveu, vem null e chega depois — acompanhe por Etiquetas do pedido ou pelo webhook pedido.rastreio_adicionado.
A API não devolve o PDF. Quem imprime é a OTL, que tem a mercadoria.
Pedido cancelado não gera etiqueta.
Limite próprio de 10 emissões por minuto, além do limite geral.

Erros possíveis

HTTP	`codigo`	Quando
400	`IDEMPOTENCY_KEY_OBRIGATORIA`	Faltou o cabeçalho `Idempotency-Key`
400	`VALIDACAO`	`servico` fora da lista, ou documento que não é CPF nem CNPJ
400	`SUPERFRETE_NOT_CONNECTED`	O parceiro não tem conta SuperFrete conectada
400	`SALE_VALUE_REQUIRED`	Há item sem valor de venda
400	`REQUISICAO_INVALIDA`	O pedido já tem etiqueta ativa, está cancelado, falta o documento ou o endereço do remetente — a mensagem diz qual
404	`NAO_ENCONTRADO`	O pedido não existe — ou é de outro parceiro
403	`ESCOPO_INSUFICIENTE`	A integração não tem `etiquetas:emitir`
502	`ERRO_INTERNO`	A SuperFrete não respondeu. Repita com a mesma `Idempotency-Key`

Ver também

Simuladores do sandbox — para simular a OTL imprimindo e despachando