🔐 Documentação de Autenticação de Cliente

📋 Visão Geral

A autenticação de cliente permite que o consumidor final acesse recursos protegidos da loja — como pedidos, endereços, lista de desejos e carteira — por meio de um token JWT.

O fluxo começa com a verificação de existência do cadastro, avança para o login (por e-mail ou documento) e, quando a loja exige autenticação multifator (MFA), inclui uma etapa adicional de confirmação antes de emitir o token definitivo.

🔄 Fluxo de Autenticação

1. Verificar existência do cadastro

Antes de apresentar o formulário de login ou cadastro, utilize POST /customer/login/check para verificar se o cliente já possui registro na loja.

A resposta retorna "exists" ou "not-exists", permitindo ao frontend direcionar o usuário para o fluxo correto sem expor dados do cliente.

2. Realizar o login

Com o cadastro confirmado, autentique o cliente por um dos dois métodos disponíveis:

• POST /customer/login/email — login por e-mail e senha
• POST /customer/login/document — login por CPF ou CNPJ e senha

Em caso de sucesso sem MFA, a resposta retorna diretamente o token JWT definitivo.

3. Concluir o MFA (quando exigido)

Quando a loja exige autenticação multifator, o login não retorna o token — retorna um mfaToken temporário.

Utilize POST /customer/login/mfa/send para enviar o código ao canal escolhido (e-mail, SMS, WhatsApp ou serviço externo) e POST /customer/login/mfa para confirmar o código e receber o token definitivo.

🪙 Token JWT

O token retornado após o login deve ser enviado no header de todas as requisições que exigem cliente autenticado:

1Authorization: Bearer {token}

O token não possui um prazo de expiração fixo por padrão — sua validade depende da configuração da loja.

🛡️ Autenticação Multifator (MFA)

O MFA é ativado por configuração da loja. Quando ativo, o fluxo de login é estendido:

Etapa	Endpoint	Descrição
Login inicial	POST /customer/login/email ou /document	Retorna mfaToken em vez do token definitivo
Enviar código	POST /customer/login/mfa/send	Dispara o código para o canal escolhido (e-mail, SMS, WhatsApp, externo)
Confirmar código	POST /customer/login/mfa	Valida o código e retorna o token definitivo

A opção app (autenticador TOTP) não passa pelo mfa/send — o código é gerado diretamente pelo aplicativo autenticador.

📌 Notas e Considerações

• Todos os endpoints de autenticação são públicos — não exigem Authorization header na requisição.
• O campo document nos endpoints de login aceita CPF e CNPJ com ou sem formatação — caracteres especiais são removidos automaticamente antes da validação.
• O mfaToken é temporário e expira após um curto período. Caso expire, o cliente deve reiniciar o fluxo de login.
• O envio de código MFA via mfa/send é suportado apenas para as opções email, sms, whatsapp e external. A opção app (TOTP) não é elegível para esse endpoint.
• Quando a loja utiliza MFA com opção app e a chave ainda não foi persistida para o cliente, o campo secretKey pode ser enviado no POST /customer/login/mfa para registrá-la durante a confirmação.

🔎 Verificar Cliente Existente

📋 Descrição

Endpoint responsável por verificar a existência de um cliente na loja a partir de um e-mail ou documento (CPF/CNPJ).

Útil para evitar duplicidade de registros e direcionar corretamente o fluxo do frontend — orientando o usuário para o formulário de login quando o cadastro existe, ou para o de criação quando não existe.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

1{
2  "identification": "cliente@exemplo.com"
3}

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/check' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "identification": "cliente@exemplo.com"
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

Cliente existe

1{
2  "status": true,
3  "data": "exists"
4}

Cliente não existe

1{
2  "status": true,
3  "data": "not-exists"
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🔎 Verificar canais de venda que o cliente possui login

📋 Descrição

Endpoint responsável por retornar os canais de venda que um cliente pode acessar a partir de um e-mail.

Útil para evitar fazer redirects entre lojas ou trocar o canal de venda direcionando para o canal de venda desejado.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

1{
2  "identification": "cliente@exemplo.com"
3}

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/check-sales-channel' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "identification": "cliente@exemplo.com"
6  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

Cliente existe

1{
2	"status": true,
3	"data": [
4		{
5			"id": 1,
6			"domain": "teste.uappi.store"
7		}
8	]
9}

🔐 Login de Cliente por Documento

📋 Descrição

Endpoint responsável por autenticar um cliente na loja por meio de documento (CPF ou CNPJ) e senha.

Em caso de sucesso, retorna um token JWT que deve ser enviado no header Authorization: Bearer {token} em todas as requisições que exigem o cliente autenticado.

Quando a loja exige autenticação multifator (MFA), o login não retorna o token diretamente — retorna um mfaToken temporário que deve ser utilizado para concluir o segundo fator de verificação.

O campo document aceita CPF e CNPJ em qualquer formato, incluindo o formato alfanumérico — caracteres especiais são removidos automaticamente antes da validação.

Se a loja tiver um app de CAPTCHA instalado, ativo, com chave configurada e com esta rota habilitada, a requisição precisa incluir o header X-Recaptcha-Token, validado junto ao provedor antes da senha ser verificada; se a validação falhar, o login é bloqueado sem que a senha seja checada (fail-closed). Quando a validação passa, a resposta inclui o header Uappi-Recaptcha: success.

Se qualquer uma dessas condições não for atendida (nenhum app instalado, app inativo, sem chave configurada, ou esta rota não configurada no app), o recaptcha é ignorado — o login segue o fluxo normal, sem nenhuma chamada de recaptcha, e o header X-Recaptcha-Token é ignorado se enviado. Não há nenhum erro nesse caso.

📝 Parâmetros

🏷️ Headers Obrigatórios

🏷️ Headers Opcionais

📦 Parâmetros do Corpo

Formatos aceitos para CNPJ: 12345678000190, 12.345.678/0001-90, 12 345 678 0001 90

CNPJ também aceita o formato alfanumérico da Receita Federal (letras nas 12 primeiras posições, dígitos verificadores sempre numéricos), por exemplo: 12ABC34501DE35, 12.ABC.345/01DE-35. O documento é normalizado automaticamente para maiúsculas antes da validação — entrada em minúsculas ou case misto é aceita normalmente.

1{
2  "document": "123.456.789-01",
3  "password": "minhasenha123"
4}

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/document' \
3  --header 'Content-Type: application/json' \
4  --header 'X-Recaptcha-Token: 03AGdBq27...' \
5  --data '{
6    "document": "123.456.789-01",
7    "password": "minhasenha123"
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

Quando o recaptcha foi validado com sucesso, a resposta inclui o header Uappi-Recaptcha: success. Se o recaptcha foi ignorado (nenhum app pronto para esta rota), o header não é enviado.

1{
2  "status": true,
3  "data": {
4    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5  }
6}

Resposta quando MFA é obrigatório

Quando o servidor exige autenticação multifator, o token não é retornado — em vez disso, é retornado um mfaToken temporário para prosseguir com a validação.

1{
2  "status": true,
3  "data": {
4    "mfaToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5  }
6}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🔐 Login de Cliente por Email

📋 Descrição

Endpoint responsável por autenticar um cliente na loja por meio de e-mail e senha.

Em caso de sucesso, retorna um token JWT que deve ser enviado no header Authorization: Bearer {token} em todas as requisições que exigem o cliente autenticado.

Quando a loja exige autenticação multifator (MFA), o login não retorna o token diretamente — retorna um mfaToken temporário que deve ser utilizado para concluir o segundo fator de verificação.

Se a loja tiver um app de CAPTCHA instalado, ativo, com chave configurada e com esta rota habilitada, a requisição precisa incluir o header X-Recaptcha-Token, validado junto ao provedor antes da senha ser verificada; se a validação falhar, o login é bloqueado sem que a senha seja checada (fail-closed). Quando a validação passa, a resposta inclui o header Uappi-Recaptcha: success.

Se qualquer uma dessas condições não for atendida (nenhum app instalado, app inativo, sem chave configurada, ou esta rota não configurada no app), o recaptcha é ignorado — o login segue o fluxo normal, sem nenhuma chamada de recaptcha, e o header X-Recaptcha-Token é ignorado se enviado. Não há nenhum erro nesse caso.

📝 Parâmetros

🏷️ Headers Obrigatórios

🏷️ Headers Opcionais

📦 Parâmetros do Corpo

1{
2  "email": "cliente@exemplo.com",
3  "password": "minhasenha123"
4}

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/email' \
3  --header 'Content-Type: application/json' \
4  --header 'X-Recaptcha-Token: 03AGdBq27...' \
5  --data '{
6    "email": "cliente@exemplo.com",
7    "password": "minhasenha123"
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

Quando o recaptcha foi validado com sucesso, a resposta inclui o header Uappi-Recaptcha: success. Se o recaptcha foi ignorado (nenhum app pronto para esta rota), o header não é enviado.

1{
2  "status": true,
3  "data": {
4    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5  }
6}

Resposta quando MFA é obrigatório

Quando o servidor exige autenticação multifator, o token não é retornado — em vez disso, é retornado um mfaToken temporário para prosseguir com a validação.

1{
2  "status": true,
3  "data": {
4    "mfaToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5  }
6}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🔐 Confirmação de Login MFA de Cliente

📋 Descrição

Endpoint responsável por concluir o login quando a loja exige autenticação multifator — recebe o mfaToken retornado no login inicial, a opção MFA selecionada e o código de verificação, e retorna o token JWT definitivo.

Para a opção app (TOTP), o campo secretKey pode ser enviado quando a chave MFA ainda não foi persistida para o cliente — o sistema registra a chave durante a confirmação.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/mfa' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "mfaToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
6    "mfaOptionId": 1,
7    "code": "123456",
8    "secretKey": "JBSWY3DPEHPK3PXP"
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI..."
5  }
6}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

📨 Envio de Desafio MFA no Login de Cliente

📋 Descrição

Endpoint responsável por enviar um novo código MFA para uma opção notificável elegível no fluxo de login.

Tipos aceitos para envio: email, sms, whatsapp e external. A opção app (TOTP) não é elegível — o código é gerado diretamente pelo aplicativo autenticador, sem necessidade de envio.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/login/mfa/send' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "mfaToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJI...",
6    "mfaOptionId": 2
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.