Autenticação e Autorização

Para começar a utilizar nossos recursos, é necessário que você possa desenvolver os processos de Autenticação e Autorização. Assim, você poderá trabalhar com os recursos privados do usuário quando autorize seu aplicativo.

Conteúdos

→Autenticação
→Autorização
→Server side
    ↳Passo a passo
    ↳Parâmetros
→Refresh token
    ↳Parâmetros
→Referencia de códigos de erro


Autenticação

O processo de autenticação é utilizado para verificar a identidade de uma pessoa em função de um ou vários fatores, garantindo que os dados de quem os enviou sejam corretos. Ainda que existam diferentes métodos, em Mercado Libre utilizamos o baseado em senhas. Os passos a seguir são:

  1. Autentique-se com seu usuário de Mercado Libre.

  2. Notas:
    - Você pode usar um usuário de teste.
    - Lembre que o usuário que inicie sessão deve ser administrador, para que o access token obtido tenha as permissões suficientes para realizar as consultas.
    - Se o usuário for operador/colaborador, o grant não será válido.
    - Os eventos a seguir podem invalidar um access token antes do tempo de expiração:
    • Alteração da senha pelo usuário.
    • Atualização do App Secret por um aplicativo.
    • Revogação de permissões para seu aplicativo pelo usuário.

  3. Coloque o seguinte URL na janela de seu navegador para obter a autorização:
  4. http://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL
    Nota:
    O atributo YOUR_URL é completado com o valor adicionado quando o aplicativo foi criado.



    - APP_ID: Uma vez criado o aplicativo, será identificado por meio de um ID.

    Exemplo:

    Se quando o aplicativo foi criado, isso foi feito com Redict URI:




    É necessário que a chamada para o recurso /authorization seja a seguinte:

    http://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=https://mercadolibre.com.ar
    Importante:
    O redirect_uri tem que corresponder exatamente ao inserido quando o aplicativo foi criado, para evitar o seguinte erro:


  5. Como último passo, o usuário será redirecionado para a tela seguinte, onde lhe será requerido que vincule o aplicativo com sua conta.


  6. Conferindo o URL, se pode observar que o parâmetro CODE foi adicionado.

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE

    Este Code, será utilizado quando for necessário gerar um access token, que permitirá acessar os nossos API.


Autorização

A autorização é o processo por meio do qual permitimos aceder a recursos privados. Nesse processo deverá ser definido que recursos e operações podem ser realizados (“só leitura” ou “leitura e escrita”).


Como obtemos a autorização?

Por meio do Protocolo OAuth 2.0, um dos mais utilizados em plataformas abertas (Twitter, Facebook, etc.) e método seguro para trabalhar com recursos privados.
Este protocolo nos oferece:

  • Confidencialidade, o usuário nunca deverá revelar sua senha.
  • Integridade, apenas poderão ver dados privados os aplicativos que tiverem permissão para fazê-lo.
  • Disponibilidade, os dados sempre serão disponibilizados no momento em que forem necessários.

Dentro desse protocolo existem 4 modos de funcionamento possíveis chamados de Grant Types:

  • The Authorization Code Grant Type (Server Side)
  • The Implicit Grant Type (Client Side)
  • The Password Credentials Grant Type
  • The Client Credentials Grant Type

A seguir mostraremos a você como trabalhar com os recursos de Mercado Livre utilizando Implicit Grant Type.


Server side

O fluxo Server side é o mais adequado para os aplicativos que executam código do lado do server. Por exemplo, aplicativos desenvolvidos em linguagens como Java, Grails, Go, etc. Recomendamos você que utilize nossos SDKs, já que facilitarão a complexidade de fluxo de autorização utilizando o protocolo OAuth.


Em resumo, o processo que estará realizando é o seguinte:

flujo_serverside_por
  1. Redireciona o aplicativo para Mercado Livre.
  2. Não tem que se preocupar pela autenticação dos usuários para Mercado Libre, nossa plataforma tomará conta disso!
  3. Página de autorização.
  4. POST para intercambiar o código de autorização por um access token.
  5. O API de Mercado Libre intercambia o código de autorização por um token.
  6. Já pode utilizar o access token para realizar chamadas ao nosso API e acessar os dados privados do usuário.

Passo a passo

Importante:
Necessitará o app_id que você obteve quando criou seu aplicativo. Se ainda não fez, já pode registre seu aplicativo.
  1. Ao iniciar o fluxo de autorização, o aplicativo que desenvolva deverá redirecionar para Mercado Livre, para que os usuários possam autenticar-se e depois autorizar seu aplicativo.
    No navegador, deve colocar:
  2. https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL
    Nota:
    No exemplo, utilizamos o URL para Argentina (MLA), porém, se estiver trabalhando em outros países, lembre de mudar o .com.ar pelo domínio do país correspondente. É necessário trocar MercadoLibre para MercadoLivre para MLB. Veja os países onde operamos.

    Parâmetros

    Response_type: enviando o valor “code” será obtido um access token que permitirá ao aplicativo interagir com Mercado Livre.
    Client_id: É o APP ID do aplicativo que foi criado.

    Para aumentar a segurança, recomendamos que você inclua o parâmetro de estado no URL de autorização para garantir que a resposta pertença a uma solicitação iniciada por seu aplicativo.
    Caso você não tenha um identificador aleatório seguro, você pode criá-lo usando SecureRandom e deve ser exclusivo para cada tentativa de chamada.
    Portanto, o URL de redirecionamento será:

    https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&state=$RANDOM_ID&redirect_uri=$REDIRECT_URL

    Exemplo:

    https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&state=ABC1234&redirect_uri=$REDIRECT_URL
  3. Assim que o usuário efetuar login, ele será redirecionado para a página de autorização do aplicativo. Lá você será apresentado com todas as licenças solicitadas.

    Assim que as permissões forem concedidas, o usuário será redirecionado para o URI REDIRECT configurado no aplicativo com o token de acesso correspondente:
  4. http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE

    Se na etapa anterior você incorporou o parâmetro de estado, receberá o código de autorização e também o identificador seguro no URL de retorno especificado:

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE&state=$RANDOM_ID

    Exemplo:

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE&state=ABC1234

    Lembre-se de verificar esse valor para certificar-se de que a resposta pertence a uma solicitação iniciada por seu aplicativo.
    Do Mercado Livre não validamos este campo.


  5. O código de autorização é usado para trocá-lo por um access token.
  6. Você deve realizar um POST enviando os parâmetros por BODY:

curl -X POST \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
'https://api.mercadolibre.com/oauth/token' \
-d 'grant_type=authorization_code' \
-d 'client_id=$APP_ID' \
-d 'client_secret=$SECRET_KEY' \
-d 'code=$SERVER_GENERATED_AUTHORIZATION_CODE' \
-d 'redirect_uri=$REDIRECT_URI'

Resposta:

{
    "access_token": "APP_USR-123456-090515-8cc4448aac10d5105474e1351-1234567",
    "token_type": "bearer",
    "expires_in": 10800,
    "scope": "offline_access read write",
    "user_id":1234567,
    "refresh_token": "TG-5b9032b4e23464aed1f959f-1234567"
}

Parâmetros

grant_type: authorization_code indica que a operação desejada é mudar o “code” por um access token.
client_id: é o APP ID do aplicativo que foi criado.
client_secret: é Secret Key que foi gerado ao criar o aplicativo.
code: o código de autorização obtido no passo anterior.
redirect_uri: o redirect URI configurado para seu aplicativo ou um dos domínios permitidos.
Pronto! Já pode utilizar o access token para realizar chamadas ao nosso API e acessar assim os recursos privados do usuário.


Refresh token

Tenha em consideração que o access token gerado expirará transcorridas 6 horas desde que foi solicitado. Por isso, para garantir que possa trabalhar por um tempo prolongado e não seja necessário, solicitar constantemente ao usuário que volte a se logar para gerar um token novo, lhe oferecemos a solução de trabalhar com um refresh token.

Importante:
Para isso, o aplicativo deve ter selecionada a opção offline_access.

Cada vez que realize a chamada que muda o code por um access token, também terá o dado de um refresh_token, que deverá guardar para trocá-lo por um access token uma vez expirado.
Para renovar seu access token deverá realizar a chamada seguinte:

curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=refresh_token&client_id=$APP_ID&client_secret=$SECRET_KEY&refresh_token=$REFRESH_TOKEN

Parâmetros

grant_type: refresh_token Indica que a operação desejada é atualizar um token.
refresh_token: O refresh token do passo de aprovação guardado previamente.
client_id: É o APP ID do aplicativo que foi criado.
client_secret: É o APP ID do aplicativo que foi criado.

Reposta:

{
    "access_token": "APP_USR-5387223166827464-090515-b0ad156bce700509ef81b273466faa15-8035443",
    "token_type": "bearer",
    "expires_in": 10800,
    "scope": "offline_access read write",
    "user_id":8035443,
    "refresh_token": "TG-5b9032b4e4b0714aed1f959f-8035443"
}

A resposta inclui um novo access token válido por mais 6 horas e um novo REFRESH_TOKEN que deverá guardar para utilizá-lo cada vez que expirar.

Importante:
- Somente permitimos utilizar o último REFRESH_TOKEN gerado para fazer o intercâmbio.
- Para otimizar os processos de seu desenvolvimento, sugerimos você que renove seu access token somente quando perder validade.

Referencia de códigos de erro

invalid_client: O client_id y/o client_secret de seu aplicativo fornecido é inválido.
invalid_grant: A autorização fornecida é inválida, expirou, foi revogada; o client_id ou o redirect uri não conferem com o original.
invalid_scope: O alcance solicitado é inválido, desconhecido ou está formado na forma errada. Os valores permitidos para o parâmetro alcance são: “offline_access”,”write”,”read”.
invalid_request: A solicitação não inclui um parâmetro obrigatório, inclui um parâmetro ou valor de parâmetro não suportado, tem algum valor dobrado ou está mal formado de outra forma.
unsupported_grant_type: Os valores permitidos para grant_type son “authorization_code” ou “refresh_token”.
forbidden: A chamada não autoriza o acesso, possivelmente esteja sendo utilizado o token de outro usuário.


Seguinte: Consulta de usuários.

ou registre-se para receber as últimas notícias sobre nossa API