# 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](https://docs.skyone.cloud/skyone-studio/modulos/gestao-de-modulos/criacao-de-modulos). ### 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: 1. **Inserção:** utiliza-se a operação de *Inserir fretes no carrinho*. 2. **Visualização:** os itens ficam disponíveis para conferência e revisão. 3. **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: 1. Acesse o painel de controle do Melhor Envio (seção Integrações/API). 2. Na aba **Área Dev**, crie uma nova aplicação. Ao finalizar, o sistema fornecerá seu Client ID e Client Secret. 3. Vá até a aba **Permissões de Acesso** para gerar um novo token de acesso (Access Token). 4. 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 1. No **Skyone Studio**, [crie um módulo](https://docs.skyone.cloud/skyone-studio/modulos/gestao-de-modulos/criacao-de-modulos) chamado Melhor Envio. 2. 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** 3. Preencha os campos conforme abaixo: * **Nome da Conta:** Melhor Envio - \[Produção/Sandbox] * **Host:** * **Produção:** [**https://melhorenvio.com.br/api**](https://melhorenvio.com.br/api) * **Desenvolvimento:** [**https://sandbox.melhorenvio.com.br/api**](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). 4. Salve as alterações e selecione a conta criada no campo **Conta conectada**. {% hint style="warning" %} 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. {% endhint %} *** ### Operações Disponíveis Abaixo listamos as operações (endpoints) mapeadas neste conector. | Nome da Operação | Método HTTP | Descrição da Função | | -------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | **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. | {% hint style="info" %} 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`). {% endhint %} *** **Leia também:** [Documentação Oficial da API](https://docs.melhorenvio.com.br/)