⚠️ Regras Técnicas Gerais de Consumo

Ordem de Consumo: Primeiro deve-se chamar a API de RESOURCES para obter os IDs únicos (ex: accountId, creditCardAccountId) antes de chamar os endpoints de detalhamento.

Parâmetros de Data: Para extratos, transações e faturas, utilize os filtros fromBookingDate e toBookingDate para limitar o período de busca.

Status do Consentimento: O consumo de qualquer endpoint acima retornará erro 403 Forbidden caso o consentimento tenha sido revogado ou tenha expirado.

Paginação: É obrigatório o tratamento dos campos meta e links (self, first, next, last) nas respostas para navegar entre grandes volumes de dados.

1. Dados Cadastrais (PF e PJ)

Retorna as informações de identificação e qualificação do cliente, fundamentais para processos de KYC (Know Your Customer) e Onboarding.

• Identificação: Nome completo, data de nascimento/constituição, CPF/CNPJ, filiação e nacionalidade.
• Qualificação: Escolaridade, profissão e renda informada (PF); Faturamento anual e data de fundação (PJ).
• Contactos: Endereços completos (logradouro, número, CEP), endereços de e-mail e números de telefone.
• Vínculos (PJ): Lista de sócios e administradores com seus respectivos poderes.

2. Contas (Depósito, Poupança e Pagamento)

Acesso a informações sobre contas correntes, poupanças e contas de pagamento pré-pagas.

• Informações de Conta: Tipo de conta, número da agência, número da conta e dígito verificador.
• Saldos: Saldo disponível em tempo real, valor bloqueado e limite de cheque especial disponível.
• Transações (Extrato): Histórico de movimentações com descrição da natureza (PIX, TED, DOC, Tarifas), data de agendamento e data de liquidação.

3. Cartão de Crédito

Fornece uma visão detalhada do uso de cartões de crédito e limites associados.

• Informações do Cartão: Bandeira, nome do titular e status do cartão.
• Limites: Limite total de crédito, limite utilizado e limite disponível para novas compras.
• Faturas: Detalhamento de faturas (abertas, fechadas e pagas), valor total, pagamento mínimo e datas de vencimento.
• Transações: Lista de compras realizadas, categoria do estabelecimento (MCC), valor e data da transação.

4. Operações de Crédito

Abrange contratos de empréstimos, financiamentos, adiantamentos de recebíveis e direitos creditórios.

• Contratos: Detalhes do contrato, data de assinatura e modalidade (ex: Crédito Pessoal, Imobiliário).
• Taxas e Custos: Taxa de juros efetiva (mensal/anual), Custo Efetivo Total (CET) e indexadores.
• Parcelas: Valor das prestações, quantidade total de parcelas, saldo devedor e cronograma de pagamentos.

5. Investimentos

Permite a visualização consolidada da carteira de ativos financeiros do cliente.

• Renda Fixa e Variável: Dados sobre CDBs, LCIs, LCAs, Tesouro Direto, Ações e ETFs.
• Fundos de Investimento: Quantidade de cotas, valor da cota no dia e CNPJ do fundo administrador.
• Previdência: Detalhes de planos PGBL e VGBL, aportes e saldos acumulados.
• Saldos e Posições: Valor de mercado atualizado de cada ativo na carteira.

6. Câmbio

Consumo de informações sobre operações de compra e venda de moedas estrangeiras.

• Histórico de Operações: Detalhamento de compras e vendas de divisas.
• Taxas e Valores: Taxa de câmbio aplicada e o VET (Valor Efetivo Total), que inclui impostos (IOF) e tarifas.
• Entrega: Informação sobre como o recurso foi transacionado (espécie, cartão de viagem ou transferência internacional).

⚠️ Regras Técnicas Gerais de Consumo

1. Ordem de Consumo: Primeiro deve-se chamar a API de RESOURCES para obter os IDs únicos (ex: accountId, creditCardAccountId) antes de chamar os endpoints de detalhamento.
2. Parâmetros de Data: Para extratos, transações e faturas, utilize os filtros fromBookingDate e toBookingDate para limitar o período de busca.
3. Status do Consentimento: O consumo de qualquer endpoint acima retornará erro 403 Forbidden caso o consentimento tenha sido revogado ou tenha expirado.
4. Paginação: É obrigatório o tratamento dos campos meta e links (self, first, next, last) nas respostas para navegar entre grandes volumes de dados.

Guia de Rate-Limits e Estratégia de Consumo (Open Finance)

Para garantir a estabilidade do ecossistema e evitar o bloqueio de acessos, a Celcoin segue as diretrizes de limites operacionais do Open Finance Brasil. O consumo dos endpoints deve ser planeado para respeitar as quotas mensais por consentimento.

1. Tabela de Limites Operacionais

🛡️ Transactions (Histórico de Longo Prazo)

Este é o endpoint mais sensível do ecossistema. Um erro de lógica aqui pode esgotar a quota mensal em poucos segundos.

• Comportamento: Permite consultar até 12 meses de histórico.
• Regra de Ouro: Deve ser utilizado apenas para a carga inicial de dados.
• Paginação Inteligente: Ao realizar a consulta, utilize o parâmetro pagination-key para navegar pelas páginas de resultados. A paginação de uma mesma consulta não conta contra o limite operacional de 4 chamadas/mês.
• Ação: Após concluir a paginação e obter todo o histórico, armazene os dados e não volte a utilizar esta rota para este consentimento no mês vigente.

🔄 Transaction-current (Manutenção Diária)

Para manter o extrato do cliente atualizado sem consumir o limite do histórico:

• Comportamento: Utilize este endpoint com filtros curtos (ex: últimos 2 a 7 dias).
• Vantagem: Com 240 chamadas disponíveis por mês, é possível realizar múltiplas consultas diárias para identificar novos lançamentos e alimentar a sua base de dados de forma incremental.

💾 Accounts (Enriquecimento de Base)

Não é recomendado o pooling (consultas recorrentes) para dados de conta.

• Estratégia: Como o número da agência, conta e tipo de conta raramente mudam, realize a chamada apenas uma vez após a autorização do consentimento e persista os dados.

Recomendações Técnicas de Implementação

1. Persistência Obrigatória: O modelo de consumo do Open Finance exige que a aplicação tenha a sua própria base de dados (cache/DB). As APIs não devem ser usadas como fonte de consulta "em tempo real" para cada clique do utilizador.
2. Tratamento de Erro 429: Caso o limite seja atingido, a API retornará o status 429 Too Many Requests. A aplicação deve estar preparada para interromper as chamadas para aquele consentimento e registar o log de quota excedida.
3. Filtros de Data: Utilize sempre os campos fromBookingDate e toBookingDate para garantir que está a solicitar apenas o intervalo de dados estritamente necessário, otimizando o payload e o processamento.
4. Retry Exponencial: Em caso de falhas de rede ou throttling, utilize algoritmos de Exponential Backoff para tentar novamente a conexão.