Perguntas frequentes

As dúvidas que mais aparecem de quem integra com a SuperFrete. Não achou a sua? fale com a gente pelo chat ou escreva para integracao@superfrete.com.

Conta e token

Onde eu gero o meu token?

No painel da SuperFrete, no menu Integrações. Clique em Nova integração, escolha a opção da API e clique em Gerar token. O token aparece na tela seguinte, com um botão para copiar.

Cada ambiente tem o seu painel e o seu token: sandbox.superfrete.com para testes e web.superfrete.com para produção. O passo a passo com imagens está em Primeiros passos.

Perdi o token. Consigo ver de novo?

Sim. Em Integrações, clique na integração da API na lista de integrações conectadas: o token aparece de novo, pronto para copiar. Isso vale para tokens gerados no painel. Tokens obtidos por OAuth ficam só com a plataforma que fez a integração.

O token expira?

Não. O token manual e o token obtido por OAuth não têm data de validade. Ele só deixa de funcionar se a integração for excluída em Integrações no painel. Nesse caso, a API responde 401 com Token inválida! e é preciso gerar um token novo.

Devo usar token manual ou OAuth?

Se você está integrando a sua própria loja (site ou sistema próprio), use o token manual. Se você tem uma plataforma com várias lojas (e-commerce, ERP, hub), use OAuth, para que cada seller conecte a própria conta sem copiar token. A comparação completa está em Autenticação.

Recebo 401 com Token inválida! mesmo com o token certo. O que pode ser?

Os motivos mais comuns, na ordem:

1. Ambiente trocado. Token de sandbox só funciona em https://sandbox.superfrete.com, e o de produção só em https://api.superfrete.com.
2. Header mal formado. O formato é Authorization: Bearer {token}, com a palavra Bearer, um espaço e o token, sem aspas.
3. Integração excluída. Se alguém excluiu a integração no painel, o token deixou de valer.
4. Token cortado ao copiar. Copie de novo pelo botão de copiar do painel.

Qual User-Agent eu devo enviar?

O nome e a versão da sua aplicação, seguidos de um e-mail de contato técnico entre parênteses: MinhaLoja/1.0 (dev@minhaloja.com.br). Usamos esse e-mail para avisar sobre mudanças e problemas na sua integração. Envie em todas as requisições.

Sandbox e produção

Qual a diferença entre sandbox e produção?

O sandbox é um ambiente de testes completo, com painel, carteira e API próprios. Etiquetas emitidas lá não têm validade nas transportadoras e o pagamento é simulado.

	Sandbox	Produção
API	https://sandbox.superfrete.com	https://api.superfrete.com
Painel	sandbox.superfrete.com	web.superfrete.com

Conta, token, saldo e Webhook Apps são separados em cada ambiente.

Como coloco saldo na carteira do sandbox?

Pelo painel do sandbox, em Carteira: clique em Recarregue com Pix, escolha um valor, copie o código Pix e cole na barra de endereço do navegador. O pagamento é simulado e o crédito aparece na hora. O passo a passo está em Primeiros passos.

A integração tem custo?

Não. Usar a API é gratuito e não tem mensalidade. Você paga só as etiquetas que emitir, com o mesmo preço do painel.

Cotação e serviços

Quais serviços de entrega estão disponíveis?

Código	Serviço
1	PAC (Correios)
2	SEDEX (Correios)
17	Mini Envios (Correios)
3	Jadlog
31	Loggi
33	J&T Express

Na cotação, envie vários códigos separados por vírgula em services. Jadlog, Loggi e J&T só aparecem quando há um ponto de postagem da transportadora perto do CEP de origem e quando estão ativas nas configurações do token. Veja Regras por transportadora.

Por que uma transportadora não aparece na minha cotação?

Confira três coisas:

1. A transportadora está ativa no token? Em Integrações, abra as configurações da integração e veja se Jadlog, Loggi ou J&T estão ligadas, com ponto de postagem escolhido.
2. Existe ponto de postagem perto da origem? Sem ponto próximo, a transportadora não entra na cotação.
3. O pacote cabe nos limites dela? Cada transportadora tem peso e medidas máximas. Quando o pacote passa do limite, o serviço volta com has_error: true e o motivo em error.

Qual a dimensão mínima de um pacote?

Nos serviços dos Correios, medidas menores que o mínimo são ajustadas automaticamente para o mínimo do formato, então você não recebe erro por pacote pequeno demais. Para uma caixa comum, o mínimo é 16 cm de largura, 24 cm de comprimento, 4 cm de altura e 0,3 kg. Os limites atualizados de cada serviço, mínimos e máximos, estão em GET /api/v0/services/info.

Devo cotar com a caixa ou com os produtos?

Se você já sabe a caixa em que o pedido vai ser enviado, cote com package. Se só conhece os produtos, cote com products e a API calcula a menor caixa que acomoda todos. Nesse caso, use a caixa devolvida pela cotação em volumes ao criar a etiqueta, para que a etiqueta saia com as mesmas medidas que foram cotadas. Se enviar os dois, package tem prioridade.

O CEP pode ir com traço?

Pode. A API remove pontos, traços e espaços de from.postal_code e to.postal_code antes de calcular. O importante é que sobrem 8 dígitos.

Etiquetas, pagamento e cancelamento

Como pago uma etiqueta pela API?

Com o saldo da carteira, chamando POST /api/v0/checkout com o ID da etiqueta. Se o saldo não cobrir o valor, a API responde 409 com Sem saldo na carteira!. Também é possível pagar pelo painel, em Etiquetas, com cartão de crédito ou saldo.

Para recarregar a carteira de produção, vá em Perfil > Carteira no painel, clique em Recarregue com Pix, escolha o valor e pague o Pix no app do seu banco. No sandbox, o Pix é simulado.

O checkout diz que o limite de etiquetas foi atingido. O que fazer?

A API responde 409 com a mensagem "Não foi possível realizar a compra pois o limite de etiquetas disponível para esta conta foi atingido…": a conta chegou ao limite de etiquetas pagas aguardando postagem. Consulte limits.shipments_available em GET /api/v0/user para acompanhar. Para liberar espaço, poste os pacotes pendentes ou cancele as etiquetas que não vai usar. Se a sua operação precisa de um limite maior, fale com integracao@superfrete.com.

Recebo user.phone is required. ao criar a etiqueta: por quê?

A conta SuperFrete dona do token não tem um número de celular cadastrado. Cadastre o celular no perfil do painel (do mesmo ambiente do token) e tente de novo.

Posso cancelar uma etiqueta?

Sim, enquanto ela não tiver sido postada. Chame POST /api/v0/order/cancel com o ID e o motivo. O valor pago volta para a carteira da conta. Se a etiqueta já foi postada ou concluída, a API responde 409 com Esse pedido não pode mais ser cancelado!.

Quando o código de rastreio fica disponível?

A partir do momento em que a etiqueta é paga (status released). Ele aparece no campo tracking de Consultar pedido e no evento order.generated dos webhooks.

Posso usar nota fiscal em vez de declaração de conteúdo?

Nos Correios, sim: não envie products e informe a chave de 44 dígitos em options.invoice.number. Sempre que products vem na requisição, a etiqueta sai com declaração de conteúdo, mesmo com nota fiscal. A nota impressa ainda precisa ir dentro do pacote. Para Jadlog, Loggi e J&T, use declaração de conteúdo (envie products).

Como imprimo a etiqueta no formato A6 (impressora térmica)?

Ative uma vez na conta: no painel, vá em Etiquetas > Configurações e ative A6 (Zebra). A partir daí, a URL devolvida por POST /api/v0/tag/print traz as etiquetas nesse formato.

Webhooks

Os webhooks não estão chegando. O que eu verifico?

1. O evento está assinado? Liste os seus Webhook Apps com GET /api/v0/webhook e confira o array events. Só chegam os eventos que estão nele.
2. A URL é pública e aceita POST? Endereços localhost, de rede interna ou atrás de login não recebem as notificações.
3. A sua URL responde em até 10 segundos com 2xx? Respostas lentas ou com erro contam como falha.
4. O ambiente é o mesmo? O Webhook App do sandbox só recebe eventos do sandbox, e o de produção só de produção.
5. No sandbox, os pacotes não são postados de verdade, então order.posted e order.delivered normalmente não chegam.

Como sei que a notificação veio mesmo da SuperFrete?

Toda notificação traz o header X-ME-Signature, um HMAC-SHA256 em hexadecimal do corpo da requisição, assinado com o secret_token do seu Webhook App. Calcule o mesmo HMAC sobre o corpo bruto e compare. Os exemplos em Node.js, Python e PHP estão no guia de webhooks.

Posso receber o mesmo evento duas vezes?

Cada evento é enviado uma vez por pedido para cada Webhook App. Mesmo assim, trate o recebimento como idempotente: use o par event + data.id para ignorar uma notificação que você já processou.

Ajuda

Com quem eu falo sobre a integração?

Dúvidas técnicas sobre a API: integracao@superfrete.com. Respostas rápidas sobre esta documentação: chat da SuperFrete, no canto da tela.

Ao escrever, mande o endpoint, o ambiente, o horário da chamada, o corpo da requisição (sem o token) e a resposta completa. Isso encurta muito a conversa.