Open Finance

O Building Block Open Finance permite integrar dados bancários dos clientes via provedores de Open Finance (ex: Pluggy, Belvo). Com ele, sua aplicação pode acessar contas, transações, identidade e mais, de forma segura e padronizada.

Base URL

Ambiente	URL
Staging	https://open-finance.stg.catalisa.app

Conceitos

Provider Config

Configuração de um provedor de Open Finance (ex: Pluggy). Contém as credenciais de API e configurações específicas do provedor.

Item

Representa uma conexão do usuário com uma instituição financeira. Após o usuário autenticar via widget, um Item é criado contendo acesso às contas e transações.

Connector

Uma instituição financeira disponível para conexão (ex: Banco do Brasil, Nubank). Listado a partir do provedor configurado.

Connect Token

Token temporário usado pelo widget frontend para iniciar o fluxo de conexão do usuário com uma instituição financeira.

Fluxo de Integração

1. Configurar provedor — Crie um Provider Config com as credenciais do provedor
2. Gerar connect token — Use o endpoint de connect para gerar um token para o widget
3. Usuário conecta — O widget do provedor autentica o usuário com a instituição
4. Sincronizar item — Após conexão, sincronize o item para obter os dados
5. Consultar dados — Acesse contas, transações e identidade do item

Endpoints

Provider Configs

Método	Endpoint	Descrição	Permissão
POST	/api/v1/provider-configs	Criar configuração	OPENFINANCE_ADMIN
GET	/api/v1/provider-configs	Listar configurações	OPENFINANCE_READ
GET	/api/v1/provider-configs/:id	Obter configuração	OPENFINANCE_READ
PATCH	/api/v1/provider-configs/:id	Atualizar configuração	OPENFINANCE_ADMIN
DELETE	/api/v1/provider-configs/:id	Excluir configuração	OPENFINANCE_ADMIN
POST	/api/v1/provider-configs/:id/set-default	Definir como padrão	OPENFINANCE_ADMIN
POST	/api/v1/provider-configs/:id/test	Testar conexão	OPENFINANCE_ADMIN

Connect

Método	Endpoint	Descrição	Permissão
POST	/api/v1/connect/token	Gerar token de conexão	OPENFINANCE_WRITE

Connectors

Método	Endpoint	Descrição	Permissão
GET	/api/v1/connectors	Listar instituições	OPENFINANCE_READ
GET	/api/v1/connectors/:id	Obter instituição	OPENFINANCE_READ

Items

Método	Endpoint	Descrição	Permissão
POST	/api/v1/items/sync	Sincronizar item	OPENFINANCE_WRITE
GET	/api/v1/items	Listar items	OPENFINANCE_READ
GET	/api/v1/items/:id	Obter item	OPENFINANCE_READ
POST	/api/v1/items/:id/refresh	Atualizar status	OPENFINANCE_WRITE
POST	/api/v1/items/:id/sync-data	Sincronizar dados completos	OPENFINANCE_WRITE
POST	/api/v1/items/:id/link-person	Vincular a pessoa	OPENFINANCE_WRITE
DELETE	/api/v1/items/:id	Excluir item	OPENFINANCE_ADMIN

Accounts e Transactions

Método	Endpoint	Descrição	Permissão
GET	/api/v1/items/:itemId/accounts	Listar contas do item	OPENFINANCE_READ
GET	/api/v1/accounts/:id	Obter conta	OPENFINANCE_READ
GET	/api/v1/accounts/:accountId/transactions	Listar transações	OPENFINANCE_READ
GET	/api/v1/transactions/:id	Obter transação	OPENFINANCE_READ

Identity

Método	Endpoint	Descrição	Permissão
GET	/api/v1/items/:itemId/identity	Obter dados de identidade	OPENFINANCE_READ

Provedores Suportados

Provedor	Tipo	Status
Pluggy	PLUGGY	Disponível
Belvo	BELVO	Em breve

Status do Item

Status	Descrição
PENDING	Conexão iniciada, aguardando sincronização
UPDATING	Dados sendo atualizados
UPDATED	Dados sincronizados com sucesso
LOGIN_ERROR	Erro de autenticação com a instituição
OUTDATED	Dados desatualizados, necessita refresh
WAITING_USER_INPUT	Aguardando ação do usuário (ex: MFA)
WAITING_USER_ACTION	Aguardando ação do usuário na instituição

Tipos de Conta

Tipo	Descrição
CHECKING	Conta corrente
SAVINGS	Conta poupança
CREDIT_CARD	Cartão de crédito
INVESTMENT	Investimento
LOAN	Empréstimo

Tipos de Transação

Tipo	Descrição
CREDIT	Entrada (crédito)
DEBIT	Saída (débito)