Bem-vindo à documentação da API do Melhor Envio.
Bem-vindo à documentação da API do Melhor Envio.
A API do Melhor Envio é utilizada por diversas plataformas do e-commerce brasileiro, viabilizando a integração junto à Plataformas de E-commerce, Marketplaces, ERPs, Hubs, etc.
Para integrar com o Melhor Envio é gratuito, não cobramos taxas ou mensalidades pela utilização da nossa API. Agimos dessa forma justamente para facilitar a vida de nossos usuários ao integrarem com nossos serviços, junto aos fluxos de seus sistemas.
Caso você seja um cliente do Melhor Envio e queira apenas utilizar os nossos serviços dentro do seu e-commerce, verifique primeiro se sua plataforma já possui integração com nosso sistema. Se ainda não possuir, entre em contato conosco para que possamos analisar a viabilidade de uma parceria. Agora, se você possuir uma Loja de desenvolvimento próprio e também quiser integrar com o Melhor Envio, basta disponibilizar o link deste conteúdo para seu desenvolvedor.
Seja um Parceiro Verificado
Você pode começar a integrar com a nossa API, conforme a documentação, e caso você deseje se tornar um Parceiro Verificado, acesse nossa Landing Page de Parceiros, para mais informações. Nosso time de Parcerias irá lhe ajudar a encontrar a modalidade de integração mais adequada ao seu modelo de negócio.
Acesse também o infográfico da Jornada do Parceiro, para conhecer o nosso fluxo de integração.
Suporte
Se você não encontrar alguma informação aqui, ou mesmo que encontre e ainda tenha dúvidas sobre algum processo específico, fique à vontade para entrar em contato com os devs do nosso suporte especializado, através do e-mail [email protected].
Atenção: a equipe do Melhor Envio não presta serviços de consultoria, por isso, não analisaremos códigos em nosso suporte.**
Sandbox
O Melhor Envio disponibiliza um ambiente desenvolvido exclusivamente para a realização de testes, que também chamamos de Melhor Envio Sandbox. Para acessá-lo, basta acessar o endereço a seguir e realizar um cadastro rapidamente.
Melhor Envio Sandbox: https://sandbox.melhorenvio.com.br/
Neste ambiente, é possível realizar requisições para nossa API sem receio de cometer qualquer erro. Observe que, como este ambiente serve apenas para teste, não é possível realizar qualquer envio na vida real com as transportadoras parceiras utilizando as etiquetas geradas através dele.
Para começar a realizar testes no ambiente sandbox, será necessário um cadastro no mesmo. Esse cadastro é simplificado, diferente de um cadastro real na plataforma do Melhor Envio, e nele você terá um saldo inicial de R$10.000,00 para gerar etiquetas no modo teste.
Após o cadastro, a integração se dará através de aplicativo utilizando exatamente o mesmo fluxo do ambiente de produção, bastando apenas trocar o domínio nos endpoints das requisições para sandbox.melhorenvio.com.br e utilizar as credenciais do respectivo ambiente.
Vale ressaltar que os ambientes de produção e sandbox são distintos e sem qualquer relação entre dados de cadastro ou envios, impossibilitando o uso do mesmo aplicativo e do mesmo usuário entre eles, sendo necessária a criação de contas separadas. Ou seja, você pode se cadastrar em ambos os ambientes com os mesmos dados, mas serão informações completamente desconectadas.
O Sandbox do Melhor Envio não possui todas as funcionalidades que a plataforma oferece no ambiente em produção, estando limitado somente para simulações de envios com as transportadoras Correios e JadLog, e para pagamentos via Mercado Pago e Moip. Os pagamentos não serão gerados nos respectivos ambientes (nem sandbox, nem produção) dos meios de pagamento, sendo aprovados automaticamente após 5 minutos.
Envios gerados terão o status modificado para postado após 15 minutos da geração das etiquetas. Essa modificação de status ocorrerá juntamente com a conferência de postagem simulando créditos e débitos de modo aleatório, simulando o comportamento real.
Envios postados terão seu status modificado para entregue após 15 minutos da postagem dos mesmos.
Principais particularidades ou limitações do ambiente Sandbox
-
Cadastro simplificado, com aprovação automática e saldo inicial para testes;
-
Inserção de saldo e pagamentos sem comunicação real com meios de pagamento, aprovando automaticamente as transações após 5 minutos (fluxo pela API também é limitado);
-
Apenas 2 transportadoras e 2 meios de pagamento disponíveis;
-
Processamento automático dos envios, trocando de status com intervalos de 15 minutos;
-
Listagens de agências e unidades própria, apenas para testes;
Dúvidas frequentes
Segue abaixo uma lista de dúvidas frequentes sobre o processo de integração:
Qual a validade do token gerado?
O access_token possui validade de 30 dias, após esse período deverá ser realizada a atualização do mesmo utilizando o refresh_token. Após realizada a atualização, o novo access_token possuirá validade de acesso por mais 30 dias.
Cada refresh_token possui validade de 45 dias e, após o término da validade do refresh_token, será necessário realizar uma nova autorização do aplicativo por parte do usuário.
Respeitando o ciclo de refresh_token, é possível manter o acesso por tempo indeterminado.
Melhor Envio Sandbox: https://sandbox.melhorenvio.com.br/
Onde encontro a validade do meu token?
A validade do token econtra-se dentro do próprio token, podendo ser obtida ao decodificar o token.
Um exemplo de como decodificar o token utilizando a linguagem PHP você encontra abaixo:
$tokenParts = explode('.', $token);
$tokenHeader = json_decode(base64_decode($tokenParts[0]));
$tokenPayload = json_decode(base64_decode($tokenParts[1]));
$tokenSignature = $tokenParts[2];
$tokenExpirationDate = date('l jS \of F Y h:i:s A', $tokenPayload->exp);
Se o aplicativo for criado em sandbox, preciso criar novamente em produção?
Sim, são ambientes distintos. Você deve realizar um cadastro oficial no Melhor Envio e assim realizar o cadastro de um novo aplicativo para ser enviado para homologação.
O saldo em sandbox pode ser usado em produção?
Não, nosso ambiente de sandbox serve somente como um ambiente para testes, não sendo possível embarcar uma etiqueta nas transportadoras parceiras.
As etiquetas possuem validade?
Sim, para cada processo há uma validade de 7 dias, conforme descrito abaixo:
- Após adicionar ao carrinho, são 7 dias para realizar o pagamento. Vencido este prazo, a etiqueta é removida do carrinho automaticamente;
- Após o envio pago, são 7 dias para gerar a etiqueta;
- Após gerada a etiqueta, são mais 7 dias para realizar a postagem;
Após vencido algum dos prazos de geração ou de postagem, a etiqueta é cancelada automaticamente.
Existe algum limite de requisições?
Estamos limitando em 250 requisições por minuto para cada usuário autenticado. Para requisições sem autenticação, o limite é feito por IP.
Está retornando “client invalid” da API, o que pode estar causando esse erro?
Este é um erro na autorização de acesso a conta no Melhor Envio. Verifique se a URL cadastrada no campo de callback é a mesma URL cadastrada em sua plataforma.
Quando o Melhor Envio implementar uma nova transportadora, é necessário modificar algo?
Quando a integração é realizada por aplicativo, não existe a necessidade de alteração de código fonte do sistema (desde que na integração o usuário não passe de forma explícita os serviços), pois todas as configurações de transportadoras oferecidas ficam do lado do Melhor Envio.
Assim sendo, será necessário apenas realizar a habilitação da nova transportadora integrada dentro do seu aplicativo (criado no Melhor Envio).
Por que não aparecem as configurações do aplicativo para o usuário em produção?
Para um aplicativo estar visível para o usuário, é necessário que o aplicativo tenha sido criado no ambiente de produção (https://melhorenvio.com.br), e o mesmo precisa ser aprovado de equipe de integrações do Melhor Envio.
Quando o aplicativo deve ser enviado para homologação?
O aplicativo só deve ser submetido para homologação após ser préviamente criado em sandbox e testado.
Uma vez o desenvolvimento estando concluído, é necessário criar o aplicativo em produção e enviar os dados necessários no formulário de homologação de aplicativo como: manual de como ativar a integração, logo da plataforma e screenshots da integração.
Importante: É necessário informar a equipe de integrações do Melhor Envio sobre o envio do aplicativo para produção.
Quais os parâmetros de autenticação?
Todas as requisições para a API do Melhor Envio devem conter nos headers os seguintes parâmetros:
| Key | Value |
|---|---|
| Authorization | Bearer {{token}} |
| User-Agent | Aplicação (email para contato técnico) |
Referência da API
Nosso meio de integração por API segue as melhores práticas de uma API RESTful. Todas as requisições que envolvam dados dos usuários devem ser autenticadas com OAuth2 via autorização de aplicativo. Tokens fornecidos via autenticação OAuth2 possuem validade de 15 dias e devem ser atualizados via refresh token que possui validade de 30 dias.
Todas as respostas seguem o formato JSON com os seus respectivos códigos de status do protocolo HTTP. Payloads para requisições, com exceção do método GET, devem ser realizadas obrigatoriamente no corpo da requisição e codificados como JSON.
Todas as requisições devem utilizar o protocolo HTTPS.
Considerações importantes
O domínio para chamada de endpoints é: www.melhorenvio.com.br
O domínio para chamada de endpoints do sandbox é: sandbox.melhorenvio.com.br
Envie o cabeçalho HTTP Accept (Accept: application/json) e Content-Type (Content-Type: application/json), com exceção para rotas de autenticação OAuth2.
É obrigatório que seja adicionado o cabeçalho HTTP User-Agent com o nome da sua aplicação junto a um email de contato/suporte.
Exemplo: Melhor Envio ([email protected])