BaaS (Banking as a Service)

O Building Block BaaS fornece funcionalidades completas de serviços bancários na Catalisa Platform, incluindo contas bancárias, transferências, Pix, boletos, extratos e conciliação.

Visão Geral

O BaaS é um módulo tenant-scoped, ou seja, requer um token com organizationId. Ele é responsável por:

Contas Bancárias (Bank Accounts) — abertura e gestão de contas digitais
Transferências (Transfers) — TED/DOC entre contas
Pix — envio, recebimento, chaves Pix e QR Code
Boletos — emissão, consulta e cancelamento de boletos bancários
Extrato (Statements) — consulta de movimentações financeiras
Conciliação (Reconciliation) — importação e matching de lançamentos
Provedores Bancários (Bank Providers) — configuração de provedores integrados

Base URL

Staging:

https://baas.stg.catalisa.app

Produção:

https://baas.catalisa.app

Recursos

Recurso	Descrição
Contas Bancárias	Abertura e gestão de contas digitais
Transferências	TED/DOC entre contas bancárias
Pix	Envio, recebimento, chaves e QR Code
Boletos	Emissão e gestão de boletos bancários
Extrato	Consulta de movimentações
Conciliação	Importação e matching de lançamentos
Provedores	Configuração de provedores bancários

Permissões

Permissão	Descrição
`BAAS_ACCOUNTS_CREATE`	Criar contas bancárias
`BAAS_ACCOUNTS_READ`	Listar e visualizar contas
`BAAS_ACCOUNTS_UPDATE`	Atualizar contas
`BAAS_ACCOUNTS_CLOSE`	Encerrar contas
`BAAS_TRANSFERS_CREATE`	Criar transferências TED/DOC
`BAAS_TRANSFERS_READ`	Listar e visualizar transferências
`BAAS_PIX_SEND`	Enviar pagamentos Pix
`BAAS_PIX_READ`	Listar e visualizar transações Pix
`BAAS_PIX_KEYS_CREATE`	Registrar chaves Pix
`BAAS_PIX_KEYS_READ`	Listar chaves Pix
`BAAS_PIX_KEYS_DELETE`	Excluir chaves Pix
`BAAS_PIX_QRCODE_CREATE`	Gerar QR Codes Pix
`BAAS_BOLETOS_CREATE`	Emitir boletos
`BAAS_BOLETOS_READ`	Listar e visualizar boletos
`BAAS_BOLETOS_CANCEL`	Cancelar boletos
`BAAS_STATEMENTS_READ`	Consultar extrato
`BAAS_RECONCILIATION_CREATE`	Importar conciliação
`BAAS_RECONCILIATION_READ`	Visualizar conciliação
`BAAS_PROVIDERS_CREATE`	Configurar provedores
`BAAS_PROVIDERS_READ`	Listar provedores
`BAAS_PROVIDERS_UPDATE`	Atualizar provedores
`BAAS_PROVIDERS_DELETE`	Excluir provedores

Exemplo Rápido

Fluxo completo para abrir uma conta e realizar um Pix:

// 1. Configurar provedor bancário
const providerResponse = await fetch('https://baas.stg.catalisa.app/baas/api/v1/providers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'providers',
      attributes: {
        name: 'Banco Principal',
        code: 'BANK_001',
        type: 'BANKING',
        status: 'ACTIVE',
        credentials: {
          clientId: 'seu-client-id',
          clientSecret: 'seu-client-secret',
          environment: 'sandbox',
        },
      },
    },
  }),
});

const { data: provider } = await providerResponse.json();

// 2. Abrir conta bancária
const accountResponse = await fetch('https://baas.stg.catalisa.app/baas/api/v1/accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'accounts',
      attributes: {
        providerId: provider.id,
        holderName: 'Empresa ABC Ltda',
        holderDocument: '12.345.678/0001-90',
        holderDocumentType: 'CNPJ',
        type: 'CHECKING',
      },
    },
  }),
});

const { data: account } = await accountResponse.json();

// 3. Registrar chave Pix
const pixKeyResponse = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-keys',
      attributes: {
        accountId: account.id,
        keyType: 'CNPJ',
        keyValue: '12345678000190',
      },
    },
  }),
});

const { data: pixKey } = await pixKeyResponse.json();

// 4. Enviar Pix
const pixResponse = await fetch('https://baas.stg.catalisa.app/baas/api/v1/pix/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'pix-payments',
      attributes: {
        accountId: account.id,
        amount: 1500.00,
        recipientKeyType: 'CPF',
        recipientKeyValue: '12345678901',
        description: 'Pagamento fornecedor',
      },
    },
  }),
});

const { data: pix } = await pixResponse.json();
console.log(`Pix enviado: ${pix.id}`);
console.log(`Status: ${pix.attributes.status}`);
console.log(`E2E ID: ${pix.attributes.e2eId}`);

Arquitetura

Componentes do BaaS

O BaaS é composto pelos seguintes componentes:

Gestão de Contas:

Bank Accounts (Contas Bancárias)
- type: CHECKING, SAVINGS, PAYMENT
- status: PENDING, ACTIVE, BLOCKED, CLOSED
- holderName: Nome do titular
- holderDocument: CPF/CNPJ do titular
- Vinculada a um provedor bancário

Movimentações:

Transfers (Transferências TED/DOC)
- type: TED, DOC
- status: PENDING, PROCESSING, COMPLETED, FAILED, REVERSED
- Suporta agendamento e transferências imediatas
Pix
- Envio e recebimento instantâneo
- Gestão de chaves Pix (CPF, CNPJ, EMAIL, PHONE, EVP)
- Geração de QR Code estático e dinâmico
- status: PENDING, PROCESSING, COMPLETED, FAILED, REVERSED
Boletos
- Emissão de boletos registrados
- status: PENDING, REGISTERED, PAID, OVERDUE, CANCELED
- Suporta juros, multa e desconto

Consultas:

Statements (Extrato)
- Movimentações por período
- Filtros por tipo, valor e data
- Saldos: abertura, fechamento e disponível
Reconciliation (Conciliação)
- Importação de arquivos de retorno bancário
- Matching automático de lançamentos
- status: PENDING, PROCESSING, COMPLETED, PARTIALLY_MATCHED, FAILED

Infraestrutura:

Bank Providers (Provedores Bancários)
- Configuração de credenciais do provedor
- Suporte a múltiplos provedores simultâneos
- status: ACTIVE, INACTIVE, SUSPENDED

Conceitos Importantes

Status da Conta Bancária

Status	Descrição
`PENDING`	Conta em processo de abertura
`ACTIVE`	Conta ativa, operacional
`BLOCKED`	Conta bloqueada temporariamente
`CLOSED`	Conta encerrada

Tipos de Conta

Tipo	Descrição
`CHECKING`	Conta corrente
`SAVINGS`	Conta poupança
`PAYMENT`	Conta de pagamento

Status de Transferência/Pix

Status	Descrição
`PENDING`	Aguardando processamento
`PROCESSING`	Em processamento no provedor
`COMPLETED`	Concluída com sucesso
`FAILED`	Falhou no processamento
`REVERSED`	Estornada

Status do Boleto

Status	Descrição
`PENDING`	Aguardando registro
`REGISTERED`	Registrado no banco
`PAID`	Pago
`OVERDUE`	Vencido
`CANCELED`	Cancelado

Tipos de Chave Pix

Tipo	Descrição
`CPF`	CPF do titular
`CNPJ`	CNPJ do titular
`EMAIL`	Endereço de e-mail
`PHONE`	Número de telefone (+55...)
`EVP`	Chave aleatória (UUID)

Eventos do BaaS

O módulo publica eventos via Redis para integração com outros módulos:

Evento	Descrição
`baas.account.created`	Conta bancária criada
`baas.account.activated`	Conta ativada
`baas.account.blocked`	Conta bloqueada
`baas.account.closed`	Conta encerrada
`baas.transfer.created`	Transferência criada
`baas.transfer.completed`	Transferência concluída
`baas.transfer.failed`	Transferência falhou
`baas.pix.sent`	Pix enviado
`baas.pix.received`	Pix recebido
`baas.pix.failed`	Pix falhou
`baas.boleto.registered`	Boleto registrado
`baas.boleto.paid`	Boleto pago
`baas.boleto.canceled`	Boleto cancelado
`baas.reconciliation.completed`	Conciliação concluída

Visão Geral​

Base URL​

Recursos​

Permissões​

Exemplo Rápido​

Arquitetura​

Componentes do BaaS​

Conceitos Importantes​

Status da Conta Bancária​

Tipos de Conta​

Status de Transferência/Pix​

Status do Boleto​

Tipos de Chave Pix​

Eventos do BaaS​