Implementando o Vínculo de Lojas e Login via ID Magalu (SSO)

Este guia descreve como permitir que lojistas conectem suas contas do aiqfome à sua aplicação externa (ex: um Dashboard de Vendas ou sistema de ERP) utilizando o login do ID Magalu.

O processo está dividido em duas partes essenciais: a configuração que o usuário final (Seller) realiza no painel do Geraldo e as etapas de código que o seu time técnico deve implementar.

Parte 1: 🧑‍💼 Lado do Lojista (Painel do Geraldo Seller)

Esta etapa trata da preparação do ambiente de negócios por parte do lojista. Antes de qualquer implementação de código, o dono do estabelecimento precisa autorizar e vincular a sua loja à conta corporativa unificada do Magalu dentro do painel administrativo do aiqfome

Como o lojista deve fazer o vínculo da conta:

• Acesse as Integrações: No menu do painel Geraldo, vá até a opção de Integrações.
• Escolha a Loja: Clique em "Trocar a loja" caso você gerencie mais de uma unidade ativa na plataforma.
• Identifique o Vínculo: Veja quais lojas já estão ligadas e selecione aquela que ainda não tem o vínculo configurado.
• Confirme a Seleção: Clique na loja desejada e confirme para prosseguir.
• Vincule o ID Magalu: Clique no botão de vincular e você será levado para a página do ID Magalu.
• Atenção ao E-mail: Use o mesmo e-mail que você já utiliza dentro do Geraldo.
• Login ou Cadastro: Se já tiver conta, entre; se não, crie uma nova na hora.
• Permissões: Marque a opção para selecionar todos os escopos de acesso e clique em continuar.
• Tudo Pronto: Assim que terminar, sua conta estará integrada e a sua parte no Geraldo está feita!

🔴 ATENÇÃO CRUCIAL AO E-MAIL ID Magalu:
O usuário deve utilizar obrigatoriamente a mesma conta de e-mail/login que ele possui cadastrada como dono da loja no portal "Geraldo". Caso e-mails diferentes sejam usados, o ecossistema não conseguirá conciliar as contas.

Parte 2: 💻 Parceiro Integrador (Passo a Passo da Implementação Técnica)

Abaixo segue o fluxo que você, como desenvolvedor da aplicação externa, deve implementar seguindo o padrão OAuth 2.0.

Antes da integração técnica funcionar, o lojista deve ter realizado o vínculo inicial no painel do Geraldo. Este é um passo manual obrigatório mencionado no início do vídeo.

Passo a Passo da Implementação Técnica:

1. Preparação da Requisição de Autorização (O Segredo do State)

Quando o usuário clicar no botão "Conectar com Aiqfome/Magalu" na sua aplicação, você deve redirecioná-lo para a URL de autorização do ID Magalu.

Ponto Crítico do Vídeo: Para saber qual loja da sua aplicação está tentando se conectar, você deve passar o ID interno da sua aplicação dentro do parâmetro state.

Estrutura da URL (Exemplo):

GET https://id.magalu.com/login?
  client_id={SEU_CLIENT_ID}&
  response_type=code&
  redirect_uri={SUA_URL_DE_CALLBACK}&
  scope={ESCOPOS_NECESSARIOS}&
  state=12345&
  choose_tenants=true

• client_id: O identificador da sua aplicação fornecido pelo Magalu.
• redirect_uri: A URL na sua aplicação que receberá a resposta.
• state: Aqui você insere o ID da loja dentro do seu banco de dados (ex: 12345). Isso garante que, quando o callback retornar, você saiba a qual usuário vincular os dados.
• choose_tenants: Permite que o usuário escolha com qual tenant (conta) irá realizar o login.

2. O Redirecionamento e Login do Usuário

O usuário será levado para a tela de login do ID Magalu.

Atenção: O usuário deve utilizar a mesma conta de e-mail/login que ele utilizou para fazer o vínculo no portal "Geraldo" (Pré-requisito).

3. Recebendo o Callback (Authorization Code)

Após o login com sucesso, o ID Magalu redirecionará o usuário de volta para a sua redirect_uri.

A requisição chegará assim:

GET https://sua-aplicacao.com/callback?code={AUTHORIZATION_CODE}&state=12345

A sua aplicação deve capturar estes dois parâmetros:

1. code: O código de autorização temporário.
2. state: O ID 12345 que você enviou no passo 1.

4. Processamento e Vínculo (Back-end)

Agora acontece a mágica da integração demonstrada no vídeo:

1. Identificação: Sua aplicação lê o state (12345) e identifica: "Ah, quem está logando é o cliente dono do dashboard número 12345".
2. Troca de Token (Padrão OAuth 2.0): Seu back-end envia o code para o servidor do Magalu em troca de um access_token.

3. Obtenção de Dados: Com o token em mãos, você consulta a API GET https://plataforma.aiqfome.io/api/v2/store Que retornará dados neste formato:

   
   

   {
             "data": [
                 {
                     "id": 54066,
                     "nome": "Nome da Sua Loja",
                     ...
                 }
             ]
         }

   A API retornará os dados da loja Aiqfome vinculada àquela conta (ex: Loja ID 54066).

4. Persistência: Você salva no seu banco de dados que a Sua Loja 12345 corresponde à Loja Aiqfome 54066.

5. Exibição dos Dados

Como mostrado no final do vídeo, uma vez que o vínculo é salvo (usando o state como chave de correspondência), sua aplicação pode começar a puxar pedidos e vendas e exibir no Dashboard.

Resumo Visual do Fluxo

Aqui está um diagrama simplificado da lógica apresentada no vídeo:

Ator	Ação	Detalhe Técnico
Sua App	Gera Link de Login	Inclui state={ID_DA_SUA_APP}
Usuário	Faz Login no ID Magalu	Usa mesma conta do Geraldo
ID Magalu	Retorna para Sua App	Devolve code + state={ID_DA_SUA_APP}
Sua App	Reconhece o Usuário	Usa o state para achar o registro no banco
Sua App	Finaliza Integração	Troca token e baixa dados do Aiqfome

Dica Importante de Segurança
Embora o vídeo sugira usar o state para passar o ID, em um ambiente de produção real, recomenda-se que este parâmetro seja uma string criptografada ou um hash que você possa decodificar no back-end, para evitar que terceiros tentem adivinhar IDs sequenciais da sua aplicação.