Como criar módulo conector do Melhor Envio
Introdução
Este artigo detalha como configurar, autenticar e integrar a API do Melhor Envio no Skyone Studio usando a opção de criar módulo.
O que é a API do Melhor Envio?
Descrição Técnica
A API do Melhor Envio utiliza uma arquitetura RESTful para permitir a interação programática com a plataforma de intermediação logística. A comunicação é realizada via protocolo HTTPS, com troca de dados padronizada no formato JSON.
Principais Capacidades:
Cotação de Fretes: Realização de cálculos de preços e prazos simultâneos em diversas transportadoras (Correios, Jadlog, Azul Cargo, etc.).
Gestão de Carrinho e Checkout: Fluxo de adição de envios ao carrinho e compra de etiquetas unificada.
Rastreamento e Gestão: Acompanhamento do status das encomendas e gerenciamento de etiquetas geradas.
Conceitos Fundamentais
O Melhor Envio opera com um fluxo lógico de "E-commerce", onde envios são produtos adicionados a um carrinho antes de serem finalizados.
Estrutura de Dados e Hierarquia
Para manipular dados no Melhor Envio com sucesso, é fundamental compreender como as informações são estruturadas:
Carrinho de Compras (Cart)
Diferente de APIs diretas de transportadoras, no Melhor Envio você não "compra" uma etiqueta imediatamente. Primeiro, você utiliza a operação de Inserir fretes no carrinho, depois pode visualizar os itens e, por fim, realizar o Checkout (Compra de fretes) para debitar o saldo e gerar as etiquetas.
Etiquetas (Orders)
Após a compra, o objeto gerado é uma "Order" (Etiqueta). Ela possui status de vida útil: Pending (Pendente), Released (Liberada), Posted (Postada), Delivered (Entregue), Canceled (Cancelada).
Agências e Serviços
Agências são os locais físicos de postagem das transportadoras. Serviços são as modalidades de envio (ex: SEDEX, PAC, .Com, Amanhã). Cada serviço possui um ID específico necessário para o cálculo de frete.
Pré-requisitos e Configuração no Melhor Envio
Para iniciar o desenvolvimento, são necessários os seguintes elementos:
Conta Ativa: Acesso ao painel do Melhor Envio.
Ambiente: Definição se o uso será em Sandbox (testes) ou Produção.
Token de API: Credenciais OAuth 2.0 obtidas no painel de integrações.
Tipos de Autenticação Suportados
A integração suporta os seguintes métodos. Escolha o mais adequado ao seu cenário:
Integração Padrão
OAuth 2.0
Média
Passo a Passo: Obtendo as Credenciais
Atenção: O Melhor Envio utiliza OAuth 2.0 padrão. Você precisará criar uma aplicação no painel para obter o Client ID e Client Secret.
Configuração da Conta no Skyone Studio
Para conectar os módulos, é necessário criar a conta de autenticação correta.
Configurando OAuth 2.0
Preencher os campos
Preencha os campos conforme abaixo:
Nome da Conta
Melhor Envio - [Produção/Sandbox]
Host
https://melhorenvio.com.br/api (Prod) ou https://sandbox.melhorenvio.com.br/api (Dev)
Client ID
Client ID (Client ID da aplicação)
Client Secret
Client Secret (Client Secret da aplicação)
Access Token
Access Token (Access Token gerado)
Endpoint de troca de token
https://sandbox.melhorenvio.com.br/oauth/token
Nota Importante: A API do Melhor Envio exige o envio do header User-Agent contendo o nome da aplicação e o e-mail do responsável técnico em todas as requisições.
Operações Disponíveis
Abaixo listamos as operações (endpoints) mapeadas neste conector.
Cálculo de Fretes
POST
Operação utilizada para calcular preços e prazos de fretes.
Inserir fretes no carrinho
POST
Adiciona uma etiqueta de envio ao carrinho de compras para posterior checkout.
Inserir logística reversa no carrinho
POST
Cria uma solicitação de devolução/logística reversa no carrinho.
Listar itens do carrinho
GET
Retorna a lista de todas as etiquetas atualmente no carrinho.
Exibir informações de item do carrinho
GET
Resgata informações de uma etiqueta específica armazenada no carrinho.
Remoção de itens do carrinho
DELETE
Remove uma etiqueta específica do carrinho de compras.
Compra de fretes
POST
Realiza o checkout (pagamento) dos itens presentes no carrinho.
Geração de etiquetas
POST
Gera a etiqueta (após a compra) informando o ID da mesma para liberar impressão.
Pré-visualização de etiquetas
POST
Retorna um link de pré-visualização da etiqueta.
Impressão de etiquetas
POST
Retorna o link para impressão da etiqueta gerada.
Impressão de etiquetas em arquivo
GET
Solicita a impressão em formatos específicos (.pdf, .zpl, .jpeg).
Listar etiquetas
GET
Lista as etiquetas (orders) do usuário filtrando por status (ex: Pending, Posted).
Listar informações de uma etiqueta
GET
Retorna detalhes de uma etiqueta específica pelo ID.
Pesquisar etiqueta
GET
Pesquisa uma etiqueta por código de rastreio, protocolo ou ID.
Status da etiqueta
POST
Retorna o status atual de rastreamento da etiqueta de envio.
Cancelamento de etiquetas
POST
Solicita o cancelamento de uma etiqueta.
Verificar se etiqueta pode ser cancelada
GET
Verifica se uma etiqueta é passível de cancelamento.
Inserir saldo na carteira do usuário
POST
Insere crédito na conta do usuário no Melhor Envio.
Saldo do usuário
GET
Consulta o saldo atual na carteira do usuário.
Listar informações do usuário
GET
Retorna os dados de cadastro do usuário.
Listar endereços do usuário
GET
Retorna a lista de endereços cadastrados pelo usuário.
Listar lojas do usuário
GET
Lista todas as lojas cadastradas na conta.
Visualizar loja
GET
Retorna informações sobre uma loja específica.
Cadastrar loja
POST
Cadastra uma nova loja do usuário no Melhor Envio.
Listar telefones de uma loja
GET
Retorna os telefones cadastrados em uma loja.
Cadastrar telefones de uma loja
GET
Realiza o cadastro de um telefone em uma loja. (Nota: Verifique se o método exigido é GET ou POST conforme versão da API).
Listar endereços de uma loja
GET
Retorna a lista de endereços de uma loja.
Cadastrar endereço de uma loja
POST
Realiza o cadastro de um endereço vinculado a uma loja.
Listar transportadoras
GET
Retorna lista com todas as transportadoras disponíveis.
Listar informações de uma transportadora
GET
Detalhes de uma transportadora específica.
Listar serviços
GET
Retorna todos os serviços de envio disponíveis.
Listar informações de um serviço
GET
Detalhes de um serviço específico.
Listar agências
GET
Retorna agências de transportadoras disponíveis (filtros por cidade/estado).
Listar informações de uma agência
GET
Detalhes de uma agência específica.
Dica: Para operações de Impressão, certifique-se de que a etiqueta já foi gerada (Geração de etiquetas) após o pagamento (Compra de fretes).
Links e Referências Úteis
Documentação Oficial da API: https://docs.melhorenvio.com.br/
Portal do Desenvolvedor (Cadastro): https://melhorenvio.com.br/
Ambiente Sandbox: https://sandbox.melhorenvio.com.br/
Atualizado
Isto foi útil?