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 recursos:
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 da integração direta com transportadoras, o fluxo no Melhor Envio é baseado em etapas transacionais. Em vez de uma compra imediata, o processo segue este ciclo de vida:
Inserção: utiliza-se a operação de Inserir fretes no carrinho.
Visualização: os itens ficam disponíveis para conferência e revisão.
Checkout (Compras de fretes): a operação de Compra de fretes é executada para debitar o saldo e autorizar a geração das 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.
Tipo de Autenticação Suportado
A API do Melhor Envio suporta autenticação do tipo OAuth 2.0.
Obtendo as Credenciais
Para integrar-se via OAuth 2.0, é necessário registrar uma aplicação no painel do Melhor Envio para gerar suas chaves de acesso (Client ID e Client Secret).
Siga os seguintes passos:
Acesse o painel de controle do Melhor Envio (seção Integrações/API).
Na aba Área Dev, crie uma nova aplicação. Ao finalizar, o sistema fornecerá seu Client ID e Client Secret.
Vá até a aba Permissões de Acesso para gerar um novo token de acesso (Access Token).
Guarde o access token.
Configuração da Conta no Skyone Studio
Para conectar os módulos, é necessário criar a conta de autenticação correta.
Configurando OAuth 2
No Skyone Studio, crie um módulo chamado Melhor Envio.
No módulo do Melhor Envio, na área de Configurações, escolha as seguintes opções:
Conectividade: REST
Tipo de Autenticação: OAuth 2.0
Conta conectada: clique em Adicionar conta conectada
Preencha os campos conforme abaixo:
Nome da Conta: Melhor Envio - [Produção/Sandbox]
Host:
Produção: https://melhorenvio.com.br/api
Desenvolvimento: https://sandbox.melhorenvio.com.br/api
Client ID: Identificador exclusivo gerado na criação da aplicação no painel do Melhor Envio.
Client Secret: Chave secreta da aplicação, utilizada para autenticar a comunicação via OAuth 2.0.
Access Token: Token de acesso gerado anteriormente
Endpoint de troca de token:
https://sandbox.melhorenvio.com.br/oauth/token(utilizado para fluxos de renovação ou troca de código de autorização).
Salve as alterações e selecione a conta criada no campo Conta conectada.
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).
Leia também: Documentação Oficial da API
Atualizado
Isto foi útil?