Jornada de Consulta de Saldo e Extrato

Esta jornada apresenta o fluxo completo para que usuários autenticados possam consultar seu saldo atual e visualizar o histórico de transações de suas contas.

1. Autenticação

Antes de consultar saldo ou extrato, é necessário estar autenticado com um token válido.

Headers Obrigatórios:

X-BuildersBank-Authorization: Token de sessão do usuário

Escopos Necessários:

accounts: Para consultar saldo
transactions: Para consultar extrato e detalhes das transações

Exemplo de Header:

X-BuildersBank-Authorization: your-session-token-here

2. Consulta de Saldo e Dados da Conta

O primeiro passo é consultar o saldo e dados completos da conta para exibir as informações financeiras e de perfil do usuário.

Endpoint: GET /holders/me/accounts

Requisição:

GET https://api.buildersbank.com.br/holders/me/accounts
X-BuildersBank-Authorization: your-session-token-here

Resposta de Sucesso (200):

{
  "account": {
    "accountIdentification": "0001-123456-7",
    "accountStatus": "ACTIVE",
    "blockedReason": null,
    "profilePictureLink": "https://storage.buildersbank.com.br/profiles/picture.jpg",
    "settlementAccount": {
      "branch": "0001",
      "account": "123456-7"
    },
    "holder": {
      "name": "Tercio",
      "document": "123.456.789-00"
    },
    "paymentsMethod": {
      "hasCard": true,
      "cardStatus": "ACTIVE"
    },
    "showPixIntroduction": false
  },
  "globalBalance": 2500.75
}

Campos da Resposta:

Account:

accountIdentification: Identificação da conta
accountStatus: Status da conta (ACTIVE, BLOCKED, PENDING_ACTIVATION, CLOSED)
blockedReason: Motivo do bloqueio (se aplicável)
profilePictureLink: URL da foto de perfil do usuário
settlementAccount: Dados bancários (agência e conta)
holder: Dados do titular (nome e documento)
paymentsMethod: Informações sobre cartões
showPixIntroduction: Flag para exibir introdução ao PIX

Balance:

globalBalance: Saldo global da conta em BRL

Possíveis Erros:

401: Token ausente ou inválido
403: Token válido mas sem escopo accounts

3. Consulta de Extrato

Após consultar o saldo, o usuário pode visualizar seu histórico de transações com filtros por período.

Endpoint: GET /holders/me/accounts/main/transactions

Parâmetros de Query:

page (opcional): Número da página (padrão: 1)
size (opcional): Itens por página (padrão: 20)
startDate (opcional): Data início (ISO 8601)
endDate (opcional): Data fim (ISO 8601)

Exemplo de Requisição:

GET https://api.buildersbank.com.br/holders/me/accounts/main/transactions?page=1&size=10&startDate=2023-10-01T00:00:00Z&endDate=2023-10-31T23:59:59Z
X-BuildersBank-Authorization: your-session-token-here

Resposta de Sucesso (200):

{
  "content": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "date": "2023-10-27T10:30:00Z",
      "description": "Transferência para João da Silva",
      "amount": -50.00,
      "type": "DEBIT",
      "status": "COMPLETED"
    }
  ],
  "page": 1,
  "size": 10,
  "totalPages": 5,
  "totalElements": 98
}

Tipos de Transação:

CREDIT: Entrada de dinheiro (valor positivo)
DEBIT: Saída de dinheiro (valor negativo)

Status Possíveis:

COMPLETED: Transação finalizada
PENDING: Aguardando processamento
CANCELED: Transação cancelada

Resposta Alternativa:

204: Nenhuma transação encontrada no período

4. Detalhes da Transação

Para obter informações completas sobre uma transação específica, use o ID da transação obtido na consulta do extrato.

Endpoint: GET /holders/me/accounts/main/transactions/{id}

Parâmetros:

id (path, obrigatório): ID da transação
type (query, obrigatório): Tipo da transação para otimizar busca

Tipos Válidos:

CASH_IN: Entrada de dinheiro
CASH_OUT: Saída de dinheiro
TRANSFER: Transferência
PAYMENT: Pagamento

Exemplo de Requisição:

GET https://api.buildersbank.com.br/holders/me/accounts/main/transactions/a1b2c3d4-e5f6-7890-1234-567890abcdef?type=TRANSFER
X-BuildersBank-Authorization: your-session-token-here

Resposta de Sucesso (200):

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "date": "2023-10-27T10:30:00Z",
  "description": "Transferência para João da Silva",
  "amount": -50.00,
  "type": "DEBIT",
  "status": "COMPLETED",
  "senderName": "Maria Oliveira",
  "senderDocument": "98765432100",
  "recipientName": "João da Silva",
  "recipientDocument": "12345678900",
  "bankName": "BuildersBank",
  "receiptUrl": "https://storage.buildersbank.com.br/receipts/a1b2c3d4-e5f6..."
}

Informações Adicionais nos Detalhes:

Dados completos do remetente e destinatário
Nome do banco envolvido
URL para download do comprovante

5. Tratamento de Erros

É importante implementar tratamento adequado para todos os possíveis erros da API.

Códigos de Erro Comuns:

401 - Não Autorizado

Token ausente ou inválido
Necessário fazer login novamente

403 - Proibido

Token válido mas sem escopo necessário
Verificar se tem permissões accounts ou transactions

404 - Não Encontrado

Transação específica não existe
Verificar se o ID está correto

Implementação Recomendada:

try {
  const response = await fetch(url, {
    headers: {
      'X-BuildersBank-Authorization': token
    }
  });

  if (response.status === 401) {
    // Redirecionar para login
    redirectToLogin();
  } else if (response.status === 403) {
    // Mostrar mensagem de permissão insuficiente
    showPermissionError();
  } else if (response.status === 404) {
    // Recurso não encontrado
    showNotFoundError();
  }

  const data = await response.json();
  return data;
} catch (error) {
  // Tratar erros de rede
  handleNetworkError(error);
}

6. Fluxo de Implementação

Sequência Recomendada de Implementação:

Verificar Autenticação
- Validar se o token está presente
- Verificar escopos necessários
Carregar Dados da Conta e Saldo
- Fazer requisição para /holders/me/accounts
- Exibir informações completas da conta na interface
- Mostrar saldo global formatado
- Exibir dados do titular e status da conta
Carregar Extrato
- Fazer requisição para /holders/me/accounts/main/transactions
- Implementar paginação
- Adicionar filtros de data opcionais
Implementar Detalhes
- Permitir clique nas transações
- Carregar detalhes completos
- Mostrar opção de download do comprovante
Adicionar Funcionalidades Extras
- Filtros por tipo de transação
- Busca por descrição
- Export do extrato
- Exibir foto de perfil do usuário
- Mostrar introdução PIX se necessário

Exemplo de Fluxo em React:

const [accountData, setAccountData] = useState(null);
const [transactions, setTransactions] = useState([]);

useEffect(() => {
  // Carregar dados da conta e saldo
  fetchAccountData();
  // Carregar extrato inicial
  fetchTransactions();
}, []);

const fetchAccountData = async () => {
  const response = await api.get('/holders/me/accounts');
  setAccountData(response.data);
};

const fetchTransactions = async (filters = {}) => {
  const response = await api.get('/holders/me/accounts/main/transactions', {
    params: filters
  });
  setTransactions(response.data.content);
};

// Renderizar dados da conta
const renderAccountInfo = () => {
  if (!accountData) return null;

  const { account, globalBalance } = accountData;

  return (
    <div>
      <h2>Saldo: R$ {globalBalance.toFixed(2)}</h2>
      <p>Conta: {account.accountIdentification}</p>
      <p>Titular: {account.holder.name}</p>
      <p>Status: {account.accountStatus}</p>
      {account.profilePictureLink && (
        <img src={account.profilePictureLink} alt="Foto de perfil" />
      )}
    </div>
  );
};

Resumo

Esta jornada cobre todo o fluxo de consulta de saldo e extrato, desde a autenticação até a visualização de detalhes das transações. A implementação agora inclui dados completos da conta como informações do titular, status da conta, dados bancários e configurações de cartão, proporcionando uma experiência mais rica e informativa para o usuário.

Resumo​

Resumo