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

→Enviar access token no header
→Autenticação
→Autorização
→Server side
    ↳Passo a passo
    ↳Parâmetros
→Refresh token
    ↳Parâmetros
→Referencia de códigos de erro
    ↳Erro Invalid Grant


Enviar access token no header

Por segurança, deve enviar o token de acess por header toda vez que fizer chamadas para a API. O header da autorização será:
Authorization: Bearer APP_USR-12345678-031820-X-12345678
Por exemplo, fazer um GET para o recurso /users/me seria:
curl -H ‘Authorization: Bearer APP_USR-12345678-031820-X-12345678’ \
https://api.mercadolibre.com/users/me

Saiba mais sobre a segurança do seu desenvolvimento.


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 e vai receber o erro invalid_operator_user_id.
    - 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. https://auth.mercadolivre.com.br/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL
    Nota:
    O atributo YOUR_URL é completado com o valor adicionado quando quando o aplicativo for 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:

    https://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.

    https://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.

Nota:
- Tenha em consideração que se o usuário for operador/colaborador, NÃO será possível otorgar o grant para a aplicação. Vai retornar o erro invalid_operator_user_id.

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.


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 registrar o 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. https://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:

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

    Exemplo:

    https://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: Os motivos são vários, pode ser porque o authorization_code ou refresh_token são inválidos, expiraram ou foram revogados, foram enviados em um fluxo incorreto, pertencem a outro cliente ou o redirect_uri usado no fluxo de autorização não corresponde ao que tem configurado seu aplicativo.
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. unauthorized_client: A aplicação não tem grant com o usuário ou as permissões (scopes) que tem o aplicativo com esse usuário, não permitem criar um token.


Erro Invalid Grant

No fluxo para obter o refresh token ou authorization code é possível obter o erro invalid_grant com a mensagem "Error validating grant. Your authorization code or refresh token may be expired or it was already used"

    
{
    "message": "Error validating grant. Your authorization code or refresh token may be expired or it was already used",
    "error": "invalid_grant",
    "status": 400,
    "cause": []
}
    

Essa mensagem indica que o authorization_code ou refresh_token enviados não existem ou foram excluídos. Alguns dos motivos são:

  • Tempo de Expiração: passado o tempo de duração do refresh_token (6 meses), vai expirar automaticamente e será necessário fazer de novo o fluxo para obter um novo refresh_token.
  • Revogação da autorização: ao revogar a autorização entre a conta do seller e sua aplicação (seja por parte do integrador ou do seller), os access_token e refresh_token serão invalidados. É possível verificar os usuários que não tem grant com sua aplicação desde a opção "Administrar Permissões" (no painel Meus Aplicativos), ou utilizando a chamada para acessar aos usuários que outorgaram licenças a seu aplicativo.
  • Revogação interna: existem alguns fluxos internos que ocasionam a exclusão das credenciais dos usuários, impedindo que os integradores possam continuar trabalhando em nome dos sellers; nesses casos, é necessário completar de novo o fluxo de autorização/autenticação. Esses fluxos são disparados principalmente por exclusão das sessões dos usuários. Os motivos são vários, mas os mais comuns são alteração de senha, desvinculação de dispositivos ou fraude.
Importante:
Tenha em conta que para esse último fluxo, apenas detalhamos alguns exemplos, não todos os casos disponíveis.

Seguinte: Consulta API Docs.

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