Openi DeveloperDeveloper
Bank account

Contas Bancárias

Documentação dos endpoints para gerenciamento de contas bancárias.

Leia transações com IA

Implemente a leitura de contas e transações da Openi Open Finance neste projeto.

## Contexto
- Base URL: https://of.openi.com.br/v1 (os caminhos abaixo são relativos a ela). Header `Authorization: Bearer $OPENI_API_KEY`, lido da variável de ambiente `OPENI_API_KEY`, só no backend.
- Doc: https://developer.openi.com.br/docs/openfinance/bank-account/list-accounts.md e https://developer.openi.com.br/docs/openfinance/bank-account/list-transactions.md

## Tarefa
1. Dado um `itemId` com status `synced`, liste as contas com `GET /items/{itemId}/accounts`.
2. Para cada conta, pagine as transações com `GET /items/{itemId}/accounts/{accountId}/transactions?page=1&limit=50` até a última página. Filtros opcionais: `from` e `to` (ISO 8601).
3. Persista as transações com upsert pelo `id`, para que reprocessar não duplique.
4. Ao receber o webhook `TRANSACTIONS_CREATED` (`data` traz `itemId`, `accountId`, `accountType` e `transactionIds`), busque só essas transações com o filtro `ids` (`?ids=<id1>&ids=<id2>`), em vez de reler tudo. Se `accountType` for `CREDIT_CARD`, use `GET /items/{itemId}/credit-cards/{accountId}/transactions`.
5. Ao receber `TRANSACTIONS_DELETED`, apague da base os `transactionIds` recebidos; em `TRANSACTIONS_UPDATED`, rebusque esses ids com `?ids=` e atualize.

## Critério de pronto
Com um item de sandbox (CPF `111.444.777-35`), mostre o total de transações por conta.

Endpoints Disponíveis

Tipos de Dados

Subtipos de Conta

  • CHECKING_ACCOUNT: Conta corrente
  • SAVINGS_ACCOUNT: Conta poupança

Status da Transação

  • PENDING: Pendente
  • POSTED: Processada

Tipo de Transação

  • CREDIT: Crédito
  • DEBIT: Débito

Tipo de Operação (operationType)

Natureza específica da operação bancária. Pode ser null quando não informado pelo provedor.

  • TED: Transferência Eletrônica Disponível
  • DOC: Documento de Ordem de Crédito
  • PIX: Transferência via Pix
  • TRANSFERENCIA_MESMA_INSTITUICAO: Transferência entre contas da mesma instituição
  • BOLETO: Pagamento de boleto
  • CONVENIO_ARRECADACAO: Convênio de arrecadação
  • PACOTE_TARIFA_SERVICOS: Pacote de tarifa de serviços
  • TARIFA_SERVICOS_AVULSOS: Tarifa de serviços avulsos
  • FOLHA_PAGAMENTO: Folha de pagamento
  • DEPOSITO: Depósito
  • SAQUE: Saque
  • CARTAO: Operação com cartão
  • ENCARGOS_JUROS_CHEQUE_ESPECIAL: Encargos e juros de cheque especial
  • RENDIMENTO_APLIC_FINANCEIRA: Rendimento de aplicação financeira
  • PORTABILIDADE_SALARIO: Portabilidade de salário
  • RESGATE_APLIC_FINANCEIRA: Resgate de aplicação financeira
  • OPERACAO_CREDITO: Operação de crédito
  • OUTROS: Outros tipos de operação

Observações

  • O campo accountSuffix está presente em algumas contas poupança
  • As transações incluem dados detalhados do pagador e recebedor quando disponíveis
  • Valores monetários são retornados como string formatada
  • A paginação é obrigatória no endpoint de transações para otimizar a performance

On this page