Pular para o conteúdo principal

Primeiros passos

Este guia leva você do zero até a primeira cotação de frete pela API. A integração é gratuita e não tem mensalidade.

Já usa uma plataforma de e-commerce?

Esta documentação é para quem tem um site ou sistema próprio. Se a sua loja está em uma plataforma como Nuvemshop, Shopify ou WooCommerce, veja antes as integrações prontas no painel.

1. Escolha o ambiente​

A SuperFrete tem dois ambientes. Cada um tem a sua URL e o seu próprio token: um token de sandbox não funciona em produção, e vice-versa.

AmbienteURL base da APIPainel para gerar o token
Sandbox (testes)https://sandbox.superfrete.comsandbox.superfrete.com/#/integrations
Produçãohttps://api.superfrete.comweb.superfrete.com/#/integrations
Sandbox é para testar

As etiquetas geradas no sandbox não têm validade e não podem ser usadas para postar nas transportadoras. Comece por lá e só troque para produção quando o fluxo estiver redondo.

2. Gere o seu token​

O passo a passo é o mesmo nos dois ambientes; só muda o endereço do painel.

  1. Entre no painel do ambiente e abra o menu Integrações (sandbox ou produção).
  2. Clique em Nova integração.
  3. Na tela Qual a integração?, escolha a opção da API (desenvolvedores).
  4. Na janela que abre, clique em Gerar token. Se aparecer um formulário curto sobre a sua loja, preencha e continue.
  5. Copie o token exibido no passo Copie e cole o token no site do parceiro e guarde em local seguro, como uma variável de ambiente do seu servidor.
Menu Integrações: o ponto de partida para gerar o token.
Clique em Gerar token para criar o token da API.
O token fica disponível aqui. Você pode voltar a esta tela depois, clicando na integração em Integrações.

O token não expira. Ele só deixa de valer se a integração for excluída em Integrações.

Se você está construindo uma plataforma com várias lojas, o caminho é outro: veja Autenticação e o fluxo OAuth 2.0.

3. Monte os headers​

Toda requisição precisa de dois headers:

  • Authorization: Bearer {token}, com o token do passo anterior.
  • User-Agent com o nome e a versão da sua aplicação e um e-mail para contato técnico entre parênteses, no formato Aplicacao/versão (email@dominio.com). Usamos esse e-mail para avisar você sobre mudanças e problemas na sua integração.
Authorization: Bearer {token}
User-Agent: MinhaLoja/1.0 (dev@minhaloja.com.br)

4. Faça a primeira cotação​

Com o token de sandbox em mãos, cote um frete de São Paulo para o Rio de Janeiro:

Cotação no sandbox
curl --request POST \
  --url https://sandbox.superfrete.com/api/v0/calculator \
  --header "Authorization: Bearer $SUPERFRETE_TOKEN" \
  --header "User-Agent: MinhaLoja/1.0 (dev@minhaloja.com.br)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "from": { "postal_code": "01153000" },
    "to": { "postal_code": "20020050" },
    "services": "1,2,17",
    "options": { "own_hand": false, "receipt": false, "insurance_value": 0, "use_insurance_value": false },
    "package": { "height": 2, "width": 11, "length": 16, "weight": 0.3 }
  }'

A resposta traz uma opção por serviço, com preço, prazo e a caixa usada no cálculo. Os detalhes de cada campo estão na referência de Cotar frete, e as regras de cada transportadora no guia de frete.

5. Adicione saldo no sandbox​

Para testar a emissão e o pagamento de etiquetas, a sua carteira de sandbox precisa de saldo. O pagamento é simulado:

  1. Acesse sandbox.superfrete.com/#/account/credits.
  2. Clique em Recarregue com Pix.
  3. Escolha um valor.
  4. Clique em Recarregar com Pix.
  5. Clique em Copiar código PIX.
  6. Cole o código na barra de endereço do navegador e pressione Enter. O pagamento é simulado e o crédito aparece na carteira de testes.

Prefere ver em vídeo? Assista ao passo a passo gravado.

Erros​

Quando algo dá errado, a API responde com o status HTTP correspondente e um JSON explicando o motivo. Erros de validação (status 400) trazem o objeto errors, com os problemas de cada campo:

{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "to.postal_code": ["(to.postal_code) é inválido."]
  }
}

Os formatos, os status e as mensagens mais comuns estão em Erros e limites.

Próximos passos​

Ficou com alguma dúvida? Escreva para integracao@superfrete.com ou fale com a gente pelo chat.