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
    ↳Como obtemos a autorização?
→Server side
    ↳Passo a passo
    ↳Parâmetros
→Refresh token
    ↳Parâmetros
→Fluxo Server side
→Client side
    ↳Passo a passo
    ↳Parâmetros
→Fluxo Client side
→Obtenha seu access token
→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:
    - Se quiser utilizar um usuário de teste, ingresse aqui.
    - 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.

  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 Server Side ou Client Side.


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.


Passo a passo

Importante:
Necessitará o app_id que você obteve quando criou seu aplicativo. Se ainda não fez, este guia lhe oferecerá os passos necessários para fazê-lo.
  • 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, digite o seguinte endereço:
  • https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID
    Notas:
    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.

  • Uma vez que o usuário inicie sessão, será redirecionado para a página de autorização do aplicativo. Ali aparecerão todas as permissões requeridas.

  • Outorgadas as permissões, o usuário será redirecionado ao REDIRECT URI configurado no aplicativo com o ACCESS_TOKEN correspondente:

    http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE
  • O código de autorização é utilizado para mudar por um ACCESS_TOKEN:
  • Deve realizar um POST sem BODY:

    curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=$APP_ID&client_secret=$SECRET_KEY&code=$SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=$REDIRECT_URI

    Resposta:

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

    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.

    Fluxo Server side

    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.

    a- Redirect

    curl -X  POST https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$REDIRECT_URL

    b- GET

    curl -X GET http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE

    c- POST

    curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=$APP_ID&client_secret=$SECRET_KEY&code=$SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=$REDIRECT_URI

    Client side

    Este fluxo é o mais adequado para os aplicativos que executam código do lado do cliente. Por exemplo, as desenvolvidas em linguagem Javascript/Ajax, Angular, Mobile, entre outros. Recomendamos você que utilize nossos SDKs já que irão facilitar a complexidade do fluxo de autorização utilizando o protocolo OAuth.

    Importante:
    Ao utilizar este fluxo não poderá obter um refresh token. Uma vez que o token expirar, você deverá redirecionar o usuário novamente ao URL de autorização para obter o novo access token.

    Passo a passo

    Importante:
    Você necessitará o APP_ID que obteve ao criar seu aplicativo. Se ainda não fez, este guia lhe oferecerá os passos necessários para fazê-lo.
    1. Ao iniciar o fluxo de autorização, o aplicativo que desenvolva deverá redirecionar para Mercado Livre, para que os usuários possam se autenticar e depois autorizar seu aplicativo:
    2. curl -X POST https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=$APP_ID
      Nota:
      No exemplo utilizamos o URL para Argentina (MLA), porém, se estiver trabalhando em outros países, lembre mudar o .com.ar pelo domínio do país correspondente. Veja os países onde Mercado Livre opera.

      Parâmetros

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

    3. Uma vez que o usuário inicie sessão, será redirecionado para a página de autorização do aplicativo onde todas as permissões solicitadas serão apresentadas a você.
    4. Quando as permissões forem outorgadas, o usuário será redirecionado ao REDIRECT URI configurado no aplicativo com o access token correspondente:

      http://YOUR_URL?access_token=$ACCESS_TOKEN&expires_in=10800&user_id=$USER_ID&domains=$APP_DOMAINS

      Parâmetros

      Access_token: Chave de acesso aos recursos privados.
      Expires_in: Vida útil do access token em segundos.
      Domains: Domínio da redirect URI.

      Pronto! Já pode utilizar o ACCESS_TOKEN para realizar chamadas ao nosso API e acessar assim os recursos privados do usuário.


      Por exemplo, para aceder as informações privadas do usuário:

      curl -X GET https://api.mercadolibre.com/users/me?access_token=$ACCESS_TOKEN

      Fluxo Client side

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

      flujo_clientside_por

      Referências

      1. Redireciona o APP para Mercado Livre.
      2. Você não tem que se preocupar com a autenticação dos usuários a Mercado Livre, nossa plataforma será responsável por isso!
      3. Página de autorização.
      4. Já pode utilizar o ACCESS_TOKEN para realizar chamadas ao nosso API e acessar assim os dados privados do usuário.

      a- POST

      curl -X POST https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=$APP_ID

      Lembre mudar o .com.br pelo domínio do país correspondente.

      b- GET

      curl -X GET http://YOUR_URL?access_token=$ACCESS_TOKEN&expires_in=10800&user_id=$USER_ID&domains=$APP_DOMAINS

      Obtenha seu access_token!

      Digite o ID do aplicativo criado: *Digite um ID de aplicativo válido

        
          -
        
      

      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.