Autenticação
Toda chamada à API da SuperFrete é autenticada com um token no header Authorization, no esquema Bearer. O que muda é como você obtém esse token.
| Token manual | OAuth 2.0 | |
|---|---|---|
| Para quem | Loja com site ou sistema próprio (um único seller) | Plataformas com várias lojas: Nuvemshop, Shopify, Wix, ERPs, hubs |
| Como o token é gerado | O próprio seller gera no painel da SuperFrete | O seller autoriza a sua plataforma e o token é emitido automaticamente |
| O que você precisa | Uma conta SuperFrete | client_id e client_secret fornecidos pela SuperFrete |
| Guia | Primeiros passos | Fluxo OAuth 2.0 |
O OAuth 2.0 é exclusivo para operações com múltiplas lojas. Integrações de um único seller (site próprio) devem usar o token manual, gerado na página de integrações.
Enviando o token
Inclua o token em todas as requisições, junto com o User-Agent da sua aplicação:
Authorization: Bearer {token}
User-Agent: MinhaLoja/1.0 (dev@minhaloja.com.br)
O User-Agent é obrigatório. Informe o nome e a versão da sua aplicação e termine com um e-mail para contato técnico entre parênteses, como no exemplo acima.
Cada token vale para um único ambiente. Use o token de sandbox com https://sandbox.superfrete.com e o de produção com https://api.superfrete.com. Se misturar os dois, a API responde 401 com Token inválida!.
Validade e revogação
Os tokens não expiram, nem o manual nem o obtido por OAuth, e não existe refresh token. Um token só deixa de valer quando a integração é excluída em Integrações no painel da SuperFrete. A partir daí, as chamadas com ele voltam 401.
Trate o token como uma senha: guarde no servidor, em variável de ambiente ou cofre de segredos, e nunca exponha no front-end. Se suspeitar de vazamento, exclua a integração no painel e gere outro token.
Token manual
É o caminho para quem integra a própria loja. O seller gera o token no menu Integrações do painel, em Nova integração, escolhendo a opção da API e clicando em Gerar token. Cada ambiente tem o seu painel:
- Produção: web.superfrete.com/#/integrations
- Sandbox: sandbox.superfrete.com/#/integrations
O passo a passo completo está em Primeiros passos.
Se a sua plataforma integra por token (sem OAuth), depois de concluir a integração com a SuperFrete você recebe uma identificação de produto parceiro. Ela aparece na seção de integrações do painel, e o seu usuário usa essa identificação para gerar o token que vai colar na sua plataforma.
OAuth 2.0
Com OAuth, o seller clica em "Integrar com a SuperFrete" dentro da sua plataforma, autoriza o acesso e a sua aplicação recebe o token, sem copiar e colar nada. A implementação segue o padrão OAuth 2.0 com o fluxo authorization code.
Para começar, peça as suas credenciais pelo formulário de solicitação. Você recebe um Client ID e um Client Secret para produção e outro par para sandbox.
No formulário você também informa a sua redirect_uri: a URL de callback da sua aplicação, para onde enviamos o código de autorização (code) temporário depois que o seller autoriza o acesso.
O passo a passo, com as URLs de autorização e a troca do código pelo token, está no guia do fluxo OAuth 2.0 e na referência de Trocar código OAuth por token.
O client_secret nunca deve aparecer no front-end, no app mobile ou em repositórios. Faça a troca do código pelo token sempre a partir do seu servidor.