Catalisa.Building Blocks
Catálogo/Financeiro/BaaS

BaaS

Beta

Contas, Pix, TED e boleto por API; troque o banco parceiro sem reescrever a integração

45
Endpoints
14
Entidades
3
Provedores
Tenant
Escopo
3015
Porta
2026-01
Desde

Você integra uma vez e passa a abrir contas, movimentar Pix e enviar TED. O banco parceiro que carrega a licença fica atrás de uma configuração — trocar de provedor deixa de ser um projeto e vira uma linha no banco de dados.

Para quem é
  • Fintechs de crédito que precisam de uma conta por operação, com parte do saldo travada por motivo e liquidação por Pix, sem virar instituição autorizada
  • Marketplaces e plataformas B2B que recebem em nome de terceiros e precisam de conciliação por conta
  • Empresas que já operam com um provedor bancário e querem reduzir o risco de depender de um só
Substitui
  • Integração direta e artesanal com a API de cada banco parceiro
  • Camada caseira de tradução entre o formato do provedor e o modelo da sua aplicação
  • Tabela própria de contas, transações e chaves Pix reimplementada dentro de cada produto
O que não é
  • Uma licença bancária — a Catalisa não é instituição autorizada pelo BACEN (ver §14)
  • Um ledger contábil ou sistema de conciliação financeira da sua operação
  • Um adquirente, gateway de cartão ou emissor de cartão
  • Um sistema de antifraude, PLD/FT ou monitoramento transacional
O que dá para fazer

87 endpoints em 13 recursos.

Explorar a API →
01

Resumo executivo

O BaaS é a camada que dá à sua aplicação uma conta bancária de verdade sem que você precise virar um banco. Você chama uma API para abrir conta, consultar saldo, registrar chave Pix, enviar Pix e TED, gerar QR Code e receber os eventos de volta. Quem executa a operação bancária é um provedor licenciado pelo Banco Central — Celcoin, QI Tech ou FitBank — e quem esconde as diferenças entre eles é este building block.

E, para quem opera aplicativo bancário de marca própria, há uma trava a mais, opcional e por conta: a conta pode exigir que toda saída de dinheiro seja assinada no celular do titular, com a chave privada presa ao hardware do aparelho e a verificação acontecendo antes de a credencial do banco parceiro ser decifrada. Quem invadir o seu backend consegue ler; não consegue transferir (§14).

Na prática isso significa que uma financeira consegue abrir uma conta por operação de crédito — rotulada pelo propósito e amarrada ao identificador da operação —, travar parte do saldo com o motivo registrado, liquidar o desembolso por Pix e conciliar o recebimento pelo endToEndId, tudo com o mesmo contrato de API. E significa também que trocar de banco parceiro seis meses depois é criar uma configuração nova e apontar as contas seguintes para ela — não é um projeto de reintegração. Esse arranjo não é uma conta escrow, e a diferença é jurídica antes de ser técnica: §16 responde, de frente, o que ele entrega e o que ele não entrega.

Está deployado nas stacks de staging e produção desde janeiro de 2026, com a esteira completa exercitada de ponta a ponta contra o provedor simulado MockBank. O status é beta, e não produção, de propósito: as três integrações com provedores reais estão implementadas e testadas com HTTP mockado, mas este repositório não guarda evidência de homologação contra os ambientes de sandbox reais desses provedores. §15 detalha exatamente o que falta.

AtributoValor
Identificadorbaas
CategoriaFinanceiro
EscopoTenant (exige organizationId no token)
Porta (standalone)3015
Path alias@baas
Prefixo HTTP/baas
Schema no bancobaas
StatusBeta — deployado desde 2026-01
Depende dePostgreSQL, Redis, IAM, Webhooks Engine

02

O problema

negócio

O cenário. Uma empresa quer movimentar dinheiro dentro do próprio produto: abrir conta para o cliente, receber por Pix, pagar fornecedor por TED, manter saldo separado por operação. Ela não quer — e na maioria dos casos não pode — pedir autorização ao Banco Central para isso. Então contrata um provedor bancário licenciado e integra a API dele.

O que trava hoje.

  • Cada provedor inventa o próprio dialeto. A Celcoin fala REST com endpoints por recurso e status em texto. O FitBank fala RPC: um único endpoint /main/execute, um campo Method no corpo e status como número de 0 a 6. A QI Tech assina cada requisição com RSA. São três modelos mentais diferentes para a mesma operação de "manda um Pix".
  • O provedor vira parte da sua arquitetura. Quando o mapeamento entre o formato do banco e o seu domínio está espalhado pelos serviços, o provedor deixa de ser fornecedor e vira dependência estrutural. A conversa comercial de renovação acontece com você sem alternativa.
  • Trocar de banco é reescrever. A migração não é só de API: é de identificador de conta, de formato de status, de semântica de webhook. Times estimam meses e adiam a decisão, que é exatamente o que o incumbente precisa.
  • Não dá para testar sem contrato. Sem sandbox liberado, o time não consegue nem começar. A esteira de produto fica bloqueada por um processo comercial e de compliance que leva semanas.
  • A conciliação é problema seu, mas o risco também. Quando os saldos que você mostra ao cliente e os que o banco parceiro registra divergem, quem responde ao cliente é você.

O custo de não resolver. O último item não é hipótese. Em 2024 a Synapse Financial Technologies — que operava exatamente como camada entre fintechs e bancos parceiros nos EUA — entrou em Chapter 11. Havia US$ 219 milhões nas contas dos bancos parceiros, e o caixa batia com os registros do Federal Reserve. O que não batia era o registro de quem era dono de quanto, que só existia no sistema da Synapse. Mais de cem mil pessoas ficaram sem acesso ao próprio dinheiro, e a curadoria nomeada pelo tribunal estimou entre US$ 65 e US$ 95 milhões de descasamento antes de concluir, em abril de 2025, que reconciliar custava mais do que o espólio tinha.

O FDIC foi direto ao ponto no alerta que publicou em 31/05/2024: "FDIC deposit insurance does not protect against the insolvency or bankruptcy of a nonbank company" — e acrescentou que é preciso manter registros que identifiquem quem é dono do dinheiro e quanto cada pessoa tem. A lição prática: numa arquitetura BaaS, saber quem carrega a licença e onde mora a titularidade não é detalhe jurídico, é desenho de sistema. §4 detalha o caso e §14 mostra o que o regulador brasileiro fez com essa lição.


03

Proposta de valor

negócio
AntesDepois
Uma integração artesanal por provedor bancárioUma API canônica; o provedor é configuração da organização
Trocar de banco parceiro é projeto de mesesCriar uma configuração nova e apontar as contas seguintes para ela
Só dá para começar depois do contrato com o bancoMockBank simula conta, saldo, DICT, Pix e QR Code desde o primeiro dia
Cada provedor exige um formato de webhook diferenteTodos os webhooks viram o mesmo conjunto de 18 eventos internos
Credenciais de banco em variável de ambienteCredenciais cifradas em AES-256-GCM no banco, por organização

O provedor é dado, não código. BaaSProviderConfig guarda o tipo do provedor e as credenciais cifradas. createBaaSProvider instancia a estratégia certa em tempo de execução. Nenhum serviço do BaaS sabe o nome de um banco.

Migração gradual, não virada de chave. Cada BaaSAccount guarda o configId a que pertence, e o provedor é resolvido a partir dele a cada operação. Isso permite que contas em provedores diferentes convivam durante a transição — as novas nascem no provedor novo, as antigas continuam funcionando onde estão. (Sobre manter dois contratos simultâneos em regime permanente, veja a ressalva do art. 6º da Resolução Conjunta nº 16/2025 em §14.)

A esteira inteira é testável sem contrato. O MockBank não é um stub de resposta: é um banco simulado com saldo real, transferência interna entre contas, geração de chave EVP, diretório de chaves, QR Code em formato EMV do BR Code e disparo de webhook. O que você prova no MockBank é o mesmo fluxo que vai rodar em produção.

Credenciais tratadas como segredo. As credenciais do provedor são cifradas com AES-256-GCM antes de tocar o banco e nunca voltam em nenhuma resposta de API — toResponseData simplesmente não as inclui.


04

Casos de uso reais

negócio

Caso 1 — Uma financeira separa o dinheiro de cada operação de crédito Cenário ilustrativo

Contexto

Financeira de crédito com garantia que desembolsa para o cliente e recebe parcelas de volta. Cada operação precisa de segregação de recursos, porque o dinheiro em trânsito não é dela.

A dor

Com uma conta única no banco parceiro, a separação virava planilha. Descobrir quanto do saldo pertencia a qual operação exigia cruzar extrato com sistema, e o processo era o mesmo tanto para fechar o mês quanto para responder a uma dúvida de cliente. O erro não aparecia no dia; aparecia na conciliação.

A solução com o BB

Cada operação abre uma conta pelo POST /baas/api/v1/accounts, com businessId carregando o identificador da operação no sistema de crédito e personId apontando para a pessoa no Customers. O desembolso sai por POST /baas/api/v1/pix/transfers. O recebimento entra como transação PIX_IN criada pelo handler de webhook, já vinculada à conta certa. GET /baas/api/v1/pix/transfers?filter[accountId]=... devolve o extrato daquela operação.

flowchart LR
  OP["Operação de crédito OP-2026-00841"]
  ACC["POST /accounts<br/>businessId = OP-2026-00841<br/>personId aponta para Customers"]
  OUT["POST /pix/transfers<br/>desembolso ao cliente"]
  IN["Webhook pix.received<br/>handler cria transação PIX_IN na conta certa"]
  EXT["GET /pix/transfers?filter[accountId]=...<br/>extrato daquela operação"]

  OP --> ACC
  ACC --> OUT
  ACC --> IN
  OUT --> EXT
  IN --> EXT
O resultado

A pergunta "quanto desta operação já voltou" deixa de ser um cruzamento manual e vira uma chamada de API filtrada por conta. E como businessId está na transação, o vínculo com o sistema de crédito sobrevive à conciliação.

Caso 2 — Um marketplace cobra por QR Code e reconhece o pagamento sozinho Cenário ilustrativo

Contexto

Marketplace B2B que fatura pedidos de lojistas e quer receber por Pix sem obrigar o comprador a copiar dados bancários.

A dor

O fluxo anterior era boleto com dois dias de compensação e uma rotina de baixa que rodava de madrugada. O comprador pagava, o pedido ficava travado até o dia seguinte, e o atendimento passava a manhã respondendo "já paguei".

A solução com o BB

No fechamento do pedido, o marketplace chama POST /baas/api/v1/pix/qr-codes/generate com amount, description e expiresInMinutes, e recebe o emvCode (copia e cola) mais o QR em base64. Quando o comprador paga, o provedor manda o webhook pix.received para POST /baas/api/v1/webhooks/{provedor}; o handler cria a transação PIX_IN e publica baas.pix.received no barramento de eventos. O Webhooks Engine entrega esse evento ao endpoint do marketplace.

sequenceDiagram
  autonumber
  participant M as Marketplace
  participant B as BaaS
  participant P as Provedor
  participant C as Comprador
  participant W as Webhooks Engine

  M->>B: POST /pix/qr-codes/generate com amount, description, expiresInMinutes
  B-->>M: emvCode copia e cola + QR em base64
  M->>C: mostra o QR no fechamento do pedido
  C->>P: paga o Pix
  P->>B: POST /webhooks/celcoin com pix.received
  B->>B: cria transação PIX_IN
  B->>W: publica baas.pix.received
  W->>M: entrega no endpoint do marketplace
  M->>M: libera o pedido
O resultado

O pedido é liberado no momento do pagamento, não no dia seguinte. E a baixa deixa de depender de uma rotina noturna — é o evento que dispara a mudança de estado.

Caso 3 — Uma operação troca de banco parceiro sem parar o produto Cenário ilustrativo

Contexto

Empresa que já opera com um provedor bancário há um ano e decide diversificar, seja por custo, por SLA ou por não querer depender de um fornecedor só.

A dor

Na integração direta, isso é uma virada de chave: reescrever o cliente HTTP, remapear status, refazer o parsing de webhook, migrar todas as contas de uma vez e rezar. O risco concentrado num fim de semana é justamente o motivo pelo qual a decisão é adiada por anos.

A solução com o BB

Cria-se uma segunda BaaSProviderConfig com o novo provedor, valida com POST /baas/api/v1/provider-configs/:id/test, e marca como padrão com POST /baas/api/v1/provider-configs/:id/set-default. As contas novas nascem no provedor novo; as antigas continuam no antigo, porque cada BaaSAccount guarda o próprio configId e o serviço resolve o provedor a partir dele a cada operação. Os dois convivem pelo tempo que for preciso.

flowchart LR
  subgraph ANTES["Integração direta — virada de chave"]
    A1["Reescrever cliente HTTP"] --> A2["Remapear status"] --> A3["Refazer parsing de webhook"] --> A4["Migrar todas as contas num fim de semana"]
  end

  subgraph DEPOIS["Catalisa BaaS — curva"]
    D1["POST /provider-configs — config nova"] --> D2["POST /provider-configs/:id/test"] --> D3["POST /provider-configs/:id/set-default"]
    D3 --> NOVAS["Contas novas nascem no provedor novo"]
    D3 --> VELHAS["Contas antigas seguem no antigo<br/>cada BaaSAccount guarda o próprio configId"]
  end
O resultado

A migração vira uma curva, não um degrau. E o poder de barganha na renovação muda de lado, porque a alternativa deixa de ser teórica.

Caso 4 — O que acontece quando a titularidade só existe no middleware Referência de mercado

Contexto

A Synapse Financial Technologies operava nos EUA como intermediária entre cerca de 100 fintechs (Yotta, Juno, Copper) e quatro bancos parceiros (Evolve, AMG National Trust, Lineage, American Bank). O desenho: no banco havia uma conta omnibus "FBO" — for benefit of — com o dinheiro de milhares de pessoas misturado. O banco enxergava um saldo agregado. Quem era dono de quanto existia apenas no ledger da Synapse, e um programa de sweep espalhava os depósitos entre vários bancos para multiplicar a cobertura de US$ 250 mil do FDIC.

A dor do mercado

Em 11/05/2024 a Synapse cortou o acesso do banco parceiro ao painel e parou de enviar o razão diário. Os bancos congelaram tudo no mesmo dia. Havia US$ 219.077.467 nas contas FBO, e o caixa reconciliava com os registros do Federal Reserve — o dinheiro estava lá. O que não fechava era o mapa de titularidade: o trial balance final gerado pela Synapse atribuía a um dos bancos um saldo diferente do saldo real, e como o dinheiro de um mesmo usuário havia circulado por várias instituições, nenhum banco tinha como reconstruir de quem era o quê — nenhum jamais teve esses dados. A curadoria estimou de US$ 65 a US$ 95 milhões de descasamento; cerca de US$ 192 milhões (87%) foram devolvidos até janeiro de 2025, e em abril de 2025 a reconciliação foi abandonada por custar mais que o espólio. O caso foi extinto em 12/11/2025, com autorização para destruir os registros remanescentes.

Como a Catalisa endereça

Quatro escolhas de desenho, todas verificáveis no código. Primeiro: a Catalisa nunca é depositária. O dinheiro fica no provedor licenciado; BaaSAccount.externalId é o identificador da conta no provedor. Segundo: não existe conta omnibus. Cada BaaSAccount corresponde a uma conta individual aberta no provedor, com agência, número e dígito próprios — a titularidade mora lá, não aqui. Terceiro: o saldo local é cache explícito, e GET /accounts/:id/balance sempre consulta a origem antes de responder. Quarto: o endToEndId do Pix é persistido e indexado, dando uma chave de conciliação que os dois lados reconhecem.

flowchart LR
  subgraph SYN["Modelo Synapse — titularidade no middleware"]
    S1["Milhares de usuários finais"] --> S2["Ledger da Synapse<br/>ÚNICO lugar que sabia quem é dono de quanto"]
    S2 --> S3["Conta omnibus FBO no banco parceiro<br/>o banco enxerga só o saldo agregado"]
    S3 --> S4["Acesso cortado em 11/05/2024 →<br/>nenhum banco conseguiu reconstruir a titularidade"]
  end

  subgraph CAT["Modelo Catalisa — titularidade na instituição licenciada"]
    C1["BaaSAccount = uma conta individual no provedor<br/>agência, número e dígito próprios"]
    C2["externalId aponta para a conta NO provedor"]
    C3["Saldo local é cache explícito;<br/>GET /accounts/:id/balance consulta a origem"]
    C4["endToEndId persistido e indexado<br/>chave de conciliação que os dois lados reconhecem"]
    C1 --> C2 --> C3 --> C4
  end
O resultado

A pergunta "de quem é este saldo" tem resposta única, e ela mora na instituição licenciada. Não é coincidência que o regulador brasileiro tenha chegado à mesma conclusão: a Resolução Conjunta nº 16/2025 exige, no art. 4º, §2º, que as contas sejam de titularidade do cliente na instituição prestadora — o que torna o modelo de conta bolsão inviável como arquitetura de BaaS no Brasil (§14).

Fontes. Valores e datas vêm dos autos da falência (In re Synapse Financial Technologies, Bankr. D. Del.), em especial os relatórios da trustee. Reação regulatória: alerta do FDIC ao consumidor sobre contas em fintechs, que originou a proposta de regra Recordkeeping for Custodial Accounts (RIN 3064-AG07, 02/10/2024) exigindo reconciliação diária e identificação do beneficiário final — proposta que até 16/08/2026 não foi finalizada; e a ação de enforcement do Federal Reserve contra o Evolve Bank & Trust, de 14/06/2024.


05

Mercado e diferenciais

negócio

Panorama. O mercado brasileiro de BaaS tem duas camadas que costumam ser confundidas na conversa comercial. Na primeira estão as instituições autorizadas pelo Banco Central — Celcoin (IP e SCD), QI Tech (SCD), Dock (IP e participante direto do Pix, código 301), Fits/FitBank (IP). São elas que carregam a licença, respondem ao regulador e custodiam recurso. Na segunda estão as camadas técnicas que integram uma ou mais dessas instituições e entregam uma API ao produto final. A Catalisa está, sem ambiguidade, na segunda camada.

Nenhum dos provedores brasileiros consultados publica tabela de preço; todos direcionam para o comercial (consulta em 2026-08-16 aos sites de Celcoin, QI Tech, Dock e Fits). Isso significa que a comparação de custo entre eles só existe dentro de uma negociação — o que, por si só, é um argumento a favor de ter mais de um contrato possível.

No exterior o padrão é o mesmo, e a última rodada de crises deixou lições que valem para quem compra aqui. A Unit declara em rodapé que "is a financial technology company and not a bank", com os serviços bancários prestados por bancos parceiros membros do FDIC. Unit e Treasury Prime anunciaram o mesmo pivô para contrato direto banco↔fintech com semanas de diferença, em fevereiro e março de 2024 — a Treasury Prime foi explícita ao dizer que "os reguladores esperam que as instituições bancárias, não intermediários, supervisionem diretamente as relações com fintechs" (Treasury Prime). Do outro lado do espectro, ter licença própria não imunizou ninguém: a Solaris, banco alemão pleno, opera sob monitor especial da BaFin desde 2022 e precisou de um resgate de €140 milhões em fevereiro de 2025; a Railsr passou por pre-pack administration em março de 2023, teve a licença de EMI da subsidiária lituana revogada e hoje não existe mais como marca, absorvida pela Equals. A conclusão útil para o comprador: licença própria troca risco de contraparte por risco de capital e supervisão — não elimina risco.

A escala do problema. O Pix processou 71,3 bilhões de transações e R$ 29,61 trilhões em 2025, e em julho de 2026 sozinho foram 7,24 bilhões de transações e R$ 3,22 trilhões. Em 31/07/2026 havia 987,5 milhões de chaves cadastradas e 871 participantes distintos no DICT (série calculada a partir da API de dados abertos do BACEN, consultada em 16/08/2026). Já o tamanho do mercado de BaaS no Brasil não tem número confiável: o BCB não publica a estatística, e a base cadastral que permitirá medi-la só produz efeitos em 01/09/2026. A cifra que circula em material comercial vem de um estudo encomendado por um participante do próprio mercado — por isso não a citamos aqui.

O Brasil regulou BaaS especificamente, e o prazo está correndo. A Resolução Conjunta nº 16, de 28/11/2025 (CMN + BCB) trata da prestação de Banking as a Service, com escopo taxativo, regra de exclusividade, alocação de responsabilidade de PLD e KYC à instituição prestadora, e poder do BCB de determinar o encerramento de contratos. Os contratos vigentes têm até 31/12/2026 para se adequar. Em paralelo, a Resolução BCB nº 517/2025 lista expressamente a prestação de BaaS entre os serviços que acrescem R$ 5 milhões ao capital regulatório mínimo da prestadora. Ser o provedor licenciado ficou mais caro em 2025 — o que reforça a tese deste building block: você quer usar um, não virar um.

E o risco jurídico do lado do provedor aumentou. Em 17/06/2026 o TJSP manteve a QI Tech SCD em execução ligada a uma pirâmide financeira aplicando a teoria menor da desconsideração da personalidade jurídica, que permite alcançar provedores de infraestrutura de pagamento sem prova de fraude própria (Times Brasil). Combinado com o art. 10 da Resolução Conjunta nº 16/2025, que aloca à prestadora a responsabilidade por KYC, antifraude e PLD/FT mesmo quando as tarefas são delegadas, isso significa que o seu provedor vai apertar o onboarding e o monitoramento. Planeje a esteira de KYC contando com isso, não com o contrário.

CritérioCatalisa BaaSCelcoinQI TechDockUnit (EUA)
Carrega licença do BACENNão — camada técnicaSim (IP + SCD)Sim (SCD)Sim (IP, part. direto Pix)Não (bancos parceiros, EUA)
Custodia recurso de clienteNãoSimSimSimNão
Provedor trocável sem reescreverSim, por configuraçãoNão se aplicaNão se aplicaNão se aplicaNão
Mais de um provedor simultâneoSim, por organizaçãoNãoNãoNãoNão
Ambiente de teste sem contratoSim (MockBank completo)Sandbox após contratoSandbox após contratoSandbox após contratoSandbox
Pix, TED e DICTSim, via provedorSimSimSimNão (mercado EUA)
Emissão de cartãoNãoSimSimSimSim
Crédito / originaçãoNão (é o Decision Platform)ParcialSimParcialSim
Boleto registradoSim — emissão, consulta e baixa, via provedorSimSimSimNão
Preço públicoPrecificação em definiçãoNão divulgadoNão divulgadoNão divulgadoNão divulgado

A pergunta de due diligence que separa os fornecedores é binária. Existe uma entidade autorizada, com CNPJ, no registro do BACEN — ou não? E atenção: a marca comercial e a razão social licenciada nem sempre coincidem. A licença por trás da marca Zoop, por exemplo, é da iFood Pago Instituição de Pagamento S.A., autorizada em outubro de 2023 como emissora de moeda eletrônica; a marca Bankly opera sob a Acesso Soluções de Pagamento S.A., hoje controlada pelo Banco BV. Já a Matera não possui nenhuma autorização — vende software de core banking e motor de Pix para instituições que já têm a própria licença, o que é um posicionamento legítimo e completamente diferente. Confira sempre a entidade que assina o contrato, não o logotipo (§14).

Nossos diferenciais

  1. O provedor é uma linha no banco de dados. BaaSProviderConfig.providerType mais credenciais cifradas é tudo que separa uma organização rodando sobre Celcoin de outra rodando sobre QI Tech. É difícil de copiar não pela técnica, mas porque exige manter três mapeadores completos em dia com três APIs que evoluem sozinhas — custo que só se paga quando ele é diluído por vários clientes.
  2. Coexistência de provedores, não apenas suporte a vários. A distinção importa: suportar N provedores é escolher um por cliente. Aqui BaaSAccount.configId amarra cada conta à sua configuração, então duas contas da mesma organização podem viver em bancos diferentes ao mesmo tempo. É o que torna a migração gradual possível. Ressalva regulatória obrigatória: o art. 6º da Resolução Conjunta nº 16/2025 veda contratar BaaS com uma prestadora quando já existe contrato vigente com outra para o mesmo tipo de conta. A capacidade técnica é real e serve à migração; usá-la para manter dois contratos simultâneos do mesmo tipo é uma decisão que passa pelo seu jurídico, não pela engenharia (§14 e §15).
  3. Um banco simulado de verdade, não um mock de resposta. O MockBank tem saldo, débito e crédito entre contas internas, DICT com chave EVP em formato UUID, endToEndId no formato de 32 caracteres da especificação, QR Code EMV parseável e disparo de webhook. O time integra e testa a esteira toda antes de o jurídico terminar o contrato.
  4. Isolamento por organização em toda consulta de escrita. Cada serviço compara organizationId do token com o do registro antes de agir, e devolve 404 — não 403 — quando não bate, para não revelar existência de recurso de outro tenant.

Quando escolher o concorrente.

Se o problema é…A resposta certa é
Uma conta, um Pix, e nada maisIntegrar direto na Celcoin ou na QI Tech
Emissão de cartão como produto centralDock
Crédito com originação, custódia e fundo no mesmo contratoQI Tech
Não deixar o banco parceiro virar dependência estruturalEste building block

Se você precisa de uma coisa só — uma conta, um Pix, e nada mais — integrar direto na Celcoin ou na QI Tech é mais simples e tem menos peças no caminho; toda abstração cobra um pedágio e o menor denominador comum vale aqui também (o ADR-0003 registra isso como consequência aceita).

Se o produto central é emissão de cartão, a Dock resolve algo que o BaaS não faz e não pretende fazer. Se a exigência é crédito com originação, custódia e fundo no mesmo contrato, a QI Tech entrega uma esteira que aqui exigiria combinar vários building blocks.

O BaaS ganha quando o problema é não querer que o banco parceiro vire dependência estrutural — e quando a operação é multi-tenant, porque aí a configuração por organização deixa de ser conveniência e vira arquitetura.


06

Modelo de cobrança e ROI

negócio

Unidade de cobrança. Precificação em definição. Não há preço fechado para este building block, e inventar um aqui seria pior do que não ter.

O que dispara custo. Três drivers, e vale entender a natureza de cada um:

DriverPor quê
Contas ativasO provedor cobra por conta aberta e mantida; é o custo que cresce com a base
Transações Pix e TED processadasCusto por transação do provedor, repassado
Chamadas de API ao provedorConsulta de saldo, DICT e status batem no provedor a cada requisição (§7 explica por que não há cache)

Comparação de custo. Não é possível montar tabela comparativa honesta: nenhum dos provedores consultados publica preço (verificado em 2026-08-16 nos sites de Celcoin, QI Tech, Dock e Fits). Toda comparação de custo entre eles acontece dentro de uma proposta comercial específica. O que dá para comparar é a estrutura de custo:

Integração direta com um provedorCatalisa BaaS
Custo transacionalDo provedor, negociadoDo provedor, negociado — o mesmo
Custo de integração inicialUma integração completa por provedorUma integração; o provedor entra por configuração
Custo de trocar de provedorNova integração completaNova configuração; contas antigas continuam no provedor antigo
Custo de ter dois provedoresDuas integrações completas e mantidasDuas configurações
Custo de testar antes do contratoBloqueado até liberação de sandboxZero — MockBank

ROI. O retorno não está na taxa por Pix: essa é do banco parceiro e continua sendo, com ou sem BaaS. Está em duas coisas.

Linha do ROIOnde ela apareceQuanto vale
Custo de integração que não se repeteLinha de engenhariaManter dois mapeadores de provedor em produção é trabalho contínuo — aqui ele é diluído entre todos os clientes da plataforma
Poder de barganha na renovaçãoTaxa por transação, todo mêsNão aparece em nenhum orçamento de projeto, e é a maior das duas

A primeira é o custo de integração que não se repete: manter dois mapeadores de provedor em produção é trabalho contínuo, e aqui ele é diluído entre todos os clientes da plataforma em vez de recair sobre a engenharia de cada um.

A segunda é menos visível e vale mais: um provedor que sabe que você não tem alternativa técnica negocia diferente de um que sabe que você tem. A conta dessa diferença não aparece na linha de engenharia — aparece na taxa por transação, todo mês.


07

Arquitetura

As cinco camadas

flowchart TD
  HTTP["Requisição HTTP"] --> APP

  subgraph APP["Hono app — basePath /baas + applyCommonMiddleware"]
    direction TB
    MW["bodyLimit 1MB · CORS · security headers · rate limit"]
    GRD["authMiddleware → requirePermission → requireOrganization"]
    EXC["webhookRouter é a exceção — não passa por JWT, ver §14"]
    MW --> GRD
    MW --> EXC
  end

  APP -->|"Zod parse → ResultAsync&lt;T, AppError&gt;"| SVC

  subgraph SVC["services/"]
    direction TB
    S1["ProviderConfigService — CRUD de config, cifra credencial, testa"]
    S2["AccountService — conta, saldo, KYC, encerramento"]
    S3["PixService — chave, DICT, transferência, QR, estorno"]
    S4["TedService — transferência TED e consulta"]
    S5["WebhookHandlerService — recebe, deduplica, aplica e republica"]
  end

  SVC -->|"decryptCredentials + createBaaSProvider do tipo"| PRV

  subgraph PRV["providers/ — interface BaaSProvider com 24 métodos canônicos"]
    direction TB
    P1["CelcoinProvider — OAuth2 client_credentials · REST · status em texto"]
    P2["FitBankProvider — Basic Auth · RPC /main/execute · status numérico"]
    P3["QITechProvider — requisição assinada com RSA · REST"]
    P4["MockBankProvider — banco simulado, tabelas mockbank_* no Postgres"]
  end

  SVC --> REPO["repositories/ com Prisma"]
  REPO --> PG[("PostgreSQL — schema baas")]

Os cinco routers montados e o que cada um responde:

CaminhoRouterRotas
/api/v1/provider-configsproviderConfigRouter7
/api/v1/accountsaccountRouter + authorizationRouter9 + 10
/api/v1/pixpixRouter10
/api/v1/tedtedRouter3
/api/v1/webhookswebhookRouter2
/health—versão do build

O caminho de uma transferência Pix

A ordem importa: o provedor confirma antes de a transação existir localmente.

sequenceDiagram
  autonumber
  participant C as Cliente
  participant R as pixRouter
  participant S as PixService
  participant CFG as providerConfigRepo
  participant P as Provedor bancário
  participant DB as transactionRepo
  participant EV as eventPublisher

  C->>R: POST /pix/transfers
  R->>S: input validado por Zod
  S->>CFG: busca a config da conta
  CFG-->>S: credenciais cifradas
  S->>S: decryptCredentials
  S->>P: provider.initiatePixTransfer — chamada de rede
  P-->>S: transação canônica com status
  S->>DB: transactionRepo.create — só depois
  S->>EV: publish baas.pix.transfer.initiated

Decisões não óbvias.

  • O provedor é instanciado por requisição, não guardado no container. getProviderForAccount busca a config, decifra as credenciais e chama createBaaSProvider a cada operação. O custo é uma decifragem AES por chamada — irrelevante perto da latência de rede do provedor. O ganho é que trocar credencial ou desativar uma config surte efeito na requisição seguinte, sem reinício e sem invalidação de cache. Num building block financeiro, revogar credencial na hora vale mais que economizar microssegundos.
  • Saldo não tem cache. GET /accounts/:id/balance sempre bate no provedor. O campo availableBalance no banco é atualizado depois, de forma assíncrona, e existe para listagem — nunca para responder "quanto tem nesta conta". Um saldo desatualizado de 30 segundos numa tela é irritação; num sistema que decide se autoriza uma transferência, é prejuízo.
  • A transação local só é criada depois que o provedor confirma. A ordem é sempre provedor primeiro, banco depois. Se o provedor falhar, não existe transação órfã em PENDING no seu banco esperando conciliação manual. O trade-off aceito é o inverso: se o provedor aceitar e a escrita local falhar, existe uma transação no banco parceiro sem contrapartida local — que é o cenário que a reconciliação por endToEndId precisa cobrir (§15).
  • Tipos canônicos, e não o formato do provedor, atravessam o serviço. CanonicalAccount, CanonicalPixTransaction, CanonicalBalance e companhia são o contrato interno. Nenhum serviço sabe que o FitBank usa TaxNumber como identificador de conta ou que a Celcoin devolve status em texto. A consequência é o menor denominador comum: uma funcionalidade exclusiva de um provedor não é exposta enquanto não couber na interface. O ADR-0003 registra isso como custo aceito.
  • externalId é o identificador no provedor, e é ele que amarra tudo. A unicidade é (configId, externalId), não externalId sozinho — porque dois provedores diferentes podem, legitimamente, emitir o mesmo identificador. É a mesma razão pela qual não existe conta "da organização": existe conta "da configuração", e a configuração é que é da organização.
  • Webhook do provedor não passa por JWT. Quem chama é o banco, que não tem token da sua plataforma. A autenticação é assinatura do provedor, e a organização vem do header X-Organization-Id ou do query param organizationId que o próprio BaaS gera na URL de callback. §14 detalha o modelo de confiança e o que ligar em produção.
  • O MockBank persiste em tabelas próprias. mockbank_accounts, mockbank_pix_keys, mockbank_transactions e mockbank_qr_codes são o "banco de dados do banco simulado", separadas das tabelas baas_* que são o registro da plataforma. A separação é deliberada: o simulador tem que se comportar como um sistema externo, inclusive perdendo e reconciliando estado, senão o teste não prova nada.

Capacidade declarada por provedor

Até aqui, capacidade ausente virava erro em tempo de execução: deposit devolve ValidationError em três dos quatro provedores. Isso serve para responder "não dá"; não serve para responder "então faça de outro jeito". E há uma decisão que precisa ser tomada antes da chamada, não depois do erro: bloquear saldo delegando ao provedor ou escriturando na nossa base.

Por isso BaaSProvider tem readonly capabilities, obrigatório:

ProvedorbalanceHoldtransactionFeeescrowAccountMétodos de bloqueio
MockBankNATIVEtruefalsecreateProviderHold, releaseProviderHold e settleProviderHold implementados
CelcoinNONEtruefalseausentes
QI TechNONEtruefalseausentes
FitBankNONEtruefalseausentes

Decisões não óbvias.

  • O membro é obrigatório de propósito. Acrescentá-lo quebra os quatro provedores em tempo de compilação — e é exatamente o que se quer. Cada um declara o que faz, ninguém herda um padrão silencioso, e um provedor novo não entra no catálogo sem responder à pergunta.
  • Quem escolhe o caminho lê a declaração, nunca o tipo do provedor. Não existe if (providerType === 'MOCKBANK') no serviço. Ligar a Celcoin no dia em que houver API de bloqueio parcial é trocar um literal e escrever três métodos.
  • Os três métodos de bloqueio são opcionais na interface, e só alcançáveis sob balanceHold === 'NATIVE'. Provedor NONE simplesmente não os tem: o compilador não deixa chamá-los sem a guarda.
  • NONE nos três provedores reais não é preguiça, é ausência de contrato. block/unblock existem nos quatro, mas congelam a conta inteira — é ato de compliance, não reserva de valor. De saldo bloqueado, o que temos é leitura (blockedBalance). Escrever cliente contra API não confirmada seria inventar contrato.
  • escrowAccount nasce tipado como a literal false, não como boolean. Nenhum dos quatro vende conta escrow, e conta de terceiro com regra de liberação é outro contrato (Res. Conjunta 16/2025, art. 4º §2º: conta de titularidade do cliente na instituição prestadora), não um campo nosso. A literal só relaxa no PR que trouxer o primeiro provedor que a venda.

Autorização do titular — a trava opcional por conta

Por padrão, quem tem BAAS_ADMIN move dinheiro. Para as contas que aderem, entra uma segunda chave: a do celular do titular. A ordem importa tanto quanto no caminho do Pix — a verificação acontece antes de a credencial do provedor ser decifrada, então uma recusa significa que o banco nunca ficou sabendo da operação.

sequenceDiagram
  autonumber
  participant APP as App do titular
  participant BE as Backend do cliente
  participant R as pixRouter
  participant S as PixService
  participant G as HolderAuthorizationService
  participant BIO as Biometrics (fachada)
  participant CFG as providerConfigRepo
  participant P as Provedor bancário

  BE->>R: POST /accounts/:id/authorization-challenges
  R-->>BE: challengeId + nonce (120s, uso único)
  BE->>APP: operação + challenge
  APP->>APP: assina o payload canônico na chave do enclave
  APP-->>BE: signature
  BE->>R: POST /pix/transfers + holderAuthorization
  R->>S: input validado por Zod
  S->>G: authorize(operação reconstruída do corpo)
  G->>G: política ≠ NONE? dispositivo ATIVO e permitido?
  G->>BIO: verifyEvidence(sessão de enrolamento, hash de enrolamento)
  BIO-->>G: válida, APPROVED, vinculada
  G->>G: verifica a assinatura sobre o payload
  G->>G: consome o desafio (update condicional)
  opt valor > requireBiometricAbove
    G->>BIO: verifyEvidence(sessão nova, operationHash)
  end
  G-->>S: autorizado
  S->>CFG: busca a config da conta
  S->>S: decryptCredentials
  S->>P: provider.initiatePixTransfer

Decisões não óbvias.

  • O payload é reconstruído pelo BaaS a partir do corpo recebido. Se o cliente mandasse o hash, um backend comprometido assinaria uma operação e executaria outra. O custo é que o aplicativo precisa reproduzir a forma canônica byte a byte — por isso ela está congelada em §14, com vetor de teste.
  • A evidência de enrolamento é reverificada a cada uso. Verificar só no cadastro deixaria a tabela de dispositivos como raiz de confiança, e o banco de dados é justamente o que se assume comprometido. O preço é uma chamada ao bloco de biometria por operação autorizada.
  • Afrouxar a política é uma operação assinada. Sem isso, o primeiro passo de qualquer ataque seria desligar a política. Apertar continua livre, e a adesão inicial (de NONE para um modo com assinatura) também — naquele momento BAAS_ADMIN sozinho já movia o dinheiro.
  • O desafio é queimado por updateMany condicional. A API roda com duas réplicas; ler e depois gravar deixaria as duas ganharem.
  • Falha fechada. Sem fachada de biometria registrada, ou com ela indisponível, a resposta é 503 — nunca uma passagem livre.

Monolito vs. standalone. Em monolito, registerBaas monta tudo no container TypeDI e o MockBank recebe o PrismaClient e o callback de webhook, que simula o POST do provedor chamando o WebhookHandlerService direto. Em standalone — o modo de produção — o BaaS sobe na porta 3015 com MODULE_SELF=baas, e a única dependência de rede é o IAM, via MODULE_IAM_URL, para validação de token. A verificação da assinatura JWT é local em ambos os modos.


08

Conceitos e modelo de dados

Glossário

TermoSignifica
Provider configConfiguração de um provedor bancário para uma organização: tipo, credenciais cifradas e ajustes. Uma organização pode ter várias, e uma delas é a padrão.
ProviderImplementação da interface BaaSProvider para um banco específico. Instanciada por requisição a partir da config.
Tipo canônicoFormato interno neutro (CanonicalAccount, CanonicalPixTransaction, ...) para o qual todo provedor traduz. É o contrato que isola o serviço do banco.
externalIdIdentificador do recurso no provedor. Único por (configId, externalId). É a chave de correlação com o mundo externo.
endToEndIdIdentificador único da transação Pix definido pela especificação do BACEN, com 32 caracteres. É a chave de conciliação entre o seu registro e o do banco.
DICTDiretório de Identificadores de Contas Transacionais — o cadastro de chaves Pix do Banco Central. POST /pix/keys/lookup consulta quem é dono de uma chave.
Chave EVPChave Pix aleatória, em formato UUID. É a única que o BaaS gera sem você informar valor.
EMV / BR CodeFormato do payload de QR Code Pix. O campo emvCode é o "copia e cola".
KYCVerificação de identidade do titular. O BaaS encaminha documentos ao provedor e reflete o status; a análise é do provedor.
MockBankProvedor simulado, com estado próprio no Postgres. Para desenvolvimento, teste e demonstração. Em produção só para organização com concessão do operador da plataforma (§9, …/simulated-provider) — ou listada em BAAS_SIMULATED_PROVIDER_ORGANIZATION_IDS, o fallback (§13); nunca ao lado de dinheiro real na mesma organização.
Política de autorizaçãoRegra por conta que diz quem precisa assinar uma escrita: NONE (comportamento atual), HOLDER_SIGNATURE (o titular), OPERATOR (uma lista de CPFs autorizados) ou QUORUM (representantes com alçada e vigência, n de m por faixa de valor — §14.9).
Chave de dispositivoChave pública ECDSA P-256 cadastrada para a conta. A privada nasce e morre no enclave do celular; o BaaS só guarda a pública e o keyId.
DesafioNonce de 32 bytes, uso único, validade de 120 s, que entra no payload assinado. É o que impede repetir uma assinatura.
Payload canônicoForma exata que o dispositivo assina: {v,type,accountId,challengeId,nonce,params} sem espaços, com chaves ordenadas e valores monetários como texto com duas casas (§14).
operationHashsha256 em hexadecimal do payload canônico. É o que amarra a sessão biométrica à operação.
MandatoA presença do titular concedida antecipadamente a uma máquina (régua de cobrança, workflow): escopo fechado de operações, limites, validade, revogável. Concedido por assinatura (mandate.grant) e reverificado a cada uso (§14).

Modelo de dados — schema baas no PostgreSQL. Dez modelos de domínio e quatro do simulador.

Modelo PrismaTabelaPropósitoCampos-chave
BaaSProviderConfigbaas.baas_provider_configsProvedor configurado para a organizaçãoproviderType, credentials (cifrado), isDefault, isActive, settings, webhookDeliveryId (endereço secreto de entrega, único global — §14), único (organizationId, name)
BaaSAccountbaas.baas_accountsConta bancária mantida no provedorexternalId, configId, status, purpose (rótulo de organização, default OWN — §15), bankCode, branchNumber, accountNumber, availableBalance, personId, businessId, único (configId, externalId)
BaaSPixKeybaas.baas_pix_keysChave Pix registrada para uma contakeyType, keyValue, status, deletedAt, único (accountId, keyType, keyValue)
BaaSTransactionbaas.baas_transactionsTransação Pix ou TED, entrada ou saídatransactionType, status, amount Decimal(15,2), endToEndId, isCredit, originalTransactionId, idempotencyKey (único por organização — é a trava da reserva), requestHash (o hash canônico do pedido, comparado na repetição), reconciliationClaimedAt (a reivindicação da varredura), único (accountId, externalId)
BaaSWebhookEventbaas.baas_webhook_eventsEvento cru recebido do provedoreventType, externalEventId, payload, processed, error, único (configId, externalEventId)
BaaSAuthorizationPolicybaas.baas_authorization_policiesQuem precisa assinar as escritas da contamode, holderDocument, requireBiometricAbove Decimal(15,2), operators, version, único (accountId)
BaaSDeviceKeybaas.baas_device_keysChave pública do celular do titular ou de um operadorpublicKey (SPKI DER base64), keyId, subjectKind, subjectDocument, status, enrollmentSessionId, único (accountId, keyId)
BaaSAuthorizationChallengebaas.baas_authorization_challengesNonce de uso único que entra no payload assinadononce, expiresAt, consumedAt
BaaSMandatebaas.baas_mandatesPresença do titular concedida a uma máquinascope[], maxAmountPerOperation, maxAmountPerDay, maxOperationsPerDay, maxOperations, notBefore, notAfter, status, a concessão guardada (grantDeviceId, grantChallengeId, grantNonce, grantSignature, grantOperationHash), usedCount, revokedByKind
BaaSMandateUsagebaas.baas_mandate_usagesContadores de um mandato por dia útilday (YYYY-MM-DD em America/Sao_Paulo), count, amount, único (mandateId, day)
BaaSBalanceHoldbaas.baas_balance_holdsSaldo travado com motivo, referência ao que o originou e vencimentoamount, reasonType, reasonText, externalReference, status, releasedAmount, settledAmount, settlementSeq, expiresAt, custody, providerHoldId, createdVia, idempotencyKey (único por organização — a trava da criação), requestHash
BaaSSimulatedProviderGrantbaas.baas_simulated_provider_grantsA concessão do provedor simulado a uma organização (G5, §13). Revogar não apaga a linha, e a próxima concessão é uma linha novaorganizationId, reason, grantedBy/grantedAt, revokedBy/revokedAt. Índice único parcial: uma concessão ativa (revoked_at IS NULL) por organização — só no SQL da migration
BaaSBalanceHoldEntrybaas.baas_balance_hold_entriesO razão do bloqueio: uma linha por ato, nunca reescritakind (CREATE/RELEASE/SETTLE/EXPIRE), amount, actorId, actorVia, mandateId, transactionId, failureReason, requestId (o pedido de quatro olhos que originou o ato; nulo na porta direta)
BaaSBalanceHoldRequestbaas.baas_balance_hold_requestsPedido de liberação ou consumo em duas etapas ("quatro olhos"): uma pessoa pede, outra decidekind, status, amount (resolvido na criação), reason (obrigatório), settlement (destino do consumo), requestedBy/requestedVia, decidedBy/decidedAt/decisionReason, entryId, transactionId, failureCode/failureReason. Índice único parcial: um pedido aberto (PENDING/EXECUTING) por bloqueio — só no SQL da migration
MockBankAccountbaas.mockbank_accountsEstado interno do banco simuladoexternalId, saldo, dados do titular, kycStatus
MockBankPixKeybaas.mockbank_pix_keysDICT do banco simuladokeyValue único globalmente
MockBankTransactionbaas.mockbank_transactionsExtrato do banco simuladoendToEndId, type, status
MockBankQrCodebaas.mockbank_qr_codesQR Codes emitidos pelo banco simuladoemvCode, expiresAt
MockBankHoldbaas.mockbank_holdsBloqueio como o banco simulado o guarda — não confundir com baas_balance_holds, que é o registro da plataformaexternalId, amount, status, reference
BaaSBalanceHoldDivergencebaas.baas_balance_hold_divergencesA divergência de bloqueio guardada: o gastável da conta saiu negativo, e a pergunta "onde foi parar este dinheiro?" espera explicação. Nada é corrigidostatus (OPEN/EXPLAINED), detectedVia, os números da primeira detecção (providerAvailable, ledgerHoldAmount, spendableBalance, gap) e da última (last*), detections, firstDetectedAt/lastDetectedAt, cause, explanation, explainedBy, explainedAt. Índice único parcial: uma aberta por conta — só no SQL da migration

O único (configId, externalEventId) em baas_webhook_events é o que dá idempotência ao recebimento de webhook: o mesmo evento reentregue pelo provedor é detectado e descartado antes de ser aplicado.

Enumerações

EnumValores
BaaSProviderTypeCELCOIN · FITBANK · QITECH · MOCKBANK
BaaSAccountStatusPENDING_KYC · KYC_IN_PROGRESS · KYC_REJECTED · ACTIVE · BLOCKED · CLOSED
BaaSAccountPurposeOWN (padrão) · ESCROW · COLLATERAL · SETTLEMENT — rótulo de organização, sem efeito bancário, jurídico ou de autorização (§15)
BaaSTransactionTypePIX_IN · PIX_OUT · TED_IN · TED_OUT · REVERSAL
BaaSTransactionStatusPENDING · PROCESSING · COMPLETED · FAILED · CANCELLED · REVERSED
BaaSPixKeyTypeCPF · CNPJ · EMAIL · PHONE · EVP
BaaSPixKeyStatusPENDING · ACTIVE · INACTIVE
KycStatusNOT_STARTED · PENDING · IN_PROGRESS · APPROVED · REJECTED · REQUIRES_UPDATE
BaaSAuthorizationModeNONE · HOLDER_SIGNATURE · OPERATOR · QUORUM
BaaSSigningRequestStatusCOLLECTING · APPROVED · EXECUTING · EXECUTED · FAILED · REJECTED · CANCELLED · EXPIRED
BaaSDeviceSubjectKindHOLDER · OPERATOR
BaaSDeviceKeyStatusACTIVE · REVOKED
BaaSMandateStatusACTIVE · REVOKED
BaaSMandateRevokerKindHOLDER · ADMIN — quem revogou o mandato
BaaSHoldReasonTypeLOAN · ADVANCE · COLLATERAL · GENERIC
BaaSHoldStatusACTIVE · RELEASED · SETTLED · EXPIRED — os dois últimos encerram, e só um moveu dinheiro
BaaSHoldCustodyLEDGER · PROVIDER — quem guarda o bloqueio
BaaSHoldDivergenceStatusOPEN · EXPLAINED — não há "corrigida": o bloco relata, não conserta
cause da divergênciaPROVIDER_FEE · EXTERNAL_DEBIT · REVERSAL · PROVIDER_DELAY · LEDGER_ERROR · OTHER — não é enum do banco: coluna TEXT com o conjunto fechado no Zod da rota (hold-divergences.router.ts)
BaaSHoldEntryKindCREATE · RELEASE · SETTLE · EXPIRE
BaaSHoldRequestKindRELEASE · SETTLE — criar bloqueio não passa por pedido
BaaSHoldRequestStatusPENDING · EXECUTING · EXECUTED · FAILED · UNRESOLVED · REJECTED — ver §9, "Pedido em duas etapas"
created_via do bloqueioHOLDER · MANDATE · ADMIN — não é enum do banco: coluna TEXT com o conjunto fechado no Zod da rota (holds.router.ts)

Como as onze tabelas se ligam

erDiagram
  BaaSProviderConfig ||--o{ BaaSAccount : "abre contas em"
  BaaSProviderConfig ||--o{ BaaSWebhookEvent : "recebe eventos de"
  BaaSAccount ||--o{ BaaSPixKey : "registra"
  BaaSAccount ||--o{ BaaSTransaction : "movimenta"
  BaaSAccount ||--o| BaaSAuthorizationPolicy : "exige assinatura conforme"
  BaaSAccount ||--o{ BaaSDeviceKey : "confia nas chaves"
  BaaSAccount ||--o{ BaaSAuthorizationChallenge : "emite desafios"
  BaaSAccount ||--o{ BaaSMandate : "concede mandatos"
  BaaSMandate ||--o{ BaaSMandateUsage : "conta por dia"
  BaaSTransaction ||--o| BaaSTransaction : "originalTransactionId no estorno"

  BaaSProviderConfig {
    string providerType "CELCOIN FITBANK QITECH MOCKBANK"
    string credentials "cifrado AES-256-GCM"
    bool isDefault
    bool isActive
  }
  BaaSAccount {
    string externalId "id no provedor"
    string configId
    string status
    decimal availableBalance "cache para listagem"
    string personId "Customers, sem FK"
    string businessId
  }
  BaaSPixKey {
    string keyType
    string keyValue
    string status
  }
  BaaSTransaction {
    string transactionType "PIX_IN PIX_OUT TED_IN TED_OUT REVERSAL"
    string status
    decimal amount "Decimal 15,2"
    string endToEndId "chave de conciliação"
    bool isCredit
  }
  BaaSWebhookEvent {
    string eventType
    string externalEventId "dedupe por configId"
    json payload
    bool processed
  }

Ciclo de vida da conta

stateDiagram-v2
  [*] --> PENDING_KYC : POST /accounts
  PENDING_KYC --> KYC_IN_PROGRESS : KYC enviado
  KYC_IN_PROGRESS --> ACTIVE : aprovado
  KYC_IN_PROGRESS --> KYC_REJECTED : reprovado
  KYC_REJECTED --> KYC_IN_PROGRESS : webhook kyc.requires_update
  ACTIVE --> BLOCKED : webhook account.blocked
  BLOCKED --> CLOSED : POST /accounts/:id/close ou webhook account.closed
  ACTIVE --> CLOSED : POST /accounts/:id/close ou webhook account.closed
  CLOSED --> [*] : terminal

Atenção. Quem move o estado é o provedor. O BaaS reflete, via resposta de submitKyc ou via webhook. Encerrar é a única transição que a sua aplicação inicia — e ela também passa pelo provedor antes de gravar. CLOSED é terminal: fechar de novo devolve 400.

Como o status de KYC do provedor vira status de conta — a regra é a mesma em AccountService.submitKyc, na consulta de KYC e no WebhookHandlerService:

Status de KYC no provedorStatus gravado na conta
APPROVEDACTIVE
REJECTEDKYC_REJECTED
Qualquer outro — NOT_STARTED, PENDING, IN_PROGRESS, REQUIRES_UPDATEKYC_IN_PROGRESS

Atenção. PENDING_KYC é escrito apenas pelos mapeadores de provedor, quando a conta nasce ou quando o provedor devolve esse status na criação. Nenhum webhook e nenhuma chamada de KYC volta a conta para PENDING_KYC: o evento kyc.requires_update cai no ramo default do handler e grava KYC_IN_PROGRESS, publicando baas.kyc.submitted. Se a sua interface exibe "documento precisa ser reenviado", leia o campo rejectedFields da consulta de KYC, não o status da conta.

Máquina de estados da transação — vale para Pix e TED, saída e entrada.

stateDiagram-v2
  [*] --> PENDING : POST /pix/transfers ou POST /ted
  PENDING --> PROCESSING : webhook transfer.created
  PROCESSING --> COMPLETED : webhook transfer.completed
  PROCESSING --> FAILED : webhook transfer.failed
  COMPLETED --> REVERSED : refund, só de PIX_IN
  FAILED --> [*] : terminal
  REVERSED --> [*] : terminal
  CANCELLED --> [*] : terminal, sem transição no código
DetalheO que acontece
Status inicialÉ o que o provedor devolveu em provider.initiate*Transfer() — não é fixado pelo BaaS
POST /transfers/:id/refundSó de PIX_IN e só se COMPLETED. Leva a original a REVERSED e cria uma transação nova REVERSAL, ligada pelo campo originalTransactionId
Entrada (PIX_IN, TED_IN)Nasce direto em COMPLETED: é criada pelo handler ao receber o webhook pix.received / ted.received — ou seja, o dinheiro já entrou quando o registro aparece
CANCELLEDTerminal, mas nenhum caminho do código leva a ele — está reservado para status vindo do provedor (§15)
GET /pix/transfers/:id e GET /ted/:idNão são consultas passivas: chamam o provedor e gravam o status novo se ele mudou. É o caminho de reconciliação para quando um webhook se perde

Tarifa — BaaSTransactionFee. Uma linha por tarifa aplicada a uma operação. Registrar não é cobrar: nenhuma linha desta tabela altera saldo nem fala com o provedor (§15).

CampoO que guarda
sourceDe onde veio o preço. PROVIDER: o fee que o banco devolveu no payload da transação. HOUSE: a tarifa da casa, decidida pelo Pricing Engine. UNPRICED: a operação aconteceu e o preço não foi apurado — ver a caixa abaixo
amountO que é devido agora. Zero quando a franquia cobre (e o preço cheio fica no retrato, em fullAmount) e zero em UNPRICED. Não é zerado pela isenção
payerBORROWER (o cliente do tenant) ou HOUSE (o tenant) — o vocabulário do Pricing Engine
operationTypeO que foi tarifado: o transactionType da transação (PIX_OUT, TED_OUT). É também a operation com que se pergunta o preço
pricingRuleId, pricingRuleVersionA regra que produziu o preço e a versão dela. Só em HOUSE
quoteSnapshotO retrato da cotação: a pergunta (operation, amount, occurrencesThisMonth), a resposta inteira do Pricing Engine e qual das tarifas da resposta é esta linha. Em UNPRICED, o motivo de não ter havido preço. Interno — não sai em nenhuma rota nem evento
waived, waiverReason, waivedByA isenção. Os três andam juntos: não existe linha isentada sem motivo e sem autor
chargeTransactionIdA transferência que cobrou esta tarifa, quando alguém cobrou

O retrato existe porque o par (pricingRuleId, pricingRuleVersion) não basta para explicar uma cobrança antiga: a regra pode ter sido apagada, e o Pricing Engine é stateless por desenho — não guarda o cálculo. A explicação mora junto do dinheiro.

UNPRICED é falha ABERTA, e é deliberado. Não "conserte". Se o Pricing Engine estiver fora do ar, lento além de 2 s, ou responder algo que não é uma cotação, a transferência acontece e a tarifa da casa é registrada com source = UNPRICED e valor zero. Recusar o Pix de um cliente porque o nosso motor de preço caiu seria puni-lo por um problema nosso. A tarifa não apurada fica como dívida registrada e visível (GET …/fees?filter[source]=UNPRICED), para alguém conciliar — ela não some.

É o oposto do portão de capacidade, do saldo gastável e da integridade da política (§14), que falham fechados. Não é inconsistência: aqueles impedem mover dinheiro errado, e ali não mover é o lado seguro; este só deixa de precificar, e aqui não cobrar é o lado seguro. A régua é "qual dos dois erros é irreversível?".

Três desfechos que parecem iguais e não são:

O que houveLinha gravadaConta na franquia
Nenhuma regra ativa cota a operação — não há tarifaNenhumaNão
A franquia cobriu — preço apurado, e é zeroHOUSE, amount = 0, fullAmount no retratoSim
O preço não foi apuradoUNPRICED, amount = 0, motivo no retratoSim — a operação aconteceu

Franquia. "Os N primeiros do mês são grátis" é regra do Pricing Engine (freeUnitsPerMonth), mas quem conta é o BaaS: o Pricing Engine não sabe quantas vezes esta conta usou no mês. Antes de pedir o preço, o BaaS conta as operações (não as linhas — uma cotação com duas tarifas é uma operação só) com linha HOUSE ou UNPRICED daquela conta e daquele operationType no mês corrente, e manda o número como occurrencesThisMonth. O mês é o do calendário de America/Sao_Paulo, não o do UTC: um Pix às 22h do dia 30 ainda é daquele mês. Se nem contar for possível, o BaaS não adivinha zero — a linha sai UNPRICED. A janela de concorrência dessa contagem está em §15.

Isenção é ato, não preço. Isentar não zera amount: a linha passa a dizer "custava X e foi isentada por fulano, por este motivo". waivedBy é sempre o usuário autenticado que chamou a rota — não é campo do corpo. Uma isenção modelada como preço zero apagaria de quanto se abriu mão.

Eventos publicados no barramento — 47 eventos (mais as recusas baas.lien.<operação>.refused|failed), consumíveis pelo Webhooks Engine com o filtro baas.*.

GrupoEventos
Contabaas.account.created · baas.account.updated · baas.account.closed · baas.account.blocked
KYCbaas.kyc.submitted · baas.kyc.approved · baas.kyc.rejected
Pixbaas.pix.key.created · baas.pix.key.deleted · baas.pix.transfer.initiated · baas.pix.transfer.completed · baas.pix.transfer.failed · baas.pix.received · baas.pix.refunded
Boletobaas.boleto.settled — a cada aviso de pagamento do banco: boletoId (nosso, ou null se o título não é conhecido), subaccountId, externalId, ourNumber, amount (face), settledAmount, settledAt, firstSettlement (este aviso liquidou?), settlementTransactionId (a linha BOLETO_IN do extrato, quando liquidou), previousStatus (duplicidade e pago após baixa chegam com false) e needsReview (dois títulos com o mesmo nosso número na conta: nada liquidado). O nosso número só casa DENTRO da conta avisada. A liquidação é reivindicada e cria o crédito na mesma transação. baas.boleto.sandbox_payment / baas.boleto.sandbox_payment_refused: o pagamento simulado pedido pela rota de sandbox (quem, quanto)
TEDbaas.ted.transfer.initiated · baas.ted.transfer.completed · baas.ted.transfer.failed · baas.ted.received
Bloqueio de saldobaas.hold.created · baas.hold.released · baas.hold.settled · baas.hold.expired · baas.hold.provider.pending · baas.hold.divergence.detected · baas.hold.request.created · baas.hold.request.approved · baas.hold.request.failed · baas.hold.request.unresolved · baas.hold.request.rejected
Divergência de bloqueio guardadabaas.hold.divergence.explained — alguém explicou (causa e autor; o texto não vai)
Trava de recebíveisbaas.lien.created · baas.lien.activated · baas.lien.captured · baas.lien.fulfilled · baas.lien.cancelled · baas.lien.expired · baas.lien.cancel.requested · baas.lien.capture.failed · e a recusa de cada operação, baas.lien.<create|activate|cancel|abandon|list|read>.refused|failed
Tarifabaas.fee.applied · baas.fee.waived
Autorizaçãobaas.authorization.granted · baas.authorization.denied · baas.authorization.policy.updated · baas.authorization.policy.changed · baas.authorization.device.enrolled · baas.authorization.device.revoked · baas.authorization.mandate.granted · baas.authorization.mandate.revoked

Payload de baas.authorization.granted e baas.authorization.denied. Além de organizationId e accountId: type (a operação), operationHash, deviceId, keyId, biometricSessionId, mandateId (null quando o titular estava presente) e, na negativa, reason (o código fechado de §9). Quando o ato foi feito sob mandato, deviceId/keyId são os da chave que concedeu o mandato e mandateConsumed diz quanto dele este ato gastou: usedCount, dayCount, dayAmount. A assinatura e o nonce nunca são publicados — a trilha diz o que foi autorizado, não como. baas.authorization.mandate.granted leva o escopo, os limites, a janela e o grantOperationHash; .mandate.revoked leva revokedByKind (HOLDER ou ADMIN).

Payload de baas.authorization.policy.changed (BB-5). É a linha que o portão confere a política contra, e por isso é publicada na mesma transação que grava a linha, sob a trava da conta: accountId, policyHash (SHA-256 do JSON canônico de {v:1, policyId, accountId, mode, holderDocument, requireBiometricAbove, operators, version} — o policyId é o sal, não viaja na trilha e, desde a revisão de segurança deste PR, também não sai no GET — ver §14), mode, version, previousVersion, holderDocument mascarado, requireBiometricAbove, operatorsCount e bootstrap (true na ancoragem inicial, que também carimba actorType: system). O CPF nunca sai. O .policy.updated continua sendo publicado, como antes, para quem já o consome.

Payload de baas.hold.expired e baas.hold.divergence.detected. O primeiro sai da varredura de vencimento, uma vez por bloqueio, com accountId, holdId, expiredAmount, currency, custody, externalReference e expiresAt. expiredAmount é o que ainda travava saldo quando o prazo passou (amount − released − settled), não o valor cheio: um bloqueio de R$ 100 mil com R$ 70 mil já liberados expira R$ 30 mil, e é esse o número que volta a ser gastável. reasonText nunca vai, como em baas.hold.created.

O segundo sai quando o saldo gastável fica negativo — alguém gastou, por fora do bloco, dinheiro que aqui estava travado. Leva accountId, providerAvailable (o disponível como o banco o informa), ledgerHoldAmount (a soma do que nós escrituramos) e gap (quanto do bloqueado já não existe no banco). Ele é um aviso, não o começo de um conserto: nada é ajustado, nem o saldo nem nenhum bloqueio — ver §15. No caminho de leitura (GET …/balance) o aviso é emitido no máximo uma vez por conta por BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES (§13); na conferência pedida (POST …/holds/reconcile), sempre. Leva também divergenceId e divergenceStatus: toda vez que o aviso sai, a divergência é guardada (GET /hold-divergences) — uma linha aberta por conta, atualizada a cada nova detecção. Se guardar falhar, o aviso sai assim mesmo, com divergenceId: null. baas.hold.divergence.explained sai uma vez por divergência, com divergenceId, cause, gap e explainedBy; o texto da explicação não vai.

Payload de baas.hold.request.* (quatro olhos). Os três levam accountId, holdId, requestId, kind (RELEASE/SETTLE), amount, status, requestedBy, decidedBy, transactionId e failureCode, e carimbam metadata.userId com quem agiu (quem pediu em .created, quem decidiu nos outros dois) e metadata.actorType — é o que a trilha lê para dizer QUEM. O desfecho da aprovação sai uma vez por pedido, e o NOME diz qual foi: .approved só quando o ato aconteceu (EXECUTED), .failed quando nada saiu do bloqueio, .unresolved quando o valor saiu e o banco não respondeu. Três nomes, e não um .approved com o estado dentro, porque quem assina approved quer saber que o dinheiro se moveu — um approved que às vezes significa "nada aconteceu" faria mentir todo consumidor que não lê status. A varredura de pedido preso publica os mesmos três, com actorType: system. O ato em si publica também o seu baas.hold.released/settled. O motivo do pedido e o da recusa nunca vão: são texto de quem escreveu, a mesma régua do reasonText do bloqueio. Na trilha, baas.hold.request.* vira o recurso baas_hold_request (pelo requestId) e o resto de baas.hold.* vira baas_balance_hold (pelo holdId) — antes caíam no espaço cru baas com a organização como recurso.

Payload de baas.fee.applied e baas.fee.waived. O primeiro diz que houve tarifa, não que houve débito; sai uma vez por linha registrada, com accountId, transactionId (quando há), feeId, operationType, amount, currency, payer, source e, em HOUSE, pricingRuleId e pricingRuleVersion. Com source = UNPRICED ele é o aviso de que o preço não foi apurado — quem fatura em cima deste evento precisa olhar source antes de ler amount = 0 como "de graça". O segundo sai uma vez por tarifa, mesmo com as duas réplicas, e leva feeId, amount (o valor cheio), currency, operationType, source, waiverReason e waivedBy. O retrato da cotação não viaja em nenhum dos dois.

Payload de baas.lien.* (trava de recebíveis). Nenhum leva documento, chave Pix nem a descrição da trava: ids, valores em centavos e a externalReference (o título, por onde a esteira concilia). baas.lien.created: lienId, accountId, amountCents, expiresAt, externalReference, status (ACTIVE ou PENDING_ACCEPTANCE), acceptanceDeadline (ISO, só na pendente), consentVia (HOLDER/ADMIN), mandateId, sourceDocumentCount. baas.lien.activated — uma vez por trava (a virada PENDING_ACCEPTANCE → ACTIVE é reivindicada; ativar de novo não publica): lienId, accountId, externalReference, amountCents, activatedAt. baas.lien.captured — uma vez por captura, quando o dinheiro chegou ao destino (a virada HELD → SETTLED é reivindicada): lienId, accountId, captureId, capturedCents, remainingCents, totalCapturedCents, inboundEndToEndId, inboundTransactionId, settlementId (a transferência de saída), holdId, externalReference. baas.lien.fulfilled: totalCents. baas.lien.cancelled e baas.lien.expired: remainingCents (amount − capturado; é o que a esteira passa a cobrar do cedente), inFlightCents, capturedCents e, no cancelamento, cause (OPERATOR com requestedBy/decidedBy, ou ABANDONED com wasPending). No vencimento da pendente que ninguém ativou, baas.lien.expired leva reason: 'acceptance-timeout' (nada foi capturado; o mandato nascido com ela é revogado). baas.lien.capture.failed: code, requestedCents, remainingCents, holdId e holdLeftActive — true quando o bloqueio ADVANCE nasceu e o consumo foi recusado (mandato revogado, por exemplo): o bloqueio fica ATIVO para um operador decidir pelo pedido de quatro olhos, e o valor volta ao restante da trava.

Trava de recebíveis futuros

Um bloqueio congela dinheiro que existe. A trava (BaaSLien) é um direito permanente sobre dinheiro que vai chegar: "o que entrar nesta conta, vindo destes pagadores, até R$ X, vai para aquela conta". Ela não move dinheiro por conta própria — na captura vira um bloqueio ADVANCE e o consumo desse bloqueio, pela mesma máquina do bloqueio (custódia, divergência, conciliação).

CampoO que é
amount / capturedAmount / reservedAmountValor travado; já transferido; reservado por capturas em curso. O restante é amount − capturado − reservado, derivado
destination{ accountId } (conta da MESMA organização, ativa, com chave Pix ativa — a captura paga nela) ou { pixKey } (nunca chave da própria conta travada)
sourceDocumentsCPFs/CNPJs dos pagadores capturados (até 20, só dígitos). Vazio = qualquer crédito — quem cria decide; o banking recusa vazio porque o desembolso cai na mesma conta
externalReferenceA operação/título que a trava garante
expiresAtNo máximo 12 meses (o teto do mandato)
statusPENDING_ACCEPTANCE (só com pendingAcceptance: true: consentida, não captura) → ACTIVE pela ativação explícita · ACTIVE → FULFILLED (capturou tudo) · CANCELLED (quatro olhos, ou o aceite que a criou não se concluiu) · EXPIRED (prazo com saldo, ou a pendente que ninguém ativou no prazo do aceite)
acceptanceDeadline / activatedAtAté quando a pendente espera a ativação (BAAS_LIEN_PENDING_ACCEPTANCE_MINUTES, padrão 30); quando foi ativada. Nulos na trava que nasceu ACTIVE
consentVia / mandateIdHOLDER com o mandato nascido junto; ADMIN em conta sem política

Consentimento. Em conta com política (§14), criar é presença sobre a operação canônica lien.create — a selfie pesa contra o valor da trava, como numa transferência desse valor —, e a mesma assinatura concede o mandato hold.settle (teto por operação = valor da trava, validade = o vencimento). Esse mandato (grantType = lien.create) só responde pela captura desta trava: em qualquer outra chamada — a rota direta de consumo, o quatro olhos, outra trava — o portão recusa com MANDATE_BOUND; e a cada captura o portão reconfere que os termos da linha da trava são os que o titular assinou (destino trocado no banco = MANDATE_INVALID). Conta sem política: quem consente é o tenant (BAAS_ADMIN), a trava nasce consentVia = ADMIN e sem mandato — o mesmo regime de um Pix nessa conta. Conta QUORUM não cria trava (o portão pede pedido de assinatura, que não cobre lien.create).

Pendente até o aceite (22/10). Achado do smoke de staging: o painel recusou o aceite do crédito (409 PROPOSAL_UNAVAILABLE), mas a trava já nascera ACTIVE e capturou o PIX_IN seguinte para o fundo — dinheiro saiu da conta do cedente sem operação de crédito. Desde então o banking cria a trava com pendingAcceptance: true: ela nasce PENDING_ACCEPTANCE, com consentimento e mandato completos, mas a captura a ignora. O banking chama o serviço de crédito; aceito, ativa (POST /liens/:id/activate, idempotente pela externalReference); recusado, desfaz (abandon). Se o app ou a rede morrer no meio, a pendente vence sozinha no prazo do aceite (varredura, acceptance-timeout) e nunca captura. Ativação depois do prazo falha fechada (409 LIEN_ACCEPTANCE_EXPIRED, e a trava é vencida ali mesmo). Só créditos que entram depois da ativação são capturados: o que chegou enquanto pendente não é capturado retroativamente. Sem pendingAcceptance, a trava nasce ACTIVE como sempre.

Captura. Todo PIX_IN/TED_IN gravado pelo webhook passa pela captura (sem segurar a resposta ao provedor). Para cada trava ACTIVE da conta que já valia quando o crédito entrou (criada antes dele, ou — a que nasceu pendente — ativada antes dele), em ordem de criação (FIFO): filtra pela contraparte; reserva min(crédito restante, restante da trava) sob atualização condicionada aos acumuladores; bloqueia (ADVANCE, a referência da trava, chave derivada da captura); consome para o destino citando o mandato (chave derivada); só então move a reserva para o capturado. O mesmo crédito nunca é capturado duas vezes pela mesma trava: índice único (lien_id, inbound_end_to_end_id) (o endToEndId, ou tx:<externalId> na TED sem E2E), CHECK captured + reserved ≤ amount no banco, e a virada condicionada de cada estado. Reenvio de webhook, duas réplicas, a varredura e o caminho ao vivo ao mesmo tempo: uma captura (provado contra Postgres em tests/integration/baas/receivables-lien.integration.test.ts).

Payload de baas.pix.received e baas.ted.received. O BaaS não expõe rota para ler uma transação, então esses dois eventos carregam a própria transação criada (PIX_IN / TED_IN) — quem consome não precisa de outra chamada para saber o valor e o pagador. Além de organizationId, accountId e transactionId (inalterados), vão: amount (número), transactionType (PIX_IN ou TED_IN), externalId, counterpartyName, counterpartyDocument, counterpartyPixKey (só Pix; null em TED), counterpartyBankCode, counterpartyBranch, counterpartyAccount, description, endToEndId (só Pix; null em TED) e processedAt (ISO 8601). Campo que o provedor não mandou vem como null.


09

Referência da API

Prefixo: /baas. Em standalone, a base é https://baas.bb.stg.catalisa.app.

Todas as rotas de negócio — as 58 fora de /webhooks — exigem, nesta ordem: authMiddleware (Bearer JWT válido), requirePermission(...) e requireOrganization (o token precisa carregar organizationId, senão 403). As permissões são apenas duas: BAAS_READ para leitura e BAAS_ADMIN para qualquer escrita.

Prefixo duplicado. Todo router está montado duas vezes: em /baas/api/v1/{recurso} (canônico) e em /baas/api/v1/baas/{recurso} (compatibilidade com clientes e testes antigos). Use o canônico em código novo; o segundo existe e funciona, mas não é o caminho preferencial.

Configurações de provedor — /baas/api/v1/provider-configs

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/provider-configsCria config, testa a conexão e cifra as credenciais. 201. 403 (com details.code: SIMULATED_PROVIDER_NOT_GRANTED — leia o código, não a mensagem) em produção para MOCKBANK ou settings.sandbox: true em organização sem concessão do provedor simulado e fora da variável de fallback (o PATCH que marca sandbox recusa igual) — ver Operador da plataforma, abaixoBAAS_ADMIN
GET/baas/api/v1/provider-configsLista, paginado. Filtros filter[providerType], filter[isActive]BAAS_READ
GET/baas/api/v1/provider-configs/:idBusca por IDBAAS_READ
PATCH/baas/api/v1/provider-configs/:idAtualiza. Se enviar credentials, testa antes de gravarBAAS_ADMIN
DELETE/baas/api/v1/provider-configs/:idExclusão lógica. 204BAAS_ADMIN
POST/baas/api/v1/provider-configs/:id/set-defaultMarca como padrão e desmarca as outrasBAAS_ADMIN
POST/baas/api/v1/provider-configs/:id/testTesta a conexão com as credenciais gravadasBAAS_ADMIN
POST/baas/api/v1/provider-configs/:id/webhook-deliveryGera ou rotaciona o endereço secreto de entrega do webhook e devolve a URL a colar no painel do provedor. É a única resposta que traz o segredo inteiro — nas leituras ele sai mascarado para quem não é BAAS_ADMIN (§14). Rotacionar invalida o anterior na hora e não mexe em credencialBAAS_ADMIN

Operador da plataforma — /baas/api/v1/admin/platform

A concessão do provedor simulado por organização (G5). É o caminho normal para deixar uma organização de demonstração pronta em produção: uma chamada, sem editar env de serviço nem reiniciar o bloco.

MétodoRotaDescriçãoQuem
GET/baas/api/v1/admin/platform/organizations/:organizationId/simulated-providerO estado: granted (há concessão ativa, com reason, grantedBy, grantedAt), allowedByEnvironment (a variável de fallback — ou NODE_ENV fora de produção — já libera) e allowed (o veredito de agora)operador da plataforma
PUT/baas/api/v1/admin/platform/organizations/:organizationId/simulated-provider { reason }Concede. reason obrigatório (até 500 caracteres; sem ele, 400 no formato de erro do bloco: { error: 'VALIDATION', message, details: [{ field, message, code }] }). Sem CPF nem CNPJ no texto — CPF, CNPJ ou CNPJ alfanumérico, colados ou separados por ponto, hífen, espaço ou barra, dão 400 com details[].code: SIMULATED_PROVIDER_REASON_HAS_DOCUMENT, nada publicado nem gravado (11 dígitos colados também, mesmo sendo celular: escreva (11) 98765-4321). O motivo vai à trilha da organização do operador, nunca à do cliente. Idempotente: repetir devolve 200 com a concessão que já existe — motivo e autor originais, nenhuma linha nova, nenhum evento novo. O autor é quem está autenticado, nunca campo do corpo. 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE se a trilha não confirmou o evento ou não está lendo o stream do operador (details.reason: NO_TRAIL_READER — audit-trail em build antigo ou desligado, §13): nada foi gravado. 503 SIMULATED_PROVIDER_NOT_RECORDED se o evento saiu e a gravação falhou: a concessão não existe; repetir é segurooperador da plataforma
DELETE/baas/api/v1/admin/platform/organizations/:organizationId/simulated-providerRevoga — todas as concessões ativas da organização (uma, com o índice único no lugar). 204 só quando não resta nenhuma ativa; 404 SIMULATED_PROVIDER_GRANT_NOT_FOUND se não havia (a mensagem diz que a organização não tem concessão ativa — o id do caminho é o dela); 409 SIMULATED_PROVIDER_STILL_GRANTED se alguém concedeu de novo durante a revogação. 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE se a trilha não confirmou o evento: nenhuma linha foi tocada e a organização SEGUE concedida. 503 SIMULATED_PROVIDER_NOT_RECORDED se o evento saiu e a gravação falhou: idem, segue concedida. A linha revogada fica, com revokedBy/revokedAt, e nunca volta a ativaoperador da plataforma
DELETE…/simulated-provider?force=trueRevogação de emergência, para a trilha fora do ar: grava a revogação mesmo sem a publicação confirmada. Responde 200 com grantIds e trail: 'confirmed' | 'unconfirmed'. Em unconfirmed, o registro do ato é um log em error com operador, organização e grantIds. force fora de true/false é 400. Não existe force para concederoperador da plataforma
  • Operador da plataforma é a mesma noção do banking (@shared/middleware/platform-operator.middleware, a função é uma só): permissão IAM_ORGANIZATIONS_UPDATE E organização do token em BANKING_PLATFORM_ORGANIZATION_IDS. O iam não tem conceito de plataforma — o ADMIN de toda organização tem toda permissão —, então só a permissão não basta. Lista vazia ou ausente: 403 para todos. Escopo de subconta: 403 SUBACCOUNT_SCOPE_FORBIDDEN. A organização alvo vem do caminho; a de quem chama, do token. Estas rotas são as únicas do bloco que não usam BAAS_READ/BAAS_ADMIN e não estão no prefixo duplicado.
  • A variável tem o nome do banking e tem de estar no serviço do baas. BANKING_PLATFORM_ORGANIZATION_IDS nasceu no banking e o nome foi mantido para não criar env nova; o baas roda em serviço próprio e lê o env dele. Sem ela gravada no bb-baas, estas rotas respondem 403 a todos (falha fechada) e a trava segue decidindo só pela variável de fallback. É configuração única — não se repete a cada organização.
  • Revogar não apaga nem desativa nada. As configurações que a organização já criou continuam ativas e servindo. A trava é de criação e de marcação (PATCH com settings.sandbox: true), como sempre foi: depois da revogação, o que volta a ser recusado é criar uma configuração simulada nova. Quem quer tirar o simulado do ar desativa a configuração (PATCH isActive: false) ou a exclui.
  • A trilha pode ter um registro a mais, nunca um a menos; o estado nunca volta atrás. O repo não tem outbox (publicação na mesma transação do ato), então a ordem é publicar antes de gravar, e não existe "desfazer" em lugar nenhum:
    • conceder — o id da concessão é gerado antes, o evento sai com ele e só com a publicação confirmada (até 2 s) a linha é inserida. Sem confirmação: 503, e a tabela não foi tocada. Não há instante em que a trava enxergue uma concessão não confirmada;
    • revogar — os grantIds ativos são lidos, o evento sai com eles e só então revokedAt/revokedBy são gravados. Sem confirmação: 503, as linhas intactas, a organização segue concedida — e quem chamou sabe (a resposta diz, e sai log em error);
    • gravação que falha depois do evento — 503 SIMULATED_PROVIDER_NOT_RECORDED: sobra na trilha o evento de um ato que não valeu. Repetir é seguro. O mesmo vale para a publicação que estoura o prazo e chega depois, e para duas chamadas simultâneas (cada uma publica; a linha é escrita uma vez);
    • a tabela de concessão nunca perde linha e nenhuma linha é reativada. As duas únicas escritas são inserir e marcar a revogação.
  • Com a trilha fora do ar não se concede, e só se revoga com force. Para conceder a falha é fechada. Para revogar, a falha é "sem mudança" — e a saída de emergência é DELETE …?force=true, só do operador da plataforma: revoga sem a confirmação, tenta publicar em melhor esforço (o evento leva forced: true), loga em error com operador, organização e grantIds, e responde trail: 'unconfirmed'. É o único caso em que há revogação sem evento garantido, e ele é escolhido por quem chama, com o log como registro. Tirar a organização de BAAS_SIMULATED_PROVIDER_ORGANIZATION_IDS não revoga uma concessão feita pela API.
  • O que sai, e onde. baas.simulated-provider.grant.created e baas.simulated-provider.grant.revoked (este com grantIds, todas as linhas revogadas) saem na trilha da organização alvo, com o operador como autor e a organização dele em operatorOrganizationId. Na trilha a revogação é uma escrita (UPDATE) na concessão. grant.created não leva o reason: a trilha da organização alvo é lida pelo cliente (GET /audit-trail/api/v1/logs), e texto livre de operador não é dado dele. O motivo sai num evento próprio, baas.simulated-provider.grant.reason.recorded, gravado na trilha da organização do operador (a do token que concedeu), com grantId, targetOrganizationId, reason, grantedBy e grantedAt; depois de revogada, a concessão some do GET, e é esse registro — e a linha da concessão, que não é apagada — que responde "por que esta organização teve o simulado?". É texto livre do operador — tem teto (500), é recusado se trouxer algo com forma de CPF/CNPJ e não vai a log. Os dois eventos saem pelo stream do operador (abaixo), nunca pelo webhook do cliente, e os dois são confirmados antes de gravar. Token de operador sem organização: o motivo fica só na linha da concessão. O evento da revogação não repete o motivo: leva os grantIds.
  • A recusa é diferente: log sempre, evento de melhor esforço. A recusa da trava (criação ou PATCH) loga sempre e publica baas.simulated-provider.refused na trilha da organização de quem tentou, sem segurar o 403 — se a trilha estiver fora, fica o log. Este evento é um ato do CLIENTE (a organização dele tentou criar configuração simulada), não do operador — e mesmo assim não vai ao webhook dele, de propósito: está sob o prefixo baas.simulated-provider. e segue só para a trilha. O cliente vê a recusa na resposta 403; o que não se entrega por webhook é o evento que revela a existência da trava e de quem a concede. Já era assim antes do stream próprio (o prefixo estava na lista do consumidor). As respostas de erro destas três rotas logam sempre ("operação de plataforma recusada") e publicam baas.simulated-provider.grant[.read|.revoke].<desfecho> na trilha da organização de quem tentou, com targetOrganizationId: o 403 de quem não é da plataforma fica na trilha dele, não na da plataforma nem na da organização alvo. O desfecho destas rotas é o preciso: refused (401/403/409, na trilha ACCESS_DENIED), not_found (404 — não havia concessão a revogar) e invalid (400 de validação) — os dois últimos entram na trilha como ACCESS, porque não são acesso negado; throttled e failed como nas demais. As rotas de bloqueio, pedido, divergência, Pix e TED não mudaram: todo 4xx delas segue …refused. O 401 (e qualquer token sem organização) não vai à trilha — ela é por organização e não tem onde gravar; o registro é o log.
  • Estes eventos não entram no barramento que o webhook lê. O prefixo baas.simulated-provider. está na lista de eventos do operador da plataforma (src/shared/lib/operator-events.ts), e o EventPublisher grava esses eventos em outro stream, platform-operator-events, que só o audit-trail consome. O consumidor de webhook lê iam-events: o que não está lá não é entregue a assinatura nenhuma — nem à padrão baas.*, nem a *, nem a filtro exato — por nenhuma versão do webhooks-engine, inclusive uma réplica de build antigo. A garantia vale a partir do momento em que o baas roda com esta versão; ela não é retroativa nem cobre um baas de build antigo, que ainda publica no iam-events (ver §13, Eventos do operador e rollout). A trilha recebe igual: organização alvo, operador como autor, mesmo tipo de recurso e mesmas ações. A frase que estava aqui até 11/10/2026 ("nenhum destes eventos chega ao webhook do cliente") dependia de todo consumidor ter o filtro, e nesse dia uma réplica órfã com código de 25/09 os entregou em staging, com actorId, grantedBy e operatorOrganizationId no payload.
  • O índice único não é premissa do código. "Uma concessão ativa por organização" é um índice único parcial, que só o SQL da migration cria (o Prisma não o declara). Medido: o prisma db push o mantém, e ele não entra na lista de DROP do prisma/pre-db-push.sql. Ainda assim o código está certo sem ele — "há concessão ativa?" vale com mais de uma linha, e revogar revoga todas. A verificação da tabela e do índice é o VERIFICAR_FILE do bloco (scripts/launch/verificar/baas-simulated-provider-grants.txt, ver §13, Subida em ambiente); se o índice faltar, reaplicar a migration o devolve (é idempotente).
  • Limites conhecidos, fora desta fatia. (1) credentials.sandbox: 'true' num provedor real (Celcoin, QI Tech, FitBank) aponta para o sandbox do banco sem passar pela trava: a trava cobre o que aceita evidência de teste (MOCKBANK e settings.sandbox: true), e essa chave está em credentials, não em settings. (2) A concessão não confere se a organização alvo já tem provedor real ativo — "nunca ao lado de dinheiro real na mesma organização" é regra de operação, não trava de código: quem concede confere antes. Conferir só na concessão seria meia garantia (não impediria criar o provedor real depois); as duas direções ficam para a próxima fatia.
  • A organização alvo é conferida só na forma (uuid): o baas não consulta o iam para saber se ela existe.

Contas — /baas/api/v1/accounts

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/accountsAbre conta no provedor e registra localmente. Aceita purpose (opcional; omitido, nasce OWN). 201BAAS_ADMIN
GET/baas/api/v1/accountsLista, paginado. Filtros filter[status], filter[purpose], filter[personId], filter[configId]. Rótulo fora do conjunto é 400, não lista vaziaBAAS_READ
GET/baas/api/v1/accounts/:idBusca por IDBAAS_READ
PATCH/baas/api/v1/accounts/:idAtualiza titular no provedor e/ou metadata/purpose locais. Com holder, exige holderAuthorization na conta que aderiu (§14). Reetiquetar sozinho é escrita local: não chama o provedor e não passa pelo portãoBAAS_ADMIN
POST/baas/api/v1/accounts/:id/closeEncerra a conta. Exige reason. Gated (§14)BAAS_ADMIN
GET/baas/api/v1/accounts/:id/balanceSaldo consultado no provedor a cada chamada, mais ledgerHoldAmount e spendableBalance — os campos antigos não mudam de significadoBAAS_READ
POST/baas/api/v1/accounts/:id/kycEnvia documentos de KYC. Gated (§14)BAAS_ADMIN
GET/baas/api/v1/accounts/:id/kycConsulta o status de KYC no provedorBAAS_READ
POST/baas/api/v1/accounts/:id/sandbox/depositSó MockBank. Credita saldo para testeBAAS_ADMIN

Bloqueio de saldo — /baas/api/v1/accounts/:id/holds

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/accounts/:id/holdsTrava parte do saldo com motivo. Exige amount e reasonType; aceita reasonText (≤ 500), externalReference, expiresAt e idempotencyKey (uuid, no corpo — ver a caixa "Reenviar a criação" abaixo). Não exige holderAuthorization nem mandateId — ver a caixa abaixo. Publica baas.hold.created. 201 novo · 200 repetição da chave · 202 repetição com a chamada ao banco sem desfecho (meta.inFlight, não reenvie) · 409 IDEMPOTENCY_KEY_REUSEDBAAS_ADMIN
GET/baas/api/v1/accounts/:id/holdsLista os bloqueios da conta, ativos e encerrados. Filtros filter[status], filter[reasonType], filter[externalReference] — este último é como a esteira acha os bloqueios de uma operação de crédito. Paginado; filtro fora do conjunto é 400, não lista vaziaBAAS_READ
GET/baas/api/v1/accounts/:id/holds/:holdIdA linha viva: valor, acumuladores e activeAmount (amount − released − settled)BAAS_READ
GET/baas/api/v1/accounts/:id/holds/:holdId/entriesO razão do bloqueio, uma linha por atoBAAS_READ
POST/baas/api/v1/accounts/:id/holds/:holdId/releaseDevolve poder de gasto. Porta direta, só para credencial de máquina (chave de API ou token client_credentials): pessoa autenticada recebe 403 HOLD_DIRECT_ACTION_MACHINE_ONLY e vai pelo pedido. Na conta que aderiu à política, exige presença ou mandato hold.releaseBAAS_ADMIN + máquina
POST/baas/api/v1/accounts/:id/holds/:holdId/settleO bloqueio vira Pix ou TED. Porta direta, só para máquina, como a de cima. Presença ou mandato hold.settle na conta que aderiu. 201/200 replayed/202 inFlightBAAS_ADMIN + máquina
POST/baas/api/v1/accounts/:id/holds/:holdId/requestsPede liberar (kind: RELEASE) ou consumir (SETTLE), com reason obrigatório (≤ 500). O autor é quem está autenticado. amount omitido na liberação pede o que resta — resolvido agora. 409 HOLD_REQUEST_ALREADY_OPEN se o bloqueio já tem pedido aberto. Publica baas.hold.request.created. 201BAAS_ADMIN
GET/baas/api/v1/accounts/:id/holds/:holdId/requestsOs pedidos deste bloqueio, abertos e decididos. filter[status]BAAS_READ
GET/baas/api/v1/accounts/:id/holds/:holdId/requests/:requestIdUm pedidoBAAS_READ
POST/baas/api/v1/accounts/:id/holds/:holdId/requests/:requestId/approveOutra pessoa aprova, e o ato acontece pelo mesmo caminho da porta direta. Aceita holderAuthorization ou mandateId. 403 HOLD_REQUEST_SAME_ACTOR (quem pediu), 403 HOLD_REQUEST_DECIDER_NOT_PERSON (máquina), 409 HOLD_REQUEST_ALREADY_DECIDEDBAAS_ADMIN + pessoa
POST/baas/api/v1/accounts/:id/holds/:holdId/requests/:requestId/rejectRecusa, com reason obrigatório. Quem pediu pode retirar o próprio pedidoBAAS_ADMIN + pessoa
GET/baas/api/v1/hold-requestsA fila da organização: filter[status]=PENDING, filter[kind], filter[accountId]. Paginado, sem totalBAAS_READ
GET/baas/api/v1/hold-requests/:requestIdUm pedido, sem precisar saber a contaBAAS_READ
POST/baas/api/v1/accounts/:id/holds/:holdId/resumeRetoma a criação no banco de um bloqueio pendingReconciliation (ver a caixa "Reenviar a criação"). Responde o bloqueio e meta.outcome: STAMPED, COMPENSATED, STILL_PENDING, NOTHING_TO_DO ou SKIPPED (outra retomada em curso). Só credencial de máquina (regra do #500): um dos desfechos libera a linha no razão, a direção que afrouxa, e pessoa não tem porta direta para afrouxar. A varredura faz o mesmo sozinhaBAAS_ADMIN + máquina
POST/baas/api/v1/accounts/:id/holds/reconcileConfere contra o banco e relata. Não conserta nada. Lê o disponível no provedor agora, soma os bloqueios escriturados e devolve providerAvailable, ledgerHoldAmount, spendableBalance, gap, divergent e corrected: false. Gastável negativo publica baas.hold.divergence.detected. 200 mesmo quando há divergência — divergência é um fato sobre a conta, não erro de requisiçãoBAAS_ADMIN
GET/baas/api/v1/hold-divergencesAs divergências guardadas da organização. filter[status]=OPEN é a fila do que ainda não foi explicado; filter[accountId]. Paginado, sem total. A conferência acima devolve o divergenceId da linhaBAAS_READ
GET/baas/api/v1/hold-divergences/:divergenceIdUma divergência: os números da primeira e da última detecção, quantas vezes foi vista, e a explicaçãoBAAS_READ
POST/baas/api/v1/hold-divergences/:divergenceId/explanationExplica, uma vez: cause (conjunto fechado) e explanation (≤ 1000, obrigatório). O autor é quem está autenticado. 409 HOLD_DIVERGENCE_ALREADY_EXPLAINED se alguém já explicou. Não corrige nada — nem bloqueio, nem saldo. Publica baas.hold.divergence.explainedBAAS_ADMIN

Criar bloqueio é livre, liberar e consumir não são. Isso é deliberado. A régua da casa é apertar é livre, afrouxar se assina — a mesma do PUT da política de autorização. Bloquear restringe o que a automação do tenant consegue gastar; liberar devolve poder de gasto e consumir move dinheiro para um terceiro. Por isso a criação fica com BAAS_ADMIN e as outras duas exigem presença do titular ou mandato, na conta que aderiu à política (§14). E há a razão de produto: a esteira de crédito bloqueia a garantia às 3 da manhã, sem celular na mão de ninguém. Antes de "corrigir" a ausência de holderAuthorization aqui, leia §14.

Pedido em duas etapas ("quatro olhos"): pessoa pede, OUTRA decide — e pessoa não tem porta direta. Liberar devolve poder de gasto e consumir move dinheiro; uma pessoa sozinha com BAAS_ADMIN não faz nenhum dos dois. Ela pede (…/requests, com motivo), e outra pessoa aprova (…/approve) ou recusa (…/reject). A regra mora no bloco, não na tela: um backoffice que chame a API direto passa por ela, e o de um cliente que escreve o próprio console herda a mesma regra sem reescrevê-la. A porta direta (…/release, …/settle) fica só para credencial de máquina — a esteira de crédito consome a garantia de madrugada, sem ninguém na frente.

A vida do pedido: PENDING → (REJECTED | EXECUTING → EXECUTED | FAILED | UNRESOLVED). Toda virada é reivindicada (atualização condicionada ao estado anterior): duas aprovações ao mesmo tempo — ou uma aprovação e uma recusa — produzem uma decisão, e só ela executa. O decisor igual ao solicitante é recusado no próprio WHERE. Depois de um erro na execução, o pedido lê o razão para saber se o valor saiu do bloqueio: sem linha, ou com linha que o banco recusou e a compensação devolveu, é FAILED; com linha e sem resposta do banco é UNRESOLVED — o dinheiro pode ter saído, e quem resolve é a conciliação da transação. Se nem o fechamento der certo, a resposta é 500 HOLD_REQUEST_OUTCOME_UNKNOWN e a varredura de pedido preso fecha (§15). O consumo por pedido usa o id do pedido como idempotencyKey. O razão grava o decisor como ator e o pedido em requestId; quem pediu está no pedido e em metadata.requestedBy.

Reenviar a criação: mande idempotencyKey, ou o reenvio prende o saldo duas vezes. Sem chave, um reenvio depois de um tempo esgotado ou de um 5xx cria um segundo bloqueio. O console do backoffice e todo integrador devem mandar uma idempotencyKey (uuid) por tentativa de envio — a mesma enquanto o pedido não muda, uma nova para um bloqueio novo. É o mesmo mecanismo do Pix, da TED e do consumo (services/idempotency.ts), com a própria linha do bloqueio como reserva:

SituaçãoResposta
Chave nova201 e o bloqueio novo
Mesma chave, mesmo pedido200 com o mesmo bloqueio, como ele está agora, e meta.idempotentReplay: true. Nada é criado, o saldo não é relido e o banco não é chamado
Mesma chave, mesmo pedido, custódia PROVIDER e a chamada ao banco sem desfecho (em voo, ou a resposta se perdeu)202 com meta.inFlight: true e meta.poll — não reenvie: o banco pode estar segurando o valor, e a repetição nunca chama o banco de novo
Mesma chave, mesmo pedido, e o banco recusou a primeira criação422 com details.code = HOLD_PROVIDER_REFUSED e details.reason (as palavras do banco). Nada ficou preso; para tentar de novo, chave nova
Mesma chave, outro pedido (outra conta, valor, moeda, reasonType, externalReference ou expiresAt)409 com details.code = IDEMPOTENCY_KEY_REUSED. Moeda omitida conta como BRL
Sem chaveComo sempre foi: cria, e o reenvio cria outro. Registra warn (baas: chamada … SEM idempotencyKey)

reasonText fica fora da conferência de propósito, como a descrição de uma transferência: reenviar com o texto corrigido não é outro bloqueio. A chave é única por organização. Duas criações simultâneas com a mesma chave produzem uma linha: na mesma conta, quem decide é a procura da chave sob o lock da conta (antes da soma — a repetição de um bloqueio que coube nunca leva 422); em contas diferentes, o índice único (organization_id, idempotency_key).

A repetição devolve o bloqueio como ele está agora (liberado depois, vencido…).

Timeout do banco na criação não libera a linha — e quem a resolve é a RETOMADA. Até aqui qualquer erro do provedor liberava o bloqueio na hora; agora só a recusa síncrona libera (a mesma régua da liberação e do estorno). Sem resposta, o banco pode ter bloqueado: a linha fica ACTIVE, custody = PROVIDER, sem providerHoldId, e a resposta do bloqueio traz pendingReconciliation: true. Enquanto isso: liberar e consumir recusam com 409 HOLD_PROVIDER_HOLD_MISSING antes de reivindicar qualquer coisa; a repetição da chave responde 202; e a varredura de vencimento pula a linha — expirar sem falar com o banco prenderia o dinheiro lá sem saída. Sai baas.hold.provider.pending (com attempts e reasonCode — só o código, nunca a mensagem do banco). A resposta da criação traz details.pendingReconciliation e o holdId; a trilha de recusas não publica create.failed para esse mesmo fato.

Quem resolve é HoldService.retomarCriacao: a varredura de retomada (a cada BAAS_HOLD_RESUME_INTERVAL_MINUTES, só linhas com mais de BAAS_HOLD_RESUME_MIN_AGE_MINUTES) e a rota POST …/holds/:holdId/resume. Ela chama o banco de novo com a mesma chave hold:<id>: ok → carimba o id e publica baas.hold.created; recusa determinada → libera a linha aqui (nada ficou preso lá); de novo sem resposta → fica como está, providerResumeAttempts +1 e outro baas.hold.provider.pending. Cada retomada é reivindicada (contador lido + prazo de 2 min), então duas réplicas não vão ao banco juntas. O provedor tem de conferir a chave antes do saldo — o MockBank confere; um que conferisse o saldo primeiro recusaria a retomada de um bloqueio que existe, e a retomada o liberaria aqui.

Se o banco aceitou e nós falhamos ao gravar o id, o carimbo é tentado 3 vezes; esgotadas, o id sai no evento baas.hold.provider.pending (providerHoldId), a linha segue pendente e a retomada o recupera do banco pela mesma chave. Nada libera a linha nesse caminho.

Códigos de recusa próprios: 422 com details.code = HOLD_EXCEEDS_BALANCE quando a soma dos bloqueios ativos, das saídas em voo da conta (G1) e do valor pedido ultrapassa o saldo total lido do provedor — a comparação é com o total e não com o disponível, porque bloquear o que o banco já bloqueou seria contar o mesmo dinheiro duas vezes.

Corrida do saldo gastável (G1) — trava por conta e saídas em voo

O portão do gastável (spendable-balance.ts) lia o disponível e a soma dos bloqueios sem trava e sem contar as saídas em voo, e a reserva da saída só era gravada depois. Disponível 1.000, bloqueio LEDGER de 600: dois Pix de 400 simultâneos liam 1.000, passavam os dois, e 400 do bloqueado saíam pelo próprio bloco. Com provedor real nem precisava de concorrência — o disponível ainda não mostra a saída PROCESSING. O desenho que fecha:

  • gastável = disponível − bloqueios LEDGER − saídas em voo. "Em voo" (outflow-in-flight.ts): débito PENDING/PROCESSING, mais o COMPLETED depois da leitura do disponível (com 5 s de folga de relógio, READ_SKEW_MS) — é o que compensa a leitura feita fora da trava.
  • A trava é a linha da conta, a mesma da criação de bloqueio. As duas se enxergam: o bloqueio criado com Pix em voo também desconta o que está saindo (HOLD_EXCEEDS_BALANCE traz inFlightAmount). Espera com teto (lock_timeout 5 s); estourou, 503 ACCOUNT_BUSY (retryable: true) sem reserva e sem provedor — repetir com a mesma chave é seguro.
  • Consumo de bloqueio: reivindicar o bloqueio e reservar a saída acontecem na mesma transação, sob a trava. A reserva leva metadata.holdCustody, e enquanto ela está em voo o valor conta como bloqueio para decidir se há o que conferir — o consumo que esgota o bloqueio o leva a SETTLED antes de o banco pagar.
  • Desfecho do provedor (closeReservationAfterProviderError): recusa determinada (4xx) ou falha nossa antes do banco → reserva FAILED, o valor volta ao gastável. Timeout/5xx → reserva fica PENDING e continua contando até o webhook ou a conciliação fecharem. É a regra do #516: desfecho desconhecido não é "não saiu".
  • Conta sem bloqueio continua sem leitura de saldo e sem recusa nova; ganha só a trava curta em volta do INSERT.
  • Trilha: as rotas de envio de Pix e TED passam por auditHoldRoute — toda recusa vira baas.pix.transfer.<desfecho> / baas.ted.transfer.<desfecho> com requested, spendableBalance, ledgerHoldAmount, availableBalance, inFlightAmount; nunca chave Pix nem documento.

Armadilhas e troubleshooting

  • "O cliente tem saldo e o Pix foi recusado com INSUFFICIENT_SPENDABLE_BALANCE." Olhe inFlightAmount no evento. Saída que estourou o tempo no banco fica PENDING e segue descontando até a conciliação; reserva sem id do provedor volta UNRESOLVED e só o backoffice a solta (claimStatus para FAILED depois de confirmar no extrato). Não "limpe" a reserva para destravar o cliente sem olhar o banco — é exatamente o furo de volta.
  • Recusa conservadora logo depois de uma saída concluída. Saída PROCESSING que o banco já debitou é descontada duas vezes até fechar; e uma concluída nos 5 s antes da leitura também. É o lado seguro por desenho; some quando o webhook/conciliação fecha a linha.
  • 503 ACCOUNT_BUSY em rajada. As saídas de UMA conta são serializadas. A trava dura três SELECT e um INSERT; se estourar 5 s, procure transação longa segurando a linha da conta (pg_locks), não o provedor — a chamada ao banco nunca fica dentro da trava.
  • Mock de teste sem withAccountLock. O portão exige a trava; mocks de TransactionRepository usam comTravaDaConta(...) (tests/unit/baas/support/spendable.ts). create e findByIdempotencyKey recebem o tx como argumento a mais.
  • A prova é contra Postgres. tests/integration/baas/spendable-race.integration.test.ts mede o pago no banco de mentira com N saídas paralelas; sem a correção, 11 de 14 casos falham. Foi ele que achou o furo do consumo que esgota o bloqueio — o teste de unidade não o via.
  • Consumo recusado pelo banco e a reserva ficou PENDING. A recusa determinada só leva a reserva a FAILED depois que o valor voltou ao bloqueio. Se a compensação não gravou (corrida no acumulador, banco fora), a reserva fica PENDING com o motivo e segue protegendo o valor — soltá-la deixaria o dinheiro fora do bloqueio e fora do "em voo". Recompor o bloqueio e fechar a reserva é do backoffice.
  • Fora do escopo do G1: o estorno de Pix recebido (refund) é saída e entra no "em voo", mas não passa pelo portão do gastável (não passava antes). O GET …/balance continua devolvendo spendableBalance = disponível − bloqueios (sem as saídas em voo): é o número do alarme de divergência, e descontar ali faria saída PROCESSING já debitada parecer divergência.

A conferência relata e para. Não existe correção automática, e isso é a decisão, não uma pendência. spendableBalance negativo significa que o disponível que o banco informa é menor que a soma dos bloqueios que escrituramos: alguém gastou por fora do bloco o dinheiro que aqui estava travado. A conferência descobre que dois registros discordam e não sabe qual dos dois está errado — se o errado for o nosso, encolher o bloqueio grava o errado e some com a pergunta; se for o do banco (leitura atrasada, transação em voo), encolher apaga a única prova da intenção para acomodar um número que vai voltar ao normal sozinho. Nos dois casos a divergência vira perda. O evento sai, e a decisão fica com quem pode ler o extrato do banco.

Vencimento. expiresAt é opcional, e bloqueio sem prazo é o caso normal — ele nunca vence. Quando há prazo, uma varredura a cada BAAS_HOLD_EXPIRY_INTERVAL_MINUTES (§13) leva o bloqueio a EXPIRED, grava a linha EXPIRE no razão com o valor que ainda travava saldo, e publica baas.hold.expired — uma vez por bloqueio, mesmo com as duas réplicas varrendo juntas. A garantia é a atualização condicionada ao estado anterior, não a trava no Redis do agendador. A varredura não fala com o provedor: com custody = PROVIDER, o bloqueio no banco continua de pé depois de a linha daqui expirar (§15). Por isso ela pula a criação PROVIDER ainda sem id (pendingReconciliation): essa linha espera a retomada, e só vence depois de carimbada.

Um consumo que cite um bloqueio fora da janela é recusado com HOLD_NOT_ACTIVE ainda que a varredura não tenha passado — o prazo é reconferido sob o lock, nunca confiado ao agendador.

Quem agiu, na trilha. Todo evento de bloqueio leva metadata.userId + metadata.actorType: user para pessoa; api_client para chave de API — o autor é a chave (apiKeyId), com o dono dela em onBehalfOf — ou para client_credentials (o client_id); system para varredura. Vale para baas.hold.created, released, settled (e o pix/ted.transfer.initiated do consumo), provider.pending, divergence.detected e reconciled, além dos hold.request.*. Sem isso a trilha gravava a organização como autora (achado D16 da matriz de smoke do CBP, 29/09). O baas.hold.created de uma retomada leva quem retomou; o criador segue em createdBy.

A conferência que confere também deixa rastro: POST …/holds/reconcile sem divergência publica baas.hold.reconciled (os números e o autor). Com divergência, o fato é baas.hold.divergence.detected — um fato, um evento.

Toda recusa e falha deixa evento e log. Regra do dono (29/09): "log e auditoria de tudo". Cada rota de bloqueio, pedido e divergência começa por auditHoldRoute (routes/hold-audit.ts): a resposta de erro — do serviço, do Zod da rota, da porta só-máquina, da autenticação ou exceção — vira log (warn na recusa, error na falha) e o evento baas.hold.<operação>.<desfecho>:

DesfechoQuandoExemplo
refused4xxbaas.hold.request.approve.refused com reason: HOLD_REQUEST_SAME_ACTOR
throttled429—
unknownHOLD_REQUEST_OUTCOME_UNKNOWN (o ato pode ter acontecido)baas.hold.request.approve.unknown
failed5xx, inclusive exceção (internalCode: UNCAUGHT_EXCEPTION)baas.hold.create.failed

Operações: hold.create, hold.reconcile, hold.resume, hold.list, hold.read, hold.entries, hold.release, hold.settle, hold.request.{create,list,read,approve,reject} e hold.divergence.{list,read,explain}. O evento leva operação, código, motivo (details.code), status, os ids da rota (conta, bloqueio, pedido, divergência), valor, tipo, trilho, os números do erro (activeAmount, totalBalance, requested, remaining) e o autor. Nunca leva chave Pix, destinatário, documento, motivo ou explicação escritos, nem a mensagem do banco. Sem organização (401, token sem organizationId) fica só o log: a trilha é por organização. A execução de um pedido aprovado que falha já publica baas.hold.request.failed|unresolved; ali só sai o log. A resposta nunca espera a trilha. A catraca é tests/unit/baas/routes/hold-refusal-audit.test.ts: rota nova sem auditHoldRoute reprova.

Travas de recebíveis — /baas/api/v1/accounts/:id/liens e /baas/api/v1/liens/:lienId

MétodoRotaPermissãoO que faz
POST/accounts/:id/liensBAAS_ADMINCria a trava. Corpo: amount (reais, 2 casas), destination ({accountId} ou {pixKey}), sourceDocuments?, externalReference, description? (≤ 140, para o titular), reasonType (padrão ADVANCE), expiresAt (≤ 12 meses), consentReference? (ex.: o termHash do aceite), mandate?: { notBefore } (o início do mandato que o aparelho assinou), idempotencyKey (obrigatória, UUID), holderAuthorization?, pendingAcceptance? (true = nasce PENDING_ACCEPTANCE, não captura até /activate). 201 nova; 200 + meta.idempotentReplay na repetição da chave (sem passar pelo portão); 409 IDEMPOTENCY_KEY_REUSED com outros termos; 403 AUTHORIZATION_REQUIRED em conta com política sem assinatura; 400 (LIEN_TERMS_INVALID, LIEN_DESTINATION_INVALID, MANDATE_UNBOUNDED) antes de queimar o desafio
GET/accounts/:id/liensBAAS_READLista (filter[status], filter[externalReference]; filtro fora do conjunto é 400). Fim pela página curta, como os bloqueios
GET/liens/:lienIdBAAS_READA trava, com as capturas em included (baas-lien-capture: crédito, valor, estado, bloqueio, transferência, failureCode, tentativas)
POST/liens/:lienId/cancelBAAS_ADMINQuatro olhos. A 1ª chamada pede (202, meta.outcome = REQUESTED, reason obrigatório); a 2ª, de OUTRA pessoa autenticada, cancela (200, CANCELLED) e revoga o mandato. 403 LIEN_CANCEL_SAME_ACTOR / LIEN_CANCEL_DECIDER_NOT_PERSON (máquina e a identidade interna da fachada pedem, nunca decidem)
POST/liens/:lienId/activateBAAS_ADMIN, só máquinaPENDING_ACCEPTANCE → ACTIVE depois que a operação garantida passou a existir. Corpo { externalReference }. 200; repetir = 200 + meta.idempotentReplay (sem segundo evento). 409 LIEN_ACCEPTANCE_EXPIRED passado o prazo do aceite (a trava é vencida, nunca ativada); 409 LIEN_ACTIVATION_NOT_ALLOWED para trava encerrada ou de outra referência; 403 LIEN_ACTIVATE_MACHINE_ONLY para pessoa
POST/liens/:lienId/abandonBAAS_ADMIN, só máquinaDesfaz a trava intocada (nada capturado nem reservado), pendente (a qualquer momento antes do prazo) ou recente (30 min), e da mesma externalReference — a compensação do aceite de crédito que não se concluiu. Fora disso 409 LIEN_ABANDON_NOT_ALLOWED

Toda recusa sai como baas.lien.<operação>.refused (4xx) ou .failed (5xx), publicada pelo próprio serviço — vale também para a chamada pela fachada, sem rota — e a trilha da rota (auditHoldRoute, escopo trava) não a publica de novo. A varredura (BAAS_LIEN_SWEEP_*, §13) vence as travas, retoma capturas sem desfecho e revê os créditos recentes.

Tarifas — /baas/api/v1/accounts/:id/fees

MétodoRotaDescriçãoPermissão
GET/baas/api/v1/accounts/:id/feesAs tarifas da conta. Filtros filter[startDate], filter[endDate] e filter[source] (PROVIDER, HOUSE, UNPRICED); paginado. Origem fora do conjunto é 400BAAS_READ
POST/baas/api/v1/accounts/:id/fees/:feeId/waiveIsenta a tarifa. Exige waiverReason (1 a 500 caracteres). O autor é o usuário do token. Publica baas.fee.waived. 200BAAS_ADMIN
POST/baas/api/v1/accounts/:id/fees/:feeId/chargeCita a transferência que cobrou a tarifa. Exige chargeTransactionId (UUID de uma transação desta organização). Não move dinheiro — a transferência já aconteceu, pelas rotas de Pix ou TED. 200BAAS_ADMIN

A tarifa também aparece em fees[] no recurso da transação (GET /pix/transfers/:id, GET /ted/:id). Esses são os dois únicos lugares — não há extrato unificado nem comprovante (§15).

O recurso (type: "baas-transaction-fee"): amount, currency, payer, source, operationType, waived, waiverReason, waivedBy, pricingRuleId, pricingRuleVersion, chargeTransactionId, createdAt. Os campos de isenção, de regra e de cobrança só aparecem quando preenchidos. quoteSnapshot não sai.

bash
curl -X POST "$BAAS/baas/api/v1/accounts/$ACCOUNT_ID/fees/$FEE_ID/waive" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"data":{"type":"baas-transaction-fee","attributes":{"waiverReason":"Cortesia comercial — contrato 2026/118"}}}'
curl -X POST "$BAAS/baas/api/v1/accounts/$ACCOUNT_ID/fees/$FEE_ID/waive" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"data":{"type":"baas-transaction-fee","attributes":{"waiverReason":"Cortesia comercial — contrato 2026/118"}}}'
SituaçãoResposta
Tarifa que não é desta conta ou desta organização404
waiverReason ausente ou vazio400
Token cujo sub não é um UUID (não identifica quem isentou)400, details.code = WAIVER_AUTHOR_REQUIRED
Isentar tarifa já isentada200 com a linha como está — não republica o evento e não troca o autor nem o motivo do primeiro ato
Isentar tarifa já cobrada409, details.code = FEE_ALREADY_CHARGED. Devolver o que foi cobrado é estorno, não isenção
Citar cobrança em tarifa isentada409, details.code = FEE_WAIVED
Citar a mesma transferência de novo200, inócuo
Citar outra transferência em tarifa já cobrada409, details.code = FEE_ALREADY_CHARGED — não sobrescreve
chargeTransactionId de transação inexistente ou de outra organização404

Isentar e citar cobrança disputam a mesma linha por atualização condicionada ao estado anterior: entre as duas, e entre réplicas, uma ganha.

Autorização do titular — /baas/api/v1/accounts/:id

MétodoRotaDescriçãoPermissão
GET/baas/api/v1/accounts/:id/authorization-policyPolítica da conta. Conta sem registro lê como NONE. Traz trail (posição da linha na trilha) e integrity (veredito ao vivo: ok, none, diverged, deleted, unanchored, pruned, unavailable). data.id é o accountId — o id da linha é o sal do policyHash e não saiBAAS_READ
PUT/baas/api/v1/accounts/:id/authorization-policyGrava a política. Afrouxar exige holderAuthorization. Publica baas.authorization.policy.changed na mesma transação e espera a trilha confirmar (até BAAS_POLICY_ANCHOR_WAIT_MS)BAAS_ADMIN
POST/baas/api/v1/accounts/:id/authorization-policy/anchorAncoragem inicial (BB-5) de uma política gravada antes de a trilha conhecê-la. Idempotente; publica só quando a trilha não tem linha para a conta. Linha existente que não bate com a linha: 409 POLICY_INTEGRITY. Sem linha e com a corrente da organização podada: 409 POLICY_TRAIL_PRUNED (com details.prunedThroughSequence) — "nunca teve política" e "linha expurgada" não se distinguem, e abençoar a linha como ela está seria a lavagem que a rota existe para recusar. Sem política: 404BAAS_ADMIN
GET/baas/api/v1/accounts/:id/devicesLista as chaves de dispositivo, ativas e revogadasBAAS_READ
POST/baas/api/v1/accounts/:id/devicesCadastra a chave pública. Exige evidência biométrica vinculada. 201BAAS_ADMIN
DELETE/baas/api/v1/accounts/:id/devices/:deviceIdRevoga a chave. Sempre permitido. 204BAAS_ADMIN
POST/baas/api/v1/accounts/:id/authorization-challengesEmite o desafio de uso único (120 s). 201BAAS_ADMIN
POST/baas/api/v1/accounts/:id/holder-identity-verifications"Esta sessão biométrica prova o titular?" Corpo { biometricSessionId }. Confere, contra o documento da política (que não sai do BaaS): evidência válida e aprovada, ambiente aceito para a conta, fluxo que compara rosto, identityProven e subjectMatches. Responde 200 { proven, reason, signedAt } — proven: false é resposta, com reason (BIOMETRIC_INVALID, BIOMETRIC_ENVIRONMENT_INVALID, BIOMETRIC_FLOW_INVALID, BIOMETRIC_IDENTITY_NOT_PROVEN, BIOMETRIC_TEMPLATE_UNUSABLE, BIOMETRIC_SUBJECT_MISMATCH, AUTHORIZATION_REQUIRED). Biometria fora do ar: 503 BIOMETRICS_UNAVAILABLE. Não grava nem gasta nada: recência e uso único são de quem chama (o banking, no primeiro login de aparelho novo)BAAS_ADMIN
POST/baas/api/v1/accounts/:id/holder-biometric-sessionsAbre a selfie AUTHENTICATION do titular, contra o cadastro facial ativo mais recente dele (referência SUBJECT_TEMPLATE do biometrics). Corpo { purpose, operationHash? } — o hash amarra a selfie a uma operação (ex.: deviceEnrollmentHash(conta, chave) no cadastro de aparelho). O CPF sai da política e vai direto ao biometrics; nunca volta. Responde 201 { sessionId, captureToken, challenges, capture, operationHash, expiresAt } — capture é { submitUrl, script, slotsMs, timeoutMs, expiresAt } para a câmera de SDK próprio (ou null sem origem pública do biometrics). O captureToken é segredo de uso único: só na resposta, nunca em log nem em evento. Titular sem cadastro âncora: 404 com details.code: BIOMETRIC_TEMPLATE_MISSING; organização sem fornecedor de biometria: 503 com BIOMETRICS_PROVIDER_MISSING (configuração, não o titular); conta sem titular ou política adulterada: 403; biometria recusou (titular bloqueado por falhas): 403 BIOMETRIC_INVALID; biometria fora do ar: 503 BIOMETRICS_UNAVAILABLEBAAS_ADMIN
POST/baas/api/v1/accounts/holder-lookupsContas da organização cuja política HOLDER_SIGNATURE tem este CPF como titular. Corpo { document } — o CPF nunca vai na URL. Responde 200 { data: [{ type, id }] } (até 20, a mais nova primeiro). É um oráculo de "este CPF tem conta", por isso BAAS_ADMIN; não autoriza nada — cada passo seguinte confere a selfie contra a mesma política, com a integridadeBAAS_ADMIN
POST/baas/api/v1/accounts/:id/authorization-policy/holder-document/revealsO CPF do TITULAR em claro, para quem precisa achar a mesma pessoa noutro sistema (o banking, propósito credit: antecipação pelo serviço de crédito). Corpo { purpose: 'credit' }. Responde 200 { data: { attributes: { document } } }; conta sem política HOLDER_SIGNATURE ou de outra organização: 404. Toda revelação publica baas.authorization.holder_document.revealed (CPF mascarado, propósito, quem pediu) — e falha se a linha não for gravadaBAAS_ADMIN
GET/baas/api/v1/accounts/:id/mandatesLista os mandatos da conta, ativos e revogados. Nunca devolve a assinatura nem o nonce da concessãoBAAS_READ
POST/baas/api/v1/accounts/:id/mandatesConcede um mandato. Escrita gated: exige holderAuthorization sobre mandate.grant, com degrau biométrico pesado contra maxAmountPerOperation. Conta sem política (ou em NONE) responde 400. 201BAAS_ADMIN
GET/baas/api/v1/accounts/:id/mandates/:mandateIdBusca por IDBAAS_READ
DELETE/baas/api/v1/accounts/:id/mandates/:mandateIdRevoga. Sempre permitido ao admin; com holderAuthorization sobre mandate.revoke, fica registrado como revogação do titular. 204BAAS_ADMIN

Corpo do POST /mandates: scope (lista não vazia de boleto.issue e/ou boleto.write_off — são os únicos tipos que uma rota lê por mandato hoje), maxAmountPerOperation?, maxAmountPerDay?, maxOperationsPerDay?, maxOperations?, notBefore, notAfter (os dois entram na assinatura, por isso vêm do cliente) e holderAuthorization. Não existe PATCH: mudar escopo ou limite é revogar e conceder outro — nenhum mandato fica, em silêncio, mais largo ou mais estreito do que o titular assinou.

A política só vale o que a trilha diz que ela vale (BB-5). Antes de liberar qualquer escrita gated — authorize, cadastro de aparelho e o próprio PUT — o BaaS recalcula o hash canônico da linha de baas_authorization_policies e compara com a última linha baas.authorization.policy.changed daquela conta na trilha (Audit Trail). Linha editada, apagada com histórico na trilha, ou gravada sem linha nenhuma: 403 com details.code = POLICY_INTEGRITY (e details.integrity dizendo qual delas: diverged, deleted, unanchored ou pruned). Trilha inalcançável: 503 POLICY_INTEGRITY_UNAVAILABLE, para toda conta — "nunca aderiu" é uma afirmação que só a trilha confirma. Conta sem linha e sem registro segue como NONE. Os dois códigos saem também em baas.authorization.denied.

Todo mandato é limitado, ou não é concedido. Pelo menos um entre maxAmountPerOperation e maxOperations é obrigatório — limite de dia sozinho não vale, porque dia sem fim é sem fim —, e notAfter fica no máximo 12 meses depois de notBefore (o precedente é o consentimento do Open Finance Brasil, fácil de defender com auditor). O tenant pode encurtar esse teto com settings.mandateMaxMonths na configuração do provedor (§13); nunca alongar. A recusa é 400 com details.code = MANDATE_UNBOUNDED, tanto no parser quanto no serviço. O motivo: um mandato sem teto e sem prazo é uma capacidade ao portador, assinada uma vez e esquecida — o contorno na direção oposta ao que o mandato existe para fechar.

Pix — /baas/api/v1/pix

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/pix/keysRegistra chave Pix. 201. Gated (§14)BAAS_ADMIN
GET/baas/api/v1/pix/keysLista chaves. Exige ?accountId=, senão 400BAAS_READ
DELETE/baas/api/v1/pix/keys/:idRemove a chave no provedor e marca deletedAt. 204. Gated (§14)BAAS_ADMIN
POST/baas/api/v1/pix/keys/lookupConsulta o DICT: quem é dono de uma chaveBAAS_READ
GET/baas/api/v1/pix/transfersLista transações Pix da organização, com dados da contaBAAS_READ
POST/baas/api/v1/pix/transfersInicia transferência Pix. 201 nova · 200 repetição da chave com desfecho conhecido · 202 repetição com a chamada gêmea ainda no banco (meta.inFlight, não reenvie). Gated (§14)BAAS_ADMIN
GET/baas/api/v1/pix/transfers/:idConsulta e sincroniza o status com o provedorBAAS_READ
POST/baas/api/v1/pix/transfers/:id/refundDevolve um Pix recebido. 201. Gated (§14)BAAS_ADMIN
POST/baas/api/v1/pix/qr-codes/generateGera QR Code estático ou dinâmico. Com amount, gated (§14)BAAS_ADMIN
POST/baas/api/v1/pix/qr-codes/decodeDecodifica um código EMVBAAS_READ

Filtros de GET /pix/transfers: page[number], page[size], filter[accountId], filter[configId], filter[status], filter[direction] (in ou out), filter[startDate], filter[endDate], filter[businessId] (a marca gravada no envio; é como o banking acha a transação de uma intenção sem percorrer o extrato).

TED — /baas/api/v1/ted

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/tedInicia transferência TED. 201BAAS_ADMIN
GET/baas/api/v1/tedLista transações TED. Aceita ?accountId= ou os mesmos filtros do PixBAAS_READ
GET/baas/api/v1/ted/:idConsulta e sincroniza o status com o provedorBAAS_READ

GET /ted muda de comportamento conforme o filtro: com accountId e sem configId, devolve a listagem por conta; caso contrário, devolve a listagem global com os dados da conta embutidos em cada item.

Boletos — /baas/api/v1/boletos

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/boletosRegistra um boleto no banco da conta. 201 — leia o status. Na conta que aderiu à política, exige holderAuthorization ou mandateId para boleto.issue; sem nenhum, 403 MANDATE_REQUIRED (§14)BAAS_ADMIN
GET/baas/api/v1/boletos?accountId=Lista os boletos de uma conta. Filtro statusBAAS_READ
GET/baas/api/v1/boletos/:idBusca por ID, sem ir ao bancoBAAS_READ
POST/baas/api/v1/boletos/:id/syncConsulta o banco e grava o que ele diz: registro, liquidação, baixaBAAS_READ
POST/baas/api/v1/boletos/:id/write-offBaixa por instrução do beneficiário. Exige título não liquidado. Na conta que aderiu à política, exige holderAuthorization ou mandateId para boleto.write_off; sem nenhum, 403 MANDATE_REQUIRED (§14)BAAS_ADMIN
POST/baas/api/v1/boletos/:id/sandbox/paySó MockBank. O sacado paga o título (amount? até 2× o valor de face, paidAt?; sem corpo, valor de face hoje). A concessão do provedor simulado é conferida no uso (403 sem ela); o pagamento é reivindicado no título antes de ir ao banco (409 para o segundo, inclusive entre réplicas); o ato vai à trilha. 202: o banco simulado avisa pelo webhook boleto.settled — o mesmo caminho de um banco real —, e é o aviso que liquida o título, cria a linha BOLETO_IN do extrato e publica baas.boleto.settled. Pendência: POST /:id/sync que encontra o título pago ainda grava SETTLED sem reivindicar, sem crédito no extrato e sem publicar o eventoBAAS_ADMIN

201 não significa registrado. O título nasce REGISTERING e o banco decide depois. A recusa chega como título em FAILED, com bankStatusCode e bankStatusMessage nas palavras do banco — não como erro HTTP. Os estados:

StatusSignifica
REGISTERINGEnviado ao banco, registro ainda não confirmado
REGISTEREDRegistrado e em cobrança
FAILEDRecusado pelo banco
SETTLEDPago e creditado. settledAmount pode diferir de amount (multa, juros, desconto)
WRITTEN_OFFBaixado por instrução nossa — saiu da cobrança sem trazer dinheiro

Nos três bancos reais o registro é assíncrono: POST devolve REGISTERING e POST /:id/sync traz a confirmação, a linha digitável quando o banco só a entrega depois e, no fim, a liquidação.

O título guarda a regra com que foi emitido — payableDaysAfterDue e o contato do sacado como valia na emissão — e devolve os três na consulta.

Corpo do POST: accountId, amount, dueDate, payer (name, document, email, phone, address), e as instruções opcionais finePercent, interestPercentPerMonth, discountAmount + discountUntil, payableDaysAfterDue, allowPartialPayment e instructions (até 5 linhas). Envie idempotencyKey (uuid): ela vai ao banco como chave de controle, e uma repetição devolve o título já criado.

ProvedorExige além do básicoNão aceita
Celcoinpayer.address completoallowPartialPayment
QI TechrequesterProfileKey na configuração (§13)—
FitBankpayer.address, payer.email ou payer.phone, e mktPlaceId na configuração (§13)—
MockBank——

Webhooks — /baas/api/v1/webhooks

MétodoRotaDescriçãoAutenticação
POST/baas/api/v1/webhooks/deliveries/:deliveryIdO caminho recomendado. Recebe webhook no endereço secreto da configuração; a organização e o provedor vêm do registro (§14)Endereço secreto + assinatura do provedor — não usa JWT
POST/baas/api/v1/webhooks/:providerTypeLEGADO, com prazo (§15). :providerType é celcoin, fitbank, qitech ou mockbank; o organizationId vem de cabeçalho ou query do próprio chamador. Só atende configuração sem endereço de entrega; 403 para as demaisAssinatura do provedor — não usa JWT
GET/baas/api/v1/webhooks/healthSonda simples do subsistema de webhookPública

Conciliação — /baas/api/v1/transactions

MétodoRotaDescriçãoPermissão
POST/baas/api/v1/transactions/:id/reconcilePergunta ao banco o desfecho de uma transação parada em PENDING/PROCESSING e grava o resultado. IdempotenteBAAS_ADMIN
POST/baas/api/v1/transactions/reconcileUma passada da varredura, restrita à organização do token. Corpo opcional: staleMinutes, limitBAAS_ADMIN

Saúde

MétodoRotaDescrição
GET/baas/healthIdentificação e versão do build. Não valida banco nem provedor

POST /baas/api/v1/provider-configs

Cria a configuração de um provedor. Antes de gravar, o serviço chama testConnection() no provedor — credencial errada falha aqui, não na primeira conta.

Todos os endpoints de escrita aceitam o corpo em dois formatos: direto, ou dentro de data.attributes. Os dois são equivalentes.

Request

json
{
  "name": "Celcoin Produção",
  "providerType": "CELCOIN",
  "credentials": {
    "clientId": "SEU_CLIENT_ID",
    "clientSecret": "SEU_CLIENT_SECRET",
    "sandbox": "false"
  },
  "isDefault": true,
  "isActive": true,
  "clientWebhookUrl": "https://sua-api.exemplo.com.br/webhooks/baas",
  "clientWebhookEvents": ["baas.pix.received", "baas.pix.transfer.completed"]
}
{
  "name": "Celcoin Produção",
  "providerType": "CELCOIN",
  "credentials": {
    "clientId": "SEU_CLIENT_ID",
    "clientSecret": "SEU_CLIENT_SECRET",
    "sandbox": "false"
  },
  "isDefault": true,
  "isActive": true,
  "clientWebhookUrl": "https://sua-api.exemplo.com.br/webhooks/baas",
  "clientWebhookEvents": ["baas.pix.received", "baas.pix.transfer.completed"]
}
CampoTipoObrigatórioDescrição
namestring (1–100)SimÚnico dentro da organização. Colisão devolve 409
providerTypeCELCOIN | FITBANK | QITECH | MOCKBANKSimDetermina qual estratégia é instanciada
credentialsRecord<string,string>SimFormato depende do provedor — ver §13. Cifrado antes de gravar
isDefaultbooleanNãoMarcar como padrão desmarca a anterior
isActivebooleanNãoPadrão true. Config inativa não pode virar padrão
settingsobjectNãoAjustes específicos do provedor
webhookUrlstring (URL)NãoOnde o provedor entrega. Omitido, o serviço gera a partir de BAAS_WEBHOOK_BASE_URL
webhookEventsstring[]NãoFiltra o que é processado. Vazio significa todos
clientWebhookUrlstring (URL)NãoOnde você quer receber. Cria uma assinatura no Webhooks Engine
clientWebhookEventsstring[]NãoFiltros de evento baas.*. Vazio vira baas.*

Resposta 201

json
{
  "data": {
    "type": "baas-provider-config",
    "id": "6f1c2e40-8d9a-4b1e-9c3f-1a2b3c4d5e6f",
    "links": { "self": "/api/v1/baas/provider-configs/6f1c2e40-..." },
    "attributes": {
      "name": "Celcoin Produção",
      "providerType": "CELCOIN",
      "isDefault": true,
      "isActive": true,
      "webhookUrl": "https://baas.bb.stg.catalisa.app/api/v1/baas/webhooks/celcoin?organizationId=...",
      "createdAt": "2026-08-16T12:00:00.000Z"
    }
  }
}
{
  "data": {
    "type": "baas-provider-config",
    "id": "6f1c2e40-8d9a-4b1e-9c3f-1a2b3c4d5e6f",
    "links": { "self": "/api/v1/baas/provider-configs/6f1c2e40-..." },
    "attributes": {
      "name": "Celcoin Produção",
      "providerType": "CELCOIN",
      "isDefault": true,
      "isActive": true,
      "webhookUrl": "https://baas.bb.stg.catalisa.app/api/v1/baas/webhooks/celcoin?organizationId=...",
      "createdAt": "2026-08-16T12:00:00.000Z"
    }
  }
}

As credenciais não voltam nesta resposta, nem em nenhuma outra. Não há endpoint que as devolva.

Erros

StatusQuando
400Corpo reprovado no Zod, credenciais incompletas, ou testConnection() falhou
403Token sem organizationId, ou sem BAAS_ADMIN
409Já existe config com esse name na organização

POST /baas/api/v1/accounts

Abre a conta no provedor e registra localmente. Se configId for omitido, usa a configuração padrão da organização.

Request

json
{
  "configId": "6f1c2e40-8d9a-4b1e-9c3f-1a2b3c4d5e6f",
  "personId": "9b7e1d22-5a10-4f88-b3d1-77c9e0a41b52",
  "businessId": "OP-2026-00841",
  "purpose": "ESCROW",
  "holder": {
    "name": "Maria Oliveira",
    "documentType": "CPF",
    "documentNumber": "00000000191",
    "email": "maria@exemplo.com.br",
    "phone": "+5511999990000",
    "birthDate": "1990-05-15",
    "motherName": "Ana Oliveira",
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01234567",
      "country": "BR"
    }
  }
}
{
  "configId": "6f1c2e40-8d9a-4b1e-9c3f-1a2b3c4d5e6f",
  "personId": "9b7e1d22-5a10-4f88-b3d1-77c9e0a41b52",
  "businessId": "OP-2026-00841",
  "purpose": "ESCROW",
  "holder": {
    "name": "Maria Oliveira",
    "documentType": "CPF",
    "documentNumber": "00000000191",
    "email": "maria@exemplo.com.br",
    "phone": "+5511999990000",
    "birthDate": "1990-05-15",
    "motherName": "Ana Oliveira",
    "address": {
      "street": "Rua Exemplo",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01234567",
      "country": "BR"
    }
  }
}
CampoTipoObrigatórioDescrição
configIduuidNãoConfig a usar. Omitido, usa a padrão
personIduuidNãoVínculo com Person do Customers. Não é chave estrangeira — ver §15
businessIdstringNãoSeu identificador de negócio. Fica na conta e nas transações
purposeOWN | ESCROW | COLLATERAL | SETTLEMENTNãoPara que a conta serve. Rótulo de organização, sem efeito jurídico nenhum — leia §15 e §16 antes de prometer escrow a alguém. Omitido, a conta nasce OWN
holder.documentTypeCPF | CNPJSimDefine quais campos o provedor vai exigir
holder.documentNumberstring (11–14)SimSem formatação
holder.legalRepresentativeobjectNãoPara CNPJ: representante legal
metadataobjectNãoChaves livres, guardadas em JSONB

Resposta 201

json
{
  "data": {
    "type": "baas-account",
    "id": "3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01",
    "attributes": {
      "status": "PENDING_KYC",
      "purpose": "ESCROW",
      "bankCode": "999",
      "branchNumber": "0001",
      "accountNumber": "0000042",
      "accountDigit": "7",
      "availableBalance": 0,
      "blockedBalance": 0,
      "personId": "9b7e1d22-5a10-4f88-b3d1-77c9e0a41b52",
      "businessId": "OP-2026-00841",
      "createdAt": "2026-08-16T12:00:00.000Z"
    }
  }
}
{
  "data": {
    "type": "baas-account",
    "id": "3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01",
    "attributes": {
      "status": "PENDING_KYC",
      "purpose": "ESCROW",
      "bankCode": "999",
      "branchNumber": "0001",
      "accountNumber": "0000042",
      "accountDigit": "7",
      "availableBalance": 0,
      "blockedBalance": 0,
      "personId": "9b7e1d22-5a10-4f88-b3d1-77c9e0a41b52",
      "businessId": "OP-2026-00841",
      "createdAt": "2026-08-16T12:00:00.000Z"
    }
  }
}

O status inicial é o que o provedor devolveu. Com MockBank e autoApproveKyc ligado, a conta já nasce ACTIVE.


POST /baas/api/v1/pix/transfers

Inicia uma transferência Pix. Informe pixKey ou recipient — sem um dos dois, 400.

Request — por chave Pix

json
{
  "accountId": "3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01",
  "amount": 150.75,
  "description": "Pagamento pedido 8841",
  "pixKey": "destinatario@exemplo.com.br"
}
{
  "accountId": "3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01",
  "amount": 150.75,
  "description": "Pagamento pedido 8841",
  "pixKey": "destinatario@exemplo.com.br"
}
CampoTipoObrigatórioDescrição
accountIduuidSimConta de origem. Precisa ser da sua organização
amountnumber > 0SimEm reais, com centavos. Precisão de Decimal(15,2)
descriptionstring (≤140)NãoVai no campo livre do Pix
pixKeystringCondicionalChave do destinatário. Celcoin e FitBank consultam o DICT antes de enviar
recipientobjectCondicionalDados bancários completos, quando não há chave
scheduledForstring (ISO 8601)NãoAgendamento. Suporte depende do provedor
businessIdstringNãoSeu identificador, guardado na transação
idempotencyKeyuuidNãoSua chave de idempotência, única por organização. A mesma chave devolve a transação já criada (200, meta.idempotentReplay: true) em vez de pagar de novo; a chave também é repassada ao provedor

Resposta 201 — data.attributes traz transactionType: "PIX_OUT", status, amount, fee, endToEndId, os campos counterparty* e processedAt. 200 quando a idempotencyKey já tinha transação: o mesmo corpo, mais meta.idempotentReplay: true.

Erros

StatusQuando
400Sem pixKey nem recipient; saldo insuficiente; valor acima do limite; conta bloqueada ou encerrada
403Token sem organizationId ou sem BAAS_ADMIN
404accountId inexistente ou de outra organização — a distinção é deliberada (§14)

POST /baas/api/v1/pix/transfers/:id/refund

Devolve um Pix recebido. Duas regras verificadas antes de chamar o provedor: a transação precisa ser PIX_IN e precisa estar COMPLETED. Qualquer outra combinação devolve 400.

json
{ "reason": "Cobrança duplicada", "amount": 50.00 }
{ "reason": "Cobrança duplicada", "amount": 50.00 }

amount é opcional; omitido, devolve o valor integral. A resposta 201 traz a transação REVERSAL nova, e a original passa a REVERSED.

Estorno devolve dinheiro da conta, então numa conta que aderiu ele exige holderAuthorization de tipo pix.refund, assinada sobre transactionId, reason e amount (§14). O limiar biométrico é comparado contra o que sai de fato — o parcial, quando vem no corpo; o valor inteiro da transação, quando não vem.


PUT /baas/api/v1/accounts/:id/authorization-policy

Define quem precisa assinar as escritas da conta. Apertar é livre; afrouxar é uma operação assinada — ver §14.

json
{
  "mode": "HOLDER_SIGNATURE",
  "holderDocument": "52998224725",
  "requireBiometricAbove": 1000.00,
  "operators": []
}
{
  "mode": "HOLDER_SIGNATURE",
  "holderDocument": "52998224725",
  "requireBiometricAbove": 1000.00,
  "operators": []
}
CampoTipoObrigatórioDescrição
modeNONE | HOLDER_SIGNATURE | OPERATOR | QUORUMSimNONE é o comportamento atual; QUORUM exige signingRules (§14.9)
holderDocumentstring (CPF)Em HOLDER_SIGNATURECPF do titular; é contra ele que a biometria do enrolamento é conferida. O PUT recebe inteiro; o GET devolve mascarado (***.982.247-**), aqui e em operators e em subjectDocument dos dispositivos — quem grava a política já tem o documento, e esta resposta nunca foi o lugar de descobri-lo. Ler a política e gravá-la de volta sem alterar o campo não funciona: mande o CPF inteiro
requireBiometricAbovenumberNãoAcima deste valor, a operação exige sessão biométrica vinculada. null = nunca
operatorsstring[] (CPF)Em OPERATORQuem pode autorizar por uma conta de empresa
holderAuthorizationobjectAo afrouxarAssinatura de policy.update sobre a política nova

POST /baas/api/v1/accounts/:id/devices

json
{
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
  "enrollmentSessionId": "0c7b1f6e-1f35-4f2a-9f1e-2b3c4d5e6f70",
  "subjectKind": "HOLDER"
}
{
  "publicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...",
  "enrollmentSessionId": "0c7b1f6e-1f35-4f2a-9f1e-2b3c4d5e6f70",
  "subjectKind": "HOLDER"
}

publicKey é o DER SPKI da chave P-256 em base64 canônico (o BaaS recusa qualquer outra grafia, porque o hash de enrolamento é calculado sobre essa string exata). O que autoriza o cadastro não é quem chamou a rota: é a sessão biométrica, cuja evidência precisa estar APPROVED, vinculada a sha256hex(canonicalJson({v:1,type:"device.enroll",accountId,publicKey})) e ao CPF do titular (ou ao subjectDocument, que precisa constar em operators).

A sessão precisa ser AUTHENTICATION com identityProven — comparação 1:1 contra o cadastro facial do próprio titular. Uma ONBOARDING não serve aqui: nela a âncora é o documento que o integrador enviou, e o integrador é justamente o ator que a trava contém (§14). Logo, o titular precisa ter cadastro facial no bloco antes de cadastrar aparelho — ele nasce na abertura da conta, numa sessão ONBOARDING com enrollOnApprove: true.

POST /baas/api/v1/accounts/:id/authorization-challenges

Resposta 201 com challengeId, nonce (32 bytes em base64url) e expiresAt. Uso único: a primeira operação que o consome o queima, mesmo com duas réplicas concorrendo.

holderAuthorization nas rotas de escrita

As rotas gated aceitam o objeto abaixo — POST /pix/transfers, POST /ted, POST /pix/transfers/:id/refund, POST /pix/keys, DELETE /pix/keys/:id (no corpo), POST /pix/qr-codes/generate (só quando tem amount), PATCH /accounts/:id (só quando tem holder), POST /accounts/:id/kyc, POST /accounts/:id/close e o próprio PUT /accounts/:id/authorization-policy:

json
{
  "holderAuthorization": {
    "deviceId": "e4a1...",
    "challengeId": "8f14e45f-ceea-467a-9c3a-0d3b1b2c9f10",
    "signature": "MEUCIQ...",
    "biometricSessionId": "opcional, exigido acima do limiar"
  }
}
{
  "holderAuthorization": {
    "deviceId": "e4a1...",
    "challengeId": "8f14e45f-ceea-467a-9c3a-0d3b1b2c9f10",
    "signature": "MEUCIQ...",
    "biometricSessionId": "opcional, exigido acima do limiar"
  }
}

Conta sem política, ou em NONE, ignora o campo — nada muda para quem não aderiu.

Códigos de recusa — conjunto fechado, em details.code:

CódigoStatusSignifica
AUTHORIZATION_REQUIRED403A conta exige assinatura e ela não veio
DEVICE_NOT_FOUND403deviceId não existe nesta conta
DEVICE_REVOKED403A chave foi revogada
DEVICE_NOT_ALLOWED403A chave existe, mas o modo da política não a aceita
ENROLLMENT_INVALID403A evidência biométrica que cadastrou a chave não se sustenta
SIGNATURE_INVALID403A assinatura não corresponde à operação que chegou
CHALLENGE_INVALID403Desafio inexistente ou de outra conta
CHALLENGE_EXPIRED403Desafio vencido
CHALLENGE_USED403Desafio já consumido
BIOMETRIC_REQUIRED403Valor acima do limiar sem sessão biométrica
BIOMETRIC_INVALID403A sessão biométrica não prova esta operação
BIOMETRIC_FLOW_INVALID403O fluxo da sessão não compara rosto contra titular (LIVENESS_ONLY, ENROLLMENT) — §14
BIOMETRIC_IDENTITY_NOT_PROVEN403A sessão provou um rosto vivo, mas o bloco não provou de quem é: sem match 1:1 contra cadastro facial do titular (§14)
BIOMETRIC_TEMPLATE_UNUSABLE403O cadastro facial contra o qual a sessão comparou foi revogado ou venceu pela retenção (identityUnprovenReason do biometrics). Numa chave de aparelho, a chave para de autorizar — de propósito (LGPD); o app pede um novo cadastro facial e recadastra o aparelho (§14)
BIOMETRIC_ENVIRONMENT_INVALID403A sessão biométrica é do ambiente de teste e a conta roda em provedor real
BIOMETRIC_SUBJECT_MISMATCH—Só como reason de holder-identity-verifications (200, proven: false): a identidade provada é de outra pessoa, não do titular da política
BIOMETRICS_UNAVAILABLE503Não deu para verificar a biometria — falha fechada, nada foi executado

POST /baas/api/v1/webhooks/:providerType

Endpoint que o provedor chama. Não passa por JWT.

A organização vem do header X-Organization-Id ou do query param organizationId — sem um dos dois, 400. A URL que o BaaS gera automaticamente já inclui o query param.

flowchart TD
  IN["POST /webhooks/:providerType"]
  T1{"providerType conhecido?"}
  T2{"config ativa daquele tipo<br/>existe na organização?"}
  T3["verifyWebhookSignature<br/>controlado por PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT"]
  T4["parseWebhookPayload → ParsedBaaSWebhook"]
  T5{"evento assinado em webhookEvents?"}
  T6{"já visto? dedupe por configId + externalEventId"}
  T7["grava em baas_webhook_events,<br/>aplica o efeito e publica baas.*"]
  DESC["descartado com received true"]
  ERR["400"]
  OK["200 received true"]

  IN --> T1
  T1 -->|não| ERR
  T1 -->|sim| T2
  T2 -->|não| ERR
  T2 -->|sim| T3 --> T4 --> T5
  T5 -->|não| DESC
  T5 -->|sim| T6
  T6 -->|repetido| DESC
  T6 -->|novo| T7 --> OK
  DESC --> OK

Pipeline de processamento, nesta ordem:

  1. Resolve a configuração. No caminho recomendado, pelo :deliveryId — e a organização vem do registro. No caminho legado, pelo :providerType mais o organizationId que o chamador mandou no cabeçalho (§14 e §15); configuração que já tem endereço próprio é recusada ali.
  2. Fonte — settings.webhookAllowedCidrs, se declarada e se a borda for confiável (§15).
  3. Assinatura — verifyWebhookSignature(headers, body, rawBody), sobre o corpo cru; quando não é verificável, decide PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT (§13).
  4. parseWebhookPayload() traduz o corpo do provedor para ParsedBaaSWebhook.
  5. Filtra por webhookEvents da config; evento não assinado é descartado com { received: true }.
  6. Replay — deduplica por (configId, id do evento), e o id do evento é o do provedor ou, na falta dele, o hash do corpo cru; repetido é descartado com { received: true }. As duas formas não têm a mesma força: sem id do provedor, a deduplicação só pega reenvio byte-idêntico, e o que segura o resto é a reivindicação condicionada (§14).
  7. Grava em baas_webhook_events, aplica o efeito e publica o evento baas.*. Toda leitura por identificador externo no caminho do efeito é escopada pela organização do evento.

Resposta 200 — { "received": true }.

Falha ao aplicar o efeito não vira erro HTTP: o evento é gravado com o erro no campo error e a resposta continua 200. É deliberado — provedor que recebe erro reentrega, e reentrega de um evento já persistido não conserta nada.


10

Início rápido

Do zero à primeira transferência Pix, usando MockBank. Não precisa de contrato com banco nenhum. Todos os comandos abaixo seguem o fluxo exercitado pelos testes end-to-end em tests/e2e/api/baas.e2e.test.ts.

1. Autenticar no IAM

bash
BASE=https://baas.bb.stg.catalisa.app/baas
ORG=b0000000-0000-0000-0000-000000000001

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"admin@catalisa.app\",\"password\":\"root123456\",\"organizationId\":\"$ORG\"}" \
  | jq -r .accessToken)

echo "${TOKEN:0:24}..."
BASE=https://baas.bb.stg.catalisa.app/baas
ORG=b0000000-0000-0000-0000-000000000001

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"admin@catalisa.app\",\"password\":\"root123456\",\"organizationId\":\"$ORG\"}" \
  | jq -r .accessToken)

echo "${TOKEN:0:24}..."

2. Criar a configuração do MockBank

bash
CONFIG=$(curl -s -X POST "$BASE/api/v1/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "MockBank Sandbox",
    "providerType": "MOCKBANK",
    "credentials": { "token": "mockbank-dev", "autoApproveKyc": "true", "simulateDelays": "false" },
    "isDefault": true,
    "isActive": true
  }')
CONFIG_ID=$(echo "$CONFIG" | jq -r '.data.id')
echo "$CONFIG_ID"
CONFIG=$(curl -s -X POST "$BASE/api/v1/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "MockBank Sandbox",
    "providerType": "MOCKBANK",
    "credentials": { "token": "mockbank-dev", "autoApproveKyc": "true", "simulateDelays": "false" },
    "isDefault": true,
    "isActive": true
  }')
CONFIG_ID=$(echo "$CONFIG" | jq -r '.data.id')
echo "$CONFIG_ID"

O POST já testou a conexão. Se voltou 201, o provedor respondeu.

3. Abrir uma conta

bash
ACC=$(curl -s -X POST "$BASE/api/v1/accounts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"configId\": \"$CONFIG_ID\",
    \"holder\": {
      \"name\": \"Maria Oliveira\",
      \"documentType\": \"CPF\",
      \"documentNumber\": \"00000000191\",
      \"email\": \"maria@exemplo.com.br\",
      \"birthDate\": \"1990-05-15\"
    }
  }")
ACC_ID=$(echo "$ACC" | jq -r '.data.id')
echo "$ACC" | jq '.data.attributes | {status, bankCode, accountNumber, accountDigit}'
ACC=$(curl -s -X POST "$BASE/api/v1/accounts" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"configId\": \"$CONFIG_ID\",
    \"holder\": {
      \"name\": \"Maria Oliveira\",
      \"documentType\": \"CPF\",
      \"documentNumber\": \"00000000191\",
      \"email\": \"maria@exemplo.com.br\",
      \"birthDate\": \"1990-05-15\"
    }
  }")
ACC_ID=$(echo "$ACC" | jq -r '.data.id')
echo "$ACC" | jq '.data.attributes | {status, bankCode, accountNumber, accountDigit}'
json
{ "status": "ACTIVE", "bankCode": "999", "accountNumber": "0000001", "accountDigit": "3" }
{ "status": "ACTIVE", "bankCode": "999", "accountNumber": "0000001", "accountDigit": "3" }

Banco 999 é o código fictício do MockBank. Nenhum banco real usa esse número — é assim que você sabe, olhando um extrato, que está em ambiente simulado.

4. Registrar uma chave Pix aleatória

bash
curl -s -X POST "$BASE/api/v1/pix/keys" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"keyType\":\"EVP\"}" \
  | jq '.data.attributes | {keyType, keyValue, status}'
curl -s -X POST "$BASE/api/v1/pix/keys" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"keyType\":\"EVP\"}" \
  | jq '.data.attributes | {keyType, keyValue, status}'

EVP é a única que dispensa keyValue — o provedor gera um UUID. Para CPF, CNPJ, EMAIL ou PHONE, informar keyValue é obrigatório.

5. Depositar saldo (só MockBank)

bash
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/sandbox/deposit" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 1000}' | jq
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/sandbox/deposit" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 1000}' | jq
json
{ "availableBalance": 1000, "blockedBalance": 0, "totalBalance": 1000, "currency": "BRL" }
{ "availableBalance": 1000, "blockedBalance": 0, "totalBalance": 1000, "currency": "BRL" }

Este endpoint existe só no MockBank. Nos provedores reais ele devolve 400 — em banco de verdade, saldo entra por Pix ou TED recebido.

6. Enviar um Pix

bash
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"accountId\": \"$ACC_ID\",
    \"amount\": 150.75,
    \"description\": \"Primeiro Pix\",
    \"recipient\": {
      \"name\": \"Destinatário Teste\",
      \"documentNumber\": \"00000000272\",
      \"bankCode\": \"001\",
      \"branchNumber\": \"0001\",
      \"accountNumber\": \"12345\",
      \"accountType\": \"CHECKING\"
    }
  }" | jq '.data.attributes | {status, amount, endToEndId}'
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"accountId\": \"$ACC_ID\",
    \"amount\": 150.75,
    \"description\": \"Primeiro Pix\",
    \"recipient\": {
      \"name\": \"Destinatário Teste\",
      \"documentNumber\": \"00000000272\",
      \"bankCode\": \"001\",
      \"branchNumber\": \"0001\",
      \"accountNumber\": \"12345\",
      \"accountType\": \"CHECKING\"
    }
  }" | jq '.data.attributes | {status, amount, endToEndId}'
json
{ "status": "COMPLETED", "amount": 150.75, "endToEndId": "E9999999920260816120012AB34CD56EF78" }
{ "status": "COMPLETED", "amount": 150.75, "endToEndId": "E9999999920260816120012AB34CD56EF78" }

7. Conferir o saldo

bash
curl -s "$BASE/api/v1/accounts/$ACC_ID/balance" -H "Authorization: Bearer $TOKEN" | jq
curl -s "$BASE/api/v1/accounts/$ACC_ID/balance" -H "Authorization: Bearer $TOKEN" | jq

Volta 849.25. Este número veio do provedor, não da coluna do banco — foi ele quem debitou.

Credenciais de staging, documentadas em AMBIENTES.md. Nunca use credencial de provedor real, chave de produção ou dado de conta de cliente em documentação, script de exemplo ou issue.


11

Receitas

Migrar de provedor sem parar a operação

Objetivo. Passar as contas novas para outro banco parceiro mantendo as antigas onde estão.

flowchart LR
  P1["1 · cria a config nova"] --> P2["2 · valida com /test"] --> P3["3 · set-default"] --> P4["4 · acompanha a distribuição"]
  P3 --> N["contas novas → provedor novo"]
  P3 --> V["contas antigas → provedor antigo, intactas"]

Passo 1 — criar a config nova. testConnection roda aqui: se a credencial estiver errada, você descobre agora e não no primeiro cliente.

bash
NEW=$(curl -s -X POST "$BASE/api/v1/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"QI Tech Produção","providerType":"QITECH",
       "credentials":{"apiKey":"...","privateKey":"...","sandbox":"false"},
       "isActive":true}')
NEW_ID=$(echo "$NEW" | jq -r '.data.id')
NEW=$(curl -s -X POST "$BASE/api/v1/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"QI Tech Produção","providerType":"QITECH",
       "credentials":{"apiKey":"...","privateKey":"...","sandbox":"false"},
       "isActive":true}')
NEW_ID=$(echo "$NEW" | jq -r '.data.id')

Resposta esperada: 201 com o id da config. Credencial errada devolve 400 com a mensagem do testConnection.

Passo 2 — validar de novo, explicitamente.

bash
curl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/test" \
  -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/test" \
  -H "Authorization: Bearer $TOKEN" | jq

Resposta esperada: 200 confirmando conectividade e credencial.

Passo 3 — virar o padrão. A partir daqui, POST /accounts sem configId abre no provedor novo.

bash
curl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/set-default" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.isDefault'
curl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/set-default" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.isDefault'

Resposta esperada: true. A config anterior é desmarcada na mesma operação.

Passo 4 — acompanhar a distribuição por provedor.

bash
curl -s "$BASE/api/v1/accounts?filter[configId]=$OLD_ID&page[size]=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'
curl -s "$BASE/api/v1/accounts?filter[configId]=$OLD_ID&page[size]=1" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta.totalItems'

Resposta esperada: o número de contas que ainda vivem no provedor antigo. É esse número que precisa chegar a zero antes de encerrar a janela de migração.

Armadilhas.

  • Não desative nem apague a config antiga enquanto houver conta nela. Cada operação resolve o provedor a partir do configId da conta; sem a config, a conta antiga fica inacessível — inclusive para consultar saldo.
  • A config nova precisa da própria URL de webhook cadastrada no painel do provedor. O BaaS gera a URL, mas quem a informa ao banco é você. Sem isso, os eventos de entrada param de chegar para as contas novas e você só descobre quando alguém reclama que um Pix recebido não apareceu.
  • Contas não migram. Não existe endpoint que mova uma conta de um provedor para outro, e não existiria: a conta é do banco. Migrar de verdade significa encerrar lá e abrir cá, com o titular no meio.
  • set-default afeta só o que vier depois. Nenhuma conta existente muda de provedor.
  • Convivência de dois provedores tem limite jurídico, não técnico. O art. 6º da Resolução Conjunta nº 16/2025 veda contrato simultâneo com duas prestadoras para o mesmo tipo de conta. Trate a coexistência como janela de migração com data de encerramento definida, e alinhe o prazo com o seu jurídico antes de começar (§14).

Reconciliar uma transferência quando o webhook não chegou

Objetivo. Descobrir o estado real de uma transação que ficou parada em PENDING ou PROCESSING.

bash
# GET não é passivo: ele consulta o provedor e grava o status novo
curl -s "$BASE/api/v1/pix/transfers/$TX_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '.data.attributes | {status, processedAt, failureReason, endToEndId}'

# Varrer tudo o que está pendente há mais tempo que o esperado
curl -s "$BASE/api/v1/pix/transfers?filter[status]=PROCESSING&filter[direction]=out&page[size]=100" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[] | "\(.id) \(.attributes.createdAt)"'
# GET não é passivo: ele consulta o provedor e grava o status novo
curl -s "$BASE/api/v1/pix/transfers/$TX_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '.data.attributes | {status, processedAt, failureReason, endToEndId}'

# Varrer tudo o que está pendente há mais tempo que o esperado
curl -s "$BASE/api/v1/pix/transfers?filter[status]=PROCESSING&filter[direction]=out&page[size]=100" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data[] | "\(.id) \(.attributes.createdAt)"'

Desde 2026-09 existe conciliação do bloco, e ela é o caminho preferido — porque grava o desfecho, publica o evento e é segura com duas réplicas:

bash
# Uma transação específica — o botão do backoffice
curl -s -X POST "$BASE/api/v1/transactions/$TX_ID/reconcile" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# → { "outcome": "COMPLETED" | "FAILED" | "UNCHANGED" | "UNRESOLVED" | "SKIPPED" }

# Uma passada na organização inteira, sem esperar a próxima janela
curl -s -X POST "$BASE/api/v1/transactions/reconcile" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"staleMinutes":15,"limit":100}' | jq '.data.attributes'
# Uma transação específica — o botão do backoffice
curl -s -X POST "$BASE/api/v1/transactions/$TX_ID/reconcile" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# → { "outcome": "COMPLETED" | "FAILED" | "UNCHANGED" | "UNRESOLVED" | "SKIPPED" }

# Uma passada na organização inteira, sem esperar a próxima janela
curl -s -X POST "$BASE/api/v1/transactions/reconcile" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"staleMinutes":15,"limit":100}' | jq '.data.attributes'

A varredura agendada faz o mesmo sozinha a cada BAAS_RECONCILIATION_INTERVAL_MINUTES (§13).

Armadilhas.

  • 202 na resposta de uma transferência quer dizer que uma chamada com a mesma chave está em voo no banco. Não reenvie: consulte o link em meta.poll.
  • outcome: UNRESOLVED com uma reserva quer dizer que o provedor nunca devolveu id: não há por onde perguntar pela interface canônica. Confira no extrato do banco e resolva pelo backoffice (§15).
  • GET bate no provedor a cada chamada. Varrer centenas de transações em laço apertado consome quota da API do banco. Espace as chamadas — a varredura do bloco já o faz, com limite.
  • endToEndId é a chave de conciliação com o extrato do banco, não o id da transação nem o externalId. É o único identificador que os dois lados reconhecem.

Bloquear a garantia e consumi-la no desembolso

Objetivo. Uma operação de crédito aprovada e ainda não desembolsada precisa reservar o dinheiro do fundo: até o desembolso sair, aquele valor não pode financiar outra coisa. É o arranjo que atende o que se costuma chamar de "conta escrow" sem conta escrow nenhuma — bloqueio + a conta por operação que o bloco já pratica (§4, §16).

1 · Bloquear, citando a operação. A esteira faz isso sozinha, de madrugada, sem celular na mão de ninguém: criar bloqueio não exige assinatura (§14).

bash
curl -s -X POST "$BASE/api/v1/accounts/$CONTA/holds" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":50000.00,
       "reasonType":"ADVANCE",
       "reasonText":"garantia da antecipacao 4821",
       "externalReference":"op-4821",
       "expiresAt":"2026-10-25T23:59:59Z"}' | jq '.data.attributes'
curl -s -X POST "$BASE/api/v1/accounts/$CONTA/holds" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":50000.00,
       "reasonType":"ADVANCE",
       "reasonText":"garantia da antecipacao 4821",
       "externalReference":"op-4821",
       "expiresAt":"2026-10-25T23:59:59Z"}' | jq '.data.attributes'

externalReference é o que devolve a operação inteira depois: GET /accounts/$CONTA/holds?filter[externalReference]=op-4821 traz os bloqueios dela, ativos e encerrados.

2 · Conferir que o dinheiro saiu do gastável.

bash
curl -s "$BASE/api/v1/accounts/$CONTA/balance" -H "Authorization: Bearer $TOKEN" \
  | jq '{availableBalance, ledgerHoldAmount, spendableBalance}'
curl -s "$BASE/api/v1/accounts/$CONTA/balance" -H "Authorization: Bearer $TOKEN" \
  | jq '{availableBalance, ledgerHoldAmount, spendableBalance}'

A partir daqui, um Pix acima do spendableBalance é recusado com 403 INSUFFICIENT_SPENDABLE_BALANCE antes de o bloco falar com o banco.

3 · Consumir no desembolso. Quando o aceite é assinado, o bloqueio vira transferência de verdade para a chave do cedente — POST …/holds/:holdId/settle, com presença do titular ou mandato hold.settle na conta que aderiu à política.

⚠️ A porta direta é só de máquina. A esteira chama …/settle com chave de API (ou token client_credentials). Um operador logado recebe 403 HOLD_DIRECT_ACTION_MACHINE_ONLY: ele pede o consumo (POST …/holds/:holdId/requests com kind: SETTLE, valor, destino e motivo) e outra pessoa aprova (…/requests/:requestId/approve). Ver §9.

4 · O que acontece se ninguém consumir. O expiresAt do passo 1 é a rede: a varredura leva o bloqueio a EXPIRED e o saldo volta a ser gastável, sozinho, sem ninguém apertar nada. Sem expiresAt, o bloqueio não vence nunca — e é uma escolha legítima para garantia de prazo indeterminado, desde que feita de olhos abertos.

5 · Conferir de tempos em tempos.

bash
curl -s -X POST "$BASE/api/v1/accounts/$CONTA/holds/reconcile" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# → { ..., "spendableBalance": -600, "gap": 600, "divergent": true, "corrected": false }
curl -s -X POST "$BASE/api/v1/accounts/$CONTA/holds/reconcile" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes'
# → { ..., "spendableBalance": -600, "gap": 600, "divergent": true, "corrected": false }

Armadilhas.

  • A trava é do portão, não do banco. Com provedor sem capacidade de bloqueio (Celcoin, QI Tech, FitBank hoje), o banco enxerga o saldo cheio e paga qualquer saída que não passe pelo baas — console do provedor, outra integração, tarifa que o próprio banco debita. É por isso que existe o passo 5, e é por isso que ele não conserta nada (§15).
  • Bloqueio sem prazo não vence. expiresAt ausente é NULL, e a varredura o ignora de propósito. Garantia esquecida trava saldo para sempre.
  • gap não é um número para ajustar. Ele é a pergunta "onde foi parar este dinheiro?", e a resposta está no extrato do banco, não aqui.
  • Não confunda blockedBalance com ledgerHoldAmount. O primeiro é do provedor; o segundo é o que nós escrituramos. Com custody = PROVIDER o nosso bloqueio aparece no primeiro e não no segundo — somá-los travaria o dobro.

Travar recebíveis futuros

Objetivo. O cedente (o médico) recebeu um adiantamento; o que ele deve tem de sair do próximo repasse do pagador (a OS), que cai na conta dele. A trava captura o devido e manda ao fundo; a sobra fica livre.

1 · Criar a trava — conta com política (o caso do app). O aparelho assina lien.create (desafio de POST /accounts/:id/authorization-challenges), com a selfie presa ao hash da operação. No CBP quem faz isso é o aceite de crédito do banking (repaymentLock, README do banking §7.4).

bash
curl -s -X POST "$BASE/api/v1/accounts/$CONTA_MEDICO/liens" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":18000.00,
       "destination":{"accountId":"'$CONTA_FUNDO'"},
       "sourceDocuments":["12345678000195"],
       "externalReference":"TIT-2026-0001",
       "description":"Hospital X",
       "expiresAt":"2026-12-15T23:59:59Z",
       "consentReference":"<termHash>",
       "mandate":{"notBefore":"2026-10-16T12:00:00.000Z"},
       "idempotencyKey":"'$(uuidgen)'",
       "holderAuthorization":{"deviceId":"…","challengeId":"…","signature":"…","biometricSessionId":"…"}}'
curl -s -X POST "$BASE/api/v1/accounts/$CONTA_MEDICO/liens" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"amount":18000.00,
       "destination":{"accountId":"'$CONTA_FUNDO'"},
       "sourceDocuments":["12345678000195"],
       "externalReference":"TIT-2026-0001",
       "description":"Hospital X",
       "expiresAt":"2026-12-15T23:59:59Z",
       "consentReference":"<termHash>",
       "mandate":{"notBefore":"2026-10-16T12:00:00.000Z"},
       "idempotencyKey":"'$(uuidgen)'",
       "holderAuthorization":{"deviceId":"…","challengeId":"…","signature":"…","biometricSessionId":"…"}}'

Em conta sem política, o mesmo corpo sem holderAuthorization e sem mandate: a trava nasce consentVia = ADMIN, e o tenant responde pelo consentimento (deixe o termo assinado com o cliente).

2 · O repasse chega. Nada a chamar. A OS paga R$ 20 mil na conta do médico → R$ 18 mil vão à chave ativa da conta do fundo → baas.lien.captured (capturedCents: 1800000, remainingCents: 0, externalReference: "TIT-2026-0001") e baas.lien.fulfilled. Repasse parcial (R$ 10 mil): captura R$ 10 mil, remainingCents: 800000, e o próximo crédito da OS completa.

3 · O que a esteira faz com os eventos. baas.lien.captured → baixa o título por externalReference com o valor capturado. baas.lien.expired com remainingCents > 0 → cobra o cedente. baas.lien.capture.failed com holdLeftActive: true → um operador decide o bloqueio pelo pedido de quatro olhos (POST …/holds/:holdId/requests).

4 · Encerrar antes. POST /liens/:id/cancel duas vezes, por duas pessoas.

Apontar o webhook do provedor para o endereço secreto

Objetivo. Tirar a configuração da rota legada, em que o organizationId vinha de um cabeçalho do próprio chamador (§14, §15).

bash
# 1 · gera (ou rotaciona) o endereço desta configuração
curl -s -X POST "$BASE/api/v1/provider-configs/$CONFIG_ID/webhook-delivery" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes.webhookDeliveryUrl'
# → https://.../baas/api/v1/webhooks/deliveries/<43 caracteres>

# 2 · cole essa URL no painel do provedor, e guarde o segredo de assinatura
curl -s -X PATCH "$BASE/api/v1/provider-configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"credentials":{"clientId":"...","clientSecret":"...","webhookSecret":"..."}}'
# 1 · gera (ou rotaciona) o endereço desta configuração
curl -s -X POST "$BASE/api/v1/provider-configs/$CONFIG_ID/webhook-delivery" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes.webhookDeliveryUrl'
# → https://.../baas/api/v1/webhooks/deliveries/<43 caracteres>

# 2 · cole essa URL no painel do provedor, e guarde o segredo de assinatura
curl -s -X PATCH "$BASE/api/v1/provider-configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"credentials":{"clientId":"...","clientSecret":"...","webhookSecret":"..."}}'

Armadilhas.

  • A partir do passo 1 a rota antiga responde 403 para esta configuração. Faça o passo 2 e troque a URL no painel do provedor na mesma janela, senão os webhooks ficam sem destino.
  • PATCH com credentials substitui tudo: mande também clientId/clientSecret, não só o webhookSecret.
  • Rotacionar é o botão de vazamento, e invalida o endereço anterior na hora. Não mexe em credencial, então o provedor continua autenticando normalmente — só muda para onde ele entrega.

Receber por QR Code e reagir ao pagamento

Objetivo. Cobrar por Pix e ser notificado quando o dinheiro entrar.

Passo 1 — assinar os eventos de entrada, na criação ou atualização da config.

bash
curl -s -X PATCH "$BASE/api/v1/provider-configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"clientWebhookUrl":"https://sua-api.exemplo.com.br/hooks/baas",
       "clientWebhookEvents":["baas.pix.received"]}' | jq '.data.attributes.webhookSubscriptionId'
curl -s -X PATCH "$BASE/api/v1/provider-configs/$CONFIG_ID" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"clientWebhookUrl":"https://sua-api.exemplo.com.br/hooks/baas",
       "clientWebhookEvents":["baas.pix.received"]}' | jq '.data.attributes.webhookSubscriptionId'

Resposta esperada: o webhookSubscriptionId da assinatura criada no Webhooks Engine. Campo vazio significa que a assinatura não foi criada — veja a armadilha abaixo.

Passo 2 — gerar o QR dinâmico.

bash
curl -s -X POST "$BASE/api/v1/pix/qr-codes/generate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":89.90,
       \"description\":\"Pedido 8841\",\"expiresInMinutes\":30}" \
  | jq '{emvCode, expiresAt}'
curl -s -X POST "$BASE/api/v1/pix/qr-codes/generate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":89.90,
       \"description\":\"Pedido 8841\",\"expiresInMinutes\":30}" \
  | jq '{emvCode, expiresAt}'

Resposta esperada: o emvCode (copia e cola) e o expiresAt calculado a partir dos 30 minutos.

Quando o pagamento entra, o provedor chama o webhook, o handler cria a transação PIX_IN e publica baas.pix.received. O Webhooks Engine entrega no seu endpoint.

Armadilhas.

  • expiresInMinutes tem teto de 1440 — 24 horas. Acima disso o Zod reprova com 400.
  • Sem amount, o QR é estático: reutilizável e sem valor definido. Com amount, é dinâmico e de uso único. Gerar estático para cobrança de pedido faz o mesmo código ser pago duas vezes.
  • A criação da assinatura de webhook falha em silêncio. Se o Webhooks Engine estiver indisponível, o PATCH registra um warn no log e devolve 200 mesmo assim, com webhookSubscriptionId vazio. Confira o campo na resposta — não assuma que assinou.

Configurar o KYC de uma conta pessoa física

Objetivo. Enviar documentos e acompanhar a análise.

bash
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/kyc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "identityDocument": { "type": "CNH", "front": "https://storage.../frente.jpg" },
    "selfie": "https://storage.../selfie.jpg",
    "proofOfAddress": "https://storage.../comprovante.pdf"
  }' | jq

curl -s "$BASE/api/v1/accounts/$ACC_ID/kyc" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, rejectionReason, rejectedFields}'
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/kyc" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "identityDocument": { "type": "CNH", "front": "https://storage.../frente.jpg" },
    "selfie": "https://storage.../selfie.jpg",
    "proofOfAddress": "https://storage.../comprovante.pdf"
  }' | jq

curl -s "$BASE/api/v1/accounts/$ACC_ID/kyc" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, rejectionReason, rejectedFields}'

Armadilhas.

  • O corpo da requisição é limitado a 1 MB por bodyLimit. Enviar documento em base64 estoura esse limite com facilidade. Prefira subir o arquivo pelo File Storage e mandar a URL — os campos aceitam base64 ou URL.
  • O status da conta muda junto: APPROVED leva a conta a ACTIVE, REJECTED a KYC_REJECTED, e qualquer outra coisa a KYC_IN_PROGRESS.
  • Quem decide é o provedor. O BaaS não avalia documento; ele encaminha e reflete. rejectedFields diz o que reenviar.
  • Conta sem KYC aprovado não transaciona. No MockBank isso é explícito (KYC_NOT_APPROVED vira 403); nos provedores reais, a recusa vem deles.

Diagnosticar por que uma chamada voltou 400

O BaaS devolve 400 com dois formatos diferentes, e saber qual é encurta o diagnóstico:

bash
# Falha de schema Zod, direto no router: { "error": { <árvore de campos> } }
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accountId":"nao-e-uuid","amount":-5}' | jq

# Falha de regra de negócio, vinda do serviço: { "error": "VALIDATION", "message": "..." }
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":1}" | jq
# Falha de schema Zod, direto no router: { "error": { <árvore de campos> } }
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"accountId":"nao-e-uuid","amount":-5}' | jq

# Falha de regra de negócio, vinda do serviço: { "error": "VALIDATION", "message": "..." }
curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":1}" | jq

Ordem de diagnóstico: o corpo passa no schema? A conta é da sua organização (senão vem 404, não 403)? A config está ativa? Tem saldo? A conta está ACTIVE? O valor está abaixo do limite do provedor?

Ligar a autorização do titular numa conta

Objetivo. Fazer com que nem o seu próprio backend consiga mover dinheiro desta conta sem o celular do titular. Exige o bloco Biometrics no ar e, desde o BB-5, o Audit Trail com o consumidor ligado: cada PUT publica baas.authorization.policy.changed e a resposta traz trail.sequence quando a trilha confirmou. Política gravada antes do BB-5 precisa de um POST /accounts/:id/authorization-policy/anchor antes de voltar a autorizar (§14, "Ancoragem inicial").

flowchart LR
  A["1 · política com o CPF do titular"] --> B["2 · sessão biométrica do enrolamento"] --> C["3 · cadastra a chave do celular"] --> D["4 · liga HOLDER_SIGNATURE"] --> E["5 · cada Pix pede desafio e assina"]

Passo 1 — declarar o titular, ainda sem exigir assinatura. Mode NONE deixa a operação atual intacta enquanto você prepara o aplicativo.

bash
curl -s -X PUT "$BASE/api/v1/accounts/$ACC_ID/authorization-policy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"NONE","holderDocument":"52998224725"}' | jq
curl -s -X PUT "$BASE/api/v1/accounts/$ACC_ID/authorization-policy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"NONE","holderDocument":"52998224725"}' | jq

Passo 2 — abrir a sessão biométrica do enrolamento. O aplicativo gera o par de chaves no enclave, calcula sha256hex(canonicalJson({v:1,type:"device.enroll",accountId,publicKey})) e abre a sessão de biometria com esse hash como operação. O CPF da sessão precisa ser o do titular.

Passo 3 — cadastrar a chave pública.

bash
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/devices" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"publicKey\":\"$PUBKEY_SPKI_B64\",\"enrollmentSessionId\":\"$SESSION\"}" | jq
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/devices" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"publicKey\":\"$PUBKEY_SPKI_B64\",\"enrollmentSessionId\":\"$SESSION\"}" | jq

Resposta esperada: 201 com deviceId e keyId. 403 ENROLLMENT_INVALID significa que a evidência não está vinculada àquela conta e àquela chave — confira o hash do passo 2.

Passo 4 — exigir a assinatura.

bash
curl -s -X PUT "$BASE/api/v1/accounts/$ACC_ID/authorization-policy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"HOLDER_SIGNATURE","holderDocument":"52998224725","requireBiometricAbove":1000}' | jq
curl -s -X PUT "$BASE/api/v1/accounts/$ACC_ID/authorization-policy" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mode":"HOLDER_SIGNATURE","holderDocument":"52998224725","requireBiometricAbove":1000}' | jq

Passo 5 — transferir. Peça o desafio, mande operação e desafio ao aplicativo, receba a assinatura e envie tudo junto:

bash
CH=$(curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/authorization-challenges" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes')

curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":150.75,\"pixKey\":\"destinatario@exemplo.com.br\",
       \"holderAuthorization\":{\"deviceId\":\"$DEVICE\",\"challengeId\":\"$CHALLENGE\",\"signature\":\"$SIG\"}}" | jq
CH=$(curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/authorization-challenges" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes')

curl -s -X POST "$BASE/api/v1/pix/transfers" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"accountId\":\"$ACC_ID\",\"amount\":150.75,\"pixKey\":\"destinatario@exemplo.com.br\",
       \"holderAuthorization\":{\"deviceId\":\"$DEVICE\",\"challengeId\":\"$CHALLENGE\",\"signature\":\"$SIG\"}}" | jq

Resposta esperada: 201. Se você mudar o valor depois de assinado, vem 403 com details.code = SIGNATURE_INVALID — e o provedor não chega a ser chamado.

Para voltar atrás (mode: NONE), o mesmo aplicativo precisa assinar uma operação policy.update. É de propósito: afrouxar é tão sensível quanto transferir.

Dar mandato à régua de cobrança numa conta que aderiu

Objetivo. A conta exige assinatura do titular, mas emissão e baixa de boleto são feitas por uma régua às 3 da manhã. O titular concede uma vez a presença dele, com limites, e a régua cita o mandato em cada emissão e em cada baixa. O instalador da vertical faz isto no onboarding do tenant (§15).

Passo 1 — o aplicativo assina a concessão. Peça o desafio e monte o mandate.grant com o escopo e os limites que o titular escolheu (a forma canônica está em §14):

bash
CH=$(curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/authorization-challenges" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes')

curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/mandates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"scope\":[\"boleto.issue\",\"boleto.write_off\"],\"maxAmountPerOperation\":5000,\"maxOperationsPerDay\":200,
       \"notBefore\":\"2026-10-01T00:00:00.000Z\",\"notAfter\":\"2027-03-31T23:59:59.000Z\",
       \"holderAuthorization\":{\"deviceId\":\"$DEVICE\",\"challengeId\":\"$CHALLENGE\",\"signature\":\"$SIG\"}}" \
  | jq -r '.data.id'
CH=$(curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/authorization-challenges" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.data.attributes')

curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/mandates" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"scope\":[\"boleto.issue\",\"boleto.write_off\"],\"maxAmountPerOperation\":5000,\"maxOperationsPerDay\":200,
       \"notBefore\":\"2026-10-01T00:00:00.000Z\",\"notAfter\":\"2027-03-31T23:59:59.000Z\",
       \"holderAuthorization\":{\"deviceId\":\"$DEVICE\",\"challengeId\":\"$CHALLENGE\",\"signature\":\"$SIG\"}}" \
  | jq -r '.data.id'

Resposta esperada: 201 com o id do mandato. Se a política tem requireBiometricAbove e o teto por operação passa dele (ou não há teto), a concessão pede biometricSessionId vinculada ao hash da concessão — a máquina vai poder mover isso sozinha, então o titular prova quem é agora.

Passo 2 — a régua cita o mandato. Nenhum desafio, nenhuma assinatura: só o mandateId, tanto no POST /boletos quanto na baixa.

bash
curl -s -X POST "$BASE/api/v1/boletos/$BOLETO_ID/write-off" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"reason\":\"Renegociado\",\"mandateId\":\"$MANDATE\"}" | jq '.data.attributes.status'
curl -s -X POST "$BASE/api/v1/boletos/$BOLETO_ID/write-off" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"reason\":\"Renegociado\",\"mandateId\":\"$MANDATE\"}" | jq '.data.attributes.status'

Resposta esperada: WRITTEN_OFF, e no barramento um baas.authorization.granted com mandateId e mandateConsumed. O 201º do dia responde 403 MANDATE_LIMIT; fora da janela, MANDATE_EXPIRED; título maior que o teto, MANDATE_LIMIT — e em todos eles o banco não é chamado.

Passo 3 — trocar limite ou revogar. DELETE /accounts/:id/mandates/$MANDATE (o admin revoga sem assinatura; o titular assina um mandate.revoke e fica registrado como dele). Para um teto diferente, revogue e conceda outro.


12

Integração com outros building blocks

Building blockComo se relacionaObrigatório
IAMEmite o token; organizationId, BAAS_READ e BAAS_ADMIN vêm deleSim
Webhooks EngineProviderConfigService cria, atualiza e apaga a assinatura de saída quando você define clientWebhookUrlSim — é dependência de container
CustomersBaaSAccount.personId aponta para Person; filter[personId] lista as contas de uma pessoaNão
BiometricsProva de vida que autoriza o cadastro de uma chave de dispositivo e o degrau biométrico acima do limiar. Via fachada BiometricsFacadeTokenSó para contas com política ≠ NONE
Audit TrailConsome os eventos baas.* para trilha de complianceNão
File StorageGuarda os documentos de KYC; o BaaS recebe a URL, não o arquivoNão
PaymentsCobrança e conciliação de recebíveis; o BaaS é a conta onde o dinheiro caiNão
Open FinanceAgrega dados de contas em outras instituições; o BaaS opera a conta que é suaNão
Decision PlatformDecide se concede o crédito; o BaaS desembolsa o resultadoNão
Pricing EngineDecide o preço da tarifa da casa. O BaaS pergunta (POST /pricing/api/v1/fees/quote) a cada Pix, TED e consumo de bloqueio, informando operation, amount e occurrencesThisMonth. Via fachada PricingFacadeTokenNão — falha aberta. Sem ele a transferência acontece e a tarifa fica UNPRICED
flowchart TD
  IAM["IAM — emite o token com organizationId + permissões"]
  DEC["Decision Platform — aprovou?"]
  BAAS["BaaS<br/>contas · Pix · TED"]
  BANCO["Celcoin · QI Tech · FitBank<br/>a licença do BACEN mora aqui"]
  CUS["Customers — quem é"]
  WHE["Webhooks Engine — entrega"]
  CLI["Endpoint do cliente"]
  AUD["Audit Trail"]

  IAM -->|Bearer JWT| BAAS
  DEC --> BAAS
  BAAS -->|"API do provedor"| BANCO
  BANCO -->|webhook| BAAS
  BAAS -->|personId| CUS
  BAAS -->|"eventos baas.*"| WHE
  WHE --> CLI
  WHE --> AUD

Pricing Engine — quem faz o quê. Esta integração não existia: MODULE_PRICING_ENGINE_URL estava declarada desde que o bloco de preço nasceu e nenhum bloco a lia. O BaaS é o primeiro consumidor.

BlocoFazNão faz
Pricing EngineDecide o preço — faixa, vigência, prioridade, quem paga, franquia (freeUnitsPerMonth), recorrênciaNão guarda o cálculo (stateless), não conta quantas vezes a conta usou, não cobra
BaaSConta a franquia, aplica, registra e explica — a linha, o retrato, a isençãoNão decide preço (nenhuma regra é reimplementada aqui) e não cobra a tarifa da casa (§15)
sequenceDiagram
  participant C as Cliente
  participant B as BaaS
  participant P as Provedor
  participant PE as Pricing Engine
  C->>B: POST /pix/transfers
  B->>P: transferência
  P-->>B: ok, com fee do banco
  B->>B: grava tarifa PROVIDER
  B->>B: conta as operações do mês
  B->>PE: POST /fees/quote (operation, amount, occurrencesThisMonth)
  alt cotação
    PE-->>B: fees[], pricingRule
    B->>B: grava HOUSE + retrato
  else fora do ar, lento (2 s) ou resposta inválida
    PE--xB: erro
    B->>B: grava UNPRICED + motivo
  end
  B-->>C: 201 — a transferência vale nos dois casos

A pergunta é feita depois de o dinheiro sair, e nada do que acontece nela muda a resposta da transferência. O custo é latência: a cotação tem teto de 2 s (menor que os 5 s padrão das chamadas entre blocos), porque quem espera é o cliente, pelo comprovante de uma transferência que já aconteceu.

ModoComo o BaaS alcança o Pricing Engine
MonólitoChamada direta ao serviço, no mesmo processo
StandaloneHTTP, com MODULE_PRICING_ENGINE_URL no serviço baas e token interno com PRICING_CALCULATE. Variável ausente não impede o BaaS de subir nem de operar: toda tarifa da casa sai UNPRICED

Monitore UNPRICED. Por ser falha aberta, um Pricing Engine fora do ar não gera erro em lugar nenhum que o cliente veja — o único sinal é a contagem de linhas UNPRICED subindo e o warn "pricing-engine não apurou o preço" no log do baas. Sem alarme em cima disso, a casa deixa de cobrar em silêncio.

O encaixe é o argumento: o Decision Platform decide, o BaaS movimenta, o Customers diz de quem é, o Webhooks Engine avisa e o Audit Trail registra. Nenhuma dessas conexões exige código de integração seu — elas acontecem por evento, com o mesmo organizationId atravessando toda a cadeia.


13

Configuração e operação

Variáveis de ambiente

VariávelDescriçãoObrigatóriaPadrão
BAAS_CREDENTIAL_MASTER_KEYChave AES-256-GCM das credenciais de provedor. Exatamente 64 caracteres hexadecimais (32 bytes). Gere com openssl rand -hex 32Sim, para usar o módulo—
BAAS_WEBHOOK_BASE_URLBase das URLs de callback geradas automaticamenteNãohttp://localhost:3000
BAAS_SIMULATED_PROVIDER_ORGANIZATION_IDSFallback da trava G5. O caminho normal é a concessão por organização, feita pelo operador da plataforma (PUT /baas/api/v1/admin/platform/organizations/:organizationId/simulated-provider, §9), que não exige editar env nem reiniciar o bloco. Em produção (NODE_ENV=production), cria configuração que aceita evidência de teste (MOCKBANK, ou settings.sandbox: true) a organização que tem concessão ativa OU está nesta lista. Ids separados por vírgula; * libera todas e só serve a ambiente que não é produção de verdade (staging). Fora de produção a trava não se aplica. O deploy nativo preserva o env: a variável tem de estar gravada no serviçoNãovazio: em produção só cria quem tem concessão
BANKING_PLATFORM_ORGANIZATION_IDSOrganizações (uuid, vírgula) do operador da plataforma — as únicas que concedem e revogam o provedor simulado (§9). É a mesma variável do banking, com o nome dele; tem de estar gravada também no serviço do baasNãovazio: ninguém concede pela API (403)
PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENToff ou on. Qualquer valor exceto off (inclusive ausente) rejeita webhook que não puder ser verificadoNãofail-closed
BAAS_WEBHOOK_TRUST_FORWARDED_FORDeclara que a borda SOBRESCREVE X-Forwarded-For. Só com isso a lista de faixas de origem (settings.webhookAllowedCidrs) é aplicada. Ver §15: sob o SNAT do Swarm o serviço não vê o cliente, e a lista sem essa garantia é teatroNãofalse
BAAS_RECONCILIATION_ENABLEDLiga a varredura de conciliação. Desligar devolve o bloco ao estado em que reserva órfã fica PENDING para sempreNãotrue
BAAS_RECONCILIATION_INTERVAL_MINUTESIntervalo entre passadasNão5
BAAS_RECONCILIATION_STALE_MINUTESQuanto tempo sem desfecho até a transação virar candidataNão15
BAAS_HOLD_EXPIRY_ENABLEDLiga a varredura de vencimento de bloqueios. Desligar deixa bloqueio vencido travando saldo para sempre — o efeito é saldo preso, não dinheiro saindo: o consumo continua recusando o bloqueio fora da janelaNãotrue
BAAS_HOLD_REQUEST_SWEEP_ENABLEDLiga a varredura de pedido de quatro olhos preso em EXECUTING. Não fala com banco: lê o razão e fecha o pedido pelo finish condicionado. Desligar deixa o pedido interrompido prendendo o bloqueioNãotrue
BAAS_HOLD_REQUEST_SWEEP_INTERVAL_MINUTESIntervalo entre passadas da varredura de pedido presoNão5
BAAS_HOLD_RESUME_ENABLEDLiga a retomada da criação de bloqueio PROVIDER sem desfecho do banco. Desligar deixa a linha pendingReconciliation até alguém chamar POST …/holds/:holdId/resumeNãotrue
BAAS_LIEN_PENDING_ACCEPTANCE_MINUTESQuanto a trava PENDING_ACCEPTANCE espera a ativação antes de a varredura a vencer (acceptance-timeout); a ativação depois disso é recusadaNão30
BAAS_LIEN_SWEEP_ENABLED / BAAS_LIEN_SWEEP_INTERVAL_MINUTES / BAAS_LIEN_CREDIT_LOOKBACK_HOURSA varredura das travas de recebíveis: vence a pendente sem ativação no prazo do aceite e a trava cujo prazo passou (baas.lien.expired), retoma a captura sem desfecho (chaves derivadas: nunca bloqueia nem paga duas vezes) e revê os créditos das últimas N horas das contas com trava ativa. Desligar deixa trava vencida ACTIVE (a captura já recusa: o prazo é reconferido na reserva) e captura presa no meioNãotrue / 2 / 48
BAAS_HOLD_RESUME_INTERVAL_MINUTESIntervalo entre passadas da retomadaNão5
BAAS_HOLD_RESUME_MIN_AGE_MINUTESIdade mínima da linha para a retomada tocá-la (abaixo disso a criação original pode estar em voo)Não5
BAAS_HOLD_REQUEST_STUCK_MINUTESHá quantos minutos um pedido precisa estar EXECUTING para a varredura o fecharNão15
BAAS_HOLD_EXPIRY_INTERVAL_MINUTESIntervalo entre passadas do vencimento. Mais barata que a de conciliação: lê pelo índice parcial e não fala com provedor nenhumNão5
BAAS_HOLD_DIVERGENCE_WINDOW_MINUTESQuanto tempo o alarme de divergência fica calado por conta no caminho de leitura de saldo (um GET que painel chama em laço). A conferência pedida (POST …/holds/reconcile) ignora a janelaNão60
MODULE_AUDIT_TRAIL_URL(standalone) Base do Audit Trail, lido antes de toda escrita gated (BB-5). Sem ele, 503 POLICY_INTEGRITY_UNAVAILABLESim, em standalone—
BAAS_POLICY_INTEGRITY_CACHE_MSQuanto tempo a última linha da trilha de uma conta é reaproveitada. 0 desliga o cacheNão5000
BAAS_POLICY_ANCHOR_WAIT_MSQuanto o PUT/anchor espera a trilha encadear a linha antes de responder sem a posiçãoNão3000
DATABASE_URLPostgreSQLSim—
REDIS_URLRedis, usado no rate limitSim—
JWT_SECRETVerificação do token do IAM. Mínimo 44 caracteresSim—
MODULE_IAM_URLURL do IAM em standaloneEm standalone—
DEPLOYMENT_MODEmonolith ou standaloneNãomonolith
PORTPorta em standaloneNão3000 (mapeada para 3015)

Autorização do titular não tem variável de ambiente. É configuração por conta, gravada em baas_authorization_policies, e a única dependência nova é o bloco de Biometrics — em monolito, pelo container; em standalone, pela fachada remota. Sem fachada registrada, conta com política ≠ NONE responde 503 (BIOMETRICS_UNAVAILABLE) e nada é executado; conta sem política segue igual.

BAAS_CREDENTIAL_MASTER_KEY não tem rotação automatizada. Trocá-la torna todas as credenciais gravadas indecifráveis — decifre e recifre antes de trocar. Guarde com SOPS, nunca em .env versionado.

Credenciais por provedor — o que vai dentro do campo credentials.

ProvedorCamposAutenticaçãoAmbientes
CELCOINclientId, clientSecret, sandboxOAuth2 client_credentials, token em cache até 5 min antes de expirarsandbox.openfinance.celcoin.dev · api.celcoin.com.br
FITBANKapiKey, apiSecret, partnerId, businessUnitId, sandboxBasic Authsandboxapi.fitbank.com.br/main/execute · api.fitbank.com.br/main/execute
QITECHapiKey, privateKey, sandboxRequisição assinada com RSAsandbox.qitech.app · api-auth.qitech.app
MOCKBANKtoken, autoApproveKyc, simulateDelays, delayMsSó confere que token não está vazioNenhum — roda local

Boleto — o que cada banco pede a mais. Vale em credentials ou em settings.

ProvedorCampoO que é
QITECHrequesterProfileKeyA carteira de cobrança da conta, sob a qual os boletos são registrados. A QI Tech cria uma padrão na abertura da conta
FITBANKmktPlaceIdIdentificador de marketplace que o FitBank fornece junto de partnerId e businessUnitId
FITBANKboletoGroupTemplateTemplate do boleto. Padrão 2, o que a documentação do FitBank indica

Mandato — o que o tenant pode apertar. Em settings da configuração do provedor:

CampoO que é
mandateMaxMonthsDuração máxima de um mandato nas contas desta configuração, em meses. O teto do bloco é 12; este valor só encurta — 24 vale 12, e valor inválido vale 12 (§9, §14)
forceLedgerHoldsSó o booleano true liga. Força o bloqueio de saldo pelo caminho escriturado (custody = LEDGER) mesmo num provedor que declara balanceHold: 'NATIVE'. Existe para que o caminho sem capacidade seja exercitável de ponta a ponta com MockBank, que é NATIVE. A string "true" não liga: configuração mal digitada não muda em silêncio onde o bloqueio é guardado. Não é chave de produção — ver §15
externalPixKeysPadrão refuse. Pix para chave que o DICT do MockBank não conhece é recusado (404, PIX_KEY_NOT_FOUND) sem débito — antes de 02/10 o envio debitava a origem, respondia COMPLETED e não creditava ninguém. Só a string 'simulate' muda: o dinheiro sai para "Instituição externa (simulada)". É para smoke com favorecido fictício (baas-holds, cbp-ambiente, cbp-day1 declaram), nunca para conta de demonstração

A Celcoin não pede nada além das credenciais: o boleto sai pela API de cobrança da própria conta BaaS.

settings do MockBank aceita defaultBalance, maxPixAmount (padrão 100.000) e maxTedAmount (padrão 500.000), úteis para exercitar o caminho de limite excedido. Em staging e produção (NODE_ENV=production), defaultBalance só vale com demoMode: true declarado na mesma configuração — sem a declaração, a conta nasce zerada. O saldo de demonstração da abertura de conta pelo aplicativo é outro caminho: o banking credita demoInitialBalanceCents (política da organização, com evento) por POST /accounts/:id/sandbox/deposit, que publica baas.account.sandbox_deposit (e ..._refused quando o provedor recusa).

Eventos do operador e rollout

  • Ordem OBRIGATÓRIA: audit-trail antes do baas. O audit-trail desta versão cria o grupo audit-trail-consumers no stream platform-operator-events; o baas desta versão publica lá. O webhooks-engine pode vir em qualquer momento.
  • Se a ordem for invertida (baas novo com audit-trail antigo, ou com AUDIT_CONSUMER_ENABLED desligado): conceder e revogar respondem 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE com details.reason: NO_TRAIL_READER — falha fechada, nada publicado, tabela intacta. Antes de publicar, o baas confere que o grupo da trilha existe no stream do operador (XINFO GROUPS; o "sim" é lembrado por 30 s, o "não" nunca). Sem essa conferência a rota responderia "confirmado" com o evento gravado num stream que ninguém lê — e staging não tem AOF: um reinício do Redis apagaria o único registro. A revogação de emergência (?force=true) segue valendo: revoga, publica em melhor esforço e responde trail: 'unconfirmed'. A recusa da trava (baas.simulated-provider.refused) e as recusas das rotas são de melhor esforço e não conferem.
  • O que a conferência NÃO garante. Ela vê que o grupo existe, não que o consumidor está vivo agora: com o grupo criado e a trilha fora, o evento espera no stream e é lido quando ela volta — desde que o Redis não perca o stream no meio. "Confirmado" continua sendo "gravado no stream com leitor registrado", não "linha de auditoria gravada".
  • O que segue exposto durante o rollout. Enquanto o baas estiver em build antigo, ele publica no iam-events; um consumidor de webhook de build anterior a ac991e3d que esteja no grupo entrega esses eventos ao cliente. O webhooks-engine desta versão descarta o que vier por esse caminho, mas não controla o que um consumidor antigo lê. Não conceda nem revogue o provedor simulado no meio do rollout, e confira antes se não há consumidor antigo.
  • Consumidor órfão. Processo do webhooks-engine de build antigo que continua no grupo webhook-delivery-consumers fora do registro do orquestrador. Vê-se pelo health: curl -s https://<host>/webhooks-engine/health | jq '.checks.consumerGroup' — unknownActiveConsumers > 0 (consumidor ativo no grupo sem batimento: build antigo) ou staleVersionActive: true. O sinal tem limites (um órfão com o mesmo pid de uma réplica nova não aparece): detalhe e leitura em src/webhooks-engine/README.md §13, Consumidor órfão. Com o baas nesta versão, um órfão não entrega evento de operador (ele não está no stream que o órfão lê); continua sendo problema para todo o resto que só o código novo faz.
  • Linhas de antes. As entregas já gravadas de baas.simulated-provider.* ficam em webhooks.webhook_delivery_logs: a API não devolve o payload delas ao cliente, e o retry (automático ou manual) é recusado e marca a linha. O que já saiu para o endpoint do cliente, saiu.

Subida em ambiente — a concessão do provedor simulado

Nenhum deploy do Launch toca o banco: a migration 20261011090000_baas_simulated_provider_grants sobe pelo procedimento de scripts/launch/ (leia o README dele), staging antes de produção. Sem a tabela, a organização fora da variável de fallback recebe 503 ao criar configuração simulada, e as rotas do operador também.

bash
# 1. aplicar (aditiva e idempotente)
MIGRATIONS="20261011090000_baas_simulated_provider_grants" ALVO=staging CONFIRMA=sim ./scripts/launch/1-migrar.sh

# 2. verificar — a tabela e o índice único parcial, pela lista do bloco (não pela lista padrão do script)
VERIFICAR_FILE=scripts/launch/verificar/baas-simulated-provider-grants.txt ALVO=staging ./scripts/launch/2-verificar.sh
# 1. aplicar (aditiva e idempotente)
MIGRATIONS="20261011090000_baas_simulated_provider_grants" ALVO=staging CONFIRMA=sim ./scripts/launch/1-migrar.sh

# 2. verificar — a tabela e o índice único parcial, pela lista do bloco (não pela lista padrão do script)
VERIFICAR_FILE=scripts/launch/verificar/baas-simulated-provider-grants.txt ALVO=staging ./scripts/launch/2-verificar.sh

Em produção, o mesmo com ALVO=prod. E, uma vez por ambiente, BANKING_PLATFORM_ORGANIZATION_IDS gravada no serviço bb-baas (§9, Operador da plataforma).

Emergência — revogar com a trilha de auditoria fora do ar

DELETE sem force responde 503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLE e não muda nada: a organização segue concedida. Se a revogação não pode esperar a trilha voltar:

bash
curl -X DELETE -H "Authorization: Bearer $TOKEN_DO_OPERADOR" \
  "$BAAS_URL/baas/api/v1/admin/platform/organizations/$ORGANIZATION_ID/simulated-provider?force=true"
curl -X DELETE -H "Authorization: Bearer $TOKEN_DO_OPERADOR" \
  "$BAAS_URL/baas/api/v1/admin/platform/organizations/$ORGANIZATION_ID/simulated-provider?force=true"

A resposta traz trail. Com unconfirmed, guarde a resposta e o log (baas: provedor simulado REVOGADO À FORÇA…, nível error): eles são o registro do ato. Revogar não desativa as configurações que a organização já criou — para tirar o simulado do ar, desative a configuração (PATCH isActive: false).

Dependências de infraestrutura

DependênciaPara quê
PostgreSQLSchema baas — configs, contas, chaves, transações, eventos e o estado do MockBank
RedisContadores de rate limit
IAMValidação do token e resolução de permissões
Webhooks EngineAssinaturas de entrega dos eventos baas.*
BiometricsSó para contas com política de autorização: evidência do enrolamento e degrau biométrico
API do provedorToda operação bancária. Indisponibilidade do banco é indisponibilidade da operação

⚠️ Antes de executar qualquer procedimento de senha do Redis (--requirepass, BB_REDIS_PASSWORD)

deploy/docker-stack.staging.yml e deploy/docker-stack.prod.yml são o caminho LEGADO. Os blocos migraram para o Launch (LXC): 39 serviços bb-* ativos em bb-prod e 35 em bb-staging, medidos em 25/09/2026. Os bb-staging_*/bb-production_* do Swarm são sobra que nenhum deploy atualiza.

Lá o Redis é o Spark (Valkey + sentinela), onde a senha é padrão e já está ligada — o provisionamento escreve requirepass no valkey.conf na criação, e não existe caminho que suba um cluster sem senha. A conexão dos blocos vem de SPARK_REDIS_URL (scripts/deploy-bb-prod.sh:21), que sobrescreve o REDIS_URL do stack (scripts/launch-criar-bb.sh:83).

Quem for rodar a janela de deploy do --requirepass (PR #448) precisa saber que está mexendo em sobra: em produção e em staging aquilo não fecha brecha, porque a senha já valia antes. O que resta em aberto do BB-5c é TLS e assinatura do publicador — ver docs/plans/2026-09-25-onde-os-blocos-rodam-de-verdade.md.

Limites

LimiteValorOnde
Corpo da requisição1 MBapplyCommonMiddleware — afeta KYC em base64
Rate limit global10.000 req / 60sRATE_LIMIT_GLOBAL_MAX
Descrição de Pix e TED140 caracteresZod
Expiração de QR dinâmico1 a 1440 minutosZod
Página padrão / listagens20 itensRouters
Precisão monetáriaDecimal(15,2)Prisma
Limites de valor por transaçãoDo provedorMockBank: 100.000 (Pix) e 500.000 (TED)

Catálogo de erros

StatusCódigoSignificaO que fazer
400(árvore Zod)Corpo reprovado no schemaCompare os campos com §9
400VALIDATIONRegra de negócio: sem saldo, sem pixKey nem recipient, conta já encerrada, estorno de transação que não é PIX_IN COMPLETEDA message diz qual regra
400VALIDATIONtestConnection() falhou ao criar ou atualizar configConfira as credenciais e o ambiente (sandbox)
400—Webhook sem X-Organization-Id nem organizationIdCorrija a URL cadastrada no painel do provedor
401UNAUTHORIZEDToken ausente, inválido ou expiradoRenove no IAM
403—Token sem organizationIdAutentique informando a organização
403FORBIDDENSem BAAS_READ ou BAAS_ADMIN; ou conta bloqueada, encerrada, ou sem KYC aprovadoConfira permissões e o status da conta
403FORBIDDEN + details.codeAutorização do titular recusada — os doze códigos de §9Leia details.code: falta assinatura, assinatura não confere, desafio queimado, biometria exigida
503SERVICE_UNAVAILABLE + BIOMETRICS_UNAVAILABLENão deu para verificar a biometriaFalha fechada: nada foi executado. Confira o bloco Biometrics
404NOT_FOUNDRecurso inexistente ou de outra organizaçãoConfira o ID e a organização do token
409CONFLICTNome de config já usado na organizaçãoEscolha outro nome
429—Rate limitRecuo exponencial
500INTERNALErro não mapeado do provedorConsulte o log; o erro cru do provedor fica lá

Observabilidade.

  • GET /baas/health devolve identificação e versão do build. Não valida banco nem provedor — para orquestrador serve como sonda de vida, não de prontidão.
  • POST /provider-configs/:id/test é a sonda real: exercita credencial e conectividade com o banco parceiro. Vale agendar por config ativa.
  • Toda tentativa de webhook com assinatura não verificada gera warn estruturado com o provedor e o motivo, tanto com enforcement ligado quanto desligado. É o log que diz se você pode ligar PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT=on sem quebrar integração.
  • baas_webhook_events é a trilha de auditoria de entrada: guarda o payload cru, se foi processado e o erro em caso de falha. processed = false acumulando é sintoma.
  • Erros de comunicação com o provedor são logados com contexto antes de virarem AppError.

14

Segurança e compliance

Quem carrega a licença — leia isto antes de tudo. A Catalisa não é instituição autorizada a funcionar pelo Banco Central do Brasil. Não é banco, não é Instituição de Pagamento, não é SCD nem SEP, não é participante do Pix e não custodia recurso de terceiro. O BaaS é uma camada de software que integra a API de instituições que são autorizadas — Celcoin (IP e SCD), QI Tech (SCD) e FitBank/Fits (IP).

flowchart LR
  CLI["Titular da conta<br/>cliente final"]
  TOM["Sua empresa — entidade tomadora<br/>não autorizada pelo BCB"]
  CAT["Catalisa BaaS<br/>camada de software — nem prestadora, nem tomadora"]
  PRE["Instituição prestadora — Celcoin, QI Tech, Fits<br/>licença do BACEN · custódia do recurso · PLD/FT e KYC"]

  CLI -->|"contrato de conta"| PRE
  TOM -->|"usa"| CAT
  CAT -->|"API"| PRE
  TOM -->|"contrato de BaaS"| PRE

A consequência prática, e ela é contratual antes de ser técnica:

  • A conta bancária é do provedor. BaaSAccount.externalId é o identificador dela lá. O que existe aqui é um espelho com histórico.
  • O saldo é do provedor. GET /accounts/:id/balance sempre consulta a origem. As colunas locais são cache para listagem.
  • O contrato de conta é entre o titular e a instituição autorizada, com a sua empresa e a Catalisa na cadeia técnica.
  • Obrigações regulatórias de PLD/FT, KYC e reporte são da instituição autorizada e, conforme o arranjo, da sua empresa. O BaaS encaminha documento de KYC e reflete o status; ele não avalia, não pontua e não decide.

A norma brasileira de BaaS — leia antes de assinar contrato. Desde 28/11/2025 existe regulação dedicada: a Resolução Conjunta nº 16 (CMN + BCB), que dispõe sobre a prestação de serviços de Banking as a Service. Ela organiza o mercado em dois papéis — a instituição prestadora (autorizada pelo BCB) e a entidade tomadora (a sua empresa, se não for autorizada) — e a Catalisa não é nenhum dos dois: é o software que a tomadora usa para falar com a prestadora. O que a norma exige de você, se for a tomadora:

DispositivoO que determinaO que isso significa na prática
Art. 4º, §2ºAs contas devem ser de titularidade do cliente na instituição prestadoraConta bolsão / omnibus deixa de ser arquitetura viável. É o desenho que este building block já adota: cada BaaSAccount é uma conta individual no provedor
Art. 6ºVedado contratar BaaS com uma prestadora se já há contrato vigente com outra para o mesmo tipo de contaA capacidade técnica de rodar dois provedores existe; o uso simultâneo para o mesmo tipo de conta é questão jurídica sua
Art. 8ºVedado à tomadora receber em conta própria valores dos clientes, cobrar tarifa em nome próprio e subcontratar os serviços. Dever de informar ao cliente que a tomadora não é instituição autorizada pelo BCBO aviso ao cliente final é obrigação sua, na sua interface — o BaaS não tem como cumpri-la por você
Art. 10PLD/FT, identificação e qualificação do cliente e prevenção a fraudes são responsabilidade da prestadora, que pode delegar tarefas acessórias sem afastar a própria responsabilidadeO BaaS encaminha documento de KYC; a análise, a decisão e o dever regulatório são da instituição
Art. 19Cooperativas de crédito e sociedades de arrendamento mercantil não podem ser prestadorasRestringe o universo de parceiros elegíveis
Art. 24O BCB pode vetar, restringir, suspender ou determinar o encerramento do contratoRisco de continuidade que precisa estar no seu plano, não só no contrato

Prazo: os contratos vigentes têm até 31/12/2026 para se adequar. Some-se a IN BCB nº 754/2026, que obriga o registro das entidades tomadoras no Unicad com efeitos a partir de 1º/09/2026.

Nomenclatura. A Resolução Conjunta nº 17/2025 proíbe o uso de "banco" e "bank" em nome, marca e domínio por quem não tem licença bancária, com prazo até 28/11/2026 — foi por isso que o FitBank virou Fits. Se o seu produto se chama "algum-coisa bank", isso é um item de projeto com data.

Outras normas que enquadram o provedor — não a Catalisa: a Resolução BCB nº 80/2021, que define as quatro modalidades de instituição de pagamento (emissor de moeda eletrônica, emissor de instrumento de pagamento pós-pago, credenciador e iniciador de transação de pagamento) e o processo de autorização; a Resolução BCB nº 1/2020, regulamento do Pix, cujo art. 3º torna a participação obrigatória para instituições autorizadas com mais de 500 mil contas ativas — e só instituições autorizadas participam do Pix; e a Resolução CMN nº 5.050/2022, que rege SCD e SEP. O regime de limiares por porte da Res. 80 foi revogado pela Res. BCB nº 494/2025, que substituiu tudo por uma janela única de autorização já encerrada — se um fornecedor disser que "está no processo de autorização", peça a data e o número do protocolo.

Se a sua empresa já é uma instituição autorizada, o enquadramento muda: contratar software de terceiro passa pela Resolução BCB nº 85/2021 (terceirização por instituições de pagamento) ou pela Resolução CMN nº 4.893/2021 (instituições financeiras). Duas consequências práticas: a responsabilidade por confiabilidade, integridade, disponibilidade, segurança e sigilo não se transfere ao fornecedor, e a contratação de serviço relevante exige notificação ao BCB em até 10 dias. Trate a adoção deste building block como contratação sujeita a essas normas.

Antes de assinar com qualquer provedor, confirme na lista de instituições em funcionamento do BACEN que a entidade que assina o contrato está autorizada, e sob qual modalidade — a marca comercial e a razão social licenciada nem sempre coincidem. Esta documentação não substitui essa verificação nem parecer jurídico.

Isolamento entre tenants. O organizationId vem do claim assinado do JWT e nunca do corpo da requisição. Todo router de negócio aplica requireOrganization, que devolve 403 quando o claim falta. Em cima disso, cada serviço compara a organização do token com a do registro antes de agir — AccountService.getById, PixService.getAccount, TedService, ProviderConfigService.getById — e devolve 404, não 403, quando não bate. A escolha é deliberada: 403 confirmaria que o recurso existe em outro tenant.

Consultas de listagem recebem organizationId como filtro obrigatório no repositório, não como parâmetro opcional.

Credenciais de provedor. Cifradas com AES-256-GCM por encryptCredentials, no formato iv:authTag:ciphertext, com IV de 12 bytes aleatório por operação. A chave mestra vem de BAAS_CREDENTIAL_MASTER_KEY e é validada como exatamente 64 caracteres hexadecimais — chave malformada faz a operação falhar em vez de degradar para algo mais fraco. O GCM garante autenticidade: ciphertext adulterado falha na decifragem, não decifra errado. As credenciais nunca aparecem em resposta de API — toResponseData não as inclui — e não há endpoint de leitura delas.

Autorização do titular — o que cada ator consegue fazer sozinho

O desenho parte de uma pergunta desconfortável: quem, hoje, consegue tirar dinheiro da conta sem o titular? A resposta, sem esta trava, é "qualquer coisa que chegue ao BaaS com BAAS_ADMIN" — o backend do cliente, um workflow com defeito, alguém com acesso de escrita ao banco de dados. A trava opcional por conta muda esse quadro:

Ator comprometidoSem política (NONE)Com HOLDER_SIGNATURE
Backend do cliente / token BAAS_ADMINMove o dinheiroNão move. Sem a assinatura do enclave do celular, a credencial do provedor nem chega a ser decifrada
Workflow ou automação com defeitoMove o dinheiroNão move. A automação não tem chave privada
Automação com mandato (régua, workflow)Move o dinheiroFaz só o que o mandato lista, dentro do teto por operação, do dia e da contagem, na janela, até a revogação — e cada ato cita o mandato na trilha. Não concede mandato a si mesma: a concessão é assinada no celular. A baixa de boleto era o buraco: destruía um recebível só com BAAS_ADMIN, sem passar por nada disto
Escrita direta no banco de dados (inserir chave de dispositivo)Não se aplicaNão move. A evidência de enrolamento é reverificada a cada uso e não bate com o hash da chave inserida
Escrita direta no banco (apagar a linha da política, ou editá-la para NONE)—Não move. A trilha encadeada guarda o hash da política a cada mudança (BB-5): linha editada é POLICY_INTEGRITY (diverged), linha apagada é POLICY_INTEGRITY (deleted) — com ou sem dispositivos —, e o PUT que tentaria "voltar para NONE" é recusado antes de decidir se precisa de assinatura. Por baixo, a trava do #428 continua: conta que tem ou já teve aparelho nunca lê como NONE mesmo se a trilha tiver perdido a linha
Escrita direta no banco do BaaS e da trilha—Move. Hoje é a mesma credencial nos dois (BB-5b, §14 e §15): apagar a última linha e rebobinar a cabeça devolve o veredito ok. O que sobra é a âncora assinada já publicada ao cliente, que a corrente reescrita não reproduz — mas quem denuncia é o GET /verify do Audit Trail, rodado por alguém; o BaaS não o chama a cada escrita
Escrita no barramento (Redis)—Move. policy.changed forjado é encadeado e ancorado como legítimo: o consumidor não verifica publicador. Desde 24/09/2026 é preciso ter a senha do Redis — e todos os blocos têm (BB-5c, §14 e §15)
BaaS e Biometrics comprometidos juntosMove o dinheiroMove — mas deixa trilha: baas.authorization.granted, o operationHash e a sessão biométrica assinada
Chave de API de sandbox da biometria—Não move. Evidência com environment: test é recusada em conta de provedor real
Credencial de produção da biometria da organização—Não move. A tentação é abrir uma sessão LIVENESS_ONLY declarando o CPF da vítima e tirar a própria selfie (BIOMETRIC_FLOW_INVALID), ou uma ONBOARDING com documento forjado (BIOMETRIC_IDENTITY_NOT_PROVEN). Cadastrar chave e passar no degrau exigem identityProven: match 1:1 contra cadastro facial do próprio titular
Celular do titular roubado e desbloqueadoMove o dinheiroMove até a revogação; acima do limiar ainda exige prova de vida
Qualquer um dos acima, numa conta COM bloqueio escriturado—Não move o que está bloqueado, pelo baas. Pix e TED conferem spendableBalance antes de falar com o banco e recusam com 403 INSUFFICIENT_SPENDABLE_BALANCE. Mas a trava é do portão: quem alcança o console do provedor, outra integração ou o próprio banco move, porque lá o saldo é o cheio. Só descobrimos na leitura seguinte, como baas.hold.divergence.detected — e nada é corrigido (§15)
BAAS_ADMIN comprometido criando bloqueios—Congela, não rouba. Criar bloqueio não exige assinatura (é a direção segura), então um token roubado consegue travar a conta inteira. O dinheiro não sai. E a saída não depende de quem congelou: o titular com o aparelho ativo libera com presença
Login de UM operador com BAAS_ADMIN, querendo liberar ou consumir bloqueioPela rota, não libera nem consome sozinho: a porta direta recusa pessoa (403 HOLD_DIRECT_ACTION_MACHINE_ONLY) e o pedido exige que OUTRA pessoa aprove (403 HOLD_REQUEST_SAME_ACTOR). Mas hoje todo papel com BAAS_ADMIN também tem API_KEYS_CREATE e IAM_ORGANIZATIONS_UPDATE: ele emite uma chave ou um segredo M2M e chama a porta direta. Até existir um papel de operador de BaaS sem essas permissões, o quatro olhos é trilha, não controle (§15)Igual, e ainda precisa de presença ou mandato

Os níveis 2 e 3, que ainda não existem, fecham o que sobra: nível 2, cossinatura do tenant (duas assinaturas independentes, a do titular e a da instituição, para faixas de valor); nível 3, verificação da assinatura do titular no provedor, o que tira o BaaS da posição de único guardião — hoje, quem compromete BaaS e Biometrics ao mesmo tempo passa.

A política ancorada na trilha (BB-5)

O que a tabela acima chama de "escrita direta no banco" tinha, até o BB-5, um contorno de uma linha: UPDATE baas_authorization_policies SET mode = 'NONE'. Fechar isso exige que o estado da política more também fora deste banco, e a trilha encadeada do Audit Trail (BB-3) já é isso: corrente por organização, âncoras assinadas que saem para o cliente, GET /verify.

O que o BB-5 fecha, dito com precisão: o one-liner. UPDATE ... SET mode='NONE' sozinho, DELETE da linha sozinho, e a restauração de uma versão antiga da linha — todos conferidos contra a cabeça da trilha e recusados. É o ataque de quem alcança só o banco do BaaS. Não fecha quem alcança a trilha ou o Redis junto: isso é BB-5b e BB-5c, no fim desta subseção, com o preço de cada um. Nada aqui promete mais do que o código entrega.

sequenceDiagram
  autonumber
  participant ADM as BAAS_ADMIN
  participant BAAS as BaaS
  participant PG as baas_authorization_policies
  participant ST as Redis Stream iam-events
  participant AT as Audit Trail
  ADM->>BAAS: PUT /accounts/:id/authorization-policy
  BAAS->>PG: BEGIN · pg_advisory_xact_lock(conta) · UPSERT (version+1) · UPDATE policy_hash
  BAAS->>ST: XADD baas.authorization.policy.changed {policyHash, mode, version, …}
  Note over BAAS,ST: falhou? ROLLBACK — mudança que a trilha não conhece não existe
  BAAS->>PG: COMMIT
  Note over BAAS,PG: o XADD é a ÚLTIMA coisa antes do COMMIT — nada nosso roda depois dele
  AT-->>ST: XREADGROUP (segundos)
  AT->>AT: linha encadeada: sequence, hash
  BAAS->>AT: GET /logs?filter[resourceType]=baas_authorization_policy&filter[resourceId]=:id (até BAAS_POLICY_ANCHOR_WAIT_MS)
  AT-->>BAAS: {sequence, hash, metadata.policyHash}
  BAAS->>PG: UPDATE trail_sequence, trail_hash, trail_anchored_at
  BAAS-->>ADM: 200 {trail: {messageId, sequence, hash, anchoredAt}}

E a cada escrita gated, antes de qualquer outra coisa — inclusive antes de decidir se a conta "não aderiu":

Linha no bancoLinha na trilhaVereditoResposta
nãonãonone — nunca aderiusegue como NONE
simsim, hash igualoksegue
simsim, hash diferentediverged — editada403 POLICY_INTEGRITY
nãosimdeleted — apagada403 POLICY_INTEGRITY
simnão, e a corrente nunca foi podadaunanchored — anterior ao BB-5, ou inserida à mão403 POLICY_INTEGRITY até ancorar
simnão, e a corrente foi podadapruned — pode ser linha expurgada, pode ser linha escrita à mão403 POLICY_INTEGRITY; no anchor, 409 POLICY_TRAIL_PRUNED
qualquernão deu para lerunavailable503 POLICY_INTEGRITY_UNAVAILABLE

Decisões que valem saber:

  • A trilha é assíncrona, e a posição vem por aperto de mão. O EventPublisher devolve o id da mensagem no stream na hora; sequence e hash só existem quando o consumidor do Audit Trail grava a linha, segundos depois. O BaaS publica, espera (limitado) a linha com o policyHash que acabou de gravar e anota a posição na própria linha. Essas colunas não são a defesa — moram no mesmo banco que o atacante controla; são conveniência para quem opera. A defesa é a comparação, a cada escrita.

  • Sempre a última linha, nunca "alguma linha". Reverter a linha para um estado antigo e legítimo (o NONE com que a conta nasceu) também é adulteração.

  • Sem janela de graça lida do banco. Entre o commit e o consumidor gravar a linha há uma fresta de milissegundos em que uma escrita é recusada por POLICY_INTEGRITY. A correção tentadora — confiar no updated_at por 30 s — é um buraco: o atacante grava updated_at = now() no mesmo UPDATE. Em vez disso, toda divergência é relida sem cache uma vez antes de valer, e o PUT espera a trilha antes de responder.

  • O hash leva o id da linha como sal — e o id não sai por lugar nenhum. A trilha é legível com AUDIT_LOGS_READ, permissão diferente de BAAS_READ. Um hash de mode + CPF + … sem sal cairia em 10¹¹ tentativas; com o CPF mascarado que a própria linha publica (***.456.789-**), cairia em ~10³. O sal só protege enquanto ele não vaza: até este PR o GET /authorization-policy devolvia o id da linha em data.id, e quem tivesse BAAS_READ e AUDIT_LOGS_READ remontava o CPF em milhares de tentativas. Agora data.id é o accountId, tanto no GET quanto no anchor, e o id da linha não aparece em resposta nenhuma. O que protege hoje, na ordem: o id não deixar o bloco; o CPF sair mascarado na trilha; e as duas permissões serem distintas. Contra quem lê este banco nada disso vale — esse já lê o CPF em claro.

  • Cache curto, por conta, invalidado na mudança. BAAS_POLICY_INTEGRITY_CACHE_MS (padrão 5000): uma leitura da trilha por conta, por réplica, por janela. Um veredito ruim nunca vem do cache — é sempre relido.

  • Publicar é a última coisa antes do COMMIT. A ordem importa: se o XADD acontecesse antes do último UPDATE, um COMMIT que falhasse depois dele deixaria a trilha em v+1 e o banco em v — diverged permanente, e o PUT (que confere o current antes) recusaria também: conta sem saída pela API. Agora grava, comita, e só então carimba o trail_message_id (informativo, best effort). Publicação que falha é ROLLBACK; COMMIT que falha deixa a conta em unanchored/diverged, estados já tratados — e para o único caso que sobra há a regra de repetição: um PUT cujo resultado seria exatamente o estado que a trilha já atesta (mesmo id, version + 1, mesmos campos) é aquele COMMIT perdido sendo refeito, e passa. Ele não lava nada: o único estado que consegue escrever é o que a trilha já assinou.

Ancoragem inicial. Política gravada antes do BB-5 não tem linha na trilha e fica em unanchored. POST /accounts/:id/authorization-policy/anchor (BAAS_ADMIN) publica a linha atual como a primeira do histórico daquela conta, com bootstrap: true e actorType: system — e só quando a trilha não tem linha nenhuma para a conta. Se já tem e não bate: 409, e nada é publicado. É uma rota, rodada uma vez por ambiente antes de o portão subir, e não um passo de boot: passo de boot rodaria em toda réplica, sem ninguém olhando.

A poda não apaga a última linha de uma política. O POST /cleanup do Audit Trail remove o prefixo mais velho que a retenção. Uma conta parada por mais tempo que a retenção perdia a sua única policy.changed, virava unanchored — e unanchored é justamente o veredito que o anchor aceita: o operador rodava o anchor e abençoava a linha como ela estivesse. Quem edita a política e espera a poda (ou encurta a retenção com AUDIT_CONFIG_MANAGE) ganhava o carimbo de graça. Duas travas fecham isso:

  1. Tipos pinados. A poda preserva, para cada (resourceType, resourceId), a linha mais nova dos tipos da lista fechada em src/audit-trail/utils/pinned-events.ts — hoje só baas.authorization.policy.changed. Lista em código, não configurável: configurável deixaria quem configura despinar a linha que protege a política. A marca da poda continua andando até o corte, e o /verify nunca relê as sobreviventes.
  2. O anchor recusa quando houve poda. A fachada latestEvent passa a expor prunedThroughSequence (de audit_chain_heads), e o BaaS distingue "nunca teve política" de "trilha podada". Conta com linha no banco, sem linha na trilha, numa organização cuja corrente foi podada: 409 com details.code = POLICY_TRAIL_PRUNED e o prunedThroughSequence de onde a poda parou. Vale para trilha podada antes deste PR, quando o pin ainda não existia — a saída é operacional, abaixo.

Recuperação de uma linha adulterada é operacional, de propósito. Não há rota que "re-abençoe" uma linha (seria a lavagem que a ancoragem existe para impedir). A linha policy.changed traz mode, version, requireBiometricAbove, o CPF mascarado e a contagem de operadores — operatorsCount, não a lista. Então a restauração não sai só da trilha: o operador precisa do CPF em claro e da lista de operadores vinda do tenant, e escreve a linha de volta (mesmo id, mesma version) até o hash bater. GET /authorization-policy diz integrity ao vivo para conferir. Se o tenant não souber a lista, não há restauração: a saída é o titular gravar a política de novo pelo PUT, assinando o afrouxamento se houver.

O que o BB-5 NÃO fecha — e quanto custa fechar. As duas brechas abaixo funcionam hoje. Estão escritas aqui, e como testes skip em tests/unit/baas/services/holder-authorization.service.test.ts ("what BB-5 does not close"), porque um teste que passa provando o ataque é a medida honesta do que falta.

#BrechaPor que funcionaO que custa fechar
BB-5bCredencial de banco compartilhada. Quem escreve na política também apaga a última linha de audit.audit_logs e rebobina audit.audit_chain_heads — e a política volta a ler okdeploy/docker-stack.prod.yml:56 dá um único DATABASE_URL (base building_blocks, usuário postgres) a todos os blocos. A trilha mora no mesmo banco, com o mesmo dono. E o BaaS só consulta latestEvent: nunca chama /verify, então uma cabeça rebobinada é indistinguível de uma legítimaTrilha em banco e credencial próprios (migração de dados + um segundo DATABASE_URL por serviço + rotina de backup separada), ou, no mínimo, usuário Postgres por schema: o baas sem DELETE/UPDATE em audit.*. O mínimo é um GRANT/REVOKE e uma variável nova, sem migrar nada. Nenhum dos dois é decisão desta frente: mexe em topologia
BB-5cPublicador não autenticado. Um policy.changed forjado é encadeado e ancorado como legítimoaudit-consumer.ts ingere qualquer entrada de iam-events e shared/lib/events.ts faz XADD cru, sem assinatura. Quem alcança o Redis escolhe o policyHash que a trilha vai atestar. A metade de rede nunca esteve aberta no ambiente que importa — e isto foi medido depois, em 25/09/2026: os blocos rodam no Launch, onde o Redis é o Spark, e lá requirepass é escrito no valkey.conf pelo provisionamento, sem liga/desliga. O PR #448 (24/09/2026) pôs --requirepass nos dois docker-stack, que são o caminho legado (§13); ele fecha o Redis do Swarm, que é sobraFalta o publicador assinado: cada entrada carrega HMAC ou assinatura do bloco emissor, e o consumidor recusa o que não verificar — chaves por bloco, rotação, e um período de tolerância em que o não-assinado ainda entra com warn. A senha tira o atacante anônimo da rede; só a assinatura tira o bloco comprometido, que é o que a trilha promete. Frente própria. O Spark tem ACL por usuário, então separar publicador de consumidor voltou a ser possível — ver docs/plans/2026-09-25-onde-os-blocos-rodam-de-verdade.md §5

Enquanto os dois não existirem, a promessa correta do BB-5 é a do primeiro parágrafo: fecha o one-liner no banco do BaaS. Quem alcança a trilha ou o barramento continua passando.

Payload canônico — a especificação que o aplicativo precisa reproduzir

O aplicativo assina exatamente os mesmos bytes que o BaaS reconstrói a partir do corpo da requisição. As regras são poucas e não admitem interpretação (é o RFC 8785/JCS restrito ao conjunto de valores abaixo):

texto
payload = canonicalJson({ v: 1, type, accountId, challengeId, nonce, params })
operationHash = sha256hex(payload)          // hex minúsculo, sobre os bytes UTF-8
assinatura = ECDSA P-256 com SHA-256 sobre os bytes UTF-8 do payload, em base64 (DER ou r||s)
payload = canonicalJson({ v: 1, type, accountId, challengeId, nonce, params })
operationHash = sha256hex(payload)          // hex minúsculo, sobre os bytes UTF-8
assinatura = ECDSA P-256 com SHA-256 sobre os bytes UTF-8 do payload, em base64 (DER ou r||s)
  • chaves de objeto ordenadas em ordem crescente de unidade de código UTF-16 (todas as nossas são ASCII);
  • sem espaço em branco algum;
  • campo opcional ausente é omitido; null explícito é emitido como null;
  • vetores preservam a ordem;
  • strings escapadas como JSON.stringify faz (RFC 8259, sem escapar não-ASCII);
  • o único número é o v; todo valor monetário é texto com exatamente duas casas ("150.75"). Valor com mais precisão do que Decimal(15,2) é recusado com 400, não arredondado;
  • operators normalizados antes de assinar: só dígitos, sem repetição, em ordem crescente.

type e o que vai em params (montado pelo BaaS a partir do corpo, nunca de um hash do cliente):

typeparams
pix.transferamount, description?, pixKey?, recipient? (name, documentNumber, bankCode, branchNumber, accountNumber, accountType), scheduledFor?
ted.transferamount, description?, recipient (idem + accountDigit?), scheduledFor?
pix.refundtransactionId (o da rota), reason, amount? — o limiar biométrico é comparado contra o que sai de fato: o parcial, quando vem no corpo; o valor inteiro da transação, quando não vem
pix.key.createkeyType, keyValue?
pix.key.deletepixKeyId
pix.qr.createamount, description?, expiresInMinutes? — só o QR dinâmico; o estático não declara valor e segue aberto
account.closereason
account.updateholder com os campos que a rota aceita: name?, documentType?, documentNumber?, email?, phone?, address? (street, number, complement?, neighborhood, city, state, zipCode, country?), birthDate?, motherName?, tradeName?, legalRepresentative? (name, documentNumber, email, birthDate)
account.kyc.submitdocumentsHash — sha256hex da forma canônica dos documentos (identityDocument? com type, front, back?; selfie?; proofOfAddress?; proofOfIncome?; socialContract?). Uma selfie em base64 tem megabytes: o celular assina o resumo dos mesmos bytes que vai enviar, e trocar um byte de qualquer documento muda o resumo
policy.updatemode, holderDocument (ou null), requireBiometricAbove (texto com duas casas ou null), operators
mandate.grantscope (único, ordenado), maxAmountPerOperation, maxAmountPerDay (texto com duas casas ou null), maxOperationsPerDay, maxOperations (inteiro ou null), notBefore, notAfter (ISO 8601 em UTC, com milissegundos — Date.toISOString()). Todo campo é explícito: ausente vira null, nunca omitido. O amount pesado contra requireBiometricAbove é o teto por operação; sem teto, conta como acima de qualquer limiar
mandate.revokemandateId — só quando o titular revoga; o admin revoga sem assinatura
boleto.issueamount, dueDate (YYYY-MM-DD), payerDocument (só dígitos), payerName
boleto.write_offboletoId (o da rota), amount (o do título — é o recebível que deixa de existir), reason?
device.enrollnão usa desafio: sha256hex(canonicalJson({v:1,type:"device.enroll",accountId,publicKey}))

Vetor de teste — o mesmo que a suíte verifica em `tests/unit/baas/fixtures/holder-authorization-vector.json`, com assinaturas nas duas codificações:

texto
payload:
{"accountId":"3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01","challengeId":"8f14e45f-ceea-467a-9c3a-0d3b1b2c9f10","nonce":"Zm9vYmFyLW5vbmNlLWV4YW1wbGUtMzJieXRlcy1YWQ","params":{"amount":"150.75","description":"Pagamento pedido 8841","pixKey":"destinatario@exemplo.com.br"},"type":"pix.transfer","v":1}

operationHash:
eb6b59e657e816026c737297ada28bca0839509341b8c2607dd54d0c3260fe93

publicKey (SPKI DER em base64):
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEz+zkOh9SjN/lpQ3cbO1FZTYp2DKaQQ2eJyT1qO34s6p325Ebz7DkoVSZMgRT6X9q3PixtaZdFnRNTKxxt6fWWw==
payload:
{"accountId":"3c9a77e1-2b45-4c8d-9e10-5f6a7b8c9d01","challengeId":"8f14e45f-ceea-467a-9c3a-0d3b1b2c9f10","nonce":"Zm9vYmFyLW5vbmNlLWV4YW1wbGUtMzJieXRlcy1YWQ","params":{"amount":"150.75","description":"Pagamento pedido 8841","pixKey":"destinatario@exemplo.com.br"},"type":"pix.transfer","v":1}

operationHash:
eb6b59e657e816026c737297ada28bca0839509341b8c2607dd54d0c3260fe93

publicKey (SPKI DER em base64):
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEz+zkOh9SjN/lpQ3cbO1FZTYp2DKaQQ2eJyT1qO34s6p325Ebz7DkoVSZMgRT6X9q3PixtaZdFnRNTKxxt6fWWw==

Implementação de referência da forma canônica (é a que roda em produção, src/baas/utils/canonical-operation.ts):

ts
function canonicalJson(value) {
  if (value === null) return 'null'
  if (typeof value === 'string') return JSON.stringify(value)
  if (typeof value === 'boolean') return value ? 'true' : 'false'
  if (typeof value === 'number') return String(value)           // só inteiros seguros
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
  const entries = Object.keys(value)
    .filter((key) => value[key] !== undefined)
    .sort()
    .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
  return `{${entries.join(',')}}`
}
function canonicalJson(value) {
  if (value === null) return 'null'
  if (typeof value === 'string') return JSON.stringify(value)
  if (typeof value === 'boolean') return value ? 'true' : 'false'
  if (typeof value === 'number') return String(value)           // só inteiros seguros
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
  const entries = Object.keys(value)
    .filter((key) => value[key] !== undefined)
    .sort()
    .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
  return `{${entries.join(',')}}`
}

Sessão de sandbox não autoriza dinheiro real. A evidência traz o environment da chave que abriu a sessão, e no ambiente test o bloco de Biometrics decide o desfecho pelo final do CPF — uma selfie falsa é aprovada de propósito. Por isso o BaaS só aceita environment === 'live', tanto no cadastro da chave quanto no degrau biométrico, e recusa com BIOMETRIC_ENVIRONMENT_INVALID. A única exceção é a conta cujo provedor é simulador: config MOCKBANK, ou config marcada com settings.sandbox: true. Nessas, test é aceito — é o que permite exercitar a esteira inteira antes de existir contrato com banco. Conta ligada a provedor real nunca aceita test, em nenhuma hipótese. A checagem lê a linha da config; a credencial cifrada continua sem ser tocada.

Rosto vivo não é o mesmo que "o rosto do titular". No bloco de Biometrics, o subjectRef (CPF) é declarado por quem abre a sessão, e a comparação facial 1:1 é dispensada quando o fluxo é LIVENESS_ONLY ou ENROLLMENT (decision.ts remove o check MATCH). Uma sessão LIVENESS_ONLY aprovada, em ambiente real, com o CPF do titular e o hash certo, prova apenas que alguém vivo estava na frente da câmera. Sem trava, quem tem a credencial de Biometrics da organização abre uma sessão dessas declarando o CPF da vítima, tira a própria selfie, cadastra o próprio aparelho na conta dela e daí assina Pix, TED, encerramento e a própria política — justamente o ator que este quadro diz conter.

Quem responde a essa pergunta é identityProven, derivado dentro do bloco: sessão aprovada, com match 1:1 PASSED contra um cadastro facial amarrado ao mesmo titular. O BaaS exige esse campo no cadastro da chave e no degrau biométrico, e recusa o resto com BIOMETRIC_IDENTITY_NOT_PROVEN. Campo ausente — fachada remota antiga — vale false, nunca "não conferido". Em cima dele fica o gate de fluxo, como defesa em profundidade: fluxo fora de ONBOARDING/AUTHENTICATION é recusado antes, com BIOMETRIC_FLOW_INVALID. As duas checagens rodam também na reverificação a cada uso: chave cadastrada por sessão que não provou identidade para de autorizar a partir de agora, sem migração nenhuma.

Cadastro facial revogado ou vencido mata a chave de aparelho — por design (LGPD). A evidência de enrolamento da chave é reverificada a cada uso, e o biometrics deixa de dar identityProven quando o cadastro de referência é revogado ou passa de expiresAt (retenção templateDays). Toda chave cadastrada contra esse cadastro para de autorizar no mesmo instante. Para não morrer em silêncio com o genérico, o bloco devolve identityUnprovenReason (TEMPLATE_REVOKED / TEMPLATE_EXPIRED) e o BaaS recusa com BIOMETRIC_TEMPLATE_UNUSABLE — no uso da chave, no cadastro dela, no degrau biométrico e em holder-identity-verifications. Qualquer outro "não provou" segue BIOMETRIC_IDENTITY_NOT_PROVEN. O caminho de volta é do app: novo cadastro facial do titular e novo cadastro do aparelho (no banking, FACE_ENROLLMENT_REQUIRED). Para evitar, estender a retenção antes do vencimento.

Decisão: ONBOARDING não cadastra chave de aparelho. identityProven é false em ONBOARDING porque ali a âncora é o documento que o integrador enviou, não um cadastro que o bloco possui — e o integrador é exatamente o ator que este quadro diz conter: documento forjado com o CPF da vítima e o rosto do atacante passaria. Como a chave de dispositivo é a raiz de confiança de toda assinatura posterior, ela exige a evidência mais forte que o bloco dá: AUTHENTICATION casada 1:1 contra cadastro facial do próprio titular. O primeiro cadastro facial acontece antes, na jornada de abertura da conta — sessão ONBOARDING com enrollOnApprove: true, que grava o template ao aprovar. Sem esse passo, não há como cadastrar aparelho, e é assim de propósito.

A ordem da verificação, dentro do serviço — e ela é a garantia principal: carrega a política → reconstrói o payload do corpo → confere o dispositivo (ativo, da conta, permitido pelo modo) → reverifica a evidência de enrolamento (válida, APPROVED, identityProven, em fluxo permitido, vinculada ao hash e ao titular, e em ambiente live) → verifica a assinatura → consome o desafio (update condicional) → acima do limiar, verifica a sessão biométrica vinculada ao operationHash, com as mesmas condições → só então chama o caminho que decifra a credencial do provedor.

Repetição idempotente continua valendo sem assinatura nova. findReplay roda antes da trava e devolve a transação que a primeira chamada criou: nenhuma chamada ao provedor, nenhuma decifragem de credencial, nenhum dinheiro a mais. Exigir assinatura ali puniria o retry honesto, e o que um atacante obtém repetindo a chave é a mesma transação que ele já leria com BAAS_READ.

Chave privada. Nunca sai do enclave do celular (Secure Enclave no iOS, StrongBox/TEE no Android). O BaaS guarda só a pública, o keyId derivado e a sessão biométrica do enrolamento. Perdeu o celular: revogue (DELETE /devices/:deviceId, sempre permitido) e enrole outro — o enrolamento novo se sustenta na prova de vida, não na chave antiga.

Mandato — a presença antecipada

Cobrança emitida por régua, baixa agendada depois da renegociação, repasse noturno: ninguém aperta isso com o dedo, e exigir o celular do titular ali faria alguém construir um contorno. O mandato é a presença do titular concedida antes, com escopo fechado, e ele obedece a seis regras:

  1. Só nasce de uma assinatura do titular. POST /accounts/:id/mandates é uma escrita gated como qualquer outra: desafio, chave de aparelho, evidência de enrolamento reverificada, assinatura sobre o mandate.grant canônico. Conta sem política, ou em NONE, não tem titular para assinar e responde 400. O degrau biométrico é pesado contra o teto por operação — "no nível que a operação exigiria se fosse manual" — e um mandato sem teto conta como acima de qualquer limiar. Sessão de sandbox é recusada como em todo o resto.
  2. A concessão é reverificada a cada uso. A linha guarda o aparelho, o desafio, o nonce, a assinatura e o hash da concessão. Quando a máquina cita o mandato, o BaaS confere que o aparelho continua ACTIVE e permitido pelo modo, reverifica a evidência que o cadastrou, reconstrói o mandate.grant a partir das próprias colunas da linha e verifica a assinatura guardada sobre ele. Linha inserida direto no banco não tem assinatura que valha (MANDATE_INVALID); escopo alargado ou limite afrouxado na linha muda o payload reconstruído e quebra a assinatura do mesmo jeito. A tabela não é raiz de confiança — a chave do celular é.
  3. Limitado, ou não nasce. Pelo menos um entre teto por operação e contagem total, e fim em até 12 meses (menos, se o tenant apertou mandateMaxMonths); senão 400 MANDATE_UNBOUNDED no parser e no serviço. Sem isso, scope: [boleto.write_off], limites null, notAfter: 2099 seria válido: uma capacidade ao portador que destrói recebível sem teto nem prazo, assinada uma vez e nunca mais pensada — o contorno na direção oposta.
  4. Escopo fechado, e fechado duas vezes. Mandato sem scope é recusado; e cada item tem de estar no conjunto que alguma rota lê por mandato hoje — boleto.issue e boleto.write_off. Um mandato para pix.transfer enquanto nenhuma rota de Pix aceita mandateId seria uma concessão que ninguém consegue usar. O conjunto cresce quando uma rota cresce. Os dois tipos valem nos dois sentidos: na conta que aderiu, emitir e baixar exigem presença ou mandato — uma régua emitindo cobrança em nome do titular sem mandato é exatamente o contorno que o mandato existe para fechar.
  5. Os limites são consumidos sob o lock da linha, antes da credencial. consumeMandate roda numa transação: SELECT … FOR UPDATE no mandato, releitura de status e janela já sob o lock (revogação correndo contra um uso: um dos dois ganha, nunca os dois), upsert da linha do dia e só então os contadores são comparados e incrementados. Dez execuções em paralelo contra maxOperations: 3 produzem exatamente três — o teste de integração mede isso. Unidade consumida por uma tentativa que o banco depois recusa fica consumida: o limite acota tentativas, e contar é a direção segura. O dia é o dia útil em America/Sao_Paulo.
  6. Revogar é sempre permitido; editar não existe. BAAS_ADMIN revoga sem assinatura, como revoga uma chave (régua descontrolada não espera); o titular revoga com um mandate.revoke assinado, e a trilha diz quem foi. Assinatura que falha na revogação é erro, não rebaixamento silencioso para revogação do admin. Revogar a chave que concedeu o mandato também o para (DEVICE_REVOKED no uso): o mandato vale o que vale a assinatura que o concedeu.

Presença vence. Quando a requisição traz holderAuthorization e mandateId, a assinatura do titular é o que autoriza, e o mandato não é consumido. Conta que não aderiu ignora o mandato: sem política, ou em NONE, nada é verificado e nada muda — inclusive para a régua que cita um mandateId por engano, e para a régua que emite sem citar nada.

A trilha cita o mandato. Sob mandato não há desafio, e o operationHash do ato é sha256hex(canonicalJson({v:1,type,accountId,mandateId,params})) — identificador para a trilha, não bytes assinados por alguém. O baas.authorization.granted leva mandateId e mandateConsumed (§8), e deviceId/keyId são os da chave que concedeu.

O que ficou de fora, e por quê. O contrato do bloco de atestado (§9 do documento de attestation) modela a concessão como grantAttestation com nível de garantia. Esse bloco não tem dono, e o contrato proíbe construir o verificador "por enquanto" dentro de um consumidor. A concessão aqui é a assinatura do aparelho que o BaaS já confia; quando o bloco existir, grantAttestation substitui a assinatura guardada e o assurance entra na trilha.

Bloqueio de saldo — por que criar é livre e soltar não é

É a decisão mais contraintuitiva deste bloco, e a que mais convida a um "conserto" bem-intencionado. O quadro:

AtoO que faz com o dinheiroPortão
hold.createRestringe o que a automação do tenant consegue gastarBAAS_ADMIN. Sem assinatura, sem mandato
hold.releaseDevolve poder de gastoMáquina pela porta direta, ou pessoa por pedido decidido por OUTRA pessoa. Conta que aderiu: presença do titular ou mandato hold.release
hold.settleMove dinheiro para um terceiroMáquina pela porta direta, ou pessoa por pedido decidido por OUTRA pessoa. Conta que aderiu: presença ou mandato hold.settle

A régua é a mesma do PUT da política acima — apertar é livre, afrouxar se assina. Ninguém rouba bloqueando: exigir assinatura para criar tornaria o produto de crédito impossível (a esteira bloqueia a garantia de madrugada, sem ninguém com o celular na mão) sem tornar o dinheiro mais seguro em nada.

O risco residual, dito em voz alta. Um BAAS_ADMIN comprometido consegue congelar a conta inteira criando bloqueios. Isso é negação de serviço, não roubo — o dinheiro não sai. E a saída não depende de quem congelou: o titular com o aparelho ativo libera com presença, exatamente como sempre pode revogar um aparelho. Foi por isso que hold.release aceita presença; se aceitasse só mandato, o atacante que detém o mandato seria o único capaz de descongelar.

Duas consequências que caem daí:

  • hold.create não entra em MANDATE_ELIGIBLE_TYPES. O conjunto só admite tipo cuja rota lê mandateId, e a criação não lê, porque não tem portão. Um mandato de criação seria uma concessão que ninguém consegue usar — e uma concessão que lista hold.create é recusada com 400.
  • O que a criação tem é o portão de capacidade (hold.create, na tabela abaixo). Ela não move dinheiro, mas fala com o banco no caminho nativo e é o vetor de congelamento: o operador precisa de uma chave para estancá-lo sem revogar o BAAS_ADMIN, que derrubaria todo o resto junto.

Quórum de assinatura e alçada por representante — modo QUORUM (§14.9, D-PJ2)

Conta de empresa com representação conjunta ("dois de três"), com alçada ("até R$ 50 mil") ou com procuração com prazo. OPERATOR não sabe nada disso — qualquer operador da lista assina sozinho e sem teto —, e por isso a abertura PJ do banking (#547) abria essas contas com pix.send e pix.keys pausados. O modo QUORUM é o que tira a pausa.

A política. PUT /accounts/:id/authorization-policy com mode: "QUORUM" e signingRules:

json
{
  "mode": "QUORUM",
  "requireBiometricAbove": 10000,
  "signingRules": {
    "representatives": [
      { "document": "52998224725", "maxAmountPerOperation": 50000, "maxAmountPerDay": 200000 },
      { "document": "11144477735", "minSigners": 2, "validUntil": "2027-06-30T23:59:59Z" },
      { "document": "39053344705", "minSigners": 2 }
    ],
    "tiers": [
      { "upTo": 50000, "required": 1 },
      { "upTo": null, "required": 2 }
    ],
    "requestTtlMinutes": 1440
  }
}
{
  "mode": "QUORUM",
  "requireBiometricAbove": 10000,
  "signingRules": {
    "representatives": [
      { "document": "52998224725", "maxAmountPerOperation": 50000, "maxAmountPerDay": 200000 },
      { "document": "11144477735", "minSigners": 2, "validUntil": "2027-06-30T23:59:59Z" },
      { "document": "39053344705", "minSigners": 2 }
    ],
    "tiers": [
      { "upTo": 50000, "required": 1 },
      { "upTo": null, "required": 2 }
    ],
    "requestTtlMinutes": 1440
  }
}
CampoO que é
maxAmountPerOperationAlçada: acima disso a assinatura dele não conta (REPRESENTATIVE_LIMIT). Ausente = sem teto
maxAmountPerDaySoma do que ele assinou no dia útil (America/Sao_Paulo), dos pedidos vivos. Ausente = sem teto
minSigners"Conjunta, n": a assinatura dele só conta num conjunto de ≥ n assinaturas que contam. 1 = isolada
validFrom / validUntilVigência (procuração). Fora dela a assinatura não conta (REPRESENTATIVE_EXPIRED)
tiers[].requiredQuantas assinaturas que contam fecham a faixa. "ALL" = todos os representantes em vigor (conjunta = todos)
requestTtlMinutesPrazo do pedido para juntar as assinaturas (padrão 24 h, máximo 7 dias)

Regras de forma, todas 400 em vez de correção silenciosa: CPF repetido, nenhuma ou duas faixas abertas (upTo: null), faixa pedindo mais assinaturas do que há representantes, minSigners maior que a lista, teto diário abaixo do teto por operação, vigência invertida, valor com três casas. operators é derivado dos representantes (o cadastro de aparelho OPERATOR e o portão leem uma lista só); mandar uma lista diferente junto é 400. signingRules entra no policyHash (BB-5) só quando existe — o hash das políticas já ancoradas não mudou. Sair de NONE para QUORUM é livre (aperta); qualquer mudança de uma política QUORUM — inclusive "só apertar" — é um pedido de assinatura policy.update, com o quórum da faixa mais exigente. Para policy.update a alçada também é medida como valor ilimitado: só conta (na criação, na assinatura e de novo no portão) quem não tem maxAmountPerOperation. Sem isso, um representante com alçada de R$ 1.000, numa faixa de 1 assinatura, assinava sozinho a política que tirava a alçada dele (o policy.update vale 0, "dentro" de qualquer teto).

O pedido de assinatura. Numa conta QUORUM nenhuma assinatura sozinha move dinheiro: Pix direto, TED direta, chave Pix direta e mandato respondem 403 QUORUM_REQUIRED. A saída é:

Operações: pix.transfer, ted.transfer, pix.key.create, pix.key.delete, policy.update.

  • O mesmo payload para todos. operationHashOf({ type, accountId, challengeId: <id do pedido>, nonce: <nonce do pedido>, params }) — o id e o nonce do pedido fazem o papel do desafio. Valor, destino e nonce estão dentro do que cada um assina. Recusar assina type: "signing.reject" com params: { operationHash }.
  • Quem conta. Aparelho OPERATOR ativo do representante, com a evidência do cadastro reconferida (os passos 2–3 do portão), assinatura válida sobre o payload, selfie vinculada acima de requireBiometricAbove (passo 6, por assinante), representante em vigor, valor dentro da alçada e do teto diário, e ainda não assinou — outro aparelho da mesma pessoa é a mesma pessoa (índice único (request_id, signer_document)).
  • O quórum. Existe um subconjunto T das assinaturas que contam com |T| ≥ required e minSigners ≤ |T| para cada uma? Isolada fecha sozinha dentro da faixa de 1; conjunta só junto de n. É monótono: assinar a mais nunca desfaz. O required é congelado na criação, junto com a versão da política; mudar a política cancela os pedidos abertos (POLICY_CHANGED).
  • Recusado na criação o pedido que ninguém conseguiria aprovar (valor acima de toda alçada, procurações vencidas): 403 QUORUM_UNREACHABLE, em vez de esperar até expirar.
  • Idempotência. idempotencyKey obrigatória: a mesma chave devolve o mesmo pedido (meta.replayed); com outro pedido, 409 IDEMPOTENCY_KEY_REUSED. Na execução a chave da transferência é o id do pedido: a retomada encontra a reserva em vez de chamar o banco.

Uma execução só — onde mora a garantia. A execução chama o mesmo serviço da rota direta (Pix, TED, chaves, política) com o id do pedido, e o portão:

  1. confere que o pedido é desta conta e da versão da política em vigor;
  2. reconstrói o payload a partir da operação que vai executar e compara com o operationHash assinado (SIGNING_REQUEST_MISMATCH se valor ou destino mudou, ou se a linha foi editada);
  3. reconfere cada assinatura contada contra o banco agora (aparelho ativo, assinatura válida, representante em vigor e na alçada) e o quórum congelado (QUORUM_NOT_MET);
  4. reivindica: APPROVED → EXECUTING (ou EXECUTING com a vez vencida, executor morto) por updateMany condicionado. Duas assinaturas finais simultâneas, a rota de retomada e a varredura produzem uma concessão.
CorridaDefesa
Duas assinaturas "finais" chegando juntastrava consultiva do pedido + COLLECTING → APPROVED condicionado: uma aprovação; a outra recebe 409 SIGNING_REQUEST_CLOSED e não grava assinatura
O mesmo representante em dois aparelhostrava do representante + índice único (P2002 vira SIGNATURE_DUPLICATE)
Teto diário com assinaturas simultâneas em pedidos diferentestrava do representante: a soma é lida e gravada sem ninguém no meio
Execuções simultâneas do mesmo pedido aprovadoreivindicação condicionada no portão (claimExecution)
Executor morre depois de reivindicarvez de 2 min; a varredura (ou …/execute) retoma; a transferência repete com a mesma chave

As duas travas são sempre tomadas na mesma ordem (representante, depois pedido), para nunca haver impasse. Não as remova achando que o índice único basta: o sintoma é a primeira aprovação em dobro, ou um teto diário estourado pela soma de duas assinaturas, achado semanas depois no extrato.

A trilha. baas.signing.request.{created, signed, refused, approved, rejected, cancelled, expired, executed, failed}, recurso baas_signing_request (id = signingRequestId). Toda recusa — de criação, assinatura, recusa, cancelamento, execução e corpo inválido na rota — publica refused com stage e code (catraca em signing-request.refusals.test.ts); a recusa do portão publica também baas.authorization.denied com signingRequestId. failed diz retriable. Nunca CPF, assinatura, nonce ou destino no evento.

Varredura. BAAS_SIGNING_REQUEST_SWEEP_ENABLED (padrão ligado), a cada BAAS_SIGNING_REQUEST_SWEEP_INTERVAL_MINUTES (2): expira o vencido (uma linha expired, pelo close condicionado) e retoma execução aprovada parada (até 5 tentativas).

O que fica de fora, de propósito. Numa conta QUORUM não há caminho para estorno de Pix, QR dinâmico, boleto, encerramento, atualização do titular, KYC nem mandato: todos respondem QUORUM_REQUIRED. É a direção segura; cada um entra no pedido quando houver consumidor.

No banking (#547). GET …/authorization-policy traz quorumGate: true (fachada: enforcesQuorum). O passo signing_policy da abertura PJ, vendo o aperto de mão, chama baas.requireSigningQuorum(org, conta, regras) (fachada em centavos; signingQuorumOf no company-onboarding.service.ts): cada membro com poder vira representante (amountLimitCents → maxAmountPerOperationCents, validUntil, conjunta, n → minSigners: n), numa faixa de 1. A conta abre sem pausedCapabilities e quorumEnforced: true. Sem o aperto de mão (BaaS antigo por trás da fachada remota), segue o OPERATOR + pausa.

Armadilhas e troubleshooting
  • 403 QUORUM_REQUIRED num Pix que "sempre funcionou". A conta virou QUORUM: a rota direta não serve mais. Abra um pedido de assinatura.
  • 403 QUORUM_UNREACHABLE na criação. Nenhum conjunto de representantes em vigor e dentro da alçada fecha a faixa daquele valor. Confira validUntil das procurações e as alçadas — não é defeito do pedido.
  • A assinatura respondeu 409 SIGNING_REQUEST_CLOSED. Outra assinatura fechou o quórum um instante antes (é o perdedor da corrida); leia o pedido — ele está APPROVED/EXECUTED.
  • Pedido parado em APPROVED/EXECUTING. A execução falhou de forma transitória (evento failed com retriable: true) ou o executor caiu. POST …/execute retoma; a varredura também, depois de 1 minuto. Para transferência, a retomada devolve a reserva da mesma chave — nunca paga duas vezes. Chave Pix não tem chave de idempotência no provedor: a retomada depois de o banco ter criado a chave tende a FAILED por "chave já existe" — confira no banco antes de reabrir.
  • FAILED com code. Recusa definitiva na execução: capacidade desligada, saldo gastável, recusa síncrona do banco, QUORUM_NOT_MET (um aparelho foi revogado ou uma procuração venceu entre a aprovação e a execução). Abra outro pedido.
  • SIGNING_REQUEST_STALE. A política mudou depois que o pedido foi aberto; ele foi cancelado com POLICY_CHANGED. Abra de novo.
  • SIGNING_REQUEST_MISMATCH na assinatura. A linha do pedido não reconstrói o próprio hash: alguém a editou no banco. Não assine; investigue.
  • O aplicativo assina e dá SIGNATURE_INVALID. Ele tem de assinar attributes.payload byte a byte (o mesmo para todos os representantes), não um JSON remontado.
  • Teto diário "errado". Conta o que o representante assinou no dia útil de São Paulo, em pedidos vivos (COLLECTING, APPROVED, EXECUTING, EXECUTED); expirado, cancelado, recusado e falho liberam o teto.
  • 403 QUORUM_UNREACHABLE / REPRESENTATIVE_LIMIT num policy.update. A troca de política só é assinada por representante sem alçada (ceilingAmountOf). Empresa em que todos têm alçada não troca a política por pedido — a mudança passa pela abertura/mesa.
  • Ciclo de módulo. types/signing.ts não importa nada de types/authorization.ts em tempo de execução (o contrário importa o schema de lá); um import de valor ali deixa o schema undefined.
  • Migration. 20261002150000_baas_signing_quorum é aditiva (ADD VALUE IF NOT EXISTS, IF NOT EXISTS, duplicate_object), como o resto: produção aplica SQL cru.

O portão de capacidade — desligar de verdade (BB-6b)

O WhatsAppDevice do painel esconde botão; aqui esconder não é desligar. Desde o BB-6b, as operações que movem dinheiro do cliente, destroem um recebível dele ou travam o saldo dele perguntam ao Feature Flags — pela fachada FeatureFlagsFacadeToken, com assertCapability — antes de existirem. O BaaS é o primeiro consumidor desse portão.

ChaveOperaçãoRota
pix.sendTransferência Pix de saídaPOST /baas/pix/transfers
ted.sendTransferência TED de saídaPOST /baas/ted/transfers
boleto.issueEmissão de boleto registradoPOST /baas/boletos
boleto.write_offBaixa por instrução do beneficiárioPOST /baas/boletos/:id/cancel
hold.createCriação de bloqueio de saldoPOST /baas/accounts/:id/holds

As chaves são estáveis e cadastradas com este nome exato no Feature Flags (a chave de flag aceita ponto). Elas vivem em BaaSCapability, em src/baas/services/capability-gate.ts, e não em literais espalhados — trocar uma é quebrar o cadastro de quem já desligou.

O que cada estado responde:

EstadoRespostadetails.code
on (ou chave não cadastrada)Segue como sempre—
maintenance503, com a chave de texto do aviso que o cms resolve (maintenanceMessageKey)CAPABILITY_MAINTENANCE
off403CAPABILITY_OFF
Feature Flags não respondeu503CAPABILITY_UNAVAILABLE

Chave não cadastrada é on. É o padrão do bloco (reason = UNREGISTERED), e a consequência precisa estar dita em voz alta: desligar exige cadastrar a chave. Enquanto ninguém criar a flag pix.send na organização, o Pix responde — como sempre respondeu. Não existe "desligado por omissão", e o portão nunca inventa uma recusa que o operador não pediu.

Onde no fluxo, e por quê. A ordem é conta → capacidade → assinatura do titular → reserva → provedor, e cada passo dessa fila está onde está por uma razão:

  1. Depois da conta. Recusar por capacidade é decisão de produto — "esta organização não tem Pix" —, e essa resposta só deve chegar a quem já provou ser dono da conta. Antes da resolução, o portão responderia a um accountId chutado e a diferença entre CAPABILITY_OFF e 404 viraria sonda de existência de conta alheia. Conta de outra organização continua respondendo 404, como no resto do §14.
  2. Antes da assinatura. O desafio do titular é de uso único. Verificar a assinatura primeiro queimaria o desafio do cliente para depois responder 403, e a próxima tentativa legítima precisaria de outro desafio.
  3. Antes da credencial. getProviderForAccount decifra a credencial cifrada do provedor. Capacidade desligada não decifra nada, não reserva linha e não fala com o banco.

Falha do Feature Flags não é liberação. Se a fachada não estiver registrada no processo, ou se o bloco não responder, estas operações recusam com 503 CAPABILITY_UNAVAILABLE. É a mesma escolha já feita para a biometria (BIOMETRICS_UNAVAILABLE) e para a trilha (POLICY_INTEGRITY_UNAVAILABLE): portão que não responde não autoriza. Entre pagar um Pix que a organização tinha desligado e recusar um Pix que ela tinha ligado, o erro caro é o primeiro — ele é irreversível e sai do bolso de terceiro, enquanto o segundo é um 503 que o chamador repete em segundos. O preço está declarado em §15, e o código de motivo é distinto de CAPABILITY_MAINTENANCE de propósito: quem opera precisa separar "nós desligamos" de "não conseguimos perguntar".

A prova de que isto não é decoração está em tests/unit/baas/services/capability-gate.test.ts: uma conta que aderiu à política, com assinatura de titular válida e pix.send em off, é recusada — o caso que passava antes do BB-6b.

Webhooks de entrada — o modelo de confiança

É a única superfície sem JWT, porque quem chama é o banco. E o alvo é uma frase: um POST não autenticado não pode mudar status de dinheiro de ninguém.

Até 2026-09 ele podia. O organizationId vinha de um cabeçalho do próprio chamador, a verificação de assinatura da Celcoin era um TODO e o MockBank devolvia true incondicional — ou seja, com o enforcement no padrão nenhum provedor real passava, e sem ele passava qualquer corpo forjado. Somava-se uma leitura por endToEndId sem filtro de organização, de modo que um webhook legítimo de uma organização alcançava a transação homônima de outra.

O modelo hoje tem três camadas, nesta ordem de confiança:

flowchart TD
  BANCO["Provedor bancário — não tem token da sua plataforma"]
  L1["1 · Endereço de entrega secreto<br/>/webhooks/deliveries/:deliveryId — dá a ORGANIZAÇÃO"]
  L2["2 · Assinatura sobre o CORPO CRU<br/>HMAC com o segredo do webhook — dá a AUTENTICIDADE"]
  L3["3 · Lista de faixas de origem<br/>reforço — só com borda declarada confiável"]
  D1["Replay: id do evento, ou hash do corpo cru"]
  D2["Persistência do payload cru em baas_webhook_events"]
  E1["Toda leitura por identificador externo é ESCOPADA por organização"]

  BANCO --> L1 --> L2 --> L3 --> D1 --> D2 --> E1

1 · Endereço de entrega, por configuração de provedor. Cada BaaSProviderConfig tem um webhookDeliveryId — 32 bytes aleatórios em base64url — e o endereço POST /baas/api/v1/webhooks/deliveries/<deliveryId> resolve a organização pelo registro. É a camada de cima porque é ela que tira a organização das mãos de quem posta. Configuração nova nasce com o endereço; POST /provider-configs/:id/webhook-delivery gera ou rotaciona (o botão para quando o endereço vazou — não mexe em credencial nenhuma). Endereço desconhecido e endereço revogado respondem igual (404): diferenciar contaria ao atacante que ele acertou uma configuração que existiu.

A rota antiga (/webhooks/:providerType com o organizationId em cabeçalho ou query) segue atendendo apenas configuração que ainda não tem endereço próprio, com aviso no log. Configuração que já tem endereço é recusada por lá — aceitar as duas anularia esta camada para quem migrou. Ela também recusa quando a organização tem mais de uma configuração ativa do mesmo provedor: não há como desempatar por providerType, e escolher a mais recente usaria a credencial errada. Prazo de remoção em §15.

O endereço é segredo, e a resposta o trata como tal. GET /provider-configs e GET /provider-configs/:id devolvem webhookDeliveryUrl e settings.webhookUrl mascarados para quem tem só BAAS_READ; o valor inteiro sai para BAAS_ADMIN e na resposta da rotação. Quem tem o endereço entrega webhook naquela configuração — deixá-lo legível com permissão de leitura daria a qualquer leitor a capacidade que a rotação protege.

2 · Assinatura, sobre o corpo CRU. verifyWebhookSignature(headers, body, rawBody). O rawBody é lido antes de qualquer parse: reserializar o JSON muda espaçamento e ordem de chave, e a assinatura nunca bate.

ProvedorVerificaçãoComo configurar
CelcoinHMAC real sobre o corpo cru, parametrizávelwebhookSecret nas credenciais; opcionalmente webhookSignatureHeader (padrão x-celcoin-signature), webhookSignatureAlgorithm (sha256), webhookSignatureEncoding (hex|base64), webhookSecretEncoding (utf8|hex|base64) e webhookToleranceSeconds (300)
MockBankHMAC-SHA256 sobre o corpo cruwebhookSecret nas credenciais; cabeçalho x-mockbank-signature
QI Tech, FitBankAinda sem esquema próprioCaem em PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT — §15

A Celcoin aceita a assinatura no cabeçalho configurado ou no campo signature do corpo; quando vem no corpo, o HMAC é conferido sobre o corpo cru sem esse campo — e o recorte é estrutural, não textual: varre-se o JSON respeitando string, escape e profundidade, e corta-se só a chave signature do nível de topo. A primeira versão cortava a primeira ocorrência da palavra, o que acertava uma descrição de Pix contendo "signature", ou um campo homônimo aninhado; o efeito não era forja, era recusa falsa — webhook legítimo rejeitado porque o corpo conferido não era o assinado. O carimbo timestamp, que viaja dentro do corpo assinado, fecha a janela de replay: corpo capturado ontem não vale hoje.

Três travas na parametrização, porque configuração frouxa aqui vira webhook falsamente verificado:

  • com webhookSecret configurado, corpo sem assinatura é RECUSA, não "não verificável" — senão bastaria ao atacante omitir o cabeçalho para cair no caminho que a variável de enforcement governa;
  • corpo sem carimbo de horário legível também é recusa. Passar calado deixaria a proteção contra reenvio inteira na deduplicação do banco, e ela é outra camada. O próprio parseWebhookPayload da Celcoin já exige timestamp, então o corpo seria rejeitado uma linha depois, com mensagem pior;
  • algoritmo restrito a sha256 e sha512. md5/sha1 não caem no padrão em silêncio: a configuração fica inválida e o webhook é recusado, com o motivo no log;
  • janela de replay com teto de 900 s. Janela larga demais é o mesmo que não ter janela.

PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT continua decidindo o que fazer quando não há verificação possível (provedor sem esquema, ou sem webhookSecret configurado): qualquer valor exceto off rejeita; off aceita com warn. O padrão é fail-closed.

A única exceção declarada à assinatura é a simulação de webhook do MockBank, que não vem da rede: ela entra pelo trustedSource do WebhookHandlerService, dentro do mesmo processo. Nenhuma rota HTTP passa essa opção.

3 · Lista de faixas de origem — declarada por configuração, e HOJE DESLIGADA. settings.webhookAllowedCidrs aceita faixas CIDR (IPv4 e IPv6). Ela só é aplicada quando BAAS_WEBHOOK_TRUST_FORWARDED_FOR=true declara que a borda sobrescreve X-Forwarded-For. Sem essa declaração, ela passa tudo, registra warn e se diz não aplicada. O porquê está em §15, e é um achado medido, não uma precaução: sob o SNAT do Swarm o serviço nunca vê o endereço real do cliente.

Replay. O identificador do evento é registrado e a repetição recusada — e quem recusa é o índice único (config_id, external_event_id), não a consulta que vem antes dele. A consulta é otimização; ler-e-depois-gravar é check-then-act, e dois reenvios simultâneos passariam os dois por ela. O índice era declarado no schema.prisma desde 2026-01 e nunca tinha ido ao banco: nenhuma migration o criava, e o migrate diff acusava isso como drift. Criado agora (20260924150000_baas_webhook_event_unique), com as duplicatas já existentes desambiguadas, não apagadas. Quando o provedor não manda um id, o identificador é o hash do corpo cru — antes, evento sem externalEventId escapava da deduplicação inteira e reenviar o mesmo corpo criava a transação de novo. Some-se a persistência do payload cru em baas_webhook_events, que dá trilha completa do que chegou.

O hash do corpo cru NÃO é uma segunda camada equivalente. Dizer "id do evento ou hash do corpo cru" sugere duas barreiras da mesma força, e não são. A barreira real é o índice único (config_id, external_event_id), e ela só é forte quando o provedor manda um id de evento estável. Na falta dele, o identificador vira o hash do corpo cru, e a deduplicação passa a valer apenas para retransmissão byte-idêntica — que é o caso menos provável num banco real. Dois avisos do mesmo pagamento com timestamps diferentes têm corpos diferentes, hashes diferentes, e passam os dois. Vale para boleto, Pix e TED. A Celcoin é candidata a cair aí: nem a documentação de assinatura dela está neste repositório (§15), quanto menos a garantia de um id de evento estável por aviso.

O que segura nesses casos é a segunda linha: a reivindicação condicionada. Quem aplica o efeito não é quem recebeu o aviso, é quem virou o registro. claimStatus, claimRefund e claimForReconciliation são updateMany condicionados ao estado anterior: o segundo aviso afeta zero linhas, não publica evento e não move dinheiro. Até 01/10/2026 isso não valia no próprio webhook: o handler gravava o status com update incondicional e publicava a cada aviso — dois avisos sem id de evento publicavam baas.pix.transfer.completed duas vezes, um created/failed atrasado rebaixava um Pix já concluído, um kyc.approved atrasado reativava conta BLOCKED e ressuscitava conta CLOSED, e o GET /pix/transfers/:id devolvia a COMPLETED um Pix recebido já estornado. Agora o webhook, a consulta e o reenvio de KYC usam advanceStatus (transação e conta), com a tabela de transições em utils/status-transitions.ts; o teste é webhook-handler.status-only-advances.test.ts. A busca da transação pelo aviso também passou a aceitar o id do provedor além do endToEndId (a Celcoin manda transactionId primeiro, e a busca só por endToEndId nunca casava) e a se restringir à configuração que recebeu o aviso. Como a busca agora casa pelo id do provedor, o pix.refunded decide pela linha citada: a REVERSAL que nós pedimos vai a COMPLETED (sem republicar), o PIX_IN original não é tocado (quem o fecha é o claimRefund, que soma os parciais) e só o PIX_OUT devolvido vira REVERSED — também a partir de PROCESSING, quando o completed se perdeu. Ela não é redundância da deduplicação — é o que sobra quando a deduplicação não pega. Os pontos estão comentados no código, no ponto exato onde alguém faria a limpeza, porque o sintoma de remover é a primeira liquidação em dobro, meses depois, sem ninguém ligar uma coisa à outra.

Por que NÃO deduplicamos por chave semântica. A saída aparente, na falta de id de evento, seria deduplicar por (tipo do evento + id externo da transação + status). Está descartada de propósito, por duas razões:

  • chave semântica errada é pior que chave ausente. Ela silencia aviso legítimo, e o modo de falha deixa de ser "baixa em dobro" para virar "pagamento que nunca foi baixado" — que ninguém reclama no mesmo dia e é muito mais difícil de achar do que uma baixa a mais;
  • ela não é idempotente para liquidação parcial seguida de complemento. São dois pagamentos legítimos com os mesmos três campos, e no boleto isso é real: o modelo tem allowPartialPayment. Se um dia entrar, o valor precisa fazer parte da chave — ou ela vale só para os tipos de evento em que um segundo aviso nunca é legítimo.

Escopo de organização em toda leitura por identificador externo. findByEndToEndId exige organizationId. A única leitura sem escopo que sobrou é findByExternalIdAny, e ela existe justamente para descobrir a organização na simulação do MockBank — está anotada como tal no repositório.

Dados pessoais e LGPD. O BaaS guarda nome, CPF ou CNPJ, e-mail, telefone, endereço, nome da mãe e data de nascimento do titular, além de nome e documento das contrapartes de cada transação. Tudo é dado pessoal; parte é dado financeiro. Três observações operacionais:

  • Não há mascaramento de documento nas respostas de API de conta e transação. Quem tem BAAS_READ vê o CPF do titular ali. Trate BAAS_READ como permissão sensível, não como leitura genérica. As rotas de autorização do titular são a exceção: GET /authorization-policy e GET /devices devolvem o CPF mascarado (***.982.247-**).
  • Documentos de KYC não são guardados aqui. Eles vão para o provedor; o BaaS não persiste imagem nem base64. Se você usa o File Storage como origem das URLs, a retenção é lá.
  • Contas e transações não têm exclusão lógica — não há deletedAt em baas_accounts nem em baas_transactions. É coerente com retenção financeira, e significa que atender a pedido de eliminação exige processo explícito, hoje não automatizado (§15).

Permissões. Só duas, e a granularidade é grossa de propósito: BAAS_READ para tudo que lê, BAAS_ADMIN para tudo que escreve. Quem pode configurar um provedor pode também enviar Pix, porque as duas coisas exigem BAAS_ADMIN. Se a sua operação precisa separar quem configura de quem transaciona, isso hoje se faz com organizações distintas — não com papéis distintos (§15).

Superfície HTTP. Todo o app passa por applyCommonMiddleware: limite de 1 MB no corpo, CORS que bloqueia cross-origin quando não há origens configuradas, cabeçalhos de segurança e rate limit global.


15

Limitações conhecidas

Maturidade dos provedores. É a limitação mais importante e a razão do status beta.

ProvedorSituação real, verificada no códigoO que falta
MockBankImplementação completa e exercitada de ponta a ponta pelos testes de integração e end-to-end. Persiste em tabelas próprias, faz débito e crédito, gera EVP, endToEndId, QR EMV e dispara webhookNada — mas é simulador. Nunca use em produção. Banco 999 e ISPB 99999999 são fictícios
CelcoinOs 27 métodos da interface implementados contra a API REST real, com OAuth2 e cache de token — boleto pela BaaS v2 Charge. Testado com HTTP mockado. Verificação de assinatura de webhook implementada (HMAC sobre o corpo cru, parametrizável — §14)O esquema exato da Celcoin não está documentado neste repositório: cabeçalho, algoritmo e formato do segredo são configuráveis com padrões assumidos (x-celcoin-signature, sha256, hex). Confirme com o provedor antes de operar; divergência se resolve na configuração, não no código. Uma suposição não é configurável e precisa ser conferida primeiro — veja abaixo. Sem evidência de homologação contra o sandbox real neste repositório
QI TechOs 27 métodos implementados, com requisição assinada — boleto pela API bank_slip da carteira de cobrança. Testado com HTTP mockadoVerificação de assinatura de webhook não implementada. Sem evidência de homologação contra o sandbox real neste repositório
FitBank / FitsOs 27 métodos implementados sobre a API RPC — boleto por GenerateBoleto, GetBoletoInById e CancelBoleto. Testado com HTTP mockadoO provedor não publica esquema de assinatura de webhook. A proteção que sobra é o endereço de entrega secreto (§14, camada 1) — a lista de faixas de IP não está disponível neste ambiente, ver abaixo. Sem evidência de homologação contra o sandbox real

Consequência direta, atualizada em 2026-09: a Celcoin e o MockBank verificam de fato, desde que a configuração tenha webhookSecret. QI Tech e FitBank ainda não, e com o enforcement no padrão (fail-closed) os webhooks deles são rejeitados. Para esses dois, o que segura hoje é o endereço de entrega secreto (§14, camada 1): sem ele o organizationId vinha de um cabeçalho do chamador e qualquer POST marcava transação de qualquer organização.

A suposição que sobra na assinatura da Celcoin — confira ANTES de ligar

Quando a assinatura vem dentro do corpo (campo signature), o código assume que a Celcoin assinou os bytes do corpo MENOS o par signature — o que é o normal, porque um payload não pode conter a própria assinatura no momento em que ela é calculada.

Se ela assinar o corpo COM o campo (por exemplo, com o campo presente e vazio, ou preenchido com um placeholder), esse caminho nunca casa, e o sintoma é "assinatura inválida" em 100% dos webhooks — não em alguns. Isso não é corrigível sem a documentação do provedor.

O que fazer ao integrar, nesta ordem: prefira o cabeçalho (webhookSignatureHeader), que não tem essa dúvida — o corpo cru inteiro é o que foi assinado. Só use a assinatura no corpo se a Celcoin não oferecer o cabeçalho, e aí confirme com eles o que exatamente entra no HMAC antes de ligar o enforcement.

A camada 3 (lista de faixas de origem) NÃO está disponível neste ambiente

settings.webhookAllowedCidrs existe e funciona, mas nasce desligada, e o motivo é medido:

neste ambiente o Swarm faz SNAT, e o serviço nunca vê o endereço real do cliente — quem chega no socket é o ingress. Já custou caro: uma lista de permissão por endereço com 10/8 liberou todo mundo e, sem ele, bloqueou todo mundo, e foram horas lendo o status do comando errado.

Por isso o código não lê o endereço do socket. Ele lê X-Forwarded-For/X-Real-IP e só confia neles quando BAAS_WEBHOOK_TRUST_FORWARDED_FOR=true declara que a borda sobrescreve esses cabeçalhos. Borda que apenas acrescenta não serve: o chamador põe o que quiser na frente. Sem essa declaração, a lista passa tudo, registra warn e se diz não aplicada — prefere-se a camada declaradamente indisponível a uma camada que mente.

O caminho certo, proposto e não implementado neste PR (ele mexe na borda, e mexer na borda é outra frente): o Traefik injetar um cabeçalho secreto na requisição antes de repassá-la, e o BaaS exigir esse cabeçalho. Isso marca a requisição de forma confiável sem depender de endereço nenhum — e resolve o SNAT em vez de contorná-lo. Enquanto isso não existe, a ordem de confiança é endereço de entrega secreto (camada 1) + assinatura (camada 2); a camada 3 é reforço opcional para quem tiver borda que sobrescreva.

Itens que esta frente NÃO cobriu, e onde eles vão

ItemSituaçãoOnde resolve
Consulta ao provedor pela chave do chamadorA interface canônica não tem. É o que faltaria para conciliar o timeout de transferência (não o de estorno, que já resolve pela original)Frente própria: estender BaaSProvider com getTransactionByClientKey nos quatro provedores
Assinatura de webhook de QI Tech e FitBankSem esquema próprio implementado; o que os segura é o endereço de entrega secretoFrente por provedor, com a documentação de cada um na mão
Bloqueio de saldoCriar, ler, liberar, consumir, expirar e conferir existem (§9): a capacidade declarada do provedor escolhe entre delegar (custody = PROVIDER, hoje só MockBank) e escriturar (LEDGER); a varredura de vencimento roda sozinha; a conferência contra o banco relata divergência; e pessoa só libera e consome em duas etapas (quatro olhos). A divergência é guardada, listada e explicada (GET /hold-divergences), sem nada ser corrigidoEspecificação própria (openspec/changes/baas-escrow-holds-e-tarifas)

Tarifas — o que o bloco NÃO faz

LimitaçãoO que significaPor quê, e o que fazer
O BaaS não cobra a tarifa da casaRegistrar uma tarifa HOUSE não debita a conta, não altera saldo e não fala com o provedor. A linha é um registro do que é devidoO bloco não tem primitiva de débito: o único jeito de mover dinheiro aqui é uma transferência para alguém. Cobrar é uma transferência do cliente para o tenant pelas rotas de Pix/TED, com o portão de qualquer transferência — e depois POST …/fees/:feeId/charge cita qual foi. Antes de automatizar isso, leia o art. 8º da Res. Conjunta 16/2025 (§14): ele veda à tomadora cobrar tarifa em nome próprio
Não há extrato unificado nem comprovanteNão existe rota que devolva transações e tarifas numa linha do tempo só, nem documento de comprovante de tarifaA tarifa aparece em dois lugares: fees[] no recurso da transação e GET /accounts/:id/fees. Quem precisa de extrato monta com as duas
chargeTransactionId é citação, não conferênciaO bloco confere que a transferência citada existe na organização. Não confere valor, destinatário, status nem que ela saiu da mesma contaQuem cita é quem cobrou, e responde pela citação. Conferir o valor exigiria decidir o que fazer com cobrança parcial ou agrupada — não decidido
A franquia pode esticar sob concorrênciaDuas transferências simultâneas da mesma conta leem a mesma contagem e as duas podem sair dentro da franquia. O desvio é limitado ao número de chamadas concorrentes e não se acumula: as duas linhas são gravadas e a operação seguinte as contaEscolha, não pendência. Fechar exigiria serializar por conta e operação (uma linha de contador sob trava) no caminho de toda transferência. O erro aceito custa uma cobrança a menos; a trava custaria contenção onde o dinheiro passa. Nenhum dinheiro é movido errado nem perdido
Tarifa UNPRICED não é reprecificada sozinhaQuando o Pricing Engine volta, as linhas UNPRICED continuam UNPRICED. Não há varredura que reapureConciliação é de quem opera: liste filter[source]=UNPRICED, e o retrato traz operation, operationAmount e occurrencesThisMonth para reapurar. Reapurar automaticamente exigiria decidir qual versão da regra vale — a do dia da operação ou a de hoje
Só transferência de saída é tarifada pela casaPix enviado, TED enviada e consumo de bloqueio perguntam o preço. Boleto, Pix recebido, TED recebida, mensalidade e manutenção nãoA tabela aceita linha sem transação (transactionId nulo) e o Pricing Engine sabe recurrence = MONTHLY, mas não há quem dispare uma cobrança recorrente. Frente própria
Transferência fechada pela conciliação ou por webhook não ganha tarifa da casaA tarifa da casa é registrada no caminho da requisição que iniciou a transferência. Se o provedor não respondeu a tempo e a transação foi concluída depois, pela varredura de conciliação ou por webhook, não há linha HOUSE nem UNPRICED para elaOs caminhos assíncronos não perguntam o preço nesta entrega. Para achar essas operações, compare as transações COMPLETED de saída com as linhas de tarifa da conta
Falha ao gravar a linha perde o registroSe o banco de dados recusar a escrita da tarifa depois de a transferência sair, a transferência vale e a tarifa não fica registrada — nem como UNPRICEDO único rastro é o error "Falha ao registrar a tarifa da casa" no log. É o mesmo desfecho da tarifa do provedor: derrubar a resposta de uma transferência consumada seria pior
waivedBy exige usuárioA isenção recusa token cujo sub não seja UUID. Automação com identidade que não seja de usuário não isentaDeliberado: "isentado pelo sistema" é o registro que não se audita

O que o bloqueio de saldo NÃO vai garantir — leia antes de desenhar produto em cima dele

Criar, ler, liberar, consumir, expirar e conferir existem (§9); liberar e consumir, para pessoa, só em duas etapas. Isto continua escrito de frente porque a promessa errada é mais cara que a ausência.

  • A trava é do PORTÃO, não do banco. Quando o provedor declara balanceHold: 'NONE' — hoje, Celcoin, QI Tech e FitBank —, o bloqueio existe só na nossa base. O banco enxerga o saldo cheio e paga qualquer saída que não passe por aqui: console do provedor, outra integração, tarifa debitada pelo próprio banco, estorno. Bloqueio escriturado é uma promessa que o BaaS cumpre, não um cadeado que o banco fecha.
  • Nenhum provedor real bloqueia saldo — só o MockBank. capabilities.balanceHold é NATIVE apenas no simulador; Celcoin, QI Tech e FitBank declaram NONE, porque nada no que está fiado das APIs deles bloqueia saldo parcial (o block/unblock que existe congela a conta inteira, e é outro ato). Em produção, portanto, todo bloqueio é escriturado e vale só no nosso portão. Ligar um provedor de verdade no dia em que houver API é trocar um literal e escrever três métodos — o encaixe está pronto, o produto do banco é que não existe.
  • Ele não vale retroativamente sobre o que já saiu, e NADA é corrigido automaticamente. A divergência aparece como saldo gastável negativo, na leitura seguinte ou na conferência (POST …/holds/reconcile), e vira o evento baas.hold.divergence.detected. Aí ela para. A conferência descobre que o nosso registro e o do banco discordam e não sabe qual dos dois está errado: se o errado for o nosso, encolher o bloqueio grava o errado e some com a pergunta; se for o do banco, encolher apaga a única prova da intenção. Nos dois casos a divergência viraria perda. O gap é a pergunta "onde foi parar este dinheiro?", e quem a responde é o extrato do banco, com um humano na frente. A pergunta fica guardada (GET /hold-divergences) até alguém responder com causa e texto; explicar registra a resposta e também não corrige nada.
  • Divergência guardada: o que ela é e o que não é. Uma linha aberta por conta, atualizada a cada detecção (last*, detections) — os números da primeira ficam como foram vistos. Explicada e vista de novo com o mesmo gap dentro de duas janelas do alarme (2 × BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES), ela continua explicada — é a mesma divergência contínua, já respondida. Com outro gap, ou se ela sumiu e voltou depois disso (meses depois, com o mesmo valor por coincidência), abre-se outra: reaproveitar a explicação velha a esconderia. Ela não fecha sozinha: a divergência que sumiu (leitura atrasada do banco) fica OPEN até alguém explicar — PROVIDER_DELAY existe para isso. No caminho de leitura só se grava quando o alarme sai, então detections conta janelas, não leituras. E como o alarme, ela só existe para conta com bloqueio escriturado.
  • O alarme de divergência do caminho de leitura é represado por conta. GET …/balance publica no máximo um baas.hold.divergence.detected por conta por BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES (§13), porque é um GET que painel chama em laço e mil cópias do mesmo fato enterrariam o primeiro aviso. Consequência a assumir: uma divergência que apareceu e sumiu dentro da janela pode não ter deixado evento. Quem quer o fato agora chama a conferência, que ignora a janela.
  • Ele não é garantia real nem segregação patrimonial. Não cria conta escrow, não é oponível a terceiros, não sobrevive a uma ordem judicial sobre a conta e não muda a titularidade de nada.
  • A conferência de saldo existe, e só vale para conta COM bloqueio. Pix e TED conferem spendableBalance antes de falar com o provedor e recusam com 403 e details.code = INSUFFICIENT_SPENDABLE_BALANCE. Uma conta sem bloqueio escriturado não é tocada por isso: o bloco não lê saldo, não gasta uma chamada a mais, e quem recusa por saldo continua sendo o provedor, com a mensagem do provedor. Com custody = PROVIDER a trava também vale no banco, porque quem a cumpre é ele.
  • Se o saldo não puder ser lido, a saída da conta com bloqueio é recusada. Falha fechada, pela mesma razão do portão de capacidade: deixar passar tornaria o bloqueio decorativo exatamente no minuto em que o provedor está instável. Conta sem bloqueio nunca chega a ler o saldo, e portanto nunca paga esse preço.
  • Hoje o quatro olhos é trilha, não controle. Hoje BAAS_ADMIN só existe em papéis que também têm API_KEYS_CREATE e IAM_ORGANIZATIONS_UPDATE, então quem pede ou aprova também consegue emitir chave ou segredo M2M e contornar o quatro olhos sozinho. Até existir um papel de operador de BaaS sem essas permissões, o quatro olhos é trilha, não controle. O que sobra de controle é o que fica registrado: a linha do razão guarda por qual credencial o ato entrou (metadata.credential), e o pedido guarda quem pediu e quem decidiu.
  • Como a credencial é classificada. Máquina é chave de API ou token client_credentials, reconhecido por sub = organizationId (é como o iam o emite; se isso mudar, ele passa a contar como pessoa, o lado seguro). Todo o resto é PERSON — inclusive o token interno de fachada com que outro bloco chama o baas: ele não tem porta direta de liberar nem de consumir.
  • Duas pessoas, não dois logins. O bloco confere que o sub de quem decide é diferente do de quem pediu. Uma pessoa com dois usuários no iam passa. E enquanto o iam não tiver segundo fator, cada login é só e-mail e senha — console de operador que libera dinheiro não deve ir para produção antes disso (decisão DB5 do plano do backoffice).
  • Pedido preso em EXECUTING. Se o processo cair (ou o fechamento lançar) entre a decisão e o fechamento, a aprovação responde 500 HOLD_REQUEST_OUTCOME_UNKNOWN com requestStatus: EXECUTING e outcome: UNKNOWN — nunca um 4xx de "falhou", porque o dinheiro pode ter saído. A varredura de pedido preso (BAAS_HOLD_REQUEST_SWEEP_*, §13) fecha, depois de BAAS_HOLD_REQUEST_STUCK_MINUTES (15), lendo o razão: sem linha → FAILED (EXECUTION_INTERRUPTED); linha com motivo → FAILED; linha sem motivo e transação COMPLETED, ou liberação escriturada → EXECUTED; senão → UNRESOLVED. Até ela passar, o pedido prende o bloqueio.
  • FAILED e UNRESOLVED soltam o bloqueio para um pedido novo, do mesmo jeito. O estado do pedido não protege o dinheiro; quem protege é a reivindicação do bloqueio: o valor que saiu sem resposta do banco continua fora do activeAmount, e o pedido novo só alcança o que resta.
  • Pedido não vence. Um PENDING espera para sempre. O bloqueio pode vencer antes — e aí a aprovação vira FAILED com HOLD_NOT_ACTIVE, sem mover nada.
  • Aprovação sem presença nem mandato, em conta que aderiu, queima o pedido. O portão do titular recusa (MANDATE_REQUIRED) e o pedido vira FAILED; é preciso pedir de novo, trazendo o instrumento na aprovação. Decidido assim porque desfazer a decisão devolveria a mesma pergunta a quem já a respondeu.
  • Bloqueio sem expiresAt não vence nunca, e essa é a forma padrão de criá-lo. A varredura só olha ACTIVE com prazo no passado; expires_at nulo não casa com a condição e é ignorado de propósito. Garantia criada sem prazo e esquecida trava o saldo indefinidamente, até alguém a liberar — máquina pela porta direta, ou pessoa por pedido decidido por outra.
  • Expirar aqui NÃO solta o bloqueio no banco. Com custody = PROVIDER, a varredura leva a nossa linha a EXPIRED e o banco continua com o valor fora do disponível dele: ela não chama o provedor, de propósito — soltar dinheiro no banco é um ato com portão e ator (hold.release), não uma decisão de agendador. O resultado, hoje, é o gastável voltar aqui e não voltar lá; em produção isso não ocorre, porque nenhum provedor real é NATIVE.
  • A varredura trabalha em lotes de 200 por passada. Uma montanha de bloqueios vencidos ao mesmo tempo leva várias passadas para escoar; a ordem é pelo prazo mais antigo, então nenhum fica para trás — mas o saldo demora a voltar.
  • settings.forceLedgerHolds: true é chave de prova, não de produção. Ela força o caminho escriturado num provedor que sabe bloquear, para que o caminho sem capacidade seja exercitável de ponta a ponta com MockBank. Ligá-la num provedor NATIVE de verdade seria abrir mão da única trava que o banco cumpre.

O ponto de extensão foi usado: a conferência entrou entre a autorização do titular e a reserva de idempotência, em pix.service.ts e ted.service.ts — depois do desafio de uso único e antes de gravar reserva ou falar com o banco. A cadeia é conta → capacidade → assinatura → saldo gastável → reserva → provedor. | Cabeçalho secreto injetado pela borda | É o caminho certo para a camada 3, e mexe no Traefik | Frente de topologia |

O purpose da conta é RÓTULO, e não produz efeito jurídico

BaaSAccountPurpose (OWN, ESCROW, COLLATERAL, SETTLEMENT) responde uma pergunta de operação — qual é a conta do fundo? — que antes só o painel respondia. Ele é o que está escrito na etiqueta, e nada além disso:

  • Não segrega patrimônio. O dinheiro continua sendo do titular, numa conta do titular, na instituição licenciada. Rotular ESCROW não separa recurso de terceiro de recurso próprio.
  • Não cria conta vinculada no sentido regulatório e não substitui contrato de escrow. Conta de terceiro com regra de liberação é outro contrato (Res. Conjunta 16/2025, art. 4º §2º), não um campo nosso.
  • Não é oponível a terceiro e não muda nada diante de uma ordem judicial sobre a conta.
  • Não é portão. Uma saída de uma conta ESCROW é autorizada exatamente pelas mesmas regras de qualquer outra: política do titular, mandato, permissão. Não existe, em lugar nenhum do código, um if (purpose === ...) que recuse operação — e, se um dia existir, o campo deixa de ser rótulo e isso é outra decisão, com outra discussão.
  • O provedor não sabe que ele existe. O rótulo não é enviado na abertura da conta nem volta dela; o tipo canônico não tem esse conceito. Reetiquetar é escrita na nossa base.

O que ele faz: aparece no recurso da conta, filtra a listagem (filter[purpose]) e dá à esteira um lugar declarado para dizer para que a conta foi aberta. §16 tem o desenho completo — e por que ele não é uma conta escrow.

A rota antiga de webhook tem prazo

POST /baas/api/v1/webhooks/:providerType, com o organizationId em cabeçalho ou query, continua aceitando enquanto houver configuração de provedor sem webhookDeliveryId, e registra warn a cada requisição. Configuração que já tem endereço é recusada por lá.

Remoção prevista para 2026-12-31. Até lá, o roteiro é: rodar POST /provider-configs/:id/webhook-delivery em cada configuração, colar a URL devolvida no painel do provedor, conferir nos logs que o warn da rota legada parou, e só então a rota some. Configuração criada a partir deste PR já nasce com endereço.

Funcionalidades ausentes ou parciais

LimitaçãoImpactoSituação
idempotencyKey ainda é OPCIONAL — e vai deixar de serSem a chave, POST /pix/transfers, POST /ted e POST /pix/transfers/:id/refund funcionam, sem nenhuma proteção contra duplicidade: um retry de rede paga duas vezes. O mesmo vale para POST /accounts/:id/holds (a chave é aceita desde 29/09): sem ela, o reenvio prende o saldo duas vezes. É o estado que sempre existiu, e cada chamada sem chave registra warn com o alvo baas: chamada que move dinheiro SEM idempotencyKeyEla seria obrigatória neste PR e não é, por um motivo concreto: o consumidor vivo é o handler INITIATE_PIX_TRANSFER do painel, que só envia a chave quando o autor do workflow a preencheu — exigi-la daria 400 em todo workflow já gravado, no dia do deploy. Obrigatória a partir de 2026-12-31, depois que o painel passar a gerar a chave por execução. Até lá: gere um uuid por operação sua. Não geramos uma chave a partir do corpo, de propósito: duas transferências legítimas e idênticas (a mesma mensalidade no mesmo dia, o mesmo repasse ao mesmo fornecedor) colidiriam, e a segunda seria engolida como repetição — recusar dinheiro que o cliente quis mandar é pior que não protegê-lo de um retry que ele controla
MUDANÇA DE COMPORTAMENTO · repetição de chave agora COMPARA o pedido (2026-09)Mesma chave com valor, destinatário ou agendamento diferentes responde 409 com details.code = IDEMPOTENCY_KEY_REUSED. Antes devolvia 200 com a transferência anterior, e o chamador acreditava ter pago a segundaUse chave nova para pedido novo. Linha anterior a este PR não tem hash gravado e não é recusada retroativamente — não há o que comparar, e recusar derrubaria retry legítimo de transferência já feita
Repetição com a chamada gêmea em voo responde 202, não 200Quem perde a corrida do índice único recebe a reserva, que ainda não tem desfecho. A resposta é 202 Accepted com meta.inFlight: true, a orientação de não reenviar e o link para consultar. 200 fica só para a repetição de uma transferência com desfecho conhecido, e 201 para a transferência novaEscolhi dizer em vez de esperar: segurar a requisição até a gêmea voltar prende o chamador pela latência do banco, e um timeout no meio disso devolve o mesmo problema pior. Trate 202 como "consulte de novo em alguns segundos", nunca como falha — reenviar é o que faz o dinheiro sair duas vezes
Estorno parcial PENDING órfão consome o teto para sempre (pré-existente)Um REVERSAL parcial que nunca receba desfecho conta como vivo na soma do claimRefund indefinidamente, e reconcileReversalByOriginal devolve UNRESOLVED para parcial sem id do provedor — o banco não marca a original, então a pergunta não separa "saiu" de "não saiu". Sintoma: POST /transfers/:id/refund respondendo 409 REFUND_AMOUNT_EXCEEDED com um alreadyRefunded que não bate com o extratoNão foi introduzido por este trabalho: é a forma parcial da mesma lacuna da consulta pela chave do chamador (linha acima). Enquanto ela não existe, a saída é o backoffice: confirmar no extrato e encerrar a linha órfã à mão. O estorno total nessa situação já se resolve sozinho
Provedor que aceita SEM devolver id deixa a linha em reserva: — o estado "aceita sem id"settle só grava externalId quando o provedor manda um. Um provedor que respondesse 200 sem id deixaria a linha com externalId = reserva:<chave>: a repetição da chave responde 202 inFlight para sempre e a conciliação a reporta UNRESOLVED a cada janelaNenhum dos quatro provedores faz isso hoje — os quatro devolvem id na resposta de criação, e é por isso que não há tratamento automático. Se aparecer um que não devolva, o sintoma é reconhecível (202 eterno + UNRESOLVED eterno na mesma linha) e a saída é a mesma do timeout: extrato do banco + POST /transactions/:id/reconcile. Fechar de vez depende da consulta pela chave do chamador, na mesma frente da linha acima
A reserva de idempotência NÃO é apagada quando o provedor falhaUma transferência cujo banco recusou (ou não respondeu) deixa a linha PENDING com o motivo, e a chave fica gastaÉ a prova de que a chamada existiu: um timeout não diz que nada saiu, diz que não sabemos. A conciliação resolve. Repetir o pedido exige chave nova
A deduplicação de webhook só é forte com id de evento do provedorO índice único (config_id, external_event_id) é a barreira real. Provedor que não manda id de evento cai no hash do corpo cru, e aí a deduplicação pega só retransmissão byte-idêntica — o caso menos provável num banco real. Dois avisos do mesmo pagamento com timestamps diferentes têm corpos diferentes, hashes diferentes, e passam os dois. Vale para boleto, Pix e TED; a Celcoin é candidata, já que nem a documentação de assinatura dela está no repositórioO que segura é a segunda linha: a reivindicação condicionada (claimStatus, claimRefund, claimForReconciliation) — só quem vira o registro publica e atua (§14). Chave semântica (tipo + id externo da transação + status) foi avaliada e recusada, por duas razões: chave semântica errada silencia aviso legítimo e troca "baixa em dobro" por "pagamento que nunca foi baixado", que é mais difícil de achar; e ela não é idempotente para liquidação parcial seguida de complemento — dois pagamentos legítimos com os mesmos três campos, e allowPartialPayment existe no modelo de boleto. Se um dia entrar, o valor precisa fazer parte da chave, ou ela vale só para os tipos em que um segundo aviso nunca é legítimo
findUnprocessed não tem chamador: não existe varredura de reprocessamento de webhookwebhook-event.repository.ts expõe findUnprocessed, e ninguém a chama. Evento marcado com error fica lá, e nada o retentaRegistrado porque muda de inerte para relevante no dia em que alguém escrever a varredura: a migration do índice único preserva a linha mais antiga de cada par duplicado, e a mais antiga pode ser justamente a que falhou ao processar. Quem escrever a varredura precisa olhar as linhas :dup: também
A conciliação NÃO resolve o timeout de TRANSFERÊNCIA — que é o caso que a motivaTimeout é justamente quando o provedor não devolveu id. A linha fica reserva:<chave>, e a varredura a reporta UNRESOLVED a cada janela, indefinidamente. Ela resolve o resto: webhook perdido, resposta lida e não gravada, e qualquer linha que já tenha id do bancoO que resolveria é consulta pela chave do chamador — a Celcoin a recebe como clientCode, o TED como externalId, e nenhum método da interface canônica lê por ela. Estender a interface (getTransactionByClientKey) é frente própria, não cabia aqui. Até lá o caminho é o extrato do banco + POST /transactions/:id/reconcile. O ESTORNO é a exceção: ele tem a transação original, que tem id do banco, então a varredura pergunta por ela — se a original voltou lá, o estorno saiu; se não, o estorno é marcado falho e a original volta a COMPLETED
Estorno com TIMEOUT deixa a original em REVERSED até a varredura passarA marcação da original é reivindicada antes da resposta do banco — é o que impede duas devoluções. Recusa síncrona (o caso comum, 400 refund not allowed) já desfaz na hora: o estorno vira FAILED e a original volta a COMPLETED. Só o timeout espera, porque aí a devolução pode ter saídoA varredura resolve perguntando ao banco pela transação original (ver a linha acima). Quem não quer esperar: POST /transactions/:id/reconcile na linha do estorno. Para estorno parcial a pergunta não decide — o banco não marca a original —, e a linha fica UNRESOLVED para o backoffice
O BaaS só confere saldo onde há bloqueio escrituradoConta com bloqueio: Pix e TED conferem spendableBalance entre a assinatura e a reserva e recusam com 403 INSUFFICIENT_SPENDABLE_BALANCE, sem falar com o banco. Conta sem bloqueio — todas, até alguém criar o primeiro: nada muda, o bloco não lê saldo e quem recusa por saldo insuficiente continua sendo o provedorDeliberado. Conferir saldo em toda transferência custaria uma ida ao banco por Pix e mudaria o que o bloco recusa para todo cliente que hoje funciona; o ganho seria zero, porque sem bloqueio o número do provedor é o mesmo que o nosso. E a trava é do portão, não do banco: dinheiro que sai por fora do baas gasta o bloqueado assim mesmo
Conciliação automática: existe, com janelaA varredura (BAAS_RECONCILIATION_ENABLED, a cada 5 min por padrão) resolve transação sem desfecho parada há mais de BAAS_RECONCILIATION_STALE_MINUTES (15). Não é instantânea, e não substitui o webhookPara fechar na hora: POST /transactions/:id/reconcile. Para uma passada sob demanda na organização: POST /transactions/reconcile. Ambas idempotentes e seguras com duas réplicas
Vencimento de bloqueio: existe, com janela e com loteA varredura (BAAS_HOLD_EXPIRY_ENABLED, a cada 5 min por padrão) leva a EXPIRED os bloqueios ACTIVE com prazo no passado, 200 por passada, e publica baas.hold.expired uma vez por bloqueio mesmo com duas réplicas. Bloqueio sem prazo nunca entra. Com custody = PROVIDER, ela não chama o banco: a nossa linha expira e a do banco não; a criação PROVIDER ainda sem id do banco é pulada (espera a retomada)A garantia contra evento em dobro é a atualização condicionada ao estado anterior (HoldRepository.claimExpiry), não a trava no Redis do agendador — sem Redis as duas réplicas varrem e uma recebe RACE em toda linha
Divergência de bloqueio: relatada, nunca corrigidaGastável negativo vira baas.hold.divergence.detected e nada mais. Não há conserto automático, e não haverá: a conferência não sabe qual dos dois registros está erradoPOST /accounts/:id/holds/reconcile para perguntar agora. No caminho de leitura o aviso é represado por conta (BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES)
Boleto acompanha por consultaRegistro, liquidação e baixa chegam pelo POST /boletos/:id/sync. Os webhooks de boleto dos bancos ainda não atualizam o título sozinhosPróxima fase: consumir os eventos de cobrança de cada banco no recebedor de webhooks
Bloquear e desbloquear conta não tem rota HTTPblockAccount e unblockAccount existem na interface e nos quatro provedores, mas nenhum router os expõe. O bloqueio só chega por webhook do provedorImplementado na camada de provedor, não exposto
personId não é chave estrangeiraO vínculo com Person do Customers é um UUID solto: sem validação na criação, sem integridade referencial, sem cascataPor design de desacoplamento entre building blocks — mas o personId inválido só aparece quando alguém tenta usar
Agendamento sem garantia uniformescheduledFor é aceito e repassado, mas o comportamento é do provedor. O MockBank ignora e executa na horaConfirme com o seu provedor antes de prometer agendamento ao cliente
Permissões grossasSó BAAS_READ e BAAS_ADMIN. Quem configura provedor também transfere dinheiroSeparar exige permissões novas no vocabulário do IAM
BAAS_READ vê CPF sem máscara nas contasConta e transação devolvem o documento inteiro. As rotas de autorização do titular (GET /authorization-policy, GET /devices) já mascaramTrate BAAS_READ como permissão sensível. Consequência do mascaramento: ler a política e gravá-la de volta sem tocar no CPF não funciona — o PUT recusa o valor mascarado com 400 (não são 11 dígitos), o que é ruidoso de propósito, e não grava lixo
KYC limitado a 1 MB por requisiçãobodyLimit global. Documento em base64 estoura facilmenteUse URL do File Storage em vez de base64
Sem expurgo para LGPDContas e transações não têm exclusão lógica nem rotina de eliminaçãoEliminação é processo manual
Config com credencial rotacionada não tem período de graçaPATCH com credentials substitui na hora. Requisição em voo com a credencial antiga falhaCoordene a janela
Sem cache de saldoToda consulta bate no provedor. Volume alto de consulta consome quota da API do bancoPor design (§7) — mas planeje a quota
Estorno só de Pix recebido e completoPOST /transfers/:id/refund exige PIX_IN e COMPLETED. Não há devolução de Pix enviado nem estorno de TEDRestrição do fluxo Pix, verificada antes de chamar o provedor
CANCELLED não é alcançávelO status existe no enum, mas nenhum caminho do código leva a eleReservado para status vindo do provedor
A catraca do ResultAsync descartado é heurística de texto — e estas classes ela NÃO pegaEla pega: construtor solto (ResultAsync.fromPromise, okAsync, errAsync, combine), método solto com cadeia (this.x.y(…).map(…)), método solto SEM cadeia quando o próprio arquivo declara que ele devolve ResultAsync (this.cacheBalance(id, saldo) sozinho — a terceira cegueira, medida ao conferir o getBalance), atribuição órfã e void sem catch — em qualquer posição do bloco, inclusive a primeira e a última. Não pega: chamada solta de método declarado em OUTRO arquivo (a leitura da assinatura é por arquivo), descarte dentro de um switch/case sem chaves, valor devolvido por função que nunca é chamada, cadeia montada em duas variáveis (const a = …; const b = a.map(…) com b órfão), descarte passado por Promise.all([...]) sem await, e qualquer coisa fora de src/baasEla foi medida três vezes por revisão e nas três pegava menos do que parecia: a primeira era cega no PRIMEIRO statement de bloco, a segunda no ÚLTIMO e a terceira na chamada solta sem cadeia. Está escrito aqui para não parecer cobertura completa — é rede, não prova. A sonda versionada (discarded-resultasync.test.ts) exercita as formas conhecidas, inclusive as que falharam nas medições anteriores, e falha se a heurística regredir. Medição de 25/09/2026, ao fechar o item 5.2: (a) a catraca PEGA o defeito real — rodada contra o account.service.ts inteiro de 373d41ff^, ela acusa as duas ocorrências que existiam ali (linhas 215 e 360, getBalance e deposit), e a forma multilinha delas entrou na sonda versionada; (b) as classes cegas acima foram varridas por um script fora da árvore que ignora de propósito a fronteira do arquivo — ele indexa TODO nome declarado em src/ com ): ResultAsync< e acusa qualquer chamada solta a esse nome em src/baas — zero irmãos: as 94 linhas que ele apontou são colisão de nome (router.get/post/delete do Hono, Map.set/Map.delete, sign.update do crypto, super(...), e publish/validateToken/invalidate, que aqui devolvem void). O zero foi acreditado só depois de controle positivo — injetadas this.accountService.getBalance(…) (assinatura em outro arquivo) e registerProviderFee(…) (função importada) soltas, a PRIMEIRA passou batida por ter a mesma cegueira de "primeiro statement do bloco" descrita acima, e as duas só foram acusadas depois de corrigi-la. Reencontrar a mesma cegueira num script novo é o melhor argumento de que ela é a armadilha padrão desta heurística, não um descuido isolado
MockBank numera contas por instânciaO contador do número da conta é por processo: dois ambientes simulados geram 0000001 e seguintes, então duas organizações podem exibir agência/conta iguais. É cosmético — o que identifica a conta no roteamento é o externalId, que é uuidv4E a busca global por externalId (a que a simulação de webhook do MockBank usa para descobrir a organização) passou a recusar ambiguidade em vez de escolher a primeira linha: se duas organizações tivessem o mesmo id, o webhook ia para a errada. Hoje isso é teórico; recusar fecha a classe
MockBank compartilha estado no processoO simulador guarda estado em estruturas estáticas por processo, não segregadas por organização. Duas organizações usando MockBank no mesmo processo enxergam o mesmo DICTAceitável para desenvolvimento; é mais um motivo para nunca usá-lo em produção
Automação do tenant numa conta que aderiu precisa de chave — ou de mandatoNuma conta em HOLDER_SIGNATURE/OPERATOR, POST /accounts/:id/kyc, PATCH /accounts/:id com holder, POST /pix/transfers/:id/refund e POST /pix/qr-codes/generate com amount exigem assinatura, e agora POST /boletos e POST /boletos/:id/write-off também. Integração que enviava KYC, emitia cobrança por QR ou emitia e baixava boleto por régua, sem aparelho do titular, para de funcionar nessas contasDeliberado: todas movem dinheiro, cobram ou destroem recebível em nome do titular, ou mudam identidade. Conta em NONE — todas as de produção hoje — segue como antes, sem nenhum campo novo obrigatório. Quem precisa automatizar numa conta que aderiu tem dois caminhos: modo OPERATOR com o aparelho de quem opera, ou, para boleto, um mandato boleto.issue + boleto.write_off concedido pelo titular à régua (§14, receita em §11)
Dependência do instalador: a régua precisa de mandato no onboarding do tenantNa conta que aderiu, POST /boletos e POST /boletos/:id/write-off respondem 403 MANDATE_REQUIRED até o titular conceder um mandato com boleto.issue e boleto.write_off e a régua citar o mandateId. Não há período de graçaNão é limitação do bloco: é o passo que o instalador da vertical dá no onboarding do tenant — ativar a política depois de conceder o mandato à régua (receita em §11), com teto e limites diários dimensionados para a carteira e folga para retry. Tenant onboardado sem esse passo tem a régua parada até alguém conceder
Mandato só para boletoscope aceita apenas boleto.issue e boleto.write_off. Pix, TED e o resto continuam exigindo presença na conta que aderiuO mecanismo é genérico; a fiação é só onde a automação roda hoje. Estender é adicionar mandateId na rota e o tipo ao conjunto elegível
Limite de mandato conta a tentativa, não o sucessoBaixa que o banco recusa gastou uma unidade do dia e da contagem. Uma régua com retry agressivo esgota maxOperationsPerDay mais cedo do que o número de baixas efetivasDireção segura de propósito: o limite acota o que a máquina tenta fazer sozinha. Dimensione o limite com folga para o retry
Mandato vive no máximo 12 meses e sempre com teto ou contagemRégua com carteira grande precisa reconceder todo ano, e não dá para conceder "sem limite" nem "só por dia" — 400 MANDATE_UNBOUNDED. O tenant só encurta (settings.mandateMaxMonths), nunca alongaDecisão consciente: capacidade ao portador sem teto nem prazo é exatamente o que o mandato existe para evitar. Dimensione maxOperations com folga para a carteira e o retry, e ponha a reconcessão anual no calendário do instalador
Mandato sem grantAttestationA concessão é a assinatura do aparelho, não um atestado com nível de garantia como o contrato do bloco attestation (§9) descreve. Não há assurance na trilhaO bloco não tem dono e o contrato proíbe construir o verificador dentro do consumidor. Quando existir, substitui a assinatura guardada sem mudar a rota
QR estático não passa pela travaPOST /pix/qr-codes/generate sem amount segue livre mesmo na conta que aderiuUm QR sem valor não declara quanto alguém deve; quem paga escolhe o valor e o dinheiro entra. Gatear custaria uma assinatura por cobrança aberta sem fechar nada
Assinatura aceita DER e r||s, sem exigir low-sA mesma assinatura pode ser reapresentada na outra codificação, ou com s complementado, e continua válida para o mesmo payloadDecisão consciente: recusar uma das codificações recusaria uma plataforma (Android emite DER, iOS emite r||s). Não é explorável porque o desafio é de uso único e queimado com update condicional — a segunda forma da mesma assinatura encontra CHALLENGE_USED
BAAS_ADMIN revoga qualquer chave sem assinaturaQuem tem o token pode revogar todos os aparelhos da conta e travá-la: nenhuma escrita gated passa maisNão é bypass — sem chave ativa nada é autorizado, e recadastrar exige prova de vida do titular. Mas é o primeiro passo de uma pressão para voltar a NONE, e é por isso que a trava do §14 conta também os dispositivos revogados. Revogar continua livre de propósito: celular perdido não espera
Toda escrita gated depende do Audit Trail responderDesde o BB-5, o BaaS lê a trilha antes de liberar qualquer escrita — inclusive em conta que nunca aderiu, porque "nunca aderiu" só a trilha confirma. Trilha fora do ar: 503 POLICY_INTEGRITY_UNAVAILABLE em Pix, TED, boleto, KYC, fechamento, política. Em standalone, MODULE_AUDIT_TRAIL_URL precisa estar no ar no serviço baas; em monólito, o repositório do audit-trail precisa estar no processoFalha fechada, de propósito. O cache por conta (BAAS_POLICY_INTEGRITY_CACHE_MS, padrão 5 s) absorve um soluço, não uma queda: é uma leitura por conta, por réplica, por janela. A alternativa — "aceita mesmo assim" — devolveria o buraco que o BB-5 fecha
Política anterior ao BB-5 para de autorizar até ser ancoradaLinha sem policy.changed na trilha é unanchored → 403 POLICY_INTEGRITY, e o PUT também é recusado. Vale para produção no dia do deployRode POST /accounts/:id/authorization-policy/anchor em cada conta com política antes de subir o portão (é idempotente). Não é automático no boot de propósito
Fresta entre o commit e o consumidorUma escrita que chegue nos milissegundos entre o PUT gravar e o consumidor do Audit Trail encadear a linha recebe 403 POLICY_INTEGRITY (diverged) — e o PUT só responde depois de esperar a trilha até BAAS_POLICY_ANCHOR_WAIT_MS (padrão 3 s); estourou, a política vale e a posição é preenchida na próxima conferênciaNão há janela de graça lida do banco (seria o buraco). Consumidor saudável encadeia em milissegundos; retry do cliente resolve
Em monólito, a trilha não é populadaO consumidor do Audit Trail só sobe em standalone (README do Audit Trail, §7). Num monólito sem ele, toda política fica unanchored para sempre e toda conta que aderiu responde 403 POLICY_INTEGRITYCorreto e ruidoso. Para desenvolver com política ligada, suba o audit-trail standalone com AUDIT_CONSUMER_ENABLED=true e aponte MODULE_AUDIT_TRAIL_URL, ou fique em NONE
Trilha podada antes deste PR não tem como ser re-ancorada pela APIA poda agora preserva a última policy.changed de cada conta (lista fechada em src/audit-trail/utils/pinned-events.ts). Para uma organização já podada antes disso, a linha pode ter sumido — e o anchor recusa com 409 POLICY_TRAIL_PRUNED em vez de abençoar a linha como ela estáDe propósito: unanchored era o veredito que o anchor aceitava, então quem editasse a política e esperasse a poda (ou encurtasse a retenção com AUDIT_CONFIG_MANAGE) ganhava o carimbo. A saída é operacional: o titular grava a política de novo pelo PUT, assinando o afrouxamento se houver
BB-5b — a trilha divide banco e credencial com quem ela auditadeploy/docker-stack.prod.yml:56 dá um único DATABASE_URL (building_blocks, usuário postgres) a todos os blocos: quem escreve na política apaga a última linha de audit.audit_logs e rebobina audit.audit_chain_heads. O BaaS só lê latestEvent, nunca /verify — cabeça rebobinada passa por legítima. O ataque funciona hoje (teste skip em holder-authorization.service.test.ts)Follow-up nomeado: trilha em banco/credencial próprios, ou no mínimo usuário Postgres por schema (o baas sem DELETE/UPDATE em audit.*). É decisão de topologia, fora do escopo do BB-5
BB-5c — o barramento aceita qualquer publicadoraudit-consumer.ts ingere qualquer entrada de iam-events e shared/lib/events.ts faz XADD cru sem assinatura. Um policy.changed forjado é encadeado e ancorado como legítimo. O Redis já exigia senha no ambiente real — os blocos rodam no Launch, e o Spark escreve requirepass no valkey.conf por construção; o --requirepass do PR #448 (24/09/2026) vale para os dois docker-stack, que são o caminho legado (§13). Senha tira o anônimo da rede — mas o ataque continua funcionando para qualquer bloco que tenha a senha, e todos têm (teste skip)Falta o publicador assinado, com verificação no consumidor: chaves por bloco, rotação e janela de tolerância. Frente própria. Caminho alternativo reaberto: ACL por usuário no Spark separa publicador de consumidor sem exigir stream próprio (docs/plans/2026-09-25-onde-os-blocos-rodam-de-verdade.md §5). Aberto também: TLS desligado nos cinco clusters Spark
Apagar política E dispositivos já não desliga a travaResolvido no BB-5: linha apagada com histórico na trilha é POLICY_INTEGRITY com ou sem dispositivos; linha editada idem. A trava do #428 (dispositivo, mesmo revogado, nunca lê como NONE) fica por baixo, para o caso de a trilha ter perdido a linhaDefesa em profundidade, não a defesa principal. O estado "sem política e com dispositivo" continua não nascendo de caminho legítimo, e o serviço continua registrando warn
Conta em MockBank aceita biometria de sandboxConfig MOCKBANK (ou settings.sandbox: true) autoriza com evidência environment: test, cujo desfecho é decidido pelo CPFÉ o que torna a esteira testável; nunca vale para provedor real, e MockBank já não pode ir a produção
A trava depende do bloco BiometricsSem fachada registrada, conta com política responde 503 e não operaFalha fechada, de propósito. Em standalone, MODULE_BIOMETRICS_URL precisa estar no ar — e, desde o BB-5, MODULE_AUDIT_TRAIL_URL também (linha acima)
Cadastrar aparelho exige cadastro facial prévioPOST /accounts/:id/devices só aceita sessão AUTHENTICATION com identityProven, isto é, comparação 1:1 contra cadastro facial do próprio titular. Titular sem cadastro facial no bloco não consegue cadastrar aparelho nenhumDecisão consciente: a chave é a raiz de confiança de toda assinatura posterior, e ONBOARDING ancora no documento que o integrador enviou — documento forjado com o CPF da vítima passaria. O cadastro facial nasce antes, na abertura da conta, em sessão ONBOARDING com enrollOnApprove: true. Quem opera contas antigas, abertas sem esse passo, precisa rodar uma sessão de cadastro facial antes de aderir
Recuperação é sempre pela biometriaSem dispositivo ativo, não há como afrouxar a política: só enrolando um dispositivo novo com prova de vidaÉ o desenho — a chave privada nunca sai do celular, então o titular é a única rota de volta
Escrita local depois da confirmação do provedorResolvido em 2026-09. A linha PENDING é gravada ANTES da chamada ao provedor, então uma resposta perdida deixa rastro em vez de nada. O que sobra é a janela entre a resposta do banco e o fechamento local, coberta pela conciliaçãoA lição do caso Synapse (§4) continua valendo: confira o extrato do provedor contra baas_transactions periodicamente

Lacunas em relação à Resolução Conjunta nº 16/2025. A norma é de novembro de 2025 e o prazo de adequação vai até 31/12/2026. O código ainda não a reflete em três pontos:

ExigênciaSituação no código
Art. 6º — exclusividade por tipo de contaNada impede tecnicamente criar duas configurações ativas de provedores diferentes. O controle é contratual e humano; não há trava no software
Art. 8º — aviso ao cliente de que a tomadora não é instituição autorizadaNão há campo, endpoint nem conteúdo para isso. É obrigação a cumprir na sua interface
IN BCB 754/2026 — registro da tomadora no Unicad (efeitos em 1º/09/2026)Não há campo para o identificador de registro nem exposição dele em API

Nenhuma dessas é falha de implementação — são obrigações que recaem sobre a tomadora e a prestadora, não sobre a camada de software. Estão aqui porque um comprador precisa saber que o building block não as cumpre por ele.

O portão de capacidade tem duas arestas declaradas (BB-6b).

LimitaçãoImpactoSituação
Desligar exige cadastrar a chaveChave não cadastrada é on (reason = UNREGISTERED) — o padrão do Feature Flags. Quem espera que "não criei a flag" signifique "está desligado" tem a expectativa invertida: sem a flag pix.send criada na organização, o Pix pagaPor design — a alternativa (bloquear por omissão) desligaria o BaaS de todo tenant no dia do deploy
Feature Flags fora do ar derruba as operações guardadasPix, TED, emissão, baixa e criação de bloqueio respondem 503 CAPABILITY_UNAVAILABLE enquanto o bloco não responder. É a escolha deliberada de falhar fechado para operação que move dinheiro (§14), e o custo é um acoplamento de disponibilidade que antes não existiaPor design — o código de motivo é distinto de CAPABILITY_MAINTENANCE justamente para a operação separar os dois
Uma consulta ao portão por operaçãoSem cache no lado do BaaS: cada Pix soma uma avaliação de flag ao caminho crítico. O cache que existe é o do próprio Feature Flags (Redis, TTL de 300s), do lado deleAceito — a avaliação é barata perto da ida ao banco; se virar gargalo, o lugar do cache é a fachada, não este bloco
Só cinco operações são guardadasChave Pix, QR Code, estorno, abertura e encerramento de conta não têm chave de capacidade. Desligar pix.send não impede criar uma chave PixEscopo do BB-6b, mais hold.create — o critério é "move dinheiro, destrói recebível ou trava saldo"

Não deployado como dependência de outro building block. Nenhum outro módulo consome o BaaS por ModuleClient. A integração com o resto do catálogo é por evento e pelo personId. Isso é coerente com o desenho, mas significa que o BaaS ainda não tem tráfego vindo de dentro da plataforma.


Trava de recebíveis: o que ela não segura

  • Custódia LEDGER: dinheiro tirado pelo console do provedor (ou por outra integração) antes da captura escapa da trava — o mesmo risco residual do bloqueio escriturado. Com PROVIDER, quem segura o bloqueio da captura é o banco; mas entre o crédito entrar e a captura bloquear (segundos) o titular pode gastar pelo próprio app. O bloqueio que "não cabe" fica pendente e é repetido até o teto (LIEN_CAPTURE_MAX_ATTEMPTS), depois falha com evento.
  • O bloqueio que não cabe logo depois de outra captura é, quase sempre, a folga de leitura do bloqueio (READ_SKEW_MS, 5 s): a transferência que acabou de sair conta como em voo. Por isso HOLD_EXCEEDS_BALANCE não fecha a captura; a varredura conclui depois da folga.
  • Consumo recusado depois do bloqueio (mandato revogado pelo titular, prazo vencido no meio): o bloqueio ADVANCE fica ativo; o mandato da trava só cobre hold.settle e não pode liberar. Quem resolve é um operador.
  • O pagador muda a chave de destino (no caso do CBP, o médico troca a chave cadastrada na fonte pagadora): a trava não vê — a detecção é do consumidor.
  • Cancelar com captura em curso: a captura que já tinha reservado termina e conta (o dinheiro estava a caminho); só não nasce captura nova.
16

Perguntas frequentes

A Catalisa é um banco? Vocês têm licença do Banco Central?

Não, e a resposta é curta de propósito. A Catalisa é a camada de software. Quem tem licença, custodia o dinheiro e responde ao Banco Central é o provedor que você contrata — Celcoin, QI Tech ou FitBank. Nós não somos instituição autorizada, não custodiamos recurso de terceiro e não somos participantes do Pix. Se alguém apresentar isto de outra forma numa proposta, a proposta está errada. §14 detalha o que isso implica em contrato.

Temos conta escrow?

Não. Não existe conta escrow neste bloco. Nenhuma rota abre uma, nenhum dos quatro provedores vende uma — capabilities.escrowAccount é tipada como a literal false nos quatro (§7) — e o tipo canônico de conta não tem esse conceito. Se um material de venda disser o contrário, o material está errado, e este parágrafo existe porque o disse por um tempo.

O que existe, e que resolve boa parte dos casos em que alguém pede "escrow", é outro desenho: uma conta por operação, com propósito declarado, mais bloqueio de saldo amarrado a uma razão. Em três peças, todas em §9:

  1. Uma conta por operação. POST /accounts abre uma conta de verdade no provedor licenciado. Você manda o businessId da sua operação e o purpose (ESCROW, COLLATERAL, SETTLEMENT); depois acha a conta por filter[purpose]. Nada impede abrir uma conta por contrato, por lastro ou por cedente — é o que a esteira de crédito faz.
  2. Bloqueio de saldo amarrado a uma razão. POST /accounts/:id/holds trava um valor com reasonType (LOAN, ADVANCE, COLLATERAL, GENERIC), texto livre, externalReference — o id da operação, por onde a esteira reencontra os bloqueios dela — e expiresAt. Cada ato vira uma linha de razão que nunca é reescrita, com quem fez e por qual porta (titular presente, mandato ou admin).
  3. Quem guarda o bloqueio depende do provedor. Quem declara balanceHold: NATIVE (hoje só o MockBank) recebe o bloqueio de verdade; os outros ficam escriturados na nossa base.

O que esse arranjo entrega: rastreabilidade e prova de intenção. Você consegue responder, com registro datado e sem depender de planilha, qual conta pertence a qual operação, quanto do saldo está comprometido, por quê, desde quando, até quando e quem comprometeu. A conciliação do que entra continua sendo pelo endToEndId.

O que ele NÃO entrega — e é aqui que a conversa com o jurídico começa:

  • Não há segregação patrimonial nem oponibilidade a terceiros. O dinheiro é do titular, numa conta do titular. Uma ordem judicial sobre a conta alcança o saldo bloqueado igual.
  • Não há condição de liberação executável por um terceiro. Escrow de verdade é um terceiro que só libera quando a condição se cumpre. Aqui quem libera é quem opera a plataforma; não existe agente fiduciário, e o rótulo não impõe nada.
  • Com os três provedores reais, a trava é do portão e não do banco. Eles declaram balanceHold: NONE: o bloqueio existe só na nossa base, o banco enxerga o saldo cheio e paga qualquer saída que não passe por aqui — console do provedor, outra integração, tarifa, estorno.
  • O ciclo do bloqueio ainda não está completo. Criar e ler existem; liberar, consumir, expirar e a conferência de saldo gastável são os PRs 4, 5 e 6 da frente (§15). Até a conferência existir, o próprio baas gasta o que escriturou como bloqueado.

Quando você realmente precisa de escrow, o caminho não é um campo nosso: é contratar o produto com quem carrega a licença, porque conta de titularidade de terceiro com regra de liberação é contrato de instituição autorizada (Res. Conjunta 16/2025, art. 4º §2º), não configuração de software. O dia em que um provedor vender isso, a literal false de escrowAccount relaxa junto com o provedor que a venda — e não antes.

Preciso ter contrato com um banco antes de começar a integrar?

Não. Use o MockBank: ele simula conta, saldo, DICT, transferência, QR Code e webhook, e a esteira que você constrói contra ele é a mesma que roda em produção. Na prática, o time de engenharia costuma terminar a integração antes de o jurídico terminar o contrato. Só não coloque MockBank em produção — o banco 999 não existe.

Dá para trocar de provedor depois? Quanto custa?

Dá, e é o motivo pelo qual este building block existe. Você cria a configuração nova, valida com /test, marca como padrão, e as contas novas nascem no provedor novo. As antigas continuam no antigo, funcionando, porque cada conta guarda o configId a que pertence. O que não dá é mover uma conta existente de um banco para outro — a conta é do banco. Migrar de verdade significa encerrar lá e abrir cá, com o titular no meio.

Posso usar dois provedores ao mesmo tempo?

Tecnicamente, sim — inclusive duas configurações do mesmo provedor com credenciais diferentes. Mas leia a ressalva antes de planejar em cima disso: o art. 6º da Resolução Conjunta nº 16/2025 veda contratar BaaS com uma prestadora quando já existe contrato vigente com outra para o mesmo tipo de conta. O que o software permite e o que o contrato permite são coisas diferentes, e aqui elas divergem. O uso seguro e claramente dentro da norma é a migração entre provedores; manter dois contratos simultâneos do mesmo tipo é conversa para o seu jurídico. §14 tem o quadro completo.

O saldo que a API retorna é confiável?

É o saldo do provedor, consultado na hora. GET /accounts/:id/balance sempre bate no banco antes de responder. As colunas availableBalance e blockedBalance que aparecem na listagem de contas são cache atualizado de forma assíncrona — servem para tela de listagem, não para decidir se uma transferência pode sair.

A mesma resposta traz dois campos que não são do provedor: ledgerHoldAmount (a soma dos bloqueios que nós escrituramos, com custody = LEDGER) e spendableBalance (availableBalance − ledgerHoldAmount). Quem decide gasto lê spendableBalance; os três campos antigos continuam sendo exatamente o que o provedor informa. Bloqueio com custody = PROVIDER não entra em ledgerHoldAmount: o banco já o descontou do disponível dele, e contá-lo de novo travaria o dobro. E spendableBalance negativo não é erro de cálculo — é o alarme de que alguém gastou o bloqueado por fora do bloco.

Uma transferência ficou presa em PROCESSING. O que faço?

Chame GET /baas/api/v1/pix/transfers/:id. Esse endpoint não é passivo: ele consulta o provedor e grava o status novo se mudou. É o caminho de reconciliação para webhook perdido. Não há varredura automática hoje (§15), então vale agendar a sua — a receita está em §11.

Como faço para o mesmo Pix não sair duas vezes se minha chamada der timeout?

Mande uma idempotencyKey (uuid) por operação sua em POST /pix/transfers e POST /ted. A chave é única por organização: se a primeira chamada criou a transação e a segunda chegou por retry, a segunda devolve a mesma transação com 200 e meta.idempotentReplay: true, sem tocar o provedor de novo — mesmo se as duas correrem ao mesmo tempo (a que perde o índice único devolve a que ganhou). A chave também vai ao provedor (Celcoin externalId, QiTech idempotency_key, FitBank Identifier), que dedupa do lado dele. Sem chave, controle a duplicidade do seu lado (§15).

Como impeço que um invasor do meu backend esvazie a conta?

Ative a política de autorização da conta (PUT /accounts/:id/authorization-policy com mode: HOLDER_SIGNATURE) e cadastre a chave do celular do titular. A partir daí, toda saída de dinheiro exige uma assinatura feita no enclave do aparelho — e o BaaS verifica essa assinatura antes de decifrar a credencial do banco. Quem tiver BAAS_ADMIN continua conseguindo ler, listar e tentar; não consegue mover. O quadro completo de quem consegue o quê está em §14.

E se o atacante simplesmente desligar a política?

Não dá pela API: afrouxar a política — voltar para NONE, trocar o titular, mexer na lista de operadores, subir ou remover o limiar biométrico — é ela própria uma operação assinada, do tipo policy.update. Apertar continua livre. O que sobra, e está registrado em §15, é quem tem escrita direta no banco de dados: esse consegue apagar a linha da política. É por isso que o nível 3 do plano é o provedor verificar a assinatura do titular.

Ativei a política e a minha régua parou de baixar boleto. E agora?

Era esperado — e era o buraco: a baixa destruía um recebível só com BAAS_ADMIN, sem passar por nada. Na conta que aderiu, a baixa exige o titular presente ou um mandato: o titular assina uma vez, no celular, um mandate.grant com escopo boleto.write_off, teto por operação, limites por dia e validade; a régua passa a mandar só o mandateId. Cada baixa é conferida contra o mandato antes de o banco ser chamado, consome o limite sob lock (duas réplicas, um vencedor por unidade) e sai na trilha citando o mandato. Emitir boleto entrou na mesma regra: na conta que aderiu, a régua sem mandato é o contorno que o mandato fecha — por isso o instalador da vertical concede à régua um mandato boleto.issue + boleto.write_off no onboarding do tenant, antes de ligar a política (§15). Receita em §11, regras em §14.

O aplicativo precisa reproduzir exatamente o quê?

O payload canônico de §14, byte a byte, e assinar com ECDSA P-256 + SHA-256. Aceitamos as duas codificações de assinatura (DER, do Android/JCA, e o r||s cru, do WebCrypto e do iOS CryptoKit), e há vetor de teste publicado para você conferir a sua implementação antes de integrar. Valor monetário vai como texto com duas casas: "150.75", nunca 150.75.

Dá para reservar um repasse que ainda não caiu?

Não com bloqueio — bloqueio não passa do saldo (o banco recusa). Com trava de recebíveis, sim: ela não reserva nada hoje; ela diz "o que entrar destes pagadores, até R$ X, vai para aquela conta", e captura quando o crédito chega. Consentimento do titular com selfie, mandato que só serve àquela trava, uma captura por crédito. §8 e a receita "Travar recebíveis futuros".

Quais eventos eu recebo, e como?

São 25 eventos baas.*, listados em §8. Configure clientWebhookUrl e clientWebhookEvents na configuração do provedor; o BaaS cria a assinatura no Webhooks Engine, que faz a entrega com retry e assinatura. Confira o campo webhookSubscriptionId na resposta — se vier vazio, a assinatura não foi criada.

Qual a diferença entre o BaaS e o Open Finance?

Direção oposta. O Open Finance lê dados de contas que o seu cliente tem em outras instituições, com consentimento. O BaaS opera uma conta que existe por causa da sua aplicação. Um enxerga; o outro movimenta.

Por que uma conta de outra organização devolve 404 e não 403?

Porque 403 responderia uma pergunta que ninguém deveria poder fazer: "este ID existe em algum lugar?". Em building block financeiro, confirmar a existência de uma conta alheia já é vazamento. O 404 é a resposta correta para "não existe para você".

Posso rodar isso em produção hoje?

O módulo está deployado nas stacks de staging e produção, e a esteira funciona. Mas antes de mover dinheiro real: resolva a verificação de assinatura de webhook do seu provedor e ligue PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT=on; trate a idempotência do lado da sua aplicação; e homologue contra o sandbox real do provedor, o que este repositório ainda não registra ter sido feito. §15 é a lista completa, e ela existe para ser lida antes da decisão, não depois.


Padrão: PADRAO-DOCUMENTACAO.md · Decisão de arquitetura: ADR-0003 · Detalhes de mapeamento por provedor: providers/README.md · Índice: INDEX.md