ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

👤 Fluxo de Primeiro Acesso

Este guia apresenta o fluxo completo para cadastro de novos usuários no sistema.

📋 Visão Geral

O fluxo de primeiro acesso permite que novos usuários criem sua conta no sistema, passando por validações de segurança e aceitando termos de uso.

Pré-requisitos

Antes de iniciar o fluxo, certifique-se de ter:

CPF e data de nascimento do cliente
Informações do dispositivo (ID, modelo, sistema operacional)
Nome do aplicativo configurado no sistema

Passo 1️⃣: Validar Dados do Cliente

Valide os dados básicos do cliente para iniciar o processo de cadastro.

Endpoint

POST {baseUrl}/identificacao/dados
Content-Type: application/json

Request Body

{
  "app": "APP_NAME",
  "fluxo": "PRIMEIRO_ACESSO",
  "cliente": {
    "cpf": "12345678909",
    "dataNascimento": "1990-01-01"
  },
  "dispositivo": {
    "dispositivoId": "device123",
    "idSistemaOperacional": "2",
    "versaoSistemaOperacional": "12",
    "modelo": "Samsung Galaxy",
    "versaoApp": "1.0.0"
  }
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`app`	string	✅	Nome do aplicativo configurado
`fluxo`	string	✅	Fixo: `"PRIMEIRO_ACESSO"`
`cliente.cpf`	string	✅	CPF do cliente (apenas números)
`cliente.dataNascimento`	string	✅	Data de nascimento (YYYY-MM-DD)
`dispositivo.dispositivoId`	string	✅	ID único do dispositivo
`dispositivo.idSistemaOperacional`	string	✅	1=iOS, 2=Android, 3=Outros
`dispositivo.versaoSistemaOperacional`	string	✅	Versão do SO (ex: "12", "17.2")
`dispositivo.modelo`	string	✅	Modelo do dispositivo
`dispositivo.versaoApp`	string	✅	Versão do aplicativo

Resposta de Sucesso

A API retorna um access_token temporário (token de sessão do cliente) que deve ser usado nos próximos passos do fluxo.

200 OK
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 900
}

⏱️ Atenção

Este token expira em 15 minutos. Complete o fluxo dentro deste prazo.

Exemplo de Código

async function iniciarPrimeiroAcesso(cpf, dataNascimento, dispositivo) {
  const response = await fetch(`${baseUrl}/identificacao/dados`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      app: 'meu-app-private-label',
      fluxo: 'PRIMEIRO_ACESSO',
      cliente: {
        cpf: cpf,
        dataNascimento: dataNascimento
      },
      dispositivo: dispositivo
    })
  });

  if (!response.ok) {
    throw new Error('Erro ao validar dados');
  }

  const { access_token } = await response.json();
  
  // Armazene o token para os próximos passos
  sessionStorage.setItem('session_token', access_token);
  
  return access_token;
}

Passo 2️⃣: Solicitar Link de Biometria (Opcional)

Se desejar validação biométrica adicional, solicite o link para captura.

Endpoint

POST {baseUrl}/identificacao/biometria
Authorization: Bearer {token-sessao-cliente}
Content-Type: application/json

Request Body

{
  "consumidor": "CONSUMIDOR_ID",
  "loja": 123456
}

Exemplo de Código

async function solicitarBiometria(sessionToken, consumidorId, lojaId) {
  const response = await fetch(`${baseUrl}/identificacao/biometria`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      consumidor: consumidorId,
      loja: lojaId
    })
  });

  const { link } = await response.json();
  
  // Abra o link em um WebView ou navegador in-app
  return link;
}

📸 Implementação

Este passo é opcional e depende da configuração do seu aplicativo. O link retornado deve ser aberto em um WebView para captura da biometria facial.

Passo 3️⃣: Enviar Token SMS

Solicite o envio de um código de verificação por SMS para o telefone cadastrado do usuário.

Endpoint

POST {baseUrl}/identificacao/token-sms/envio
Authorization: Bearer {token-sessao-cliente}

Exemplo de Código

async function enviarSMS(sessionToken) {
  const response = await fetch(`${baseUrl}/identificacao/token-sms/envio`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`
    }
  });

  if (!response.ok) {
    throw new Error('Erro ao enviar SMS');
  }

  return await response.json();
}

📱 SMS

O código enviado tem 6 dígitos e é válido por 5 minutos.

Passo 4️⃣: Validar Token SMS

Valide o código de 6 dígitos recebido por SMS.

Endpoint

POST {baseUrl}/identificacao/token-sms
Authorization: Bearer {token-sessao-cliente}
Content-Type: application/json

Request Body

{
  "pinCode": "123456",
  "analise": {
    "userID": "12345678909",
    "origem": "APP_NAME",
    "deviceID": "device123",
    "integrationName": "app-login-pl",
    "dadosMaquina": {
      "ip": "192.168.0.1",
      "fingerPrint": "{fingerprint}"
    }
  }
}

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`pinCode`	string	✅	Código de 6 dígitos recebido por SMS
`analise.userID`	string	✅	CPF do usuário
`analise.origem`	string	✅	Nome do aplicativo
`analise.deviceID`	string	✅	ID do dispositivo
`analise.integrationName`	string	✅	Nome da integração
`analise.dadosMaquina.ip`	string	✅	Endereço IP do dispositivo
`analise.dadosMaquina.fingerPrint`	string	✅	Fingerprint do dispositivo

Exemplo de Código

async function validarSMS(sessionToken, pinCode, dadosDispositivo) {
  const response = await fetch(`${baseUrl}/identificacao/token-sms`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      pinCode: pinCode,
      analise: {
        userID: dadosDispositivo.cpf,
        origem: 'meu-app-private-label',
        deviceID: dadosDispositivo.dispositivoId,
        integrationName: 'app-login-pl',
        dadosMaquina: {
          ip: dadosDispositivo.ip,
          fingerPrint: dadosDispositivo.fingerprint
        }
      }
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Código SMS inválido');
  }

  return await response.json();
}

🛡️ Análise de Fraude

O objeto analise contém informações para análise de fraude. Certifique-se de enviar dados precisos do dispositivo.

Passo 5️⃣: Validar Perguntas de Segurança (Se Aplicável)

Alguns fluxos podem exigir resposta a perguntas de segurança para validação adicional.

Endpoint

POST {baseUrl}/identificacao/perguntas
Authorization: Bearer {token-sessao-cliente}
Content-Type: application/json

Request Body

{
  "respostas": [
    {
      "codigoPergunta": 1,
      "resposta": "resposta1"
    },
    {
      "codigoPergunta": 2,
      "resposta": "resposta2"
    }
  ]
}

Exemplo de Código

async function validarPerguntas(sessionToken, respostas) {
  const response = await fetch(`${baseUrl}/identificacao/perguntas`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      respostas: respostas
    })
  });

  if (!response.ok) {
    throw new Error('Respostas incorretas');
  }

  return await response.json();
}

📋 Condicional

Este passo só é exigido se a API retornar status indicando necessidade de validação adicional.

Passo 6️⃣: Buscar Termo de Aceite

Obtenha o texto completo do termo de uso e política de privacidade que o usuário deve aceitar.

Endpoint

GET {baseUrl}/contratos/termo-aceite
Authorization: Bearer {token-sessao-cliente}

Exemplo de Resposta

{
  "termo": {
    "id": 123,
    "versao": "2.1",
    "titulo": "Termos de Uso e Política de Privacidade",
    "conteudo": "Texto completo do termo...",
    "dataPublicacao": "2025-01-01T00:00:00Z"
  }
}

Exemplo de Código

async function buscarTermo(sessionToken) {
  const response = await fetch(`${baseUrl}/contratos/termo-aceite`, {
    headers: {
      'Authorization': `Bearer ${sessionToken}`
    }
  });

  const { termo } = await response.json();
  
  // Exiba o termo na interface
  return termo;
}

Passo 7️⃣: Aceitar Termo

Registre a aceitação do termo pelo usuário na interface do app.

Endpoint

PUT {baseUrl}/contratos/termo-aceite
Authorization: Bearer {token-sessao-cliente}
Content-Type: application/json

Request Body

{
  "aceite": true
}

Exemplo de Código

async function aceitarTermo(sessionToken) {
  const response = await fetch(`${baseUrl}/contratos/termo-aceite`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      aceite: true
    })
  });

  if (!response.ok) {
    throw new Error('Erro ao aceitar termo');
  }

  return await response.json();
}

⚖️ Legal

Certifique-se de apresentar o termo completo ao usuário e obter consentimento explícito antes de enviar o aceite.

Passo 8️⃣: Criar Senha de Acesso

Finalize o cadastro criando a senha do usuário. Este é o último passo do fluxo.

Endpoint

POST {baseUrl}/usuario/acesso
Authorization: Bearer {token-sessao-cliente}
Content-Type: application/json

Request Body

{
  "senha": "SenhaSegura123"
}

Exemplo de Código

async function criarSenha(sessionToken, senha) {
  // Validar senha antes de enviar
  if (!validarSenha(senha)) {
    throw new Error('Senha não atende aos requisitos de segurança');
  }

  const response = await fetch(`${baseUrl}/usuario/acesso`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${sessionToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      senha: senha
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Erro ao criar senha');
  }

  return await response.json();
}

function validarSenha(senha) {
  // Mínimo 8 caracteres
  if (senha.length < 8) return false;
  
  // Pelo menos 1 letra maiúscula
  if (!/[A-Z]/.test(senha)) return false;
  
  // Pelo menos 1 letra minúscula
  if (!/[a-z]/.test(senha)) return false;
  
  // Pelo menos 1 número
  if (!/[0-9]/.test(senha)) return false;
  
  // Pelo menos 1 caractere especial
  if (!/[!@#$%^&*(),.?":{}|<>]/.test(senha)) return false;
  
  return true;
}

✅ Cadastro Concluído!

Após este passo, o usuário terá seu acesso criado e poderá fazer login normalmente usando CPF e a senha cadastrada.

🔐 Política de Senhas

Recomendações para senhas seguras:

Mínimo de 8 caracteres
Pelo menos 1 letra maiúscula
Pelo menos 1 letra minúscula
Pelo menos 1 número
Pelo menos 1 caractere especial

🔄 Fluxo Completo - Exemplo

async function fluxoPrimeiroAcessoCompleto(dadosCliente, dadosDispositivo) {
  try {
    // Passo 1: Validar dados
    const sessionToken = await iniciarPrimeiroAcesso(
      dadosCliente.cpf,
      dadosCliente.dataNascimento,
      dadosDispositivo
    );

    // Passo 2: Biometria (opcional)
    // const linkBiometria = await solicitarBiometria(sessionToken, consumidorId, lojaId);
    
    // Passo 3: Enviar SMS
    await enviarSMS(sessionToken);
    
    // Aguardar usuário digitar código
    const pinCode = await aguardarCodigoSMS();
    
    // Passo 4: Validar SMS
    await validarSMS(sessionToken, pinCode, dadosDispositivo);
    
    // Passo 5: Perguntas de segurança (se aplicável)
    // await validarPerguntas(sessionToken, respostas);
    
    // Passo 6: Buscar termo
    const termo = await buscarTermo(sessionToken);
    
    // Exibir termo ao usuário
    await exibirTermo(termo);
    
    // Aguardar aceite
    const aceitou = await aguardarAceite();
    
    if (!aceitou) {
      throw new Error('Usuário recusou o termo de aceite');
    }
    
    // Passo 7: Aceitar termo
    await aceitarTermo(sessionToken);
    
    // Passo 8: Criar senha
    const senha = await solicitarSenha();
    await criarSenha(sessionToken, senha);
    
    console.log('✅ Cadastro concluído com sucesso!');
    
    // Redirecionar para tela de login
    navegarParaLogin();
    
  } catch (error) {
    console.error('Erro no cadastro:', error);
    exibirErro(error.message);
  }
}

⚠️ Tratamento de Erros

Código	Descrição	Ação Recomendada
400	Dados inválidos	Verifique CPF, data de nascimento e dados do dispositivo
401	Token expirado	Reinicie o fluxo do início
404	Cliente não encontrado	Verifique se o CPF está correto
409	Cliente já cadastrado	Redirecione para tela de login
422	Código SMS inválido	Solicite novo código ou permita reenvio

📚 Recursos Relacionados

Login - Autenticação de usuários
Troca de Dispositivo - Autorizar novo dispositivo
Recuperar Senha - Redefinir senha esquecida

Última atualização: 03 de Dezembro de 2025

📋 Visão Geral​

Passo 1️⃣: Validar Dados do Cliente​

Endpoint​

Request Body​

Parâmetros​

Resposta de Sucesso​

Exemplo de Código​

Passo 2️⃣: Solicitar Link de Biometria (Opcional)​

Endpoint​

Request Body​

Exemplo de Código​

Passo 3️⃣: Enviar Token SMS​

Endpoint​

Exemplo de Código​

Passo 4️⃣: Validar Token SMS​

Endpoint​

Request Body​

Parâmetros​

Exemplo de Código​

Passo 5️⃣: Validar Perguntas de Segurança (Se Aplicável)​

Endpoint​

Request Body​

Exemplo de Código​

Passo 6️⃣: Buscar Termo de Aceite​

Endpoint​

Exemplo de Resposta​

Exemplo de Código​

Passo 7️⃣: Aceitar Termo​

Endpoint​

Request Body​

Exemplo de Código​

Passo 8️⃣: Criar Senha de Acesso​

Endpoint​

Request Body​

Exemplo de Código​

🔄 Fluxo Completo - Exemplo​

⚠️ Tratamento de Erros​

📚 Recursos Relacionados​

📋 Visão Geral

Passo 1️⃣: Validar Dados do Cliente

Endpoint

Request Body

Parâmetros

Resposta de Sucesso

Exemplo de Código

Passo 2️⃣: Solicitar Link de Biometria (Opcional)

Endpoint

Request Body

Exemplo de Código

Passo 3️⃣: Enviar Token SMS

Endpoint

Exemplo de Código

Passo 4️⃣: Validar Token SMS

Endpoint

Request Body

Parâmetros

Exemplo de Código

Passo 5️⃣: Validar Perguntas de Segurança (Se Aplicável)

Endpoint

Request Body

Exemplo de Código

Passo 6️⃣: Buscar Termo de Aceite

Endpoint

Exemplo de Resposta

Exemplo de Código

Passo 7️⃣: Aceitar Termo

Endpoint

Request Body

Exemplo de Código

Passo 8️⃣: Criar Senha de Acesso

Endpoint

Request Body

Exemplo de Código

🔄 Fluxo Completo - Exemplo

⚠️ Tratamento de Erros

📚 Recursos Relacionados