# Como crear modulo conector de Mercado 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](broken://pages/zwgnhjBaI9j64MrYeI67). ### 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: * **Contas conectadas:** 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/) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.skyone.cloud/espanol/skyone-studio/how-to/como-crear-modulo-conector-de-mercado-envio.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.