Autenticação

A autenticação deve ser realizada através da criação de um aplicativo no Painel do Melhor Envio, 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 "NOVO APLICATIVO" no painel de gerenciamento de autorizações 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 url de redirecionamento/callback (url para onde o usuário é redirecionado após autorizar o aplicativo).

Para disponibilizar a solicitação de autorização do aplicativo, deve-se realizar um redirect para a rota /oauth/authorize informando as seguintes informações:

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)

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 transaportadoras)
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 (Rastreio de fretes)
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)

O usuário irá autorizar ou não a solicitação de acesso, redirecionando para a url de redirecionamento (redirect_uri), retornando um parâmetro error caso não autorizado e um parâmetro code caso autorizado.
O code retornado neste redirecionamento é o mesmo que deverá ser enviado para a requisição do token.

Abaixo um exemplo de como a URL deve ser montada:

{{url}}/oauth/authorize?client_id={{client_id}}&redirect_uri={{callback}}&response_type=code&scope=cart-read

🚧
Nota: esta rota deve ser chamada através de redirect.

🚧
Nota: a URL de callback 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