Integração Melhor Envio

Guia completo para configurar a integração com o Melhor Envio através da Fanmarket.

📥 Collection Postman

Baixar Collection - Melhor Envio

Visão Geral

A integração com o Melhor Envio permite calcular fretes e gerenciar envios diretamente através da API da Fanmarket, usando o OAuth 2.0 para autorização.

Pré-requisitos

Antes de começar, você precisará:

• Conta no Melhor Envio (homologação ou produção)
• Credenciais de acesso fornecidas pela Fanbase
• URL de callback configurada em conjunto com a Fanbase

Ambientes

Ambiente	URL Melhor Envio	URL Fanmarket
Homologação	https://sandbox.melhorenvio.com.br	https://fanmarketapi.fantest.com.br
Produção	https://melhorenvio.com.br	https://fanmarketapi.fanbase.com.br

---

Passo 1: Criar Conta no Melhor Envio

1. Acesse o site do Melhor Envio:

   • Homologação: https://sandbox.melhorenvio.com.br/login
   • Produção: https://melhorenvio.com.br/login

2. Crie uma conta ou faça login

---

Passo 2: Criar Aplicativo

1. No menu lateral, acesse Integrações → Área Dev
2. Clique em Cadastrar Aplicativo
3. Preencha o formulário com os seguintes dados:

Campo	Valor
Nome da Plataforma	Fanmarket
E-mail de contato	Seu e-mail de contato
URL do seu ambiente para testes	https://fanmarketapi.fantest.com.br
Site da plataforma	https://fanmarketapi.fanbase.com.br
E-mail do seu suporte técnico	E-mail do suporte
URL de redirecionamento após autorização	Fornecido pela Fanbase
Descrição do aplicativo	Descrição do seu aplicativo

4. Após criar, anote o Client ID e Secret gerados

---

Passo 3: Obter Credenciais

Após criar o aplicativo, você receberá:

• Client ID: Identificador público do aplicativo
• Secret: Chave secreta (deve ser mantida em sigilo)

Importante

Envie essas credenciais para a Fanbase para configuração da integração.

---

Passo 4: Gerar Link de Autorização

Para liberar as permissões de cotação de frete, você precisa autorizar o aplicativo através de um link de autorização OAuth.

Formato do Link

https://{{UrlMelhorEnvio}}/oauth/authorize?client_id={{ClientId}}&redirect_uri={{UrlCallback}}&response_type=code&state={{State}}&scope=shipping-calculate ecommerce-shipping

Parâmetros

Parâmetro	Descrição	Exemplo
UrlMelhorEnvio	URL base do Melhor Envio	sandbox.melhorenvio.com.br ou melhorenvio.com.br
client_id	Client ID do aplicativo	1010
redirect_uri	URL de callback da Fanmarket	Ver tabela abaixo
response_type	Tipo de resposta OAuth	code
state	Identificador do ambiente	teste ou prod
scope	Permissões solicitadas	shipping-calculate ecommerce-shipping

URLs de Callback

Ambiente	URL de Callback
Homologação	https://fanmarketapi.fantest.com.br/api/delivery/shipping/callback/{identificador}
Produção	https://fanmarketapi.fanbase.com.br/api/delivery/shipping/callback/{identificador}

Nota

O {identificador} no callback será fornecido pela Fanbase e é único para cada cliente.

---

Links de Autorização Completos

Homologação

GET

https://sandbox.melhorenvio.com.br/oauth/authorize?client_id=1010&redirect_uri=https://fanmarketapi.fantest.com.br/api/delivery/shipping/callback/teste&response_type=code&state=teste&scope=shipping-calculate ecommerce-shipping

Produção

GET

https://melhorenvio.com.br/oauth/authorize?client_id=1010&redirect_uri=https://fanmarketapi.fanbase.com.br/api/delivery/shipping/callback/prod&response_type=code&state=prod&scope=shipping-calculate ecommerce-shipping

Atenção

Substitua o client_id pelo Client ID do seu aplicativo e ajuste o identificador no callback conforme orientação da Fanbase.

---

Passo 5: Autorizar Aplicativo

1. Abra o link de autorização gerado no navegador
2. Faça login na plataforma Melhor Envio (se necessário)
3. Autorize as permissões solicitadas
4. Você será redirecionado automaticamente para a URL de callback
5. Deve aparecer a mensagem: "Token salvo com sucesso"

---

Escopos Disponíveis

Escopo	Descrição
shipping-calculate	Calcular fretes
ecommerce-shipping	Gerenciar envios de e-commerce

---

Fluxo de Autorização

sequenceDiagram
    participant Usuario as Usuário
    participant ME as Melhor Envio
    participant Fanmarket
    
    Usuario->>ME: 1. Acessa link de autorização
    ME->>Usuario: 2. Exibe tela de login/autorização
    Usuario->>ME: 3. Autoriza permissões
    ME->>Fanmarket: 4. Redireciona com código
    Note right of Fanmarket: /api/delivery/shipping/callback
    Fanmarket->>ME: 5. Troca código por token
    ME-->>Fanmarket: 6. Retorna access_token
    Fanmarket->>Usuario: 7. "Token salvo com sucesso"

---

Verificação

Após concluir todos os passos:

✅ O token será salvo automaticamente pela Fanbase

✅ Você verá a mensagem "Token salvo com sucesso"

✅ A integração estará pronta para uso

---

Resolução de Problemas

Problema	Solução
"Token não salvo"	Verifique se o client_id e callback estão corretos
"Permissão negada"	Certifique-se de autorizar todos os escopos solicitados
"URL de callback inválida"	Confirme a URL de callback com a Fanbase
"Aplicativo não encontrado"	Verifique se o aplicativo foi criado corretamente

---

Próximos Passos

Após a configuração, você poderá utilizar os endpoints da Fanmarket para:

• Calcular fretes
• Gerar etiquetas de envio
• Rastrear pacotes
• Gerenciar envios

---

Suporte

Em caso de dúvidas ou problemas durante a configuração, entre em contato com o suporte técnico da Fanbase.