Conta SuperFrete

Se o parceiro tem conta SuperFrete conectada, e o saldo da carteira dele.

GET/v1/superfrete

Quando usar

Antes de emitir uma etiqueta, para saber se a emissão tem como dar certo: há conta conectada? há saldo? É mais barato perguntar do que descobrir pelo erro.

A etiqueta é paga pelo parceiro, não pela OTL

A mercadoria é da OTL, mas o frete é do parceiro: a etiqueta é emitida na conta SuperFrete dele, com o saldo dele. A OTL imprime e despacha.

Exemplo

curl "https://api.otlshoes.com.br/v1/superfrete" \
  -H "Authorization: Bearer otl_prod_SEU_TOKEN"

curl "https://api-sandbox.otlshoes.com.br/v1/superfrete" \
  -H "Authorization: Bearer otl_sbx_SEU_TOKEN"

const resposta = await fetch('https://api.otlshoes.com.br/v1/superfrete', {
  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/superfrete', {
  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/superfrete');
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/superfrete');
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/superfrete",
    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.get(
    "https://api-sandbox.otlshoes.com.br/v1/superfrete",
    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 testeGET

Resposta

{
  "conectada": true,
  "ambiente": "producao",
  "conta": {
    "nome": "João da Silva",
    "conectadaEm": "2026-09-01T09:00:00-03:00"
  },
  "saldo": "87.50"
}

Campo	Tipo	Descrição
`conectada`	booleano	Há uma conta SuperFrete conectada e utilizável. `false` também quando a conta conectada é de outro ambiente.
`ambiente`	texto	`producao` ou `sandbox` — com qual SuperFrete este ambiente fala.
`conta`	objeto	`nome` e `conectadaEm`. `null` se o parceiro nunca conectou.
`saldo`	dinheiro	O saldo da carteira do parceiro. `null` quando não há conta conectada ou a SuperFrete não respondeu.

Regras que não se leem no JSON

Conectar e desconectar só no painel. É uma autorização do parceiro com a SuperFrete; a API não tem como fazer por ele.
O token da SuperFrete nunca aparece em resposta nenhuma.
saldo: null não é saldo zero: é “não deu para saber agora”. Tente de novo antes de concluir.

Erros possíveis

HTTP	`codigo`	Quando
403	`ESCOPO_INSUFICIENTE`	A integração não tem `etiquetas:ler`