Obter Autorização do Seller via OAuth 2.0

O processo de autenticação para as APIs do Magalu segue o protocolo OAuth 2.0, utilizando o fluxo Authorization Code. Este fluxo permite que sua aplicação obtenha acesso seguro às informações dos sellers através da autorização explícita dos mesmos.

pré-requisito

Antes de implementar a autenticação, certifique-se de ter criado um cliente de aplicação e ter em mãos seu client_id e client_secret. Se você ainda não possui essas credenciais, consulte a seção Como Criar e Configurar um Cliente.
Também é importante garantir que seu cliente esteja configurado corretamente com os escopos necessários.

Vídeo de Instruções para Autenticação

Passo a Passo para Autenticação OAuth 2.0

Solicitar consentimento do seller

Para iniciar o processo de autenticação, você precisa redirecionar o seller para uma página de consentimento onde ele autorizará sua aplicação a acessar suas informações.

Existem duas formas de implementar esta etapa:

Usar o botão de consentimento do Magalu - Solução mais simples e recomendada
Gerar URL de consentimento customizada - Ideal para testar o fluxo de consentimento

Botão 'Autorizar com o ID Magalu'
Gerar URL de consentimento

Implementação do Botão de Consentimento

Adicione um botão "Autorizar com o ID Magalu" ao seu site para que os sellers possam realizar o login diretamente no ID Magalu e conceder as permissões solicitadas pela sua aplicação.

vantagem

Após o consentimento, o ID Magalu redirecionará automaticamente o seller com as informações necessárias para continuar a autenticação na sua aplicação.

Parâmetros do componente

Campo	Tipo	Descrição	Obrigatório
`client-id`	string	ID público da aplicação cliente no ID Magalu	Sim
`redirect-uri`	string	URI de redirecionamento do cliente que receberá o código de autorização OAuth 2.0	Sim
`state`	string	String alfanumérica que sua aplicação adiciona à solicitação inicial. O ID Magalu incluirá este valor ao redirecionar de volta para sua aplicação. Útil para identificar qual seller realizou o consentimento	Não
`scope`	string	Escopos adicionais que devem ser solicitados para consentimento. Importante: Estes escopos serão combinados com os escopos padrão (`--scopes-default`) configurados no client. O seller verá: escopos padrão + escopos definidos aqui. Use este campo para solicitar escopos extras além dos padrão.	Não

Exemplo de implementação:

<html>
  <head>
    <script type="module" src="https://openapi.magalu.com/script/script.js" async></script>
  </head>

  <body>
    <div
      class="magalu-consent-content"
      client-id="<client_id>"
      redirect-uri="<redirect_uri>"
      state="<informação de estado para identificar o seller>"
      scope="<escopos separados por espaço>"
    ></div>
  </body>
</html>

Geração Manual de URL de Consentimento

Neste método, sua aplicação montará uma URL personalizada com os parâmetros necessários para realizar o consentimento através de uma requisição GET direta.

Parâmetros obrigatórios para a URL

Campo	Tipo	Descrição	Obrigatório
`client_id`	string	ID público da aplicação cliente no ID Magalu	Sim
`redirect_uri`	string	URL de redirecionamento do cliente que receberá o código de autorização OAuth 2.0	Sim
`scope`	string	Escopos adicionais de consentimento separados por espaços. Importante: Estes escopos serão combinados com os escopos padrão (`--scopes-default`) configurados no client. O seller verá na tela de consentimento: escopos padrão + escopos definidos aqui. Exemplo: `scope_1 scope_2 scope_3`	Sim
`response_type`	string	Deve sempre ser `code` para o fluxo Authorization Code. Este parâmetro especifica que você deseja receber um código de autorização na `REDIRECT_URI`	Sim
`choose_tenants`	string	Deve sempre ser `true` para sellers. `choose_tenants=true` permite que seja selecionada a organização (loja) que está autorizando o acesso. Se for `false`, o consentimento é aplicado apenas para a pessoa física que fez login	Sim
`state`	string	String alfanumérica que sua aplicação adiciona à solicitação. O ID Magalu incluirá este valor ao redirecionar de volta. Útil para validação de segurança e identificação do seller	Não

Estrutura da URL de consentimento:

https://id.magalu.com/login?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=<SCOPES>&response_type=code&choose_tenants=true

Exemplo prático:

https://id.magalu.com/login?client_id=fSbG5kB3iv5x9sLioaweMSaw3Qhb5xlTC3JpxGFdpd0&redirect_uri=http://localhost:3000/redirect&scope=open:portfolio:read open:order-order:read&response_type=code&choose_tenants=true

Independentemente do método escolhido, o seller será direcionado para a tela de login do ID Magalu:

importante

O seller deve usar as credenciais da loja (pessoa jurídica) para acessar os recursos de seller. Login com credenciais de pessoa física pode não ter acesso aos escopos necessários.

Autorizar escopos (etapa executada pelo seller)

Após fazer login, o sistema verifica se existem permissões pendentes de autorização. Se houver escopos que ainda não foram concedidos pelo seller, a tela de consentimento será apresentada:

Nesta tela, o seller pode:

Revisar quais permissões estão sendo solicitadas
Acessar os termos de uso e política de privacidade da aplicação
Autorizar ou negar o acesso aos escopos solicitados

importante

Se o seller já concedeu todas as permissões solicitadas em uma sessão anterior, esta tela será omitida e ele será redirecionado diretamente para a próxima etapa do fluxo.

Termos de Uso e Política de Privacidade

Durante esta etapa, o seller terá acesso aos links dos Termos de Uso e Política de Privacidade da sua aplicação, configurados através dos parâmetros --terms-of-use e --privacy-term durante a criação do client. Certifique-se de que essas URLs estejam acessíveis e contenham informações claras sobre o uso dos dados.

Receber o código de autorização

Após a autorização dos escopos, o protocolo OAuth 2.0 é finalizado com o redirecionamento automático do seller para a REDIRECT_URI configurada no seu client. O ID Magalu anexará o código de autorização como um query parameter na URL de callback.

Estrutura do redirecionamento:

A URL de callback seguirá o padrão OAuth 2.0 padrão:

https://sua-aplicacao.com/callback?code=CODIGO_DE_AUTORIZACAO&state=SEU_STATE

Exemplo do redirecionamento:

Parâmetros retornados:

code: Código de autorização temporário que deve ser trocado por tokens de acesso
state: Valor de estado enviado na requisição inicial (se fornecido)

importante

Segurança e Validade:

O código de autorização possui validade limitada de 10 minutos
Deve ser utilizado imediatamente para obter os tokens de acesso
É de uso único - não pode ser reutilizado após a troca por tokens
Esta limitação temporal é uma medida de segurança essencial do protocolo OAuth 2.0

Trocar o código por tokens de acesso

Com o código de autorização em mãos, sua aplicação deve executar uma requisição server-to-server para trocar o código temporário por tokens de acesso permanentes. Esta é a etapa final do fluxo OAuth 2.0 Authorization Code.

Parâmetros da requisição:

Campo	Tipo	Descrição	Obrigatório
`grant_type`	string	Deve ser `authorization_code` para este fluxo	Sim
`client_id`	string	ID público da aplicação cliente no ID Magalu	Sim
`client_secret`	string	Segredo da aplicação cliente no ID Magalu	Sim
`redirect_uri`	string	A mesma URL de redirecionamento utilizada na geração da URL de consentimento ou no botão de consentimento. Este campo é obrigatório para validação de segurança do protocolo OAuth 2.0	Sim
`code`	string	Código de autorização temporário recebido via query parameter na `redirect_uri`	Sim

Exemplo de chamada:

curl --location --request POST 'https://id.magalu.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "redirect_uri": "<REDIRECT_URI>",
    "code": "<CODE>",
    "grant_type": "authorization_code"
}
'

Resposta:

Campo	Tipo	Descrição
`access_token`	string	Token JWT de acesso às APIs da plataforma
`refresh_token`	string	Token JWT utilizado para renovar o access_token quando este expirar
`token_type`	string	Tipo do token. Sempre será `Bearer` para este fluxo
`expires_in`	integer	Tempo de vida do access_token em segundos (exemplo: 7200 = 2 horas)
`scope`	string	Lista de escopos autorizados pelo seller, separados por espaços
`created_at`	timestamp	Timestamp Unix de quando os tokens foram criados

Exemplo de resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "open:portfolio:read open:order-order:read",
  "created_at": 1640995200
}

Renovar o token de acesso

Para realizar o processo de renovação do token (refresh_token), execute a seguinte chamada:

Exemplo de chamada:

curl --location 'https://id.magalu.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'refresh_token=<REFRESH_TOKEN>'

Resposta:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "<TOKEN_TYPE>",
  "expires_in": "<EXPIRES_IN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "scope": "<SCOPES>",
  "created_at": "<CREATED_AT>"
}

Vídeo de Instruções para Autenticação​

Passo a Passo para Autenticação OAuth 2.0​

Solicitar consentimento do seller

Implementação do Botão de Consentimento​

Parâmetros do componente​

Exemplo de implementação:​

Geração Manual de URL de Consentimento​

Parâmetros obrigatórios para a URL​

Estrutura da URL de consentimento:​

Exemplo prático:​

Fazer login no ID Magalu (etapa executada pelo seller)

Autorizar escopos (etapa executada pelo seller)

Receber o código de autorização

Estrutura do redirecionamento:​

Exemplo do redirecionamento:​

Trocar o código por tokens de acesso

Parâmetros da requisição:​

Exemplo de chamada:​

Resposta:​

Exemplo de resposta:​

Renovar o token de acesso

Exemplo de chamada:​

Resposta:​

Vídeo de Instruções para Autenticação

Passo a Passo para Autenticação OAuth 2.0

Implementação do Botão de Consentimento

Parâmetros do componente

Exemplo de implementação:

Geração Manual de URL de Consentimento

Parâmetros obrigatórios para a URL

Estrutura da URL de consentimento:

Exemplo prático:

Estrutura do redirecionamento:

Exemplo do redirecionamento:

Parâmetros da requisição:

Exemplo de chamada:

Resposta:

Exemplo de resposta:

Exemplo de chamada:

Resposta: