BaaS
BetaContas, Pix, TED e boleto por API; troque o banco parceiro sem reescrever a integração
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.
- 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ó
- 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
- 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
87 endpoints em 13 recursos.
/baas/api/v1/provider-configs/baas/api/v1/admin/platform/organizations/baas/api/v1/accounts/baas/api/v1/baas/api/v1/accounts/baas/api/v1/accounts/baas/api/v1/pix/baas/api/v1/ted/baas/api/v1/baas/api/v1/webhooks/baas/api/v1/transactions/baas/healthResumo 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.
| Atributo | Valor |
|---|---|
| Identificador | baas |
| Categoria | Financeiro |
| Escopo | Tenant (exige organizationId no token) |
| Porta (standalone) | 3015 |
| Path alias | @baas |
| Prefixo HTTP | /baas |
| Schema no banco | baas |
| Status | Beta — deployado desde 2026-01 |
| Depende de | PostgreSQL, Redis, IAM, Webhooks Engine |
O problema
negócioO 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 campoMethodno 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.
Proposta de valor
negócio| Antes | Depois |
|---|---|
| Uma integração artesanal por provedor bancário | Uma API canônica; o provedor é configuração da organização |
| Trocar de banco parceiro é projeto de meses | Criar uma configuração nova e apontar as contas seguintes para ela |
| Só dá para começar depois do contrato com o banco | MockBank simula conta, saldo, DICT, Pix e QR Code desde o primeiro dia |
| Cada provedor exige um formato de webhook diferente | Todos os webhooks viram o mesmo conjunto de 18 eventos internos |
| Credenciais de banco em variável de ambiente | Credenciais 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.
Casos de uso reais
negócioCaso 1 — Uma financeira separa o dinheiro de cada operação de crédito Cenário ilustrativo
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.
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.
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
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
Marketplace B2B que fatura pedidos de lojistas e quer receber por Pix sem obrigar o comprador a copiar dados bancários.
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".
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 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
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ó.
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.
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"]
endA 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
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.
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.
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
endA 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.
Mercado e diferenciais
negócioPanorama. 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ério | Catalisa BaaS | Celcoin | QI Tech | Dock | Unit (EUA) |
|---|---|---|---|---|---|
| Carrega licença do BACEN | Não — camada técnica | Sim (IP + SCD) | Sim (SCD) | Sim (IP, part. direto Pix) | Não (bancos parceiros, EUA) |
| Custodia recurso de cliente | Não | Sim | Sim | Sim | Não |
| Provedor trocável sem reescrever | Sim, por configuração | Não se aplica | Não se aplica | Não se aplica | Não |
| Mais de um provedor simultâneo | Sim, por organização | Não | Não | Não | Não |
| Ambiente de teste sem contrato | Sim (MockBank completo) | Sandbox após contrato | Sandbox após contrato | Sandbox após contrato | Sandbox |
| Pix, TED e DICT | Sim, via provedor | Sim | Sim | Sim | Não (mercado EUA) |
| Emissão de cartão | Não | Sim | Sim | Sim | Sim |
| Crédito / originação | Não (é o Decision Platform) | Parcial | Sim | Parcial | Sim |
| Boleto registrado | Sim — emissão, consulta e baixa, via provedor | Sim | Sim | Sim | Não |
| Preço público | Precificação em definição | Não divulgado | Não divulgado | Não divulgado | Nã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
- O provedor é uma linha no banco de dados.
BaaSProviderConfig.providerTypemais 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. - Coexistência de provedores, não apenas suporte a vários. A distinção importa: suportar N provedores é escolher um por cliente. Aqui
BaaSAccount.configIdamarra 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). - 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,
endToEndIdno 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. - Isolamento por organização em toda consulta de escrita. Cada serviço compara
organizationIddo token com o do registro antes de agir, e devolve404— não403— 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 mais | Integrar direto na Celcoin ou na QI Tech |
| Emissão de cartão como produto central | Dock |
| Crédito com originação, custódia e fundo no mesmo contrato | QI Tech |
| Não deixar o banco parceiro virar dependência estrutural | Este 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.
Modelo de cobrança e ROI
negócioUnidade 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:
| Driver | Por quê |
|---|---|
| Contas ativas | O provedor cobra por conta aberta e mantida; é o custo que cresce com a base |
| Transações Pix e TED processadas | Custo por transação do provedor, repassado |
| Chamadas de API ao provedor | Consulta 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 provedor | Catalisa BaaS | |
|---|---|---|
| Custo transacional | Do provedor, negociado | Do provedor, negociado — o mesmo |
| Custo de integração inicial | Uma integração completa por provedor | Uma integração; o provedor entra por configuração |
| Custo de trocar de provedor | Nova integração completa | Nova configuração; contas antigas continuam no provedor antigo |
| Custo de ter dois provedores | Duas integrações completas e mantidas | Duas configurações |
| Custo de testar antes do contrato | Bloqueado até liberação de sandbox | Zero — 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 ROI | Onde ela aparece | Quanto vale |
|---|---|---|
| Custo de integração que não se repete | Linha de engenharia | Manter 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ção | Taxa por transação, todo mês | Nã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.
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<T, AppError>"| 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:
| Caminho | Router | Rotas |
|---|---|---|
/api/v1/provider-configs | providerConfigRouter | 7 |
/api/v1/accounts | accountRouter + authorizationRouter | 9 + 10 |
/api/v1/pix | pixRouter | 10 |
/api/v1/ted | tedRouter | 3 |
/api/v1/webhooks | webhookRouter | 2 |
/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.
getProviderForAccountbusca a config, decifra as credenciais e chamacreateBaaSProvidera 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/balancesempre bate no provedor. O campoavailableBalanceno 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
PENDINGno 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 porendToEndIdprecisa cobrir (§15). - Tipos canônicos, e não o formato do provedor, atravessam o serviço.
CanonicalAccount,CanonicalPixTransaction,CanonicalBalancee companhia são o contrato interno. Nenhum serviço sabe que o FitBank usaTaxNumbercomo 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ãoexternalIdsozinho — 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-Idou do query paramorganizationIdque 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_transactionsemockbank_qr_codessão o "banco de dados do banco simulado", separadas das tabelasbaas_*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:
| Provedor | balanceHold | transactionFee | escrowAccount | Métodos de bloqueio |
|---|---|---|---|---|
| MockBank | NATIVE | true | false | createProviderHold, releaseProviderHold e settleProviderHold implementados |
| Celcoin | NONE | true | false | ausentes |
| QI Tech | NONE | true | false | ausentes |
| FitBank | NONE | true | false | ausentes |
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'. ProvedorNONEsimplesmente não os tem: o compilador não deixa chamá-los sem a guarda. NONEnos três provedores reais não é preguiça, é ausência de contrato.block/unblockexistem 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.escrowAccountnasce tipado como a literalfalse, não comoboolean. 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.initiatePixTransferDecisõ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
NONEpara um modo com assinatura) também — naquele momentoBAAS_ADMINsozinho já movia o dinheiro. - O desafio é queimado por
updateManycondicional. 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.
Conceitos e modelo de dados
Glossário
| Termo | Significa |
|---|---|
| Provider config | Configuraçã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. |
| Provider | Implementação da interface BaaSProvider para um banco específico. Instanciada por requisição a partir da config. |
| Tipo canônico | Formato interno neutro (CanonicalAccount, CanonicalPixTransaction, ...) para o qual todo provedor traduz. É o contrato que isola o serviço do banco. |
externalId | Identificador do recurso no provedor. Único por (configId, externalId). É a chave de correlação com o mundo externo. |
endToEndId | Identificador ú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. |
| DICT | Diretó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 EVP | Chave Pix aleatória, em formato UUID. É a única que o BaaS gera sem você informar valor. |
| EMV / BR Code | Formato do payload de QR Code Pix. O campo emvCode é o "copia e cola". |
| KYC | Verificação de identidade do titular. O BaaS encaminha documentos ao provedor e reflete o status; a análise é do provedor. |
| MockBank | Provedor 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ção | Regra 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 dispositivo | Chave 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. |
| Desafio | Nonce de 32 bytes, uso único, validade de 120 s, que entra no payload assinado. É o que impede repetir uma assinatura. |
| Payload canônico | Forma 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). |
operationHash | sha256 em hexadecimal do payload canônico. É o que amarra a sessão biométrica à operação. |
| Mandato | A 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 Prisma | Tabela | Propósito | Campos-chave |
|---|---|---|---|
BaaSProviderConfig | baas.baas_provider_configs | Provedor configurado para a organização | providerType, credentials (cifrado), isDefault, isActive, settings, webhookDeliveryId (endereço secreto de entrega, único global — §14), único (organizationId, name) |
BaaSAccount | baas.baas_accounts | Conta bancária mantida no provedor | externalId, configId, status, purpose (rótulo de organização, default OWN — §15), bankCode, branchNumber, accountNumber, availableBalance, personId, businessId, único (configId, externalId) |
BaaSPixKey | baas.baas_pix_keys | Chave Pix registrada para uma conta | keyType, keyValue, status, deletedAt, único (accountId, keyType, keyValue) |
BaaSTransaction | baas.baas_transactions | Transação Pix ou TED, entrada ou saída | transactionType, 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) |
BaaSWebhookEvent | baas.baas_webhook_events | Evento cru recebido do provedor | eventType, externalEventId, payload, processed, error, único (configId, externalEventId) |
BaaSAuthorizationPolicy | baas.baas_authorization_policies | Quem precisa assinar as escritas da conta | mode, holderDocument, requireBiometricAbove Decimal(15,2), operators, version, único (accountId) |
BaaSDeviceKey | baas.baas_device_keys | Chave pública do celular do titular ou de um operador | publicKey (SPKI DER base64), keyId, subjectKind, subjectDocument, status, enrollmentSessionId, único (accountId, keyId) |
BaaSAuthorizationChallenge | baas.baas_authorization_challenges | Nonce de uso único que entra no payload assinado | nonce, expiresAt, consumedAt |
BaaSMandate | baas.baas_mandates | Presença do titular concedida a uma máquina | scope[], maxAmountPerOperation, maxAmountPerDay, maxOperationsPerDay, maxOperations, notBefore, notAfter, status, a concessão guardada (grantDeviceId, grantChallengeId, grantNonce, grantSignature, grantOperationHash), usedCount, revokedByKind |
BaaSMandateUsage | baas.baas_mandate_usages | Contadores de um mandato por dia útil | day (YYYY-MM-DD em America/Sao_Paulo), count, amount, único (mandateId, day) |
BaaSBalanceHold | baas.baas_balance_holds | Saldo travado com motivo, referência ao que o originou e vencimento | amount, reasonType, reasonText, externalReference, status, releasedAmount, settledAmount, settlementSeq, expiresAt, custody, providerHoldId, createdVia, idempotencyKey (único por organização — a trava da criação), requestHash |
BaaSSimulatedProviderGrant | baas.baas_simulated_provider_grants | A 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 nova | organizationId, reason, grantedBy/grantedAt, revokedBy/revokedAt. Índice único parcial: uma concessão ativa (revoked_at IS NULL) por organização — só no SQL da migration |
BaaSBalanceHoldEntry | baas.baas_balance_hold_entries | O razão do bloqueio: uma linha por ato, nunca reescrita | kind (CREATE/RELEASE/SETTLE/EXPIRE), amount, actorId, actorVia, mandateId, transactionId, failureReason, requestId (o pedido de quatro olhos que originou o ato; nulo na porta direta) |
BaaSBalanceHoldRequest | baas.baas_balance_hold_requests | Pedido de liberação ou consumo em duas etapas ("quatro olhos"): uma pessoa pede, outra decide | kind, 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 |
MockBankAccount | baas.mockbank_accounts | Estado interno do banco simulado | externalId, saldo, dados do titular, kycStatus |
MockBankPixKey | baas.mockbank_pix_keys | DICT do banco simulado | keyValue único globalmente |
MockBankTransaction | baas.mockbank_transactions | Extrato do banco simulado | endToEndId, type, status |
MockBankQrCode | baas.mockbank_qr_codes | QR Codes emitidos pelo banco simulado | emvCode, expiresAt |
MockBankHold | baas.mockbank_holds | Bloqueio como o banco simulado o guarda — não confundir com baas_balance_holds, que é o registro da plataforma | externalId, amount, status, reference |
BaaSBalanceHoldDivergence | baas.baas_balance_hold_divergences | A divergência de bloqueio guardada: o gastável da conta saiu negativo, e a pergunta "onde foi parar este dinheiro?" espera explicação. Nada é corrigido | status (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)embaas_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
| Enum | Valores |
|---|---|
BaaSProviderType | CELCOIN · FITBANK · QITECH · MOCKBANK |
BaaSAccountStatus | PENDING_KYC · KYC_IN_PROGRESS · KYC_REJECTED · ACTIVE · BLOCKED · CLOSED |
BaaSAccountPurpose | OWN (padrão) · ESCROW · COLLATERAL · SETTLEMENT — rótulo de organização, sem efeito bancário, jurídico ou de autorização (§15) |
BaaSTransactionType | PIX_IN · PIX_OUT · TED_IN · TED_OUT · REVERSAL |
BaaSTransactionStatus | PENDING · PROCESSING · COMPLETED · FAILED · CANCELLED · REVERSED |
BaaSPixKeyType | CPF · CNPJ · EMAIL · PHONE · EVP |
BaaSPixKeyStatus | PENDING · ACTIVE · INACTIVE |
KycStatus | NOT_STARTED · PENDING · IN_PROGRESS · APPROVED · REJECTED · REQUIRES_UPDATE |
BaaSAuthorizationMode | NONE · HOLDER_SIGNATURE · OPERATOR · QUORUM |
BaaSSigningRequestStatus | COLLECTING · APPROVED · EXECUTING · EXECUTED · FAILED · REJECTED · CANCELLED · EXPIRED |
BaaSDeviceSubjectKind | HOLDER · OPERATOR |
BaaSDeviceKeyStatus | ACTIVE · REVOKED |
BaaSMandateStatus | ACTIVE · REVOKED |
BaaSMandateRevokerKind | HOLDER · ADMIN — quem revogou o mandato |
BaaSHoldReasonType | LOAN · ADVANCE · COLLATERAL · GENERIC |
BaaSHoldStatus | ACTIVE · RELEASED · SETTLED · EXPIRED — os dois últimos encerram, e só um moveu dinheiro |
BaaSHoldCustody | LEDGER · PROVIDER — quem guarda o bloqueio |
BaaSHoldDivergenceStatus | OPEN · EXPLAINED — não há "corrigida": o bloco relata, não conserta |
cause da divergência | PROVIDER_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) |
BaaSHoldEntryKind | CREATE · RELEASE · SETTLE · EXPIRE |
BaaSHoldRequestKind | RELEASE · SETTLE — criar bloqueio não passa por pedido |
BaaSHoldRequestStatus | PENDING · EXECUTING · EXECUTED · FAILED · UNRESOLVED · REJECTED — ver §9, "Pedido em duas etapas" |
created_via do bloqueio | HOLDER · 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 provedor | Status gravado na conta |
|---|---|
APPROVED | ACTIVE |
REJECTED | KYC_REJECTED |
Qualquer outro — NOT_STARTED, PENDING, IN_PROGRESS, REQUIRES_UPDATE | KYC_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
| Detalhe | O que acontece |
|---|---|
| Status inicial | É o que o provedor devolveu em provider.initiate*Transfer() — não é fixado pelo BaaS |
POST /transfers/:id/refund | Só 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 |
CANCELLED | Terminal, mas nenhum caminho do código leva a ele — está reservado para status vindo do provedor (§15) |
GET /pix/transfers/:id e GET /ted/:id | Nã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).
| Campo | O que guarda |
|---|---|
source | De 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 |
amount | O 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 |
payer | BORROWER (o cliente do tenant) ou HOUSE (o tenant) — o vocabulário do Pricing Engine |
operationType | O que foi tarifado: o transactionType da transação (PIX_OUT, TED_OUT). É também a operation com que se pergunta o preço |
pricingRuleId, pricingRuleVersion | A regra que produziu o preço e a versão dela. Só em HOUSE |
quoteSnapshot | O 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, waivedBy | A isenção. Os três andam juntos: não existe linha isentada sem motivo e sem autor |
chargeTransactionId | A 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 comsource = UNPRICEDe 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 houve | Linha gravada | Conta na franquia |
|---|---|---|
| Nenhuma regra ativa cota a operação — não há tarifa | Nenhuma | Não |
| A franquia cobriu — preço apurado, e é zero | HOUSE, amount = 0, fullAmount no retrato | Sim |
| O preço não foi apurado | UNPRICED, amount = 0, motivo no retrato | Sim — 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.*.
| Grupo | Eventos |
|---|---|
| Conta | baas.account.created · baas.account.updated · baas.account.closed · baas.account.blocked |
| KYC | baas.kyc.submitted · baas.kyc.approved · baas.kyc.rejected |
| Pix | baas.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 |
| Boleto | baas.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) |
| TED | baas.ted.transfer.initiated · baas.ted.transfer.completed · baas.ted.transfer.failed · baas.ted.received |
| Bloqueio de saldo | baas.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 guardada | baas.hold.divergence.explained — alguém explicou (causa e autor; o texto não vai) |
| Trava de recebíveis | baas.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 |
| Tarifa | baas.fee.applied · baas.fee.waived |
| Autorização | baas.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).
| Campo | O que é |
|---|---|
amount / capturedAmount / reservedAmount | Valor 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) |
sourceDocuments | CPFs/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 |
externalReference | A operação/título que a trava garante |
expiresAt | No máximo 12 meses (o teto do mandato) |
status | PENDING_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 / activatedAt | Até 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 / mandateId | HOLDER 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.
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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/provider-configs | Cria 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, abaixo | BAAS_ADMIN |
GET | /baas/api/v1/provider-configs | Lista, paginado. Filtros filter[providerType], filter[isActive] | BAAS_READ |
GET | /baas/api/v1/provider-configs/:id | Busca por ID | BAAS_READ |
PATCH | /baas/api/v1/provider-configs/:id | Atualiza. Se enviar credentials, testa antes de gravar | BAAS_ADMIN |
DELETE | /baas/api/v1/provider-configs/:id | Exclusão lógica. 204 | BAAS_ADMIN |
POST | /baas/api/v1/provider-configs/:id/set-default | Marca como padrão e desmarca as outras | BAAS_ADMIN |
POST | /baas/api/v1/provider-configs/:id/test | Testa a conexão com as credenciais gravadas | BAAS_ADMIN |
POST | /baas/api/v1/provider-configs/:id/webhook-delivery | Gera 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 credencial | BAAS_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étodo | Rota | Descrição | Quem |
|---|---|---|---|
GET | /baas/api/v1/admin/platform/organizations/:organizationId/simulated-provider | O 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 é seguro | operador da plataforma |
DELETE | /baas/api/v1/admin/platform/organizations/:organizationId/simulated-provider | Revoga — 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 ativa | operador da plataforma |
DELETE | …/simulated-provider?force=true | Revogaçã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 conceder | operador da plataforma |
- Operador da plataforma é a mesma noção do
banking(@shared/middleware/platform-operator.middleware, a função é uma só): permissãoIAM_ORGANIZATIONS_UPDATEE organização do token emBANKING_PLATFORM_ORGANIZATION_IDS. Oiamnão tem conceito de plataforma — oADMINde toda organização tem toda permissão —, então só a permissão não basta. Lista vazia ou ausente:403para 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 usamBAAS_READ/BAAS_ADMINe não estão no prefixo duplicado. - A variável tem o nome do
bankinge tem de estar no serviço dobaas.BANKING_PLATFORM_ORGANIZATION_IDSnasceu nobankinge o nome foi mantido para não criar env nova; obaasroda em serviço próprio e lê o env dele. Sem ela gravada nobb-baas, estas rotas respondem403a 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 (
PATCHcomsettings.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
idda 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
grantIdsativos são lidos, o evento sai com eles e só entãorevokedAt/revokedBysão gravados. Sem confirmação:503, as linhas intactas, a organização segue concedida — e quem chamou sabe (a resposta diz, e sai log emerror); - 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.
- conceder — 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 levaforced: true), loga emerrorcom operador, organização egrantIds, e respondetrail: '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 deBAAS_SIMULATED_PROVIDER_ORGANIZATION_IDSnão revoga uma concessão feita pela API. - O que sai, e onde.
baas.simulated-provider.grant.createdebaas.simulated-provider.grant.revoked(este comgrantIds, todas as linhas revogadas) saem na trilha da organização alvo, com o operador como autor e a organização dele emoperatorOrganizationId. Na trilha a revogação é uma escrita (UPDATE) na concessão.grant.creatednão leva oreason: 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), comgrantId,targetOrganizationId,reason,grantedByegrantedAt; depois de revogada, a concessão some doGET, 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 osgrantIds. - A recusa é diferente: log sempre, evento de melhor esforço. A recusa da trava (criação ou
PATCH) loga sempre e publicabaas.simulated-provider.refusedna trilha da organização de quem tentou, sem segurar o403— 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 prefixobaas.simulated-provider.e segue só para a trilha. O cliente vê a recusa na resposta403; 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 publicambaas.simulated-provider.grant[.read|.revoke].<desfecho>na trilha da organização de quem tentou, comtargetOrganizationId: o403de 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 trilhaACCESS_DENIED),not_found(404— não havia concessão a revogar) einvalid(400de validação) — os dois últimos entram na trilha comoACCESS, porque não são acesso negado;throttledefailedcomo nas demais. As rotas de bloqueio, pedido, divergência, Pix e TED não mudaram: todo4xxdelas segue…refused. O401(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 oEventPublishergrava esses eventos em outro stream,platform-operator-events, que só oaudit-trailconsome. O consumidor de webhook lêiam-events: o que não está lá não é entregue a assinatura nenhuma — nem à padrãobaas.*, nem a*, nem a filtro exato — por nenhuma versão dowebhooks-engine, inclusive uma réplica de build antigo. A garantia vale a partir do momento em que obaasroda com esta versão; ela não é retroativa nem cobre umbaasde build antigo, que ainda publica noiam-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, comactorId,grantedByeoperatorOrganizationIdno 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 pusho mantém, e ele não entra na lista deDROPdoprisma/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 é oVERIFICAR_FILEdo 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 (MOCKBANKesettings.sandbox: true), e essa chave está emcredentials, não emsettings. (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
baasnão consulta oiampara saber se ela existe.
Contas — /baas/api/v1/accounts
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/accounts | Abre conta no provedor e registra localmente. Aceita purpose (opcional; omitido, nasce OWN). 201 | BAAS_ADMIN |
GET | /baas/api/v1/accounts | Lista, paginado. Filtros filter[status], filter[purpose], filter[personId], filter[configId]. Rótulo fora do conjunto é 400, não lista vazia | BAAS_READ |
GET | /baas/api/v1/accounts/:id | Busca por ID | BAAS_READ |
PATCH | /baas/api/v1/accounts/:id | Atualiza 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ão | BAAS_ADMIN |
POST | /baas/api/v1/accounts/:id/close | Encerra a conta. Exige reason. Gated (§14) | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/balance | Saldo consultado no provedor a cada chamada, mais ledgerHoldAmount e spendableBalance — os campos antigos não mudam de significado | BAAS_READ |
POST | /baas/api/v1/accounts/:id/kyc | Envia documentos de KYC. Gated (§14) | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/kyc | Consulta o status de KYC no provedor | BAAS_READ |
POST | /baas/api/v1/accounts/:id/sandbox/deposit | Só MockBank. Credita saldo para teste | BAAS_ADMIN |
Bloqueio de saldo — /baas/api/v1/accounts/:id/holds
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/accounts/:id/holds | Trava 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_REUSED | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/holds | Lista 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 vazia | BAAS_READ |
GET | /baas/api/v1/accounts/:id/holds/:holdId | A linha viva: valor, acumuladores e activeAmount (amount − released − settled) | BAAS_READ |
GET | /baas/api/v1/accounts/:id/holds/:holdId/entries | O razão do bloqueio, uma linha por ato | BAAS_READ |
POST | /baas/api/v1/accounts/:id/holds/:holdId/release | Devolve 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.release | BAAS_ADMIN + máquina |
POST | /baas/api/v1/accounts/:id/holds/:holdId/settle | O 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 inFlight | BAAS_ADMIN + máquina |
POST | /baas/api/v1/accounts/:id/holds/:holdId/requests | Pede 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. 201 | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/holds/:holdId/requests | Os pedidos deste bloqueio, abertos e decididos. filter[status] | BAAS_READ |
GET | /baas/api/v1/accounts/:id/holds/:holdId/requests/:requestId | Um pedido | BAAS_READ |
POST | /baas/api/v1/accounts/:id/holds/:holdId/requests/:requestId/approve | Outra 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_DECIDED | BAAS_ADMIN + pessoa |
POST | /baas/api/v1/accounts/:id/holds/:holdId/requests/:requestId/reject | Recusa, com reason obrigatório. Quem pediu pode retirar o próprio pedido | BAAS_ADMIN + pessoa |
GET | /baas/api/v1/hold-requests | A fila da organização: filter[status]=PENDING, filter[kind], filter[accountId]. Paginado, sem total | BAAS_READ |
GET | /baas/api/v1/hold-requests/:requestId | Um pedido, sem precisar saber a conta | BAAS_READ |
POST | /baas/api/v1/accounts/:id/holds/:holdId/resume | Retoma 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 sozinha | BAAS_ADMIN + máquina |
POST | /baas/api/v1/accounts/:id/holds/reconcile | Confere 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ção | BAAS_ADMIN |
GET | /baas/api/v1/hold-divergences | As 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 linha | BAAS_READ |
GET | /baas/api/v1/hold-divergences/:divergenceId | Uma divergência: os números da primeira e da última detecção, quantas vezes foi vista, e a explicação | BAAS_READ |
POST | /baas/api/v1/hold-divergences/:divergenceId/explanation | Explica, 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.explained | BAAS_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
PUTda 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 comBAAS_ADMINe 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 deholderAuthorizationaqui, 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_ADMINnã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óprioWHERE. 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_UNKNOWNe a varredura de pedido preso fecha (§15). O consumo por pedido usa o id do pedido comoidempotencyKey. O razão grava o decisor como ator e o pedido emrequestId; quem pediu está no pedido e emmetadata.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 um5xxcria um segundo bloqueio. O console do backoffice e todo integrador devem mandar umaidempotencyKey(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ção Resposta Chave nova 201e o bloqueio novoMesma chave, mesmo pedido 200com o mesmo bloqueio, como ele está agora, emeta.idempotentReplay: true. Nada é criado, o saldo não é relido e o banco não é chamadoMesma chave, mesmo pedido, custódia PROVIDERe a chamada ao banco sem desfecho (em voo, ou a resposta se perdeu)202commeta.inFlight: trueemeta.poll— não reenvie: o banco pode estar segurando o valor, e a repetição nunca chama o banco de novoMesma chave, mesmo pedido, e o banco recusou a primeira criação 422comdetails.code = HOLD_PROVIDER_REFUSEDedetails.reason(as palavras do banco). Nada ficou preso; para tentar de novo, chave novaMesma chave, outro pedido (outra conta, valor, moeda, reasonType,externalReferenceouexpiresAt)409comdetails.code = IDEMPOTENCY_KEY_REUSED. Moeda omitida conta comoBRLSem chave Como sempre foi: cria, e o reenvio cria outro. Registra warn(baas: chamada … SEM idempotencyKey)
reasonTextfica 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 leva422); 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, semproviderHoldId, e a resposta do bloqueio trazpendingReconciliation: true. Enquanto isso: liberar e consumir recusam com409 HOLD_PROVIDER_HOLD_MISSINGantes de reivindicar qualquer coisa; a repetição da chave responde202; e a varredura de vencimento pula a linha — expirar sem falar com o banco prenderia o dinheiro lá sem saída. Saibaas.hold.provider.pending(comattemptsereasonCode— só o código, nunca a mensagem do banco). A resposta da criação trazdetails.pendingReconciliatione oholdId; a trilha de recusas não publicacreate.failedpara esse mesmo fato.Quem resolve é
HoldService.retomarCriacao: a varredura de retomada (a cadaBAAS_HOLD_RESUME_INTERVAL_MINUTES, só linhas com mais deBAAS_HOLD_RESUME_MIN_AGE_MINUTES) e a rotaPOST …/holds/:holdId/resume. Ela chama o banco de novo com a mesma chavehold:<id>: ok → carimba o id e publicabaas.hold.created; recusa determinada → libera a linha aqui (nada ficou preso lá); de novo sem resposta → fica como está,providerResumeAttempts+1 e outrobaas.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ébitoPENDING/PROCESSING, mais oCOMPLETEDdepois 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_BALANCEtrazinFlightAmount). Espera com teto (lock_timeout5 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 aSETTLEDantes de o banco pagar. - Desfecho do provedor (
closeReservationAfterProviderError): recusa determinada (4xx) ou falha nossa antes do banco → reservaFAILED, o valor volta ao gastável. Timeout/5xx → reserva ficaPENDINGe 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 virabaas.pix.transfer.<desfecho>/baas.ted.transfer.<desfecho>comrequested,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." OlheinFlightAmountno evento. Saída que estourou o tempo no banco ficaPENDINGe segue descontando até a conciliação; reserva sem id do provedor voltaUNRESOLVEDe só o backoffice a solta (claimStatusparaFAILEDdepois 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
PROCESSINGque 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_BUSYem rajada. As saídas de UMA conta são serializadas. A trava dura trêsSELECTe umINSERT; 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 deTransactionRepositoryusamcomTravaDaConta(...)(tests/unit/baas/support/spendable.ts).createefindByIdempotencyKeyrecebem otxcomo argumento a mais. - A prova é contra Postgres.
tests/integration/baas/spendable-race.integration.test.tsmede opagono 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 aFAILEDdepois que o valor voltou ao bloqueio. Se a compensação não gravou (corrida no acumulador, banco fora), a reserva ficaPENDINGcom 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). OGET …/balancecontinua devolvendospendableBalance = disponível − bloqueios(sem as saídas em voo): é o número do alarme de divergência, e descontar ali faria saídaPROCESSINGjá 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.
spendableBalancenegativo 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>:
| Desfecho | Quando | Exemplo |
|---|---|---|
refused | 4xx | baas.hold.request.approve.refused com reason: HOLD_REQUEST_SAME_ACTOR |
throttled | 429 | — |
unknown | HOLD_REQUEST_OUTCOME_UNKNOWN (o ato pode ter acontecido) | baas.hold.request.approve.unknown |
failed | 5xx, 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étodo | Rota | Permissão | O que faz |
|---|---|---|---|
POST | /accounts/:id/liens | BAAS_ADMIN | Cria 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/liens | BAAS_READ | Lista (filter[status], filter[externalReference]; filtro fora do conjunto é 400). Fim pela página curta, como os bloqueios |
GET | /liens/:lienId | BAAS_READ | A trava, com as capturas em included (baas-lien-capture: crédito, valor, estado, bloqueio, transferência, failureCode, tentativas) |
POST | /liens/:lienId/cancel | BAAS_ADMIN | Quatro 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/activate | BAAS_ADMIN, só máquina | PENDING_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/abandon | BAAS_ADMIN, só máquina | Desfaz 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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /baas/api/v1/accounts/:id/fees | As tarifas da conta. Filtros filter[startDate], filter[endDate] e filter[source] (PROVIDER, HOUSE, UNPRICED); paginado. Origem fora do conjunto é 400 | BAAS_READ |
POST | /baas/api/v1/accounts/:id/fees/:feeId/waive | Isenta a tarifa. Exige waiverReason (1 a 500 caracteres). O autor é o usuário do token. Publica baas.fee.waived. 200 | BAAS_ADMIN |
POST | /baas/api/v1/accounts/:id/fees/:feeId/charge | Cita 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. 200 | BAAS_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.
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ção | Resposta |
|---|---|
| Tarifa que não é desta conta ou desta organização | 404 |
waiverReason ausente ou vazio | 400 |
Token cujo sub não é um UUID (não identifica quem isentou) | 400, details.code = WAIVER_AUTHOR_REQUIRED |
| Isentar tarifa já isentada | 200 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á cobrada | 409, details.code = FEE_ALREADY_CHARGED. Devolver o que foi cobrado é estorno, não isenção |
| Citar cobrança em tarifa isentada | 409, details.code = FEE_WAIVED |
| Citar a mesma transferência de novo | 200, inócuo |
| Citar outra transferência em tarifa já cobrada | 409, details.code = FEE_ALREADY_CHARGED — não sobrescreve |
chargeTransactionId de transação inexistente ou de outra organização | 404 |
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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
GET | /baas/api/v1/accounts/:id/authorization-policy | Polí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 sai | BAAS_READ |
PUT | /baas/api/v1/accounts/:id/authorization-policy | Grava 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/anchor | Ancoragem 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: 404 | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/devices | Lista as chaves de dispositivo, ativas e revogadas | BAAS_READ |
POST | /baas/api/v1/accounts/:id/devices | Cadastra a chave pública. Exige evidência biométrica vinculada. 201 | BAAS_ADMIN |
DELETE | /baas/api/v1/accounts/:id/devices/:deviceId | Revoga a chave. Sempre permitido. 204 | BAAS_ADMIN |
POST | /baas/api/v1/accounts/:id/authorization-challenges | Emite o desafio de uso único (120 s). 201 | BAAS_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-sessions | Abre 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_UNAVAILABLE | BAAS_ADMIN |
POST | /baas/api/v1/accounts/holder-lookups | Contas 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 integridade | BAAS_ADMIN |
POST | /baas/api/v1/accounts/:id/authorization-policy/holder-document/reveals | O 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 gravada | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/mandates | Lista os mandatos da conta, ativos e revogados. Nunca devolve a assinatura nem o nonce da concessão | BAAS_READ |
POST | /baas/api/v1/accounts/:id/mandates | Concede 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. 201 | BAAS_ADMIN |
GET | /baas/api/v1/accounts/:id/mandates/:mandateId | Busca por ID | BAAS_READ |
DELETE | /baas/api/v1/accounts/:id/mandates/:mandateId | Revoga. Sempre permitido ao admin; com holderAuthorization sobre mandate.revoke, fica registrado como revogação do titular. 204 | BAAS_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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/pix/keys | Registra chave Pix. 201. Gated (§14) | BAAS_ADMIN |
GET | /baas/api/v1/pix/keys | Lista chaves. Exige ?accountId=, senão 400 | BAAS_READ |
DELETE | /baas/api/v1/pix/keys/:id | Remove a chave no provedor e marca deletedAt. 204. Gated (§14) | BAAS_ADMIN |
POST | /baas/api/v1/pix/keys/lookup | Consulta o DICT: quem é dono de uma chave | BAAS_READ |
GET | /baas/api/v1/pix/transfers | Lista transações Pix da organização, com dados da conta | BAAS_READ |
POST | /baas/api/v1/pix/transfers | Inicia 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/:id | Consulta e sincroniza o status com o provedor | BAAS_READ |
POST | /baas/api/v1/pix/transfers/:id/refund | Devolve um Pix recebido. 201. Gated (§14) | BAAS_ADMIN |
POST | /baas/api/v1/pix/qr-codes/generate | Gera QR Code estático ou dinâmico. Com amount, gated (§14) | BAAS_ADMIN |
POST | /baas/api/v1/pix/qr-codes/decode | Decodifica um código EMV | BAAS_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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/ted | Inicia transferência TED. 201 | BAAS_ADMIN |
GET | /baas/api/v1/ted | Lista transações TED. Aceita ?accountId= ou os mesmos filtros do Pix | BAAS_READ |
GET | /baas/api/v1/ted/:id | Consulta e sincroniza o status com o provedor | BAAS_READ |
GET /tedmuda de comportamento conforme o filtro: comaccountIde semconfigId, 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étodo | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/boletos | Registra 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 status | BAAS_READ |
GET | /baas/api/v1/boletos/:id | Busca por ID, sem ir ao banco | BAAS_READ |
POST | /baas/api/v1/boletos/:id/sync | Consulta o banco e grava o que ele diz: registro, liquidação, baixa | BAAS_READ |
POST | /baas/api/v1/boletos/:id/write-off | Baixa 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/pay | Só 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 evento | BAAS_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:
| Status | Significa |
|---|---|
REGISTERING | Enviado ao banco, registro ainda não confirmado |
REGISTERED | Registrado e em cobrança |
FAILED | Recusado pelo banco |
SETTLED | Pago e creditado. settledAmount pode diferir de amount (multa, juros, desconto) |
WRITTEN_OFF | Baixado 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.
| Provedor | Exige além do básico | Não aceita |
|---|---|---|
| Celcoin | payer.address completo | allowPartialPayment |
| QI Tech | requesterProfileKey na configuração (§13) | — |
| FitBank | payer.address, payer.email ou payer.phone, e mktPlaceId na configuração (§13) | — |
| MockBank | — | — |
Webhooks — /baas/api/v1/webhooks
| Método | Rota | Descrição | Autenticação |
|---|---|---|---|
POST | /baas/api/v1/webhooks/deliveries/:deliveryId | O 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/:providerType | LEGADO, 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 demais | Assinatura do provedor — não usa JWT |
GET | /baas/api/v1/webhooks/health | Sonda simples do subsistema de webhook | Pública |
Conciliação — /baas/api/v1/transactions
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /baas/api/v1/transactions/:id/reconcile | Pergunta ao banco o desfecho de uma transação parada em PENDING/PROCESSING e grava o resultado. Idempotente | BAAS_ADMIN |
POST | /baas/api/v1/transactions/reconcile | Uma passada da varredura, restrita à organização do token. Corpo opcional: staleMinutes, limit | BAAS_ADMIN |
Saúde
| Método | Rota | Descrição |
|---|---|---|
GET | /baas/health | Identificaçã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
{
"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"]
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string (1–100) | Sim | Único dentro da organização. Colisão devolve 409 |
providerType | CELCOIN | FITBANK | QITECH | MOCKBANK | Sim | Determina qual estratégia é instanciada |
credentials | Record<string,string> | Sim | Formato depende do provedor — ver §13. Cifrado antes de gravar |
isDefault | boolean | Não | Marcar como padrão desmarca a anterior |
isActive | boolean | Não | Padrão true. Config inativa não pode virar padrão |
settings | object | Não | Ajustes específicos do provedor |
webhookUrl | string (URL) | Não | Onde o provedor entrega. Omitido, o serviço gera a partir de BAAS_WEBHOOK_BASE_URL |
webhookEvents | string[] | Não | Filtra o que é processado. Vazio significa todos |
clientWebhookUrl | string (URL) | Não | Onde você quer receber. Cria uma assinatura no Webhooks Engine |
clientWebhookEvents | string[] | Não | Filtros de evento baas.*. Vazio vira baas.* |
Resposta 201
{
"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
| Status | Quando |
|---|---|
400 | Corpo reprovado no Zod, credenciais incompletas, ou testConnection() falhou |
403 | Token sem organizationId, ou sem BAAS_ADMIN |
409 | Já 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
{
"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"
}
}
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
configId | uuid | Não | Config a usar. Omitido, usa a padrão |
personId | uuid | Não | Vínculo com Person do Customers. Não é chave estrangeira — ver §15 |
businessId | string | Não | Seu identificador de negócio. Fica na conta e nas transações |
purpose | OWN | ESCROW | COLLATERAL | SETTLEMENT | Não | Para 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.documentType | CPF | CNPJ | Sim | Define quais campos o provedor vai exigir |
holder.documentNumber | string (11–14) | Sim | Sem formatação |
holder.legalRepresentative | object | Não | Para CNPJ: representante legal |
metadata | object | Não | Chaves livres, guardadas em JSONB |
Resposta 201
{
"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
{
"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"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
accountId | uuid | Sim | Conta de origem. Precisa ser da sua organização |
amount | number > 0 | Sim | Em reais, com centavos. Precisão de Decimal(15,2) |
description | string (≤140) | Não | Vai no campo livre do Pix |
pixKey | string | Condicional | Chave do destinatário. Celcoin e FitBank consultam o DICT antes de enviar |
recipient | object | Condicional | Dados bancários completos, quando não há chave |
scheduledFor | string (ISO 8601) | Não | Agendamento. Suporte depende do provedor |
businessId | string | Não | Seu identificador, guardado na transação |
idempotencyKey | uuid | Não | Sua 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
| Status | Quando |
|---|---|
400 | Sem pixKey nem recipient; saldo insuficiente; valor acima do limite; conta bloqueada ou encerrada |
403 | Token sem organizationId ou sem BAAS_ADMIN |
404 | accountId 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.
{ "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.
{
"mode": "HOLDER_SIGNATURE",
"holderDocument": "52998224725",
"requireBiometricAbove": 1000.00,
"operators": []
}{
"mode": "HOLDER_SIGNATURE",
"holderDocument": "52998224725",
"requireBiometricAbove": 1000.00,
"operators": []
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
mode | NONE | HOLDER_SIGNATURE | OPERATOR | QUORUM | Sim | NONE é o comportamento atual; QUORUM exige signingRules (§14.9) |
holderDocument | string (CPF) | Em HOLDER_SIGNATURE | CPF 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 |
requireBiometricAbove | number | Não | Acima deste valor, a operação exige sessão biométrica vinculada. null = nunca |
operators | string[] (CPF) | Em OPERATOR | Quem pode autorizar por uma conta de empresa |
holderAuthorization | object | Ao afrouxar | Assinatura de policy.update sobre a política nova |
POST /baas/api/v1/accounts/:id/devices
{
"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:
{
"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ódigo | Status | Significa |
|---|---|---|
AUTHORIZATION_REQUIRED | 403 | A conta exige assinatura e ela não veio |
DEVICE_NOT_FOUND | 403 | deviceId não existe nesta conta |
DEVICE_REVOKED | 403 | A chave foi revogada |
DEVICE_NOT_ALLOWED | 403 | A chave existe, mas o modo da política não a aceita |
ENROLLMENT_INVALID | 403 | A evidência biométrica que cadastrou a chave não se sustenta |
SIGNATURE_INVALID | 403 | A assinatura não corresponde à operação que chegou |
CHALLENGE_INVALID | 403 | Desafio inexistente ou de outra conta |
CHALLENGE_EXPIRED | 403 | Desafio vencido |
CHALLENGE_USED | 403 | Desafio já consumido |
BIOMETRIC_REQUIRED | 403 | Valor acima do limiar sem sessão biométrica |
BIOMETRIC_INVALID | 403 | A sessão biométrica não prova esta operação |
BIOMETRIC_FLOW_INVALID | 403 | O fluxo da sessão não compara rosto contra titular (LIVENESS_ONLY, ENROLLMENT) — §14 |
BIOMETRIC_IDENTITY_NOT_PROVEN | 403 | A 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_UNUSABLE | 403 | O 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_INVALID | 403 | A 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_UNAVAILABLE | 503 | Nã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 --> OKPipeline de processamento, nesta ordem:
- Resolve a configuração. No caminho recomendado, pelo
:deliveryId— e a organização vem do registro. No caminho legado, pelo:providerTypemais oorganizationIdque o chamador mandou no cabeçalho (§14 e §15); configuração que já tem endereço próprio é recusada ali. - Fonte —
settings.webhookAllowedCidrs, se declarada e se a borda for confiável (§15). - Assinatura —
verifyWebhookSignature(headers, body, rawBody), sobre o corpo cru; quando não é verificável, decidePROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT(§13). parseWebhookPayload()traduz o corpo do provedor paraParsedBaaSWebhook.- Filtra por
webhookEventsda config; evento não assinado é descartado com{ received: true }. - 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). - Grava em
baas_webhook_events, aplica o efeito e publica o eventobaas.*. 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.
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
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
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
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}'{ "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
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)
curl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/sandbox/deposit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"amount": 1000}' | jqcurl -s -X POST "$BASE/api/v1/accounts/$ACC_ID/sandbox/deposit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"amount": 1000}' | jq{ "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
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}'{ "status": "COMPLETED", "amount": 150.75, "endToEndId": "E9999999920260816120012AB34CD56EF78" }{ "status": "COMPLETED", "amount": 150.75, "endToEndId": "E9999999920260816120012AB34CD56EF78" }7. Conferir o saldo
curl -s "$BASE/api/v1/accounts/$ACC_ID/balance" -H "Authorization: Bearer $TOKEN" | jqcurl -s "$BASE/api/v1/accounts/$ACC_ID/balance" -H "Authorization: Bearer $TOKEN" | jqVolta 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.
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.
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.
curl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/test" \
-H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST "$BASE/api/v1/provider-configs/$NEW_ID/test" \
-H "Authorization: Bearer $TOKEN" | jqResposta esperada: 200 confirmando conectividade e credencial.
Passo 3 — virar o padrão. A partir daqui, POST /accounts sem configId abre no provedor novo.
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.
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
configIdda 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-defaultafeta 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.
# 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:
# 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.
202na 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 emmeta.poll.outcome: UNRESOLVEDcom 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).GETbate 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 oidda transação nem oexternalId. É 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).
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.
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
…/settlecom chave de API (ou tokenclient_credentials). Um operador logado recebe403 HOLD_DIRECT_ACTION_MACHINE_ONLY: ele pede o consumo (POST …/holds/:holdId/requestscomkind: 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.
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.
expiresAtausente éNULL, e a varredura o ignora de propósito. Garantia esquecida trava saldo para sempre. gapnã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
blockedBalancecomledgerHoldAmount. O primeiro é do provedor; o segundo é o que nós escrituramos. Comcustody = PROVIDERo 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).
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).
# 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
403para 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. PATCHcomcredentialssubstitui tudo: mande tambémclientId/clientSecret, não só owebhookSecret.- 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.
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.
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.
expiresInMinutestem teto de 1440 — 24 horas. Acima disso o Zod reprova com400.- Sem
amount, o QR é estático: reutilizável e sem valor definido. Comamount, é 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
PATCHregistra umwarnno log e devolve200mesmo assim, comwebhookSubscriptionIdvazio. 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.
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:
APPROVEDleva a conta aACTIVE,REJECTEDaKYC_REJECTED, e qualquer outra coisa aKYC_IN_PROGRESS. - Quem decide é o provedor. O BaaS não avalia documento; ele encaminha e reflete.
rejectedFieldsdiz o que reenviar. - Conta sem KYC aprovado não transaciona. No MockBank isso é explícito (
KYC_NOT_APPROVEDvira403); 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:
# 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}" | jqOrdem 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.
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"}' | jqcurl -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"}' | jqPasso 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.
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\"}" | jqcurl -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\"}" | jqResposta 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.
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}' | jqcurl -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}' | jqPasso 5 — transferir. Peça o desafio, mande operação e desafio ao aplicativo, receba a assinatura e envie tudo junto:
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\"}}" | jqCH=$(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\"}}" | jqResposta 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çãopolicy.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):
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.
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.
Integração com outros building blocks
| Building block | Como se relaciona | Obrigatório |
|---|---|---|
| IAM | Emite o token; organizationId, BAAS_READ e BAAS_ADMIN vêm dele | Sim |
| Webhooks Engine | ProviderConfigService cria, atualiza e apaga a assinatura de saída quando você define clientWebhookUrl | Sim — é dependência de container |
| Customers | BaaSAccount.personId aponta para Person; filter[personId] lista as contas de uma pessoa | Não |
| Biometrics | Prova de vida que autoriza o cadastro de uma chave de dispositivo e o degrau biométrico acima do limiar. Via fachada BiometricsFacadeToken | Só para contas com política ≠ NONE |
| Audit Trail | Consome os eventos baas.* para trilha de compliance | Não |
| File Storage | Guarda os documentos de KYC; o BaaS recebe a URL, não o arquivo | Não |
| Payments | Cobrança e conciliação de recebíveis; o BaaS é a conta onde o dinheiro cai | Não |
| Open Finance | Agrega dados de contas em outras instituições; o BaaS opera a conta que é sua | Não |
| Decision Platform | Decide se concede o crédito; o BaaS desembolsa o resultado | Não |
| Pricing Engine | Decide 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 PricingFacadeToken | Nã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.
| Bloco | Faz | Não faz |
|---|---|---|
| Pricing Engine | Decide o preço — faixa, vigência, prioridade, quem paga, franquia (freeUnitsPerMonth), recorrência | Não guarda o cálculo (stateless), não conta quantas vezes a conta usou, não cobra |
| BaaS | Conta a franquia, aplica, registra e explica — a linha, o retrato, a isenção | Nã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 casosA 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.
| Modo | Como o BaaS alcança o Pricing Engine |
|---|---|
| Monólito | Chamada direta ao serviço, no mesmo processo |
| Standalone | HTTP, 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 linhasUNPRICEDsubindo e owarn"pricing-engine não apurou o preço" no log dobaas. 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.
Configuração e operação
Variáveis de ambiente
| Variável | Descrição | Obrigatória | Padrão |
|---|---|---|---|
BAAS_CREDENTIAL_MASTER_KEY | Chave AES-256-GCM das credenciais de provedor. Exatamente 64 caracteres hexadecimais (32 bytes). Gere com openssl rand -hex 32 | Sim, para usar o módulo | — |
BAAS_WEBHOOK_BASE_URL | Base das URLs de callback geradas automaticamente | Não | http://localhost:3000 |
BAAS_SIMULATED_PROVIDER_ORGANIZATION_IDS | Fallback 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ço | Não | vazio: em produção só cria quem tem concessão |
BANKING_PLATFORM_ORGANIZATION_IDS | Organizaçõ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 baas | Não | vazio: ninguém concede pela API (403) |
PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT | off ou on. Qualquer valor exceto off (inclusive ausente) rejeita webhook que não puder ser verificado | Não | fail-closed |
BAAS_WEBHOOK_TRUST_FORWARDED_FOR | Declara 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 é teatro | Não | false |
BAAS_RECONCILIATION_ENABLED | Liga a varredura de conciliação. Desligar devolve o bloco ao estado em que reserva órfã fica PENDING para sempre | Não | true |
BAAS_RECONCILIATION_INTERVAL_MINUTES | Intervalo entre passadas | Não | 5 |
BAAS_RECONCILIATION_STALE_MINUTES | Quanto tempo sem desfecho até a transação virar candidata | Não | 15 |
BAAS_HOLD_EXPIRY_ENABLED | Liga 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 janela | Não | true |
BAAS_HOLD_REQUEST_SWEEP_ENABLED | Liga 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 bloqueio | Não | true |
BAAS_HOLD_REQUEST_SWEEP_INTERVAL_MINUTES | Intervalo entre passadas da varredura de pedido preso | Não | 5 |
BAAS_HOLD_RESUME_ENABLED | Liga a retomada da criação de bloqueio PROVIDER sem desfecho do banco. Desligar deixa a linha pendingReconciliation até alguém chamar POST …/holds/:holdId/resume | Não | true |
BAAS_LIEN_PENDING_ACCEPTANCE_MINUTES | Quanto a trava PENDING_ACCEPTANCE espera a ativação antes de a varredura a vencer (acceptance-timeout); a ativação depois disso é recusada | Não | 30 |
BAAS_LIEN_SWEEP_ENABLED / BAAS_LIEN_SWEEP_INTERVAL_MINUTES / BAAS_LIEN_CREDIT_LOOKBACK_HOURS | A 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 meio | Não | true / 2 / 48 |
BAAS_HOLD_RESUME_INTERVAL_MINUTES | Intervalo entre passadas da retomada | Não | 5 |
BAAS_HOLD_RESUME_MIN_AGE_MINUTES | Idade mínima da linha para a retomada tocá-la (abaixo disso a criação original pode estar em voo) | Não | 5 |
BAAS_HOLD_REQUEST_STUCK_MINUTES | Há quantos minutos um pedido precisa estar EXECUTING para a varredura o fechar | Não | 15 |
BAAS_HOLD_EXPIRY_INTERVAL_MINUTES | Intervalo entre passadas do vencimento. Mais barata que a de conciliação: lê pelo índice parcial e não fala com provedor nenhum | Não | 5 |
BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES | Quanto 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 janela | Não | 60 |
MODULE_AUDIT_TRAIL_URL | (standalone) Base do Audit Trail, lido antes de toda escrita gated (BB-5). Sem ele, 503 POLICY_INTEGRITY_UNAVAILABLE | Sim, em standalone | — |
BAAS_POLICY_INTEGRITY_CACHE_MS | Quanto tempo a última linha da trilha de uma conta é reaproveitada. 0 desliga o cache | Não | 5000 |
BAAS_POLICY_ANCHOR_WAIT_MS | Quanto o PUT/anchor espera a trilha encadear a linha antes de responder sem a posição | Não | 3000 |
DATABASE_URL | PostgreSQL | Sim | — |
REDIS_URL | Redis, usado no rate limit | Sim | — |
JWT_SECRET | Verificação do token do IAM. Mínimo 44 caracteres | Sim | — |
MODULE_IAM_URL | URL do IAM em standalone | Em standalone | — |
DEPLOYMENT_MODE | monolith ou standalone | Não | monolith |
PORT | Porta em standalone | Não | 3000 (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 ≠NONEresponde503(BIOMETRICS_UNAVAILABLE) e nada é executado; conta sem política segue igual.
BAAS_CREDENTIAL_MASTER_KEYnã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.envversionado.
Credenciais por provedor — o que vai dentro do campo credentials.
| Provedor | Campos | Autenticação | Ambientes |
|---|---|---|---|
CELCOIN | clientId, clientSecret, sandbox | OAuth2 client_credentials, token em cache até 5 min antes de expirar | sandbox.openfinance.celcoin.dev · api.celcoin.com.br |
FITBANK | apiKey, apiSecret, partnerId, businessUnitId, sandbox | Basic Auth | sandboxapi.fitbank.com.br/main/execute · api.fitbank.com.br/main/execute |
QITECH | apiKey, privateKey, sandbox | Requisição assinada com RSA | sandbox.qitech.app · api-auth.qitech.app |
MOCKBANK | token, autoApproveKyc, simulateDelays, delayMs | Só confere que token não está vazio | Nenhum — roda local |
Boleto — o que cada banco pede a mais. Vale em credentials ou em settings.
| Provedor | Campo | O que é |
|---|---|---|
QITECH | requesterProfileKey | A 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 |
FITBANK | mktPlaceId | Identificador de marketplace que o FitBank fornece junto de partnerId e businessUnitId |
FITBANK | boletoGroupTemplate | Template 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:
| Campo | O que é |
|---|---|
mandateMaxMonths | Duraçã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) |
forceLedgerHolds | Só 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 |
externalPixKeys | Padrã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-trailantes dobaas. Oaudit-traildesta versão cria o grupoaudit-trail-consumersno streamplatform-operator-events; obaasdesta versão publica lá. Owebhooks-enginepode vir em qualquer momento. - Se a ordem for invertida (
baasnovo comaudit-trailantigo, ou comAUDIT_CONSUMER_ENABLEDdesligado): conceder e revogar respondem503 SIMULATED_PROVIDER_TRAIL_UNAVAILABLEcomdetails.reason: NO_TRAIL_READER— falha fechada, nada publicado, tabela intacta. Antes de publicar, obaasconfere 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 respondetrail: '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
baasestiver em build antigo, ele publica noiam-events; um consumidor de webhook de build anterior aac991e3dque esteja no grupo entrega esses eventos ao cliente. Owebhooks-enginedesta 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-enginede build antigo que continua no grupowebhook-delivery-consumersfora 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) oustaleVersionActive: true. O sinal tem limites (um órfão com o mesmo pid de uma réplica nova não aparece): detalhe e leitura emsrc/webhooks-engine/README.md§13, Consumidor órfão. Com obaasnesta 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 emwebhooks.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.
# 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.shEm 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:
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ência | Para quê |
|---|---|
| PostgreSQL | Schema baas — configs, contas, chaves, transações, eventos e o estado do MockBank |
| Redis | Contadores de rate limit |
| IAM | Validação do token e resolução de permissões |
| Webhooks Engine | Assinaturas de entrega dos eventos baas.* |
| Biometrics | Só para contas com política de autorização: evidência do enrolamento e degrau biométrico |
| API do provedor | Toda 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.ymledeploy/docker-stack.prod.ymlsão o caminho LEGADO. Os blocos migraram para o Launch (LXC): 39 serviçosbb-*ativos embb-prode 35 embb-staging, medidos em 25/09/2026. Osbb-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
requirepassnovalkey.confna criação, e não existe caminho que suba um cluster sem senha. A conexão dos blocos vem deSPARK_REDIS_URL(scripts/deploy-bb-prod.sh:21), que sobrescreve oREDIS_URLdo 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 — verdocs/plans/2026-09-25-onde-os-blocos-rodam-de-verdade.md.
Limites
| Limite | Valor | Onde |
|---|---|---|
| Corpo da requisição | 1 MB | applyCommonMiddleware — afeta KYC em base64 |
| Rate limit global | 10.000 req / 60s | RATE_LIMIT_GLOBAL_MAX |
| Descrição de Pix e TED | 140 caracteres | Zod |
| Expiração de QR dinâmico | 1 a 1440 minutos | Zod |
| Página padrão / listagens | 20 itens | Routers |
| Precisão monetária | Decimal(15,2) | Prisma |
| Limites de valor por transação | Do provedor | MockBank: 100.000 (Pix) e 500.000 (TED) |
Catálogo de erros
| Status | Código | Significa | O que fazer |
|---|---|---|---|
400 | (árvore Zod) | Corpo reprovado no schema | Compare os campos com §9 |
400 | VALIDATION | Regra de negócio: sem saldo, sem pixKey nem recipient, conta já encerrada, estorno de transação que não é PIX_IN COMPLETED | A message diz qual regra |
400 | VALIDATION | testConnection() falhou ao criar ou atualizar config | Confira as credenciais e o ambiente (sandbox) |
400 | — | Webhook sem X-Organization-Id nem organizationId | Corrija a URL cadastrada no painel do provedor |
401 | UNAUTHORIZED | Token ausente, inválido ou expirado | Renove no IAM |
403 | — | Token sem organizationId | Autentique informando a organização |
403 | FORBIDDEN | Sem BAAS_READ ou BAAS_ADMIN; ou conta bloqueada, encerrada, ou sem KYC aprovado | Confira permissões e o status da conta |
403 | FORBIDDEN + details.code | Autorização do titular recusada — os doze códigos de §9 | Leia details.code: falta assinatura, assinatura não confere, desafio queimado, biometria exigida |
503 | SERVICE_UNAVAILABLE + BIOMETRICS_UNAVAILABLE | Não deu para verificar a biometria | Falha fechada: nada foi executado. Confira o bloco Biometrics |
404 | NOT_FOUND | Recurso inexistente ou de outra organização | Confira o ID e a organização do token |
409 | CONFLICT | Nome de config já usado na organização | Escolha outro nome |
429 | — | Rate limit | Recuo exponencial |
500 | INTERNAL | Erro não mapeado do provedor | Consulte o log; o erro cru do provedor fica lá |
Observabilidade.
GET /baas/healthdevolve 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
warnestruturado com o provedor e o motivo, tanto com enforcement ligado quanto desligado. É o log que diz se você pode ligarPROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT=onsem 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 = falseacumulando é sintoma.- Erros de comunicação com o provedor são logados com contexto antes de virarem
AppError.
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/balancesempre 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:
| Dispositivo | O que determina | O que isso significa na prática |
|---|---|---|
| Art. 4º, §2º | As contas devem ser de titularidade do cliente na instituição prestadora | Conta 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 conta | A 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 BCB | O aviso ao cliente final é obrigação sua, na sua interface — o BaaS não tem como cumpri-la por você |
| Art. 10 | PLD/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 responsabilidade | O BaaS encaminha documento de KYC; a análise, a decisão e o dever regulatório são da instituição |
| Art. 19 | Cooperativas de crédito e sociedades de arrendamento mercantil não podem ser prestadoras | Restringe o universo de parceiros elegíveis |
| Art. 24 | O BCB pode vetar, restringir, suspender ou determinar o encerramento do contrato | Risco 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 comprometido | Sem política (NONE) | Com HOLDER_SIGNATURE |
|---|---|---|
Backend do cliente / token BAAS_ADMIN | Move o dinheiro | Não move. Sem a assinatura do enclave do celular, a credencial do provedor nem chega a ser decifrada |
| Workflow ou automação com defeito | Move o dinheiro | Não move. A automação não tem chave privada |
| Automação com mandato (régua, workflow) | Move o dinheiro | Faz 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 aplica | Nã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 juntos | Move o dinheiro | Move — 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 desbloqueado | Move o dinheiro | Move 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 bloqueio | Pela 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 banco | Linha na trilha | Veredito | Resposta |
|---|---|---|---|
| não | não | none — nunca aderiu | segue como NONE |
| sim | sim, hash igual | ok | segue |
| sim | sim, hash diferente | diverged — editada | 403 POLICY_INTEGRITY |
| não | sim | deleted — apagada | 403 POLICY_INTEGRITY |
| sim | não, e a corrente nunca foi podada | unanchored — anterior ao BB-5, ou inserida à mão | 403 POLICY_INTEGRITY até ancorar |
| sim | não, e a corrente foi podada | pruned — pode ser linha expurgada, pode ser linha escrita à mão | 403 POLICY_INTEGRITY; no anchor, 409 POLICY_TRAIL_PRUNED |
| qualquer | não deu para ler | unavailable | 503 POLICY_INTEGRITY_UNAVAILABLE |
Decisões que valem saber:
A trilha é assíncrona, e a posição vem por aperto de mão. O
EventPublisherdevolve o id da mensagem no stream na hora;sequenceehashsó existem quando o consumidor do Audit Trail grava a linha, segundos depois. O BaaS publica, espera (limitado) a linha com opolicyHashque 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
NONEcom 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 noupdated_atpor 30 s — é um buraco: o atacante gravaupdated_at = now()no mesmoUPDATE. Em vez disso, toda divergência é relida sem cache uma vez antes de valer, e oPUTespera a trilha antes de responder.O hash leva o
idda linha como sal — e oidnão sai por lugar nenhum. A trilha é legível comAUDIT_LOGS_READ, permissão diferente deBAAS_READ. Um hash demode + 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 oGET /authorization-policydevolvia oidda linha emdata.id, e quem tivesseBAAS_READeAUDIT_LOGS_READremontava o CPF em milhares de tentativas. Agoradata.idé oaccountId, tanto noGETquanto noanchor, e oidda linha não aparece em resposta nenhuma. O que protege hoje, na ordem: oidnã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 oXADDacontecesse antes do últimoUPDATE, umCOMMITque falhasse depois dele deixaria a trilha emv+1e o banco emv—divergedpermanente, e oPUT(que confere ocurrentantes) recusaria também: conta sem saída pela API. Agora grava, comita, e só então carimba otrail_message_id(informativo, best effort). Publicação que falha éROLLBACK;COMMITque falha deixa a conta emunanchored/diverged, estados já tratados — e para o único caso que sobra há a regra de repetição: umPUTcujo resultado seria exatamente o estado que a trilha já atesta (mesmoid,version + 1, mesmos campos) é aqueleCOMMITperdido 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:
- Tipos pinados. A poda preserva, para cada
(resourceType, resourceId), a linha mais nova dos tipos da lista fechada emsrc/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/verifynunca relê as sobreviventes. - O
anchorrecusa quando houve poda. A fachadalatestEventpassa a exporprunedThroughSequence(deaudit_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:409comdetails.code = POLICY_TRAIL_PRUNEDe oprunedThroughSequencede 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.
| # | Brecha | Por que funciona | O que custa fechar |
|---|---|---|---|
| BB-5b | Credencial 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 ok | deploy/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ítima | Trilha 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-5c | Publicador não autenticado. Um policy.changed forjado é encadeado e ancorado como legítimo | audit-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 é sobra | Falta 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):
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;
nullexplícito é emitido comonull; - vetores preservam a ordem;
- strings escapadas como
JSON.stringifyfaz (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 queDecimal(15,2)é recusado com400, não arredondado; operatorsnormalizados 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):
type | params |
|---|---|
pix.transfer | amount, description?, pixKey?, recipient? (name, documentNumber, bankCode, branchNumber, accountNumber, accountType), scheduledFor? |
ted.transfer | amount, description?, recipient (idem + accountDigit?), scheduledFor? |
pix.refund | transactionId (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.create | keyType, keyValue? |
pix.key.delete | pixKeyId |
pix.qr.create | amount, description?, expiresInMinutes? — só o QR dinâmico; o estático não declara valor e segue aberto |
account.close | reason |
account.update | holder 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.submit | documentsHash — 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.update | mode, holderDocument (ou null), requireBiometricAbove (texto com duas casas ou null), operators |
mandate.grant | scope (ú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.revoke | mandateId — só quando o titular revoga; o admin revoga sem assinatura |
boleto.issue | amount, dueDate (YYYY-MM-DD), payerDocument (só dígitos), payerName |
boleto.write_off | boletoId (o da rota), amount (o do título — é o recebível que deixa de existir), reason? |
device.enroll | nã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:
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):
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:
ONBOARDINGnão cadastra chave de aparelho.identityProvenéfalseemONBOARDINGporque 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á:AUTHENTICATIONcasada 1:1 contra cadastro facial do próprio titular. O primeiro cadastro facial acontece antes, na jornada de abertura da conta — sessãoONBOARDINGcomenrollOnApprove: 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:
- 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 omandate.grantcanônico. Conta sem política, ou emNONE, não tem titular para assinar e responde400. 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. - 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
ACTIVEe permitido pelo modo, reverifica a evidência que o cadastrou, reconstrói omandate.granta 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 é. - 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ão400 MANDATE_UNBOUNDEDno parser e no serviço. Sem isso,scope: [boleto.write_off], limitesnull,notAfter: 2099seria 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. - 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.issueeboleto.write_off. Um mandato parapix.transferenquanto nenhuma rota de Pix aceitamandateIdseria 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. - Os limites são consumidos sob o lock da linha, antes da credencial.
consumeMandateroda numa transação:SELECT … FOR UPDATEno 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 contramaxOperations: 3produzem 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 emAmerica/Sao_Paulo. - Revogar é sempre permitido; editar não existe.
BAAS_ADMINrevoga sem assinatura, como revoga uma chave (régua descontrolada não espera); o titular revoga com ummandate.revokeassinado, 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_REVOKEDno 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:
| Ato | O que faz com o dinheiro | Portão |
|---|---|---|
hold.create | Restringe o que a automação do tenant consegue gastar | BAAS_ADMIN. Sem assinatura, sem mandato |
hold.release | Devolve poder de gasto | Máquina pela porta direta, ou pessoa por pedido decidido por OUTRA pessoa. Conta que aderiu: presença do titular ou mandato hold.release |
hold.settle | Move dinheiro para um terceiro | Má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.createnão entra emMANDATE_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 listahold.createé recusada com400.- 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 oBAAS_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:
{
"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
}
}| Campo | O que é |
|---|---|
maxAmountPerOperation | Alçada: acima disso a assinatura dele não conta (REPRESENTATIVE_LIMIT). Ausente = sem teto |
maxAmountPerDay | Soma 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 / validUntil | Vigência (procuração). Fora dela a assinatura não conta (REPRESENTATIVE_EXPIRED) |
tiers[].required | Quantas assinaturas que contam fecham a faixa. "ALL" = todos os representantes em vigor (conjunta = todos) |
requestTtlMinutes | Prazo 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 assinatype: "signing.reject"comparams: { operationHash }. - Quem conta. Aparelho
OPERATORativo 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 derequireBiometricAbove(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| ≥
requiredeminSigners ≤ |T|para cada uma? Isolada fecha sozinha dentro da faixa de 1; conjunta só junto de n. É monótono: assinar a mais nunca desfaz. Orequiredé 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.
idempotencyKeyobrigató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:
- confere que o pedido é desta conta e da versão da política em vigor;
- reconstrói o payload a partir da operação que vai executar e compara com o
operationHashassinado (SIGNING_REQUEST_MISMATCHse valor ou destino mudou, ou se a linha foi editada); - 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); - reivindica:
APPROVED → EXECUTING(ouEXECUTINGcom a vez vencida, executor morto) porupdateManycondicionado. Duas assinaturas finais simultâneas, a rota de retomada e a varredura produzem uma concessão.
| Corrida | Defesa |
|---|---|
| Duas assinaturas "finais" chegando juntas | trava 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 aparelhos | trava do representante + índice único (P2002 vira SIGNATURE_DUPLICATE) |
| Teto diário com assinaturas simultâneas em pedidos diferentes | trava do representante: a soma é lida e gravada sem ninguém no meio |
| Execuções simultâneas do mesmo pedido aprovado | reivindicação condicionada no portão (claimExecution) |
| Executor morre depois de reivindicar | vez 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_REQUIREDnum Pix que "sempre funcionou". A conta virouQUORUM: a rota direta não serve mais. Abra um pedido de assinatura.403 QUORUM_UNREACHABLEna criação. Nenhum conjunto de representantes em vigor e dentro da alçada fecha a faixa daquele valor. ConfiravalidUntildas 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 (eventofailedcomretriable: true) ou o executor caiu.POST …/executeretoma; 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 aFAILEDpor "chave já existe" — confira no banco antes de reabrir. FAILEDcomcode. 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 comPOLICY_CHANGED. Abra de novo.SIGNING_REQUEST_MISMATCHna 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 assinarattributes.payloadbyte 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_LIMITnumpolicy.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.tsnão importa nada detypes/authorization.tsem tempo de execução (o contrário importa o schema de lá); um import de valor ali deixa o schemaundefined. - 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.
| Chave | Operação | Rota |
|---|---|---|
pix.send | Transferência Pix de saída | POST /baas/pix/transfers |
ted.send | Transferência TED de saída | POST /baas/ted/transfers |
boleto.issue | Emissão de boleto registrado | POST /baas/boletos |
boleto.write_off | Baixa por instrução do beneficiário | POST /baas/boletos/:id/cancel |
hold.create | Criação de bloqueio de saldo | POST /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:
| Estado | Resposta | details.code |
|---|---|---|
on (ou chave não cadastrada) | Segue como sempre | — |
maintenance | 503, com a chave de texto do aviso que o cms resolve (maintenanceMessageKey) | CAPABILITY_MAINTENANCE |
off | 403 | CAPABILITY_OFF |
| Feature Flags não respondeu | 503 | CAPABILITY_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 flagpix.sendna 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:
- 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
accountIdchutado e a diferença entreCAPABILITY_OFFe404viraria sonda de existência de conta alheia. Conta de outra organização continua respondendo404, como no resto do §14. - 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. - Antes da credencial.
getProviderForAccountdecifra 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.
| Provedor | Verificação | Como configurar |
|---|---|---|
| Celcoin | HMAC real sobre o corpo cru, parametrizável | webhookSecret nas credenciais; opcionalmente webhookSignatureHeader (padrão x-celcoin-signature), webhookSignatureAlgorithm (sha256), webhookSignatureEncoding (hex|base64), webhookSecretEncoding (utf8|hex|base64) e webhookToleranceSeconds (300) |
| MockBank | HMAC-SHA256 sobre o corpo cru | webhookSecret nas credenciais; cabeçalho x-mockbank-signature |
| QI Tech, FitBank | Ainda sem esquema próprio | Caem 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
webhookSecretconfigurado, 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
parseWebhookPayloadda Celcoin já exigetimestamp, então o corpo seria rejeitado uma linha depois, com mensagem pior; - algoritmo restrito a
sha256esha512.md5/sha1nã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_READvê o CPF do titular ali. TrateBAAS_READcomo permissão sensível, não como leitura genérica. As rotas de autorização do titular são a exceção:GET /authorization-policyeGET /devicesdevolvem 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á
deletedAtembaas_accountsnem embaas_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.
Limitações conhecidas
Maturidade dos provedores. É a limitação mais importante e a razão do status beta.
| Provedor | Situação real, verificada no código | O que falta |
|---|---|---|
| MockBank | Implementaçã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 webhook | Nada — mas é simulador. Nunca use em produção. Banco 999 e ISPB 99999999 são fictícios |
| Celcoin | Os 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 Tech | Os 27 métodos implementados, com requisição assinada — boleto pela API bank_slip da carteira de cobrança. Testado com HTTP mockado | Verificação de assinatura de webhook não implementada. Sem evidência de homologação contra o sandbox real neste repositório |
| FitBank / Fits | Os 27 métodos implementados sobre a API RPC — boleto por GenerateBoleto, GetBoletoInById e CancelBoleto. Testado com HTTP mockado | O 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
| Item | Situação | Onde resolve |
|---|---|---|
| Consulta ao provedor pela chave do chamador | A 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 FitBank | Sem esquema próprio implementado; o que os segura é o endereço de entrega secreto | Frente por provedor, com a documentação de cada um na mão |
| Bloqueio de saldo | Criar, 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 corrigido | Especificação própria (openspec/changes/baas-escrow-holds-e-tarifas) |
Tarifas — o que o bloco NÃO faz
| Limitação | O que significa | Por quê, e o que fazer |
|---|---|---|
| O BaaS não cobra a tarifa da casa | Registrar 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 é devido | O 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 comprovante | Não existe rota que devolva transações e tarifas numa linha do tempo só, nem documento de comprovante de tarifa | A 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ência | O bloco confere que a transferência citada existe na organização. Não confere valor, destinatário, status nem que ela saiu da mesma conta | Quem 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ência | Duas 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 conta | Escolha, 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 sozinha | Quando o Pricing Engine volta, as linhas UNPRICED continuam UNPRICED. Não há varredura que reapure | Conciliaçã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 casa | Pix enviado, TED enviada e consumo de bloqueio perguntam o preço. Boleto, Pix recebido, TED recebida, mensalidade e manutenção não | A 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 casa | A 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 ela | Os 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 registro | Se 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 UNPRICED | O ú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ário | A isenção recusa token cujo sub não seja UUID. Automação com identidade que não seja de usuário não isenta | Deliberado: "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éNATIVEapenas no simulador; Celcoin, QI Tech e FitBank declaramNONE, porque nada no que está fiado das APIs deles bloqueia saldo parcial (oblock/unblockque 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 eventobaas.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. Ogapé 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 mesmogapdentro de duas janelas do alarme (2 ×BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES), ela continua explicada — é a mesma divergência contínua, já respondida. Com outrogap, 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) ficaOPENaté alguém explicar —PROVIDER_DELAYexiste para isso. No caminho de leitura só se grava quando o alarme sai, entãodetectionsconta 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 …/balancepublica no máximo umbaas.hold.divergence.detectedpor conta porBAAS_HOLD_DIVERGENCE_WINDOW_MINUTES(§13), porque é umGETque 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
spendableBalanceantes de falar com o provedor e recusam com403edetails.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. Comcustody = PROVIDERa 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_ADMINsó existe em papéis que também têmAPI_KEYS_CREATEeIAM_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 porsub = organizationId(é como oiamo 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 obaas: ele não tem porta direta de liberar nem de consumir. - Duas pessoas, não dois logins. O bloco confere que o
subde quem decide é diferente do de quem pediu. Uma pessoa com dois usuários noiampassa. E enquanto oiamnã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 responde500 HOLD_REQUEST_OUTCOME_UNKNOWNcomrequestStatus: EXECUTINGeoutcome: 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 deBAAS_HOLD_REQUEST_STUCK_MINUTES(15), lendo o razão: sem linha →FAILED(EXECUTION_INTERRUPTED); linha com motivo →FAILED; linha sem motivo e transaçãoCOMPLETED, ou liberação escriturada →EXECUTED; senão →UNRESOLVED. Até ela passar, o pedido prende o bloqueio. FAILEDeUNRESOLVEDsoltam 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 doactiveAmount, e o pedido novo só alcança o que resta.- Pedido não vence. Um
PENDINGespera para sempre. O bloqueio pode vencer antes — e aí a aprovação viraFAILEDcomHOLD_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 viraFAILED; é 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
expiresAtnão vence nunca, e essa é a forma padrão de criá-lo. A varredura só olhaACTIVEcom prazo no passado;expires_atnulo 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 aEXPIREDe 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 provedorNATIVEde 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
ESCROWnã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, umif (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ção | Impacto | Situação |
|---|---|---|
idempotencyKey ainda é OPCIONAL — e vai deixar de ser | Sem 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 idempotencyKey | Ela 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 segunda | Use 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 200 | Quem 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 nova | Escolhi 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 extrato | Nã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 janela | Nenhum 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 falha | Uma 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 provedor | O í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ório | O 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 webhook | webhook-event.repository.ts expõe findUnprocessed, e ninguém a chama. Evento marcado com error fica lá, e nada o retenta | Registrado 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 motiva | Timeout é 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 banco | O 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 passar | A 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ído | A 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 escriturado | Conta 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 provedor | Deliberado. 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 janela | A 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 webhook | Para 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 lote | A 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 corrigida | Gastá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á errado | POST /accounts/:id/holds/reconcile para perguntar agora. No caminho de leitura o aviso é represado por conta (BAAS_HOLD_DIVERGENCE_WINDOW_MINUTES) |
| Boleto acompanha por consulta | Registro, liquidação e baixa chegam pelo POST /boletos/:id/sync. Os webhooks de boleto dos bancos ainda não atualizam o título sozinhos | Próxima fase: consumir os eventos de cobrança de cada banco no recebedor de webhooks |
| Bloquear e desbloquear conta não tem rota HTTP | blockAccount e unblockAccount existem na interface e nos quatro provedores, mas nenhum router os expõe. O bloqueio só chega por webhook do provedor | Implementado na camada de provedor, não exposto |
personId não é chave estrangeira | O vínculo com Person do Customers é um UUID solto: sem validação na criação, sem integridade referencial, sem cascata | Por design de desacoplamento entre building blocks — mas o personId inválido só aparece quando alguém tenta usar |
| Agendamento sem garantia uniforme | scheduledFor é aceito e repassado, mas o comportamento é do provedor. O MockBank ignora e executa na hora | Confirme com o seu provedor antes de prometer agendamento ao cliente |
| Permissões grossas | Só BAAS_READ e BAAS_ADMIN. Quem configura provedor também transfere dinheiro | Separar exige permissões novas no vocabulário do IAM |
BAAS_READ vê CPF sem máscara nas contas | Conta e transação devolvem o documento inteiro. As rotas de autorização do titular (GET /authorization-policy, GET /devices) já mascaram | Trate 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ção | bodyLimit global. Documento em base64 estoura facilmente | Use URL do File Storage em vez de base64 |
| Sem expurgo para LGPD | Contas e transações não têm exclusão lógica nem rotina de eliminação | Eliminação é processo manual |
| Config com credencial rotacionada não tem período de graça | PATCH com credentials substitui na hora. Requisição em voo com a credencial antiga falha | Coordene a janela |
| Sem cache de saldo | Toda consulta bate no provedor. Volume alto de consulta consome quota da API do banco | Por design (§7) — mas planeje a quota |
| Estorno só de Pix recebido e completo | POST /transfers/:id/refund exige PIX_IN e COMPLETED. Não há devolução de Pix enviado nem estorno de TED | Restrição do fluxo Pix, verificada antes de chamar o provedor |
CANCELLED não é alcançável | O status existe no enum, mas nenhum caminho do código leva a ele | Reservado para status vindo do provedor |
A catraca do ResultAsync descartado é heurística de texto — e estas classes ela NÃO pega | Ela 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/baas | Ela 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ância | O 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 é uuidv4 | E 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 processo | O 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 DICT | Aceitá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 mandato | Numa 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 contas | Deliberado: 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 tenant | Na 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ça | Nã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 boleto | scope aceita apenas boleto.issue e boleto.write_off. Pix, TED e o resto continuam exigindo presença na conta que aderiu | O 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 sucesso | Baixa 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 efetivas | Direçã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 contagem | Ré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 alonga | Decisã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 grantAttestation | A 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 trilha | O 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 trava | POST /pix/qr-codes/generate sem amount segue livre mesmo na conta que aderiu | Um 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-s | A mesma assinatura pode ser reapresentada na outra codificação, ou com s complementado, e continua válida para o mesmo payload | Decisã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 assinatura | Quem tem o token pode revogar todos os aparelhos da conta e travá-la: nenhuma escrita gated passa mais | Nã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 responder | Desde 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 processo | Falha 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 ancorada | Linha sem policy.changed na trilha é unanchored → 403 POLICY_INTEGRITY, e o PUT também é recusado. Vale para produção no dia do deploy | Rode 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 consumidor | Uma 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ência | Nã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 é populada | O 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_INTEGRITY | Correto 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 API | A 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 audita | deploy/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 publicador | audit-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 trava | Resolvido 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 linha | Defesa 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 sandbox | Config 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 Biometrics | Sem fachada registrada, conta com política responde 503 e não opera | Falha 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évio | POST /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 nenhum | Decisã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 biometria | Sem 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 provedor | Resolvido 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ção | A 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ência | Situação no código |
|---|---|
| Art. 6º — exclusividade por tipo de conta | Nada 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 autorizada | Nã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ção | Impacto | Situação |
|---|---|---|
| Desligar exige cadastrar a chave | Chave 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 paga | Por 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 guardadas | Pix, 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 existia | Por 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ção | Sem 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 dele | Aceito — 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 guardadas | Chave 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 Pix | Escopo 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. ComPROVIDER, 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 issoHOLD_EXCEEDS_BALANCEnã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
ADVANCEfica ativo; o mandato da trava só cobrehold.settlee 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.
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:
- Uma conta por operação.
POST /accountsabre uma conta de verdade no provedor licenciado. Você manda obusinessIdda sua operação e opurpose(ESCROW,COLLATERAL,SETTLEMENT); depois acha a conta porfilter[purpose]. Nada impede abrir uma conta por contrato, por lastro ou por cedente — é o que a esteira de crédito faz. - Bloqueio de saldo amarrado a uma razão.
POST /accounts/:id/holdstrava um valor comreasonType(LOAN,ADVANCE,COLLATERAL,GENERIC), texto livre,externalReference— o id da operação, por onde a esteira reencontra os bloqueios dela — eexpiresAt. Cada ato vira uma linha de razão que nunca é reescrita, com quem fez e por qual porta (titular presente, mandato ou admin). - 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
baasgasta 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