Pular para o conteúdo principal

Jornada de Gestão de Conta e Perfis

Esta documentação apresenta o fluxo de gestão de contas e perfis no sistema Finway, focando nas operações fundamentais de consulta e atualização de dados da conta e perfil do usuário.

Visão Geral​

A jornada de gestão de conta e perfis permite que usuários já onboardados realizem operações básicas de gestão da conta, incluindo:

  • Consulta de dados e status da conta
  • Verificação de saldo atual
  • Atualização de dados pessoais
  • Gestão de documentos e endereço
  • Configuração de preferências de notificação
1. Consulta de Conta e Saldo

Recuperar Saldo e Status da Conta​

Endpoint: GET /holders/{document}/accounts

Este endpoint deve ser chamado ANTES e DEPOIS de ativar a conta no Backoffice para verificar o status atual.

Exemplo de Requisição​

curl --location 'https://api-dev.finway.com.br/api/bank-services/holders/60483453000148/accounts' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX'

Parâmetros​

  • {document}: CPF/CNPJ do titular ou "me" para usuário autenticado
  • X-buildersbank-Authorization: Token JWT de autenticação
  • client_id: Identificador do cliente

Resposta​

{
  "account": {
    "id": "acc_123456789",
    "accountIdentification": "12345-6",
    "holder": {
      "name": "João Silva Santos",
      "document": "12345678901",
      "email": "joao.silva@email.com"
    },
    "accountStatus": "ACTIVE",
    "provider": "DOCK"
  },
  "globalBalance": 1250.75,
  "menus": [
    {
      "id": "pix",
      "name": "PIX",
      "enabled": true,
      "order": 1
    },
    {
      "id": "transfer",
      "name": "Transferências",
      "enabled": true,
      "order": 2
    },
    {
      "id": "statements",
      "name": "Extratos",
      "enabled": true,
      "order": 3
    }
  ]
}

Status da Conta​

  • ACTIVE: Conta ativa e operacional
  • INACTIVE: Conta inativa
  • BLOCKED: Conta bloqueada
  • PENDING: Conta pendente de ativação
  • CANCELLED: Conta cancelada

Campos Retornados​

  • account.id: Identificador único da conta
  • account.accountIdentification: Número da conta formatado
  • account.holder: Dados do titular da conta
  • account.accountStatus: Status atual da conta
  • account.provider: Provedor de serviços bancários
  • globalBalance: Saldo atual da conta (em centavos)
  • menus: Lista de funcionalidades disponíveis para o usuário
2. Atualização de Dados da Conta

Atualizar Dados da Conta​

Endpoint: PUT /holders/{document}/accounts

Atualiza dados de ativação da conta, incluindo informações pessoais do portador.

Exemplo de Requisição​

curl --location --request PUT 'https://api-dev.finway.com.br/api/bank-services/holders/me/accounts' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX' \
--header 'Content-Type: application/json' \
--data '{
    "name": "João Silva Santos",
    "motherName": "Maria Santos Silva",
    "birthDate": "1990-05-15"
}'

Campos Obrigatórios​

  • name: Nome completo do portador da conta
  • motherName: Nome completo da mãe
  • birthDate: Data de nascimento (formato YYYY-MM-DD)

Atualização Parcial da Conta​

Endpoint: PATCH /holders/{document}/accounts

Executa atualizações parciais nas informações da conta, como foto do perfil ou metadados.

Exemplo de Requisição​

curl --location --request PATCH 'https://api-dev.finway.com.br/api/bank-services/holders/me/accounts' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX' \
--header 'Content-Type: application/json' \
--data '{
    "profilePictureLink": "https://storage.googleapis.com/profile-pics/user123_new.jpg"
}'
3. Gerenciamento de Endereço

Obter Endereço da Conta​

Endpoint: GET /holders/{document}/accounts/address

Recupera as informações atuais de endereço do portador da conta.

Exemplo de Requisição​

curl --location 'https://api-dev.finway.com.br/api/bank-services/holders/me/accounts/address' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX'

Resposta​

{
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01234-567",
    "country": "Brasil"
  },
  "updatedAt": "2023-11-15T10:30:00Z"
}
4. Upload de Documentos

Upload de Documento (V2)​

Endpoint: POST /v2/holders/{document}/accounts/documents

Faz upload de documentos usando payload JSON com conteúdo codificado em base64.

Exemplo de Requisição​

curl --location 'https://api-dev.finway.com.br/api/bank-services/v2/holders/me/accounts/documents' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX' \
--header 'Content-Type: application/json' \
--data '{
    "documentType": "CPF_FRONT",
    "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
    "fileName": "cpf_frente.jpg",
    "mimeType": "image/jpeg"
}'

Tipos de Documento Aceitos​

  • CPF_FRONT: Frente do CPF
  • CPF_BACK: Verso do CPF
  • RG_FRONT: Frente do RG
  • RG_BACK: Verso do RG
  • CNH_FRONT: Frente da CNH
  • CNH_BACK: Verso da CNH
  • PROOF_OF_INCOME: Comprovante de renda
  • PROOF_OF_ADDRESS: Comprovante de endereço
  • SELFIE: Selfie do usuário
5. Preferências de Notificação

Obter Preferências de Notificação​

Endpoint: GET /holders/{document}/notifications/preferences

Recupera as preferências atuais de notificação do usuário.

Exemplo de Requisição​

curl --location 'https://api-dev.finway.com.br/api/bank-services/holders/me/notifications/preferences' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX'

Atualizar Preferências de Notificação​

Endpoint: PUT /holders/{document}/notifications/preferences

Atualiza as preferências de notificação do usuário.

Exemplo de Requisição​

curl --location --request PUT 'https://api-dev.finway.com.br/api/bank-services/holders/me/notifications/preferences' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX' \
--header 'Content-Type: application/json' \
--data '{
    "preferences": [
        {
            "notificationType": "EMAIL",
            "category": "TRANSACTION",
            "enabled": true
        },
        {
            "notificationType": "SMS",
            "category": "SECURITY",
            "enabled": true
        }
    ]
}'

Tipos de Notificação​

  • EMAIL: Notificações por email
  • SMS: Notificações por SMS
  • PUSH: Notificações push
  • IN_APP: Notificações no aplicativo

Categorias de Notificação​

  • TRANSACTION: Notificações de transação
  • SECURITY: Alertas de segurança
  • MARKETING: Comunicações de marketing
  • ACCOUNT: Atualizações da conta
  • PIX: Notificações PIX
6. Integração com Backoffice

Ativação de Conta​

O endpoint de consulta de conta é essencial no processo de ativação via Backoffice:

Fluxo de Ativação​

  1. Antes da Ativação: Consultar status atual (geralmente PENDING)
  2. Ativar no Backoffice: Processo administrativo de ativação
  3. Após a Ativação: Consultar novamente para confirmar status ACTIVE

Exemplo de Verificação​

# 1. Verificar status antes da ativação
curl --location 'https://api-dev.finway.com.br/api/bank-services/holders/60483453000148/accounts' \
--header 'X-buildersbank-Authorization: {token}' \
--header 'client_id: XXX'

# Resultado esperado: "accountStatus": "PENDING"

# 2. Após ativação no Backoffice, verificar novamente
# Resultado esperado: "accountStatus": "ACTIVE"

Sincronização de Dados​

A consulta de conta também serve para sincronizar dados entre sistemas:

Dados Sincronizados​

  • Status atual da conta
  • Saldo atualizado
  • Menus e funcionalidades disponíveis
  • Informações do titular
  • Configurações da conta

Considerações de Segurança​

Autenticação​

  • Todas as operações requerem token JWT válido no header X-buildersbank-Authorization
  • Token de cliente válido no header client_id
  • Tokens têm TTL limitado e devem ser renovados periodicamente

Controle de Acesso​

  • Usuários só podem consultar suas próprias contas
  • Parâmetro {document} deve corresponder ao usuário autenticado ou usar "me"
  • Tentativas de acesso não autorizado são registradas

Proteção de Dados​

  • Informações sensíveis são mascaradas quando necessário
  • Logs de acesso são mantidos para auditoria
  • Dados pessoais seguem LGPD

Códigos de Status HTTP​

  • 200 OK: Consulta realizada com sucesso
  • 401 Unauthorized: Token inválido ou expirado
  • 403 Forbidden: Acesso negado ao recurso
  • 404 Not Found: Conta não encontrada
  • 500 Internal Server Error: Erro interno do servidor

Próximos Passos​

Após verificar o status da conta e confirmar que está ativa, o usuário pode:

  • Acessar funcionalidades PIX (ver documentação específica)
  • Consultar extratos e transações (ver documentação específica)
  • Gerar relatórios de renda através do endpoint de income-report
  • Gerenciar documentos legais através dos endpoints de documentos