API Martins Log

O fluxo em 4 chamadas

Uma venda paga na sua loja vira um envio despachado em quatro chamadas, nesta ordem. Cada uma depende do resultado da anterior.

O preço nunca viaja no corpo da requisição. A cotação fica salva no servidor e o /cart a referencia pelo id — se você mandar um campo price, ele é descartado em silêncio. Isso é proposital: o valor cobrado não pode depender do que o cliente envia.

Exemplo completo

# 1. cotar
curl -X POST https://app.martinslog.net/api/v0/calculator \
  -H "Authorization: Bearer frete_live_..." \
  -H "Content-Type: application/json" \
  -d '{"cepOrigem":"12321-313","cepDestino":"80010-000","formato":"CAIXA",
       "pesoRealG":1000,"alturaCm":20,"larguraCm":15,"comprimentoCm":10}'

# devolve, entre outras: {"id":"clx123:svc-eco","price":"12.30", ...}

# 2. criar o envio com o id da opção escolhida
curl -X POST https://app.martinslog.net/api/v0/cart \
  -H "Authorization: Bearer frete_live_..." \
  -H "Content-Type: application/json" \
  -d '{"service":"clx123:svc-eco","remetente":{...},"destinatario":{...},
       "produtos":[{"nome":"Kit 4em1","quantidade":1,"valorUnitarioCentavos":9790}]}'

# devolve: {"id":"shp_abc","price":"12.30","label_fee":"1.00","charged":false,"status":"PENDING"}

# 3. pagar
curl -X POST https://app.martinslog.net/api/v0/checkout \
  -H "Authorization: Bearer frete_live_..." \
  -H "Content-Type: application/json" \
  -d '{"orders":["shp_abc"]}'

# 4. ler o rastreio
curl https://app.martinslog.net/api/v0/order/info/shp_abc \
  -H "Authorization: Bearer frete_live_..."

Autenticação

Toda chamada de /api/v0 exige o token no cabeçalho:

Authorization: Bearer frete_live_a1b2c3...

O token é criado no painel, em Integrações, e pertence a uma conta. A carteira que paga o frete é a da conta dona do token — uma loja, um token.

Token ausente, malformado, inválido ou revogado responde 401 TOKEN_INVALIDO. O prefixo é rótulo, não credencial: a entropia inteira está nos 32 bytes que vêm depois dele.

Sandbox e produção

Mesma URL, mesmos campos, mesmas respostas. Só o token muda. Não existe host separado de teste.

Limite de requisições

60 requisições por minuto, por token. A contagem é por token, não por IP — uma loja não derruba a cota de outra que esteja atrás do mesmo servidor.

A janela é fixa, não deslizante: ela abre na primeira requisição e vale um minuto inteiro. Estourar no segundo 5 bloqueia os 55 segundos restantes — a cota não vai se liberando aos poucos. Distribua as chamadas em vez de disparar tudo de uma vez.

Estourando, a resposta é 429 LIMITE_REQUISICOES_EXCEDIDO com o cabeçalho Retry-After: 60 e o tempo real que falta, em segundos, na mensagem. Respeite o cabeçalho em vez de repetir imediatamente.

Uma venda consome 3 ou 4 chamadas. O teto prático é de cerca de 15 vendas por minuto por loja. Para importar histórico, enfileire — não existe endpoint em lote.

Erros

Todo erro tem a mesma forma:

{
  "codigo": "SALDO_INSUFICIENTE",
  "mensagem": "Saldo insuficiente para pagar este envio."
}

Erro de validação acrescenta campos, com a lista de problemas por campo:

{
  "codigo": "CORPO_INVALIDO",
  "mensagem": "Dados de cotação inválidos.",
  "campos": { "cepDestino": ["CEP de destino inválido"] }
}

Programe contra o codigo, nunca contra a mensagem — o texto muda, o código não.

404 em vez de 403 é decisão de segurança. Um id que existe em outra conta responde exatamente como um id que não existe — a diferença de código revelaria quais ids são reais.

Os três números

Confundi-los é o erro de integração mais caro. São valores diferentes, com donos diferentes.

Todos os valores monetários são strings em reais com duas casas ("12.30"), nunca centavos e nunca número. Nos campos de entrada vale o contrário: valorUnitarioCentavos é inteiro em centavos. A assimetria é real; não deduza uma coisa da outra.

charged é lido do livro-caixa, não do status nem da flag de sandbox. Some label_fee apenas onde charged for true, ou você vai contabilizar dinheiro que nunca saiu.

A taxa é por etiqueta, não proporcional ao frete: uma encomenda de R$ 12,30 e outra de R$ 180,00 custam o mesmo R$ 1,00 a você. O price aparece na etiqueta e no rastreio; o label_fee aparece no seu extrato. Nunca cobre o label_fee do comprador — ele não é frete.

1 · Cotação

Corpo

Medidas são inteiras. 20.5 é recusado com CORPO_INVALIDO — arredonde para cima antes de enviar.

Resposta 200

[
  {
    "id": "clx123abc:svc-economico",
    "name": "Econômico",
    "price": "12.30",
    "discount": "3.70",
    "delivery_time": 5,
    "company": { "name": "Martins Log" }
  }
]

• id — no formato quoteId:servicoId. É o que vai no service do passo 2, inteiro e sem alterações.
• delivery_time — prazo em dias corridos, e a contagem começa na emissão da etiqueta (o evento order.generated), não na postagem nem na compra. Sábado, domingo e feriado contam. Se a sua loja anuncia o prazo em dias úteis, converta antes de mostrar ao comprador — são números diferentes.
• Serviços indisponíveis para a rota não aparecem. Lista vazia é resposta válida e significa "não atendemos esse trecho" — trate na sua tela, não como erro.

2 · Criar envio

Corpo

Endereço

email tem uma pegadinha: se o campo existir, precisa ser um e-mail válido ou exatamente "". Mandar null ou "—" derruba a requisição inteira. Se não tem e-mail, omita a chave.

Produto

A soma dos produtos vira o valor declarado do envio, que é a base do seguro. Declarar menos que o real reduz a cobertura.

Resposta 201

{
  "id": "shp_9f2c...",
  "price": "12.30",
  "label_fee": "1.00",
  "charged": false,
  "status": "PENDING"
}

Guarde o id no seu pedido agora. Ele é a única chave que liga a sua venda ao envio, e é o que impede a duplicação descrita no checklist.

3 · Pagar

Debita a carteira e, em produção, emite a etiqueta na sequência. Você não precisa chamar mais nada para obter o código de rastreio.

Corpo

{ "orders": ["shp_9f2c..."] }

Aceita vários ids, mas o processamento é sequencial e sem transação: se o terceiro falhar por saldo, os dois primeiros já foram pagos e continuam pagos. Mandar um id por chamada torna o tratamento de erro muito mais simples.

Resposta 200

{
  "success": true,
  "purchase": {
    "status": "approved",
    "orders": [ { "id": "shp_9f2c...", "status": "GENERATED" } ]
  }
}

Sem saldo, a resposta é 402 SALDO_INSUFICIENTE e o envio permanece PENDING — nada se perde. Basta recarregar e chamar de novo com o mesmo id.

4 · Consultar

{
  "id": "shp_9f2c...",
  "status": "POSTED",
  "tracking": "EC000000014BR",
  "tracking_url": "/r/EC000000014BR",
  "price": "12.30",
  "label_fee": "1.00",
  "charged": true,
  "sandbox": false,
  "returned_at": null,               // preenchido = voltou ao remetente
  "created_at": "2026-09-01T10:00:00.000Z"
}

tracking e tracking_url são null enquanto o envio não tem código — na prática, antes de GENERATED. Datas são sempre ISO 8601 em UTC.

Ciclo de vida do envio

Sete estados. As transições são verificadas no servidor: tentar um salto inválido devolve 422 TRANSICAO_INVALIDA.

Cancelamento só é possível até GENERATED. Depois de POSTED a carga está na rua e não há mais o que cancelar.

Webhooks

A alternativa a ficar consultando /order/info. Nós avisamos a cada mudança de estado.

Regras da URL de destino

• https obrigatório — http é recusado.
• Sem usuário e senha embutidos na URL.
• Sem localhost, .localhost, .internal ou IP de rede privada.

URL recusada devolve 422 ARQUIVO_INVALIDO com o motivo.

Eventos

Se você só puder escutar um, escute order.generated — é onde o código de rastreio aparece.

Corpo entregue

{
  "event": "order.generated",
  "data": {
    "id": "shp_9f2c...",
    "status": "GENERATED",
    "tracking": "EC000000014BR",
    "tracking_url": "/r/EC000000014BR",   // relativo
    "price": "12.30",                     // string, em reais
    "created_at": "2026-09-01T10:00:00.000Z"
  },
  "sent_at": "2026-09-01T10:00:01.000Z"
}

// `sandbox: true` entra no mesmo nível de `event` — mas SÓ em
// order.created e order.released. Este exemplo é order.generated,
// que nunca traz o campo, nem quando o envio é de teste.

Entrega e retentativa

A fila é processada por um agendador que roda a cada minuto. Um evento não sai no mesmo instante em que acontece: espere até um minuto entre a mudança de status e a chegada da entrega. Não é fila travada.

Responda rápido e com 2xx. Grave o evento numa fila sua e processe depois; passar de 5 segundos conta como falha e gera reentrega. Um 404 (rota errada) faz o sistema desistir na primeira tentativa — o que é proposital: repetir contra uma URL inexistente por catorze horas só martelaria o seu servidor.

Entregas podem chegar fora de ordem ou repetidas. Trate cada uma como idempotente: ignore um order.posted que chegue depois de um order.delivered já processado.

Verificar a assinatura

Toda entrega vai assinada. Dois cabeçalhos:

A assinatura é o HMAC-SHA256 de <timestamp>.<corpo>, com o segredo devolvido no cadastro. O timestamp entra dentro do que é assinado — por isso alterá-lo invalida a assinatura, e uma requisição capturada não serve para sempre.

Node.js

const { createHmac, timingSafeEqual } = require('crypto')

function verificar(segredo, corpoCru, assinatura, timestamp) {
  // 1. janela de 5 minutos
  if (!/^\d+$/.test(timestamp)) return false
  const agora = Math.floor(Date.now() / 1000)
  if (Math.abs(agora - Number(timestamp)) > 300) return false

  // 2. o timestamp entra no que é assinado
  const esperada = createHmac('sha256', segredo)
    .update(`${timestamp}.${corpoCru}`)
    .digest('hex')

  if (!assinatura.startsWith('sha256=')) return false
  const recebida = assinatura.slice('sha256='.length)
  if (recebida.length !== esperada.length) return false

  // 3. comparação em tempo constante
  return timingSafeEqual(
    Buffer.from(recebida, 'hex'),
    Buffer.from(esperada, 'hex'),
  )
}

PHP

function verificar($segredo, $corpoCru, $assinatura, $timestamp) {
  if (!ctype_digit($timestamp)) return false;
  if (abs(time() - (int)$timestamp) > 300) return false;

  $esperada = 'sha256=' . hash_hmac('sha256', "$timestamp.$corpoCru", $segredo);
  return hash_equals($esperada, $assinatura);
}

// o corpo cru, nunca $_POST
$corpoCru = file_get_contents('php://input');

Rastreio

Formato do código

EC 00000001 4 BR — duas letras de serviço, oito dígitos sequenciais, um dígito verificador módulo 11 e o sufixo do país. O formato segue a convenção dos Correios para que leitores de código de barras e planilhas já existentes o aceitem; o código em si é nosso.

Em sandbox o formato é outro: SANDBOX seguido de 12 caracteres hexadecimais.

Página para o seu cliente

https://app.martinslog.net/r/EC000000014BR

Aberta, sem login, e não mostra nome, documento nem endereço de ninguém — só serviço, situação e cidade/UF de cada etapa. É o link seguro para pôr no e-mail de confirmação.

Consulta programática

Não exige autenticação, e por isso tem limite próprio: 30 consultas a cada 5 minutos por IP, com Retry-After na resposta 429.

O 422 é útil: significa que o código foi digitado errado e dá para corrigir. O 404 significa que o código é plausível mas não existe.

Cada evento traz sequencia, codigo, titulo, descricao, cidade, uf e ocorridoEm. Os códigos possíveis são ETIQUETA_EMITIDA, POSTADO, TRANSFERENCIA, AGUARDANDO_TRATAMENTO, SAIU_PARA_ENTREGA, TENTATIVA_FRUSTRADA, AGUARDANDO_RETIRADA, ENTREGUE, EXTRAVIADO, DEVOLUCAO_INICIADA e DEVOLVIDO.

Checklist de checkout

O que separa uma integração que funciona de uma que cobra duas vezes.

Grave o id do envio antes de qualquer outra coisa

Assim que o /cart responder, guarde o id no seu pedido e só chame o /cart quando esse campo estiver vazio. Duas chamadas para a mesma venda criam dois envios e duas cobranças na sua carteira.

Dispare a partir do pagamento confirmado, não do clique

O gatilho é o webhook do seu gateway confirmando o PIX ou o cartão. Criar o envio no clique de "finalizar compra" gera etiqueta para venda que não foi paga.

Trate 402 como estado, não como erro

Saldo insuficiente é rotina. O envio fica PENDING e nada se perde: avise o lojista, e tente de novo com o mesmo id depois da recarga. Não deixe o pedido travado em silêncio.

Prefira o webhook ao polling

Consultar /order/info de minuto em minuto consome a cota de 60/min que você vai precisar para vender. Use o webhook e reserve a consulta para conferência.

Confira sandbox em toda entrada

Tanto no webhook quanto no /order/info. Um pedido de teste tratado como venda real gera código de rastreio que não abre para o cliente.

Nunca mande preço

Não existe campo de preço em nenhum corpo de requisição. Se você enviar um, ele é descartado sem erro — e você vai passar horas procurando por que o valor "não foi aplicado".

O que ainda não existe

Limites reais da versão v0, listados para que você não os descubra em produção.