Integração Melhor envio
Atualizado em
Integração com a Melhor Envio
Como funciona
A integração com a Melhor Envio permite que sua loja utilize serviços de frete diretamente na plataforma, como cálculo de frete, emissão de etiquetas e gestão de envios, usando sua própria conta da Melhor Envio. A conexão é feita por meio de um aplicativo cadastrado na Melhor Envio, utilizando o fluxo de autorização padrão da plataforma (OAuth2), garantindo segurança e controle de acesso.
Como é o fluxo
Quando um pedido é finalizado utilizando a cotação da Melhor Envio, o sistema envia automaticamente as informações desse pedido para a Melhor Envio, criando a etiqueta correspondente no ambiente da plataforma. Essa etiqueta não é comprada automaticamente pela nossa plataforma. Em vez disso, ela é enviada para o carrinho da Melhor Envio, onde o lojista deve acessar sua conta para revisar os dados do envio, realizar o pagamento do frete e, após a confirmação do pagamento, imprimir a etiqueta. Todo esse processo de compra e impressão acontece diretamente no painel da Melhor Envio, seguindo o fluxo padrão da própria plataforma, sendo necessário que o lojista conclua essa etapa para que o envio possa ser realizado.
1. Premissas para utilizar a integração
Antes de iniciar a configuração, é importante garantir que sua conta esteja pronta para integração.
1.1 Requisitos obrigatórios
Conta criada na Melhor Envio
Conta verificada/aprovada
Limite de envios simultâneos suficiente
Ajustes do template conforme item 1.2.
1.2. Ajustes no Checkout para Melhor Envio
Para que a seleção de transportadora da Melhor Envio funcione corretamente, é necessário realizar os ajustes abaixo nos arquivos de checkout customizados.
Arquivo: Checkout/index.html.twig
Alteração 1 - Na função getShippingMethodValue
Localize o trecho:
if (shippingMethodDto.isCarrier) {
return shippingMethodDto.name + '_' + shippingMethodDto.shippingServiceCode;
}
return '' + shippingMethodDto.shippingMethodConfigurationId;Adicione antes da linha return '' + shippingMethodDto.shippingMethodConfigurationId;
if (shippingMethodDto.isMelhorEnvio) {
return shippingMethodDto.name;
}Alteração 2 - Na montagem das opções de frete
Localize o trecho:
if (shippingMethodDto.isAxado || shippingMethodDto.isTranspoFrete) {
shippingMethodValue = shippingMethodDto.name;
}Substitua por:
if (shippingMethodDto.isAxado || shippingMethodDto.isTranspoFrete || shippingMethodDto.isMelhorEnvio) {
shippingMethodValue = shippingMethodDto.name;
}Alteração 3 - Na seção de múltiplas lojas (se aplicável)
Localize o trecho:
if (shippingMethodDto.isTranspoFrete) {
shippingMethodValue = shippingMethodDto.name;
}
let pickUpOnPlaceAnyTime = false,Adicione antes da linha let pickUpOnPlaceAnyTime = false,
if (shippingMethodDto.isMelhorEnvio) {
shippingMethodValue = shippingMethodDto.name;
}Arquivo: Checkout/scripts.html.twig
Alteração 1 - Na montagem das opções de frete
Localize o trecho:
if (method.isAxado || method.isTranspoFrete) methodValue = method.name;Substitua por:
if (method.isAxado || method.isTranspoFrete || method.isMelhorEnvio) methodValue = method.name;Alteração 2 - Na seção de múltiplas lojas (se aplicável)
Localize o trecho:
if (shippingMethodDto.isTranspoFrete) {
shippingMethodValue = shippingMethodDto.name;
}
let pickUpOnPlaceAnyTime = false,Adicione antes da linha let pickUpOnPlaceAnyTime = false,
if (shippingMethodDto.isMelhorEnvio) {
shippingMethodValue = shippingMethodDto.name;
}2. Cadastro do aplicativo na Melhor Envio
Para que a nossa plataforma possa se conectar à sua conta, é necessário criar um aplicativo de integração no painel da Melhor Envio.
Onde cadastrar
No painel da Melhor Envio, acesse a área de Integrações / Aplicativos e clique em Cadastrar novo aplicativo.
2.1 Como preencher o cadastro do aplicativo
Na tela de Área dev, clique em "Cadastrar aplicativo":
Na tela Cadastrar novo aplicativo, preencha os campos conforme abaixo:
Nome da plataforma: Informe um nome identificável, por exemplo Integração Flexy
Site da plataforma: Informe o site principal da loja ou da plataforma.
E-mail de contato: E-mail principal para contato.
E-mail do seu suporte técnico: E-mail de suporte da flexy suporte@flexy.com.br
URL do seu ambiente para testes: Domínio da sua loja + flexyadmin/melhor-envio
URL de redirecionamento após autorização (Callback):
Este campo deve ser preenchido com a URL exibida na tela de configuração da integração em nossa plataforma. Essa URL é gerada automaticamente pelo sistema em Entregas -> Melhor envio -> Selecione a loja:
Descrição do aplicativo: Breve explicação sobre o uso da integração.
Permitir que o usuário altere as configurações de transportadora e serviços: Recomendado manter ativado.
Após preencher, clique em Cadastrar e irá aparecer as informações conforme a imagem abaixo:
Como saber que deu certo?
O aplicativo aparece listado no painel
As credenciais ficam disponíveis
2.2 Credenciais geradas
Após o cadastro do aplicativo, a Melhor Envio irá disponibilizar:
Client ID
Client Secret
❗ Essas informações serão utilizadas na configuração dentro da nossa plataforma.
3. Configuração da integração na nossa plataforma
Com o aplicativo criado, o próximo passo é conectar a integração no painel administrativo.
Onde acessar no sistema
Configurações → Entregas → Melhor Envio
3.1 Como configurar
Na tela de configuração da Melhor Envio:
Marque a opção Habilitado
Selecione o Ambiente
Sandbox (Testes) ou Produção ❗ Cada ambiente utiliza credenciais diferentes.
Preencha conforme as informações da melhor envio:
Client ID
Client Secret
Informe o CPF do responsável
Defina o Status do pedido para envio de etiquetas
Exemplo: Aprovado/Pago
Clique em Conectar com Melhor Envio e preencha os dados
Clique em salvar.
3.2 Autorização da conta
Após clicar em Conectar com Melhor Envio:
Você será redirecionado para a Melhor Envio
Autorize o acesso do aplicativo
Ao finalizar, você será redirecionado automaticamente de volta ao sistema
Como saber que deu certo? ✔ A mensagem “Não conectado” deixa de aparecer ✔ A integração passa a constar como conectada ✔ O cálculo de frete da Melhor Envio fica disponível
4. Configuração do Webhook da Melhor Envio
Para que o sistema receba atualizações automáticas da Melhor Envio (como status de envio), é necessário configurar o webhook.
URL do Webhook
A URL deve seguir o padrão:
https://SEU-DOMÍNIO/webhook/melhor-envioExemplo: https://minhaloja.com.br/webhook/melhor-envio
5. Como gerar etiquetas
5.1 Status do pedido concluido
Para gerar a etiqueta, clique no ícone do caminhão em laranja. Em seguida, o sistema exibirá as informações da compra da etiqueta, como modalidade de envio, valores e dados da entrega. Após conferir as informações, clique no botão laranja “Comprar”.
5.2 Compra da etiqueta
Após isso, verifique as informações de compra da etiqueta e clique o botão laranja comprar
5.3 Confirmação de compra
Quando a compra da etiqueta for concluída com sucesso, o sistema exibirá a mensagem “Etiqueta comprada com sucesso”.
5.4 Download da etiqueta
Após a confirmação, o ícone do caminhão mudará para a cor cinza. Isso indica que a etiqueta já está disponível para download. Clique novamente no ícone para visualizar ou baixar o PDF da etiqueta diretamente no seu computador.
6. O que muda após a integração
✔ A loja passa a calcular fretes via Melhor Envio ✔ As etiquetas podem ser enviadas automaticamente ao carrinho da melhor envio conforme o status definido
7. Quando o comportamento não muda
Se a integração não estiver conectada, a loja continua funcionando normalmente e outras transportadoras habilitadas também.
Outros métodos de frete permanecem ativos.
Credenciais inválidas impedem apenas a conexão com a Melhor Envio
8. Dicas e boas práticas
✔ Sempre cadastre corretamente a URL de callback ✔ Utilize o ambiente Sandbox para testes ✔ Guarde o Client Secret com segurança