Autenticação

A autenticação deve ser realizada através da criação de um aplicativo no Painel do Melhor Envio em "Integrações" > "Área Dev.", sendo que este aplicativo valerá para que a plataforma possa gerenciar os tokens de maneira que o usuário da plataforma não precise se preocupar com isto.

Através do aplicativo, o usuário apenas dará permissão para que a plataforma possa realizar requisições conforme as permissões concedidas. O usuário não deverá possuir acesso aos dados do aplicativo.

No formulário de cadastro de aplicativo, é necessário que sejam preenchidos com atenção todos os campos.

É de suma importância que o campo de callback seja idêntico a URL de callback de retorno da sua aplicação. Caso este campo esteja diferente, nossa API irá retornar Client invalid impedindo a autorização do aplicativo.

A autenticação é baseada no padrão OAuth2.

Também disponibilizamos um fluxograma que poderá lhe auxiliar a visualizar este processo, assim como servir de base para que você adapte da melhor maneira ao fluxo de seu sistema.

Para uma documentação mais descritiva sobre como integrar o fluxo de autenticação, clique aqui para consultar o respectivo tópico de nossa nova documentação.

Autorização

Após o cadastro do aplicativo, serão fornecidas duas informações que serão essenciais no desenvolvimento do processo de autenticação com a API para solicitar a autorização dos usuários, estas informações são o Client ID e o Secret.

📘
Para Criar um novo app, basta clicar em “Cadastrar Aplicativo” no painel Area Dev. e preencher o formulário com as informações solicitadas.

📘
Dentre as informações que requerem maior cuidado estão o nome do aplicativo (que deve ser alusivo ao nome da plataforma) e a redirect uri ou callback (url para onde o usuário é redirecionado após autorizar o aplicativo).

Para dar início a solicitação de autorização do aplicativo, deve-se realizar um redirect pelo navegador utilizando a URL de redirecionamento, informando os seguintes parâmetros:

O Client ID (fornecido após cadastro do app);
A URL de redirecionamento (cadastrado no app);
As permissões (separado por espaço).

Lista de permissões

(solicitar apenas as permissões necessárias para sua integração)

Permissões	Descrição
`cart-read`	Visualização dos itens do carrinho
`cart-write`	Cadastro e edição dos itens do carrinho
`companies-read`	Visualização das informações de empresas
`companies-write`	Cadastro e edição das informações de empresas
`coupons-read`	Visualização dos cupons cadastrados
`coupons-write`	Cadastro de novos cupons
`notifications-read`	Visualização das notificações
`orders-read`	Visualização das etiquetas
`products-read`	Visualização de produtos
`products-write`	Cadastro e edição de produtos
`purchases-read`	Visualização das compras
`shipping-calculate`	Cotação de fretes
`shipping-cancel`	Cancelamento de etiquetas
`shipping-checkout`	Checkout para compra de fretes, utiliza saldo da carteira
`shipping-companies`	Consulta de transportadoras
`shipping-generate`	Geração de novas etiquetas
`shipping-preview`	Pré-visualização de etiquetas
`shipping-print`	Impressão de etiquetas
`shipping-share`	Compartilhamento de etiquetas
`shipping-tracking`	Status do ciclo de vida da etiqueta
`ecommerce-shipping`	Cotação e compra de fretes para sua loja
`transactions-read`	Visualização das transações da carteira
`users-read`	Visualização das informações pessoais
`users-write`	Edição das informações pessoais

Ao acessar o fluxo de Autorização o usuário deverá autorizar a solicitação de acesso, ao final do fluxo será redirecionado para o endereço cadastrado no redirect_uri com o parâmetro CODE informado na barra de endereços do navegador. O CODE retornado neste redirecionamento é o mesmo que deverá ser enviado para requisição de Solicitação do Token.

Abaixo um exemplo de como a URL de redirecionamento deve ser montada:

{{url}}/oauth/authorize?client_id={{client_id}}&redirect_uri={{callback}}&response_type=code&state=teste&scope={{permissao1}} {{permissao2}}

🚧
Nota:

Essa rota deve ser chamada através de um redirect padrão pelo navegador;

A URL de callback(redirect_uri) deve ser estática e conforme configurada no app.

Caso deseje passar algum argumento, é possível passar o campo state com o valor desejado para que retorne junto ao code, o campo state é passado do mesmo modo que o Client ID, a URL de redirecionamento e as demais informações.

Abaixo um exemplo com todas as permissões e parâmetro state:

{{url}}/oauth/authorize?client_id={{client_id}}&redirect_uri={{callback}}&response_type=code&state=teste&scope=cart-read cart-write companies-read companies-write coupons-read coupons-write notifications-read orders-read products-read products-write purchases-read shipping-calculate shipping-cancel shipping-checkout shipping-companies shipping-generate shipping-preview shipping-print shipping-share shipping-tracking ecommerce-shipping transactions-read users-read users-write