Pular para o conteúdo principal

Jornada de Alteração de PIN

Diagrama do Fluxo​

Representação documental do fluxo de alteração de PIN com dupla validação (e-mail + SMS), conforme os passos descritos nesta jornada.

Esta página detalha o processo completo para alterar seu PIN de acesso usando a API de Segurança da Finway, garantindo que você possa fazer essa mudança de forma segura e eficiente.

Headers Obrigatórios​

Todos os endpoints requerem os seguintes headers:

X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json
Passo 1: Gerar Challenge Email para Alteração de PIN

Endpoint: POST /security/me/pin/mail/otp/challenge​

Gera um código OTP via email para iniciar o processo de alteração de PIN.

Request​

POST /security/me/pin/mail/otp/challenge
X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json

Response (200 OK)​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 3
}

Funcionalidades​

  • Geração de código de 6 dígitos enviado por email
  • Token temporário para próximas etapas do processo
  • Tempo de expiração configurado (300 segundos)
  • Controle de tentativas (máximo 3 tentativas)
informação

Dica: O token retornado será necessário para validar o OTP no próximo passo.

Passo 2: Validar OTP Email para Alteração de PIN

Endpoint: POST /security/me/pin/mail/otp/validate​

Valida o código OTP recebido via email para alteração de PIN.

Request​

POST /security/me/pin/mail/otp/validate
X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json

Request Body​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456",
  "document": "12345678900"
}

Response (200 OK)​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 2
}

Validações​

  • Código deve ter 6 dígitos numéricos
  • Token deve ser válido e não expirado
  • Máximo de 3 tentativas de validação
  • CPF deve corresponder ao usuário autenticado
informação

Importante: Após 3 tentativas incorretas, será necessário gerar um novo challenge.

Passo 3: Gerar Challenge SMS para Alteração de PIN

Endpoint: POST /security/me/pin/sms/otp/challenge​

Gera um código OTP via SMS para dupla validação do processo de alteração de PIN.

Request​

POST /security/me/pin/sms/otp/challenge
X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json

Request Body​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456",
  "document": "12345678900"
}

Response (200 OK)​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 3
}

Funcionalidades​

  • Código de 6 dígitos enviado via SMS
  • Token temporário atualizado para próxima etapa
  • Rate limiting para prevenção de spam
  • Integração com provedores de SMS confiáveis
informação

Nota: O SMS pode levar até 3 minutos para chegar, dependendo da operadora.

Passo 4: Validar OTP SMS para Alteração de PIN

Endpoint: POST /security/me/pin/sms/otp/validate​

Valida o código OTP recebido via SMS para confirmação final da alteração.

Request​

POST /security/me/pin/sms/otp/validate
X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json

Request Body​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "123456",
  "document": "12345678900"
}

Response (200 OK)​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300,
  "attempts": 2
}

Validações de Segurança​

  • Dupla confirmação (Email + SMS)
  • Tokens sequenciais validados
  • Logs de segurança atualizados
  • Notificação de tentativas suspeitas
informação

Segurança: Este passo confirma que você tem acesso tanto ao email quanto ao telefone cadastrado.

Passo 5: Alterar PIN

Endpoint: POST /security/me/pin/validate​

Finaliza o processo alterando o PIN após validação completa dos OTPs.

Request​

POST /security/me/pin/validate
X-BuildersBank-Authorization: {jwt_token}
Content-Type: application/json

Request Body​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "credential": "1234",
  "oldCredential": "4321"
}

Response (200 OK)​

HTTP/1.1 200 OK
Content-Type: application/json

Critérios do Novo PIN​

  • 4 dígitos numéricos
  • Não pode ser sequencial (1234, 4321)
  • Não pode ser repetitivo (1111, 2222)
  • Diferente do PIN anterior

Processo de Alteração​

  1. Validação final do token
  2. Criptografia do novo PIN
  3. Atualização no banco de dados
  4. Invalidação de tokens temporários
  5. Notificações de segurança enviadas
informação

Sucesso: PIN alterado com sucesso. Faça logout e login novamente para testar.

Códigos de Erro e Troubleshooting

Códigos de Erro Comuns​

400 - Bad Request​

{
  "error": "VALIDATION_ERROR",
  "message": "Erro de validação nos campos",
  "violations": [
    {
      "field": "code",
      "message": "Código deve conter 6 dígitos"
    }
  ]
}

401 - Unauthorized​

{
  "error": "UNAUTHORIZED",
  "message": "Token de acesso inválido ou expirado"
}

403 - Forbidden​

{
  "error": "FORBIDDEN",
  "message": "Token válido, mas não possui o escopo 'accounts-consumer'"
}

Troubleshooting​

Token Expirado​

  • Problema: Token inválido ou expirado
  • Solução: Reiniciar o processo do Passo 1

Código SMS não Recebido​

  • Problema: SMS não chegou
  • Solução: Aguardar 3 minutos ou tentar novamente

Tentativas Esgotadas​

  • Problema: Máximo de tentativas atingido
  • Solução: Gerar um novo challenge
informação

Dica: Todos os tokens têm TTL (Time To Live) configurado para segurança. Se um processo demorar muito, será necessário recomeçar.

Segurança e Boas Práticas​

  • Sempre use HTTPS para todas as requisições
  • Não compartilhe tokens entre sessões ou dispositivos
  • Implemente retry logic com backoff exponencial
  • Log todas as operações para auditoria
  • Monitore rate limits para evitar bloqueios