Criação de um aplicativo no Painel do Melhor Envio
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