Cancelar etiqueta

Cancela uma etiqueta e estorna o valor na carteira SuperFrete do parceiro.

DELETE/v1/pedidos/{id}/etiquetas/{etiquetaId}

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`id` obrigatório	texto	—	O identificador do pedido, no caminho.
`etiquetaId` obrigatório	texto	—	O `id` da etiqueta, no caminho.

Exemplo

curl -X DELETE "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN"

curl -X DELETE "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN"

const resposta = await fetch('https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003', {
  method: 'DELETE',
  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/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003', {
  method: 'DELETE',
  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/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
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/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
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.delete(
    "https://api.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003",
    headers={
        "Authorization": "Bearer otl_prod_SEU_TOKEN",
    },
    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.delete(
    "https://api-sandbox.otlshoes.com.br/v1/pedidos/cmg8k1p2a0007/etiquetas/cmg8p2r5v0003",
    headers={
        "Authorization": "Bearer otl_sbx_SEU_TOKEN",
    },
    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 testeDELETE

Resposta

200 OK, com a etiqueta — ela não some, passa a CANCELADA:

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

Regras que não se leem no JSON

O valor volta para a carteira SuperFrete do parceiro, não para a OTL.
Só antes de despachada. Etiqueta DESPACHADA responde 400. Impressa e ainda não despachada pode ser cancelada — avise a equipe OTL, porque o papel já existe.
Cancelar uma etiqueta já cancelada devolve a etiqueta, sem erro.
Depois de cancelar, o pedido aceita uma etiqueta nova.
O rastreio que a etiqueta colocou no pedido não é removido automaticamente.

Erros possíveis

HTTP	`codigo`	Quando
400	`REQUISICAO_INVALIDA`	A etiqueta já foi despachada, ou a SuperFrete recusou o cancelamento
400	`SUPERFRETE_NOT_CONNECTED`	A conta SuperFrete foi desconectada depois da emissão
404	`NAO_ENCONTRADO`	O pedido ou a etiqueta não existe — ou é de outro parceiro
403	`ESCOPO_INSUFICIENTE`	A integração não tem `etiquetas:emitir`