Autenticação, Credenciamento e Vínculo

Antes de realizar o onboarding ou transacionar pedidos na camada Open Delivery, o integrador deve registrar sua aplicação no ecossistema, realizar o vínculo individual de cada estabelecimento e obter as credenciais de acesso através do protocolo OAuth 2.0.

1. Cadastrar Aplicativo de Integração no Portal do Desenvolvedor

1. Acesso e Login: Acesse o Portal do Desenvolvedor e realize o login utilizando uma conta ID Magalu. Certifique-se de conceder todas as permissões solicitadas durante o primeiro acesso (Token de Acesso, Dados Básicos, Criar/Atualizar/Listar Clientes).
2. Seleção do Tipo de Aplicativo: No menu "Meus aplicativos", inicie um novo cadastro e selecione obrigatoriamente a opção "Aplicativo de Integração". Este fluxo é exclusivo para parceiros que gerenciam a operação interna de lojas via API.
3. Preenchimento de Informações Gerais: Insira o nome do app, e-mail de contato, CNPJ da empresa parceira (que passará por validação automática) e a URL de Redirecionamento (Redirect URI).
4. Seleção de Escopos (Atenção Operacional): Na etapa de escopos, é obrigatório selecionar os escopos de Loja (Gestão de Loja) e de Pedidos para que a camada Open Delivery opere corretamente. O escopo de Itens pode ser adicionado de forma opcional.
5. Geração de Credenciais: Após revisar e finalizar o cadastro, o sistema gerará o Client ID e o Client Secret.

Nota de Segurança: Salve o Client Secret em um local seguro imediatamente. Por motivos de segurança, ele não será exibido novamente no portal.

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

O fluxo de autorização é individualizado por loja. Para que a integração funcione, o lojista e a aplicação do parceiro devem seguir os passos abaixo:

Ação Prévia do Lojista (Painel Geraldo Seller)

Antes de qualquer chamada via código, o lojista (Seller) deve acessar o painel administrativo Geraldo, navegar até o menu Integrações, selecionar a loja desejada e clicar no botão de vínculo. Ele será redirecionado para a tela do ID Magalu.

Regra Crucial: O lojista deve obrigatoriamente utilizar a mesma conta de e-mail/login que possui cadastrada como dono do estabelecimento no portal Geraldo. Caso use e-mails diferentes, o sistema não conseguirá conciliar as contas.

Fluxo Técnico da Aplicação (Uso do State)

Quando o usuário clicar no botão de integração dentro do seu sistema (ex: "Conectar com aiqfome"), o seu back-end deve redirecioná-lo para a URL de autorização do ID Magalu.

Para identificar qual estabelecimento está iniciando a rotina de autorização ao receber o retorno, você deve obrigatoriamente injetar o ID único da loja do seu banco de dados dentro do parâmetro state:

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

Recebendo o Callback (Authorization Code)

Após o lojista efetuar o login e conceder os consentimentos na tela do ID Magalu, o servidor de identidade redirecionará o navegador de volta para a sua redirect_uri cadastrada, injetando os parâmetros code e state na URL:

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

A sua aplicação deve capturar ambos os parâmetros no Endpoint de Callback:

• code: O código de autorização temporário que será trocado pelo token final.
• state: O ID que você enviou no início do fluxo (ex: 12345), permitindo mapear qual conta do seu sistema está recebendo a credencial.

3. Troca do CODE pelo Access Token

Com o code capturado e o usuário devidamente identificado pelo state, seu back-end deve realizar uma requisição HTTP POST para o servidor de autenticação do ID Magalu para gerar as credenciais de acesso.

Nota: O code possui uso único e expira imediatamente após a primeira tentativa de troca.

curl --request POST \
  --url https://id.magalu.com/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data redirect_uri=<REDIRECT_URI> \
  --data code=<AUTHORIZATION_CODE> \
  --data grant_type=authorization_code

Exemplo de Resposta (Status 200 OK)

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "rfr_8x923...",
  "scope": "aqf:store:read aqf:order:read aqf:order:write",
  "created_at": 1719343200
}

Regra de Armazenamento Exclusivo: Como a autorização na API é por filial, cada loja possui seu próprio Access Token exclusivo. Salve o par access_token e refresh_token vinculando-os diretamente ao ID da loja recuperado no parâmetro state.

4. Renovação de Credenciais (Refresh Token)

Os tokens de acesso possuem validade de 2 horas (expires_in: 7200). Sempre que um token expirar, utilize o respectivo refresh_token armazenado para renovar o acesso sem a necessidade de uma nova intervenção ou login por parte do lojista.

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

O retorno desta chamada entregará um novo access_token válido e um novo refresh_token que deverá substituir o anterior na sua base de dados. Se o seu Refresh Token expirar por falta de uso, será mandatório reiniciar o fluxo de consentimento com o lojista para obter um novo code.