# BIAN na prática: como um banco funciona por dentro

> O mapa de serviços do BIAN 14 aplicado ao dia a dia do arquiteto: domínios, Control Records, Semantic APIs, Pix e Open Finance no mapa, heatmap de sistemas e IA para mapear com precisão.

_Curso gratuito de Fernando F. Azevedo · 9 aulas · ~3h_

## O que você vai saber fazer

- Ler o Service Landscape do BIAN 14 e explicar camadas, Control Record e Behavior Qualifier.
- Reconhecer padrões funcionais e action terms e ler uma Semantic API até o OpenAPI.
- Posicionar Pix, Open Finance e a regulação brasileira no mapa.
- Montar um heatmap de sistemas e desenhar fronteiras de serviço e de evento.
- Usar IA com grounding nas definições oficiais para mapear e revisar contratos, com validação e avaliação.

## Módulo 1: O mapa

O que é o BIAN, as camadas do landscape, Control Record, padrões funcionais e action terms.

### 01. O que é o BIAN, e o que ele não é

_Quem mantém, o que entrega e por que não é produto nem especificação de implementação._

Dois times do mesmo banco chamam a mesma coisa por nomes diferentes: um fala em 'cadastro', outro em 'onboarding', o fornecedor fala em 'party management'. Nenhum está errado, e a integração entre os três custa meses. O BIAN existe para resolver esse problema de vocabulário, e só ele. Esta aula diz quem mantém o padrão, o que ele entrega e, com a mesma ênfase, o que ele não é.

## O problema que o BIAN resolve

Pense num banco com dez anos de aquisições nas costas. O core chama a abertura de conta de 'cadastro'. O canal digital chama de 'onboarding'. O antifraude, comprado de fora, chama de 'customer due diligence'. O time de dados chama de 'party'. São quatro nomes para uma capacidade só, e cada integração começa com uma reunião para descobrir isso.

O custo aparece em três lugares.

**Integração:** cada par de sistemas negocia o próprio contrato, com o próprio dicionário, e o mapeamento entre eles vira código que alguém mantém por anos.

**Compra de software:** o RFP descreve a necessidade com palavras internas, o fornecedor responde com as dele, e a comparação entre propostas é feita no olho.

**Decisão de arquitetura:** sem um inventário de capacidades, 'temos isso duplicado?' é uma pergunta que ninguém responde sem entrevistar meia dúzia de pessoas.

O BIAN ataca a raiz: um vocabulário de capacidades bancárias mantido fora de qualquer banco e de qualquer fornecedor. Quando dois times dizem 'Party Reference Data Directory', estão falando da mesma coisa, com a mesma fronteira. Para quem programa, a analogia é uma `interface` compartilhada: ela não implementa nada, mas obriga quem implementa a concordar nos nomes.

## Quem mantém e o que entrega

O BIAN e.V. é uma associação independente e sem fins lucrativos, sediada em Frankfurt. São 113 membros: 40 bancos, 59 parceiros de software e o restante entre consultorias e instituições. Isso importa porque o padrão não pertence a um fornecedor: nenhum deles ganha quando você adota o vocabulário.

A versão corrente é a 14.0, de fevereiro de 2026. Ela traz três entregas, e cada uma serve a uma tarefa diferente do seu dia.

**Service Landscape:** o mapa. Cerca de 340 Service Domains ativos, cada um uma capacidade de negócio com fronteira definida, desenhados em ArchiMate 3.2. É o que você abre para responder 'quais capacidades este sistema cobre?' e 'onde termina Payment Order Initiation e começa Payment Settlement?'. Serve para heatmap, inventário e conversa com produto.

**Semantic APIs:** 242 contratos, com operações e payloads nomeados por Service Domain. Servem de ponto de partida para o contrato de um serviço e de língua comum com o fornecedor. O próprio BIAN avisa que os endpoints estão 'far from implementation specifications'.

**Business Object Model:** os objetos de negócio, em UML, que as APIs compartilham. É a entrega com ligação crescente com a ISO 20022, o que interessa a quem lida com mensagens de pagamento.

Há três certificações: Foundation, Banking Architecture e Data Architecture. O curso não substitui nenhuma, mas deixa você pronto para a primeira.

## As três entregas do BIAN e quem consome cada uma

O mesmo problema (uma capacidade, vários nomes) entra pelo mapa e sai como heatmap, contrato e RFP com vocabulário comum.

### 📘 BIAN e.V. (Frankfurt): três entregas da v14.0

- Service Landscape ~340 Service Domains, ArchiMate 3.2 (data)
- Semantic APIs 242 contratos, longe de implementação (compute)
- Business Object Model UML, ligação com ISO 20022 (storage)

### 👤 Quem consome

- Arquiteto mapeia e decide fronteiras (security)
- Time de produto nomeia a capacidade (frontend)
- Fornecedor alinha módulo e contrato (external)

### 📤 O que sai do mapa

- Heatmap de sistemas aula 07 (ai)
- Contrato OpenAPI aula 04 (compute)
- RFP e compra vocabulário comum (messaging)

### Fluxos

- banco -> sl: nomeia a capacidade uma vez
- sl -> api: um ou mais contratos por domínio
- bom -> api: objetos e campos compartilhados
- sl -> arq: fronteiras e inventário
- sl -> prod: nome comum da capacidade
- api -> forn: semântica do contrato
- api -> arq: ponto de partida, não produção
- arq -> heat: sistema x Service Domain
- arq -> contrato: acrescenta auth, erros, versão
- forn -> rfp: responde nas mesmas caixas
- prod -> rfp: pede nas mesmas caixas

### Vocabulário do BIAN

- **Service Landscape**: O mapa de todas as capacidades de um banco, organizado em áreas, domínios de negócio e Service Domains.
- **Service Domain**: Uma capacidade de negócio com responsabilidade única, como Current Account ou Fraud Evaluation.
- **Semantic API**: A descrição das operações de um Service Domain, publicada também em OpenAPI, ainda longe de especificação de implementação.
- **Business Object Model**: O modelo de objetos de negócio que dá forma aos dados trocados pelas APIs.
- **ArchiMate 3.2**: A linguagem de modelagem usada no landscape; o detalhe usa UML.

## O que o BIAN não é

Boa parte dos projetos de BIAN que dão errado começa com uma destas três confusões.

**Não é produto.** Não existe 'instalar o BIAN'. Um fornecedor pode vender um core cujos módulos foram nomeados segundo o landscape, o que ajuda, mas o trabalho de ler o seu banco contra o mapa continua sendo seu.

**Não é arquitetura de referência para copiar.** Os cerca de 340 Service Domains são uma decomposição funcional, não um desenho de deployment. Transformar cada domínio em um microsserviço é o erro mais caro que já vi: centenas de serviços pequenos com fronteiras que o negócio nunca pediu e um plantão que ninguém consegue cobrir. O mapa diz o que o banco faz; quantos serviços você constrói, e em que agrupamento, é decisão sua, com os seus volumes e o seu time.

**Não é especificação pronta de API.** As Semantic APIs definem semântica: nome da operação, objetos de entrada e saída. Não definem autenticação, versionamento, paginação, erros, idempotência nem limites de taxa. Quem publica a Semantic API direto como OpenAPI de produção descobre isso no primeiro incidente.

Guarde a frase do próprio BIAN sobre os endpoints: 'far from implementation specifications'. Quem escreveu o padrão não quer que você o copie. Quer que você o leia.

> **Na prática:** Na prática, uso o BIAN como uso um mapa de metrô: para saber onde estou, onde a linha termina e quais estações já existem antes de propor uma nova. O trajeto, o horário e o trem continuam sendo decisão de quem opera. Quando alguém me apresenta uma 'arquitetura alvo baseada em BIAN' com um serviço por domínio, a primeira pergunta que faço é quem acorda às 2h quando trezentos serviços falham em cascata.

## Como este curso usa o BIAN

Este curso trata o BIAN como instrumento de leitura e decisão, não como planta. Você vai usar o mapa para três coisas.

**Entender o banco:** nomear o que cada sistema faz com um vocabulário que outro arquiteto, em outro banco, reconhece. É a base do heatmap da aula 07.

**Decidir fronteiras:** quando um domínio vira um serviço, quando dois domínios moram no mesmo sistema e quando um legado cobre cinco domínios de uma vez. A aula 02 traz o Control Record, a unidade que torna essa decisão objetiva.

**Conversar com fornecedor e regulador:** Pix, Open Finance, SCR e LGPD entram no mapa nas aulas 05 e 06, para que a conversa com o Banco Central e com o fornecedor use as mesmas caixas.

Na reta final, as aulas 08 e 09 mostram o jeito IA Builder de trabalhar: a IA rascunha mapeamento e contrato com grounding nas definições oficiais, o humano decide, e tudo é medido. Nada disso funciona se a aula de hoje não ficou clara: o modelo só rascunha bem quando o vocabulário é compartilhado e estável, e é exatamente isso que o BIAN entrega.

### Checagem rápida

1. **Qual afirmação descreve melhor o BIAN?**
- [x] Um vocabulário e mapa padrão de capacidades bancárias, mantido por uma associação sem fins lucrativos, _É um padrão de referência; a implementação continua sendo sua._
- [ ] Um core bancário open source pronto para implantar, _O BIAN não entrega software._
- [ ] Uma norma do Banco Central do Brasil, _É uma associação da indústria, sem poder regulatório._
- [ ] Uma especificação de API pronta para produção, _O próprio BIAN diz que os endpoints estão longe de especificação de implementação._

## O que levar desta aula

- BIAN e.V. é associação independente e sem fins lucrativos em Frankfurt, com 113 membros (40 bancos, 59 parceiros de software). O vocabulário não pertence a nenhum fornecedor.
- Três entregas na v14.0 (fevereiro de 2026): Service Landscape com cerca de 340 Service Domains em ArchiMate 3.2, 242 Semantic APIs e o Business Object Model em UML, com ligação crescente com a ISO 20022.
- O BIAN não é produto, não é arquitetura de referência para copiar e não é especificação pronta de API. Os próprios endpoints estão 'far from implementation specifications'.
- Neste curso o mapa serve para entender o banco, decidir fronteiras e conversar com fornecedor e regulador. Um domínio não é, por padrão, um serviço.

### 02. Camadas do mapa e Control Record

_Ler o landscape de cima a baixo e entender o registro que cada domínio controla._

Abrir o Service Landscape do BIAN pela primeira vez é como abrir o mapa de metrô de uma cidade que você não conhece: centenas de caixas, duas versões do mesmo mapa e nenhuma legenda óbvia. A boa notícia é que o mapa tem só seis camadas, e dá para atravessar todas com um único exemplo: a conta corrente. Nesta aula você desce do topo até a operação de serviço e descobre por que a camada do meio, o Control Record, é a que mais responde pergunta de arquiteto.

## Seis camadas, uma conta corrente

Pense no landscape como um namespace de seis níveis. Cada nível restringe o anterior, e o exemplo da conta corrente cabe inteiro nele.

**Business Area:** a fatia mais larga do banco. Conta corrente vive em Operations and Execution, a área que executa produtos e transações no dia a dia.

**Business Domain:** um agrupamento dentro da área. Aqui é Loans and Deposits, onde moram os produtos de captação e crédito.

**Service Domain:** a unidade que importa. Current Account é um Service Domain: uma capacidade de negócio com responsabilidade única, que não se divide mais. É o nível em que você faz heatmap, atribui dono e desenha fronteira de API.

**Control Record:** o registro que o domínio controla. Para Current Account é `CurrentAccountFacility`, a conta em si com tudo que ela guarda e decide.

**Behavior Qualifier:** uma fatia do Control Record. `AmountBlock` é a fatia que trata bloqueio de valor na conta; `DebitandCredit` é a que trata lançamentos.

**Service Operation:** a ação executável sobre uma fatia. `InitiateAmountBlock` cria um bloqueio. É o que vira endpoint na Semantic API.

Se você programa, a analogia que funciona é pacote, módulo, classe, estado, atributo composto e método. Não é perfeita, mas acerta no essencial: a hierarquia não é organograma, é escopo. Cada nível responde onde uma coisa mora, e só isso. A aula 03 trata os action terms, como o `Initiate` de `InitiateAmountBlock`; aqui o objetivo é ler o caminho inteiro sem se perder.

## A pirâmide de camadas, com a conta corrente em cada nível

Do mais amplo ao mais específico. A value chain é outra estante para o mesmo Service Domain: do Current Account para baixo, nada muda.

### 🏦 Business Area (matriz: 5 áreas)

- Operations and Execution (network)

### 📂 Business Domain (matriz: 38)

- Loans and Deposits (network)

### 🧩 Service Domain

- Current Account padrão Fulfill (compute)

### 📋 Control Record

- CurrentAccountFacility Current Account + Fulfill (data)

### 🔀 Behavior Qualifiers (9 na v14, MECE)

- DebitandCredit (storage)
- AmountBlock (storage)
- +7 outros +7 others (storage)

### ⚙️ Service Operation

- InitiateAmountBlock (frontend)
- Semantic API endpoint (aula 04) (edge)

### Fluxos

- ba -> bd: contém
- bd -> sd: contém
- vc -> sd: mesmo Service Domain, outra estante
- sd -> cr: controla o ciclo de vida
- cr -> bq1: fatia
- cr -> bq2: fatia
- cr -> bq3: fatia
- bq2 -> op: expõe
- op -> api: vira endpoint

## Duas visões, os mesmos Service Domains

O BIAN publica o landscape em duas visões, e a primeira confusão de todo mundo é achar que são dois mapas. São duas estantes para os mesmos livros.

**Matriz:** cinco Business Areas (Reference Data, Sales and Service, Operations and Execution, Risk and Compliance, Business Support) e 38 Business Domains. É a visão de capacidade: agrupa pelo tipo de coisa que o domínio faz, independentemente de quem usa.

**Value chain:** oito áreas, organizadas pela sequência em que o valor é produzido. É a visão de processo: responde 'em que ponto da cadeia isso acontece'.

Current Account é o mesmo Service Domain nas duas, com o mesmo Control Record e os mesmos Behavior Qualifiers. Muda só a prateleira em que ele aparece.

Por que manter as duas? Porque arquiteto e negócio fazem perguntas diferentes. Quando eu faço heatmap de sistemas, uso a matriz: quero saber quais capacidades estão cobertas, duplicadas ou órfãs, e o agrupamento por tipo deixa isso visível. Quando preciso explicar para uma área de produto onde entra a parte dela, a value chain fala a língua do fluxo.

A regra prática: escolha uma visão por entregável e diga qual é no cabeçalho. Misturar as duas no mesmo desenho é a forma mais comum de produzir um mapa que ninguém contesta porque ninguém consegue ler.

## Control Record: o que o domínio guarda e decide

Se eu pudesse ensinar só um conceito do BIAN para um time, seria este.

Todo Service Domain segue um padrão funcional (a aula 03 lista os padrões). Current Account segue o padrão Fulfill: ele cumpre um produto contratado. O Control Record é o resultado de aplicar esse padrão a um tipo de ativo. Current Account + Fulfill = `CurrentAccountFacility`: a conta corrente como instância viva, com saldo, lançamentos, bloqueios e tudo que o domínio precisa acompanhar para cumprir o produto.

Pense nele como o agregado raiz do domínio, no sentido de DDD. É o registro cujo ciclo de vida o Service Domain controla do começo ao fim. Ninguém mais cria, altera ou encerra uma `CurrentAccountFacility` sem passar por Current Account.

É por isso que o Control Record responde a pergunta que mais trava reunião de arquitetura: quem é dono desse dado? Se o dado faz parte do Control Record de um domínio, aquele domínio é a fonte da verdade. Os outros consultam ou recebem evento. Quando dois sistemas gravam saldo de conta cada um do seu jeito, não é problema de integração, é dois donos para um Control Record.

Os Behavior Qualifiers dividem o Control Record em fatias MECE: mutuamente exclusivas e coletivamente exaustivas. Nada cai em duas fatias e nada fica de fora. Current Account tem nove na v14; `DebitandCredit` e `AmountBlock` são duas delas. Na hora de mapear um sistema legado, essa divisão vira checklist: cada fatia que o sistema não cobre é lacuna explícita, não suposição.

### Do mais amplo ao mais específico

Ordene as camadas do mapa usando o exemplo da conta corrente.

1. Operations and Execution (Business Area)
2. Loans and Deposits (Business Domain)
3. Current Account (Service Domain)
4. CurrentAccountFacility (Control Record)
5. AmountBlock (Behavior Qualifier)
6. InitiateAmountBlock (Service Operation)

## O que levar desta aula

- Seis camadas, do mais amplo ao mais específico: Business Area, Business Domain, Service Domain, Control Record, Behavior Qualifier, Service Operation.
- Matriz (5 áreas, 38 Business Domains) e value chain (8 áreas) organizam os mesmos Service Domains. Uma visão por entregável.
- Control Record = padrão funcional aplicado a um tipo de ativo. Current Account + Fulfill = CurrentAccountFacility.
- Dono do dado é o domínio cujo Control Record contém o dado. Todo o resto consulta ou recebe evento.

> **Na prática:** Na prática, eu começo todo mapeamento pelo Control Record, não pelo nome do Service Domain. Nome engana: dois times chamam de 'conta' coisas diferentes. Quando eu pergunto 'qual registro esse sistema cria, altera e encerra sozinho?', a resposta aponta o Service Domain certo em minutos, e a lista de Behavior Qualifiers diz na hora o que ele cobre e o que ele só consulta de outro lugar. Mapeamento que pula o Control Record costuma virar inventário de sistemas com rótulo BIAN colado por cima.

### Checagem rápida

1. **O que forma o Control Record de um Service Domain?**
- [x] O padrão funcional aplicado a um tipo de ativo, _Fulfill + Current Account = CurrentAccountFacility._
- [ ] A tabela principal do sistema legado, _Control Record é conceito de negócio, não de banco de dados._
- [ ] O conjunto de endpoints REST do domínio, _Endpoints operam sobre o Control Record, não o definem._
- [ ] A soma dos Behavior Qualifiers, _Os qualifiers dividem o Control Record, não o criam._

## Perguntas frequentes

### Service Domain e Control Record são a mesma coisa com dois nomes?

Não. O Service Domain é a capacidade (quem faz); o Control Record é o registro que ela controla (o que ela guarda e decide). Current Account é o domínio, CurrentAccountFacility é o registro.

### A hierarquia muda entre a matriz e a value chain?

Mudam as camadas acima do Service Domain, que é onde cada visão agrupa do seu jeito. Do Service Domain para baixo (Control Record, Behavior Qualifier, Service Operation) é idêntico nas duas.

### Posso criar um Behavior Qualifier novo para o meu banco?

Pode estender, mas antes verifique se a necessidade não cabe numa das fatias existentes. Como a divisão é MECE, um qualifier novo que sobrepõe outro quebra a regra e a interoperabilidade com quem segue o padrão. Trate extensão como exceção documentada.

### 03. Padrões funcionais e action terms

_Os 19 padrões com uma analogia do cotidiano para cada um, e os 17 verbos das operações._

Na aula anterior o Control Record ficou claro: é o objeto que um Service Domain cuida do começo ao fim. Falta a pergunta seguinte: cuida como? É isso que o padrão funcional responde em uma palavra, e é por isso que, quando abro um domínio novo, o padrão é a primeira coisa que leio. Esta aula apresenta os 19 padrões, com uma analogia do cotidiano para cada um, e os 17 verbos que aparecem em toda operação do BIAN.

## O padrão é a pista mais rápida

Um Service Domain tem nome, Control Record, operações e atributos. Dá para ler tudo isso e ainda não saber como ele se comporta. O padrão funcional resolve isso em uma palavra: ele diz qual é o ciclo de vida do Control Record. Se nasce e morre numa transação, se acumula por anos, se emite um veredito e encerra.

Pense no padrão como a classe base de que o domínio herda. Duas classes com a mesma base têm o mesmo esqueleto de operações, mesmo que uma trate de cartão e a outra de câmbio. É isso que torna o BIAN previsível para quem programa: dominou o esqueleto de Fulfill, entende qualquer domínio Fulfill em metade do tempo.

Três padrões confundem quem começa porque parecem a mesma coisa, "olhar dados". Não são. **Track** acumula lançamentos ao longo do tempo e mantém uma posição, como um extrato. **Assess** dá um veredito pontual sobre um caso e pronto, como um detector de metais. **Analyse** lê o histórico inteiro e devolve uma leitura, como a nutricionista com o diário alimentar na mão.

Se o seu sistema de fraude tem uma pontuação recalculada a cada evento e um perfil revisto por mês, você tem dois padrões diferentes e, quase sempre, dois domínios. Separar isso antes de desenhar a API poupa a refatoração que viria depois.

## Os 19 padrões funcionais, um por linha
| Padrão | Analogia do cotidiano | O que o Control Record faz |
| --- | --- | --- |
| Fulfill | Plano de academia | Cumpre um acordo ao longo do tempo até encerrar |
| Transact | Compra no caixa | Uma transação curta: começa, conclui, acaba |
| Track | Extrato | Acumula lançamentos e mantém a posição |
| Process | Emissão de fatura | Executa um procedimento em etapas até sair o resultado |
| Agree Terms | Contrato de aluguel | Negocia e mantém os termos vigentes |
| Catalog | Agenda de contatos | Mantém uma lista de referência consultável |
| Assess | Detector de metais | Avalia um caso e emite veredito pontual |
| Analyse | Nutricionista lendo o histórico | Lê o histórico e devolve uma leitura |
| Monitor | Termômetro | Observa um sinal contínuo e alerta no desvio |
| Operate | Catraca | Opera um recurso em uso contínuo |

## Quando o padrão muda, o domínio muda

O padrão não é rótulo decorativo. Ele define que operações existem e que estado o Control Record carrega. Por isso trocar o padrão é uma mudança real, não cosmética.

Na v14 alguns domínios mudaram de padrão. O exemplo mais limpo é **Legal Advisory**, que saiu de Fulfill para Advise. A leitura é direta: antes o domínio era modelado como quem cumpre um acordo de prestação de serviço jurídico, agora é modelado como quem responde a uma consulta. O Control Record deixa de ser um arranjo de serviço e passa a ser uma sessão de aconselhamento, e as operações seguem essa troca.

No mapeamento isso tem um uso prático. Quando um sistema seu "não cabe" no domínio que parecia óbvio, teste o padrão antes de inventar domínio novo. Pergunte: o que o meu sistema guarda, acumula, encerra ou emite? Se acumula, procure um Track. Se emite veredito, um Assess. Se mantém um acordo vivo, um Fulfill ou um Agree Terms. Na maioria das vezes o domínio aparece, e o que parecia lacuna era só padrão errado.

Vale também para avaliar o que uma IA propõe: um mapeamento que coloca um sistema de posição de saldo num domínio Assess está errado pelo padrão, antes de qualquer discussão sobre nome. A aula 08 volta a isso com grounding nas definições oficiais.

> **Na prática:** Quando recebo um inventário de sistemas para mapear, a primeira coluna que preencho é o padrão, não o domínio. Padrão se decide olhando o banco de dados do sistema: tabela que só cresce é Track, tabela de casos com status final é Assess, tabela de contratos com vigência é Agree Terms ou Fulfill. Com o padrão certo, a lista de domínios candidatos cai de dezenas para um punhado, e a discussão com o time vira "qual destes" em vez de "onde isso entra".

### Domínio e padrão funcional (v14)

- **Current Account** → Fulfill
- **Payment Order Initiation** → Transact
- **Position Keeping** → Track
- **Fraud Evaluation** → Assess
- **Fraud Diagnosis** → Analyse
- **Payment Rail** → Operate
- **Issued Device Administration** → Allocate
- **Customer Billing** → Process
- **Party Reference Data Directory** → Catalog
- **Customer Agreement** → Agree Terms

## Os 17 action terms em quatro famílias

Toda operação de um Service Domain é um action term aplicado a uma parte do Control Record: `Initiate` abre, `Update` altera, `Retrieve` lê. São 17 verbos, organizados em quatro famílias conforme o que tocam.

**Governar o domínio:** `Activate`, `Configure` e `Feedback`. Não mexem em registro nenhum. Ligam o domínio, ajustam parâmetros e recebem retorno sobre o serviço. É o painel de administração, não a transação.

**Criar registro:** `Initiate`, `Create`, `Register`, `Evaluate` e `Provide`. Cada um abre uma instância nova do Control Record. O verbo muda com o padrão: um domínio Fulfill inicia, um Catalog registra, um Assess avalia. Mesmo efeito, nasce um registro, verbo escolhido pelo ciclo de vida.

**Agir sobre registro:** `Update`, `Control`, `Exchange`, `Capture`, `Execute`, `Request` e `Grant`. Alteram um registro que já existe. `Control` suspende e retoma, `Exchange` aceita ou rejeita, `Capture` grava um evento vindo de fora, `Execute` roda uma etapa, `Request` pede uma ação, `Grant` concede.

**Ler sem alterar:** `Retrieve` e `Notify`. Devolvem estado ou avisam que algo mudou, sem mudar nada. O guia do BIAN cita CQRS ao separar leitura de escrita; para quem já separa command de query, é a mesma ideia levada à borda do serviço. Na implementação isso significa que `Retrieve` pode ser servido pela réplica de leitura e os outros quinze ficam no caminho transacional. Decidir isso cedo evita que a API de consulta herde o lock da API de escrita.

## Quatro famílias de action terms em volta do Control Record

Três verbos governam o domínio sem tocar em registro; cinco criam uma instância; sete alteram uma instância existente; dois leem ou avisam sem alterar nada, o lado de consulta do CQRS.

### ⚙️ Governar o domínio

- Activate · Configure · Feedback liga e parametriza o serviço (security)

### 🏦 Service Domain

- Configuração do domínio parâmetros do serviço (compute)
- Control Record instância com ciclo de vida do padrão (data)

### 🆕 Criar registro

- Initiate · Create · Register Evaluate · Provide (compute)

### ✏️ Agir sobre registro

- Update · Control · Exchange Capture (messaging)
- Execute · Request · Grant altera estado existente (messaging)

### 🔎 Ler sem alterar

- Retrieve devolve o estado atual (data)
- Notify avisa que algo mudou (data)

### Fluxos

- consumer -> govern: administração
- govern -> domain: ajusta o serviço, não o registro
- consumer -> create: abre uma instância
- create -> cr: nasce o registro
- consumer -> act-a: altera
- consumer -> act-b: altera
- act-a -> cr: muda estado
- act-b -> cr: muda estado
- cr -> retrieve: leitura, pode vir da réplica
- cr -> notify: evento de mudança
- retrieve -> consumer: estado
- notify -> consumer: aviso

## O que levar desta aula

- O padrão funcional é o ciclo de vida do Control Record em uma palavra: leia-o antes do nome do domínio.
- Track acumula, Assess dá veredito pontual, Analyse lê o histórico. Parecem iguais e são três padrões diferentes.
- Troca de padrão é mudança real: Legal Advisory saiu de Fulfill para Advise na v14 e o Control Record mudou junto.
- Os 17 action terms se dividem em governar o domínio, criar registro, agir sobre registro e ler sem alterar.
- Retrieve e Notify são o lado de consulta; o guia do BIAN cita CQRS, e isso autoriza réplica de leitura desde o desenho.

### Action terms por família

- **Governar o domínio**: Activate, Configure, Feedback
- **Criar um registro**: Initiate, Create, Register, Evaluate, Provide
- **Agir sobre um registro**: Update, Control, Exchange, Capture, Execute, Request, Grant
- **Ler sem alterar**: Retrieve, Notify

## Perguntas que aparecem nesta altura

### Todo Service Domain expõe os 17 verbos?

Não. Cada padrão usa o subconjunto que faz sentido para o seu ciclo de vida: um Catalog registra e consulta, um Fulfill inicia, atualiza, controla e consulta. A lista exata por padrão não é tema desta aula; na aula 04 você vê isso lendo um domínio até o OpenAPI.

### Posso criar um action term próprio quando nenhum dos 17 serve?

Quase sempre o verbo que falta é um dos 17 mal escolhido, ou um sinal de que a operação pertence a outro domínio. Antes de inventar, pergunte se você está criando, alterando ou lendo um registro e se o registro é mesmo deste Control Record. Verbo fora do vocabulário quebra a previsibilidade que é o motivo de usar BIAN.

## Módulo 2: Do domínio à regulação

Da Semantic API ao OpenAPI, o Pix no mapa e a regulação brasileira no lugar certo.

### 04. Lendo um Service Domain até o OpenAPI

_O caminho de cada endpoint, o mapeamento para HTTP e o que fica para a sua implementação._

Abrir um YAML do BIAN pela primeira vez dá a sensação de que a API já está pronta: caminho, método, schema, tudo ali. Não está. O que o BIAN publica é o contrato semântico; quem decide autenticação, idempotência, versão e modelo de erro é você. Esta aula ensina a ler um Service Domain até o OpenAPI sabendo exatamente onde a especificação termina e onde a sua implementação começa.

## A anatomia do caminho

Todo endpoint dos YAMLs da v14 tem a mesma forma:

`/{ServiceDomain}/{crId}/{BehaviorQualifier}/{bqId}/{ActionTerm}`

Cada segmento aponta para uma camada do mapa que você viu na aula 02. O primeiro é o Service Domain. O segundo identifica uma instância do Control Record. O terceiro é o Behavior Qualifier, a parte do Control Record que a operação toca. O quarto identifica uma instância desse qualifier. O quinto é o action term da aula 03: o verbo.

Pegue o Current Account na v14 como referência. Ele segue o padrão funcional Fulfill, o Control Record se chama `CurrentAccountFacility`, a especificação lista 34 operações e 9 Behavior Qualifiers, e o nome proposto no alinhamento com ISO 20022 é `CashAccountService`. Quando você lê `/CurrentAccount/{id}/...`, está lendo: um domínio, uma conta, uma faceta dessa conta, um evento nessa faceta, uma ação.

**O que o caminho não carrega:** tenant, canal, versão, ambiente. Nada disso está no YAML, e é de propósito. O BIAN descreve o que o banco faz, não como a sua empresa publica isso. Guarde essa frase: ela explica tudo o que vem no fim da aula.

A leitura que recomendo: trate o caminho como o mapa dobrado numa URL. Se um segmento não corresponde a uma camada do mapa, ou você leu errado ou alguém inventou um segmento.

## Cada segmento do caminho aponta para uma camada do mapa

Exemplo real da v14: PUT /CurrentAccount/{crId}/DebitandCredit/{bqId}/Execute. Os cinco segmentos vêm do BIAN; o que está no grupo de baixo é responsabilidade sua.

### 🔗 URL: os cinco segmentos

- /CurrentAccount (edge)
- /{crId} uma conta (edge)
- /DebitandCredit (edge)
- /{bqId} um movimento (edge)
- /Execute (edge)

### 🗺️ BIAN: camadas do mapa

- Service Domain Current Account (Fulfill) (compute)
- Control Record CurrentAccountFacility (data)
- Behavior Qualifier 1 de 9 (data)
- Action Term Execute (messaging)

### 🧩 Sua implementação

- Método HTTP YAML v14: PUT (frontend)
- Auth, Idempotency-Key, versão, erro, SLO (security)

### Fluxos

- seg-sd -> sd: nomeia
- seg-cr -> cr: instância
- seg-bq -> bq: faceta do CR
- seg-bqid -> bq: instância
- seg-at -> at: verbo
- at -> http: mapeamento fixo
- http -> yours: BIAN não decide

## Lendo /CurrentAccount/{id}/DebitandCredit/{id}/Execute segmento a segmento

1. **/CurrentAccount**: O Service Domain. Padrão Fulfill: ele cumpre um produto já contratado. Na leitura DDD, é o bounded context candidato.

2. **/{id} (primeiro)**: O crId: uma instância de CurrentAccountFacility, ou seja, uma conta específica. Tudo depois deste segmento acontece dentro dessa conta.

3. **/DebitandCredit**: O Behavior Qualifier, um dos 9 do Current Account. É a faceta do Control Record que trata lançamentos de débito e crédito.

4. **/{id} (segundo)**: O bqId: um lançamento específico dentro daquela conta. Não é um agregado próprio; vive dentro do Control Record.

5. **/Execute**: O action term. Nos YAMLs da v14 vira PUT. Executar um lançamento é a ação que move dinheiro, e é exatamente aqui que idempotência deixa de ser detalhe.

## Do action term ao método HTTP, e os quatro sabores

O mapeamento nos YAMLs da v14 é fixo e vale a pena decorar: **Retrieve vira GET**, **Initiate vira POST**, e **Update, Execute e Exchange viram PUT**. A lógica é a do HTTP: Initiate cria uma instância (POST), Retrieve lê (GET), e os três últimos agem sobre uma instância que o caminho já identifica (PUT).

Essa escolha tem uma consequência que o YAML não discute. PUT, pela semântica do HTTP, é idempotente: repetir a chamada deveria dar o mesmo resultado. Um Execute de débito repetido não é naturalmente idempotente. Então o BIAN entrega um método que promete idempotência e você precisa cumprir a promessa, com chave de idempotência e armazenamento do resultado. Isso volta no bloco final.

**Os quatro sabores de publicação.** A mesma semântica sai em quatro formas: REST ou assíncrona, cada uma com o Business Object Model do próprio BIAN ou com mensagens ISO 20022. São dois eixos, não quatro padrões diferentes. O que muda é o transporte e o vocabulário dos payloads; o que não muda é o Service Domain, o Control Record e o action term.

Minha regra: REST com Business Object Model quando a API é interna e consumida por times de produto; ISO 20022 quando a mensagem atravessa a fronteira do banco para trilho ou parceiro, que é o caso do Pix na aula 05. Assíncrono quando a operação não cabe no tempo de uma requisição ou quando o consumidor precisa de evento, não de resposta.

### Leia o caminho

1. **Em /CurrentAccount/{id}/DebitandCredit/{id}/Execute, o que é DebitandCredit?**
- [x] Um Behavior Qualifier do Control Record da conta, _Fica entre o id do Control Record e o id do qualifier._
- [ ] Um Service Domain, _O Service Domain é CurrentAccount, o primeiro segmento._
- [ ] Um action term, _O action term é Execute, o último segmento._
- [ ] Um padrão funcional, _O padrão (Fulfill) não aparece no caminho._

2. **Que método HTTP o Execute usa nos YAMLs v14?**
- [x] PUT, _Update, Execute e Exchange viram PUT._
- [ ] GET, _GET é do Retrieve._
- [ ] POST, _POST é do Initiate._
- [ ] DELETE, _Não é o mapeamento usado pelo BIAN para Execute._

## Action term x método HTTP nos YAMLs da v14
| Action term | Método HTTP | O que faz | O que fica com você |
| --- | --- | --- | --- |
| Retrieve | GET | Lê uma instância do Control Record ou do Behavior Qualifier | Paginação, filtros e cache; o YAML não os define |
| Initiate | POST | Cria uma nova instância | Idempotência de criação e geração do id |
| Update | PUT | Altera uma instância existente | Controle de concorrência e auditoria da mudança |
| Execute | PUT | Executa a ação de negócio na instância | Idempotency-Key obrigatória; é onde o dinheiro se move |
| Exchange | PUT | Aceita, rejeita ou responde a uma instância | Autorização por papel: quem pode aceitar o quê |

## Leitura DDD e o que fica com você

Se você vem de Domain-Driven Design, a tradução é curta. O **Service Domain é um bounded context candidato**. Candidato, não decreto: a aula 07 mostra que um Service Domain pode virar dois sistemas e três Service Domains podem morar num só. O **Control Record é o aggregate**: a fronteira de consistência. O Behavior Qualifier vive dentro dele, por isso `DebitandCredit/{id}` não é um agregado separado, é uma entidade dentro de `CurrentAccountFacility`.

Essa leitura resolve uma dúvida frequente: "posso ter uma transação que toca dois Control Records?". Pode, mas ela atravessa dois agregados, e isso é saga ou orquestração, não uma chamada só. O caminho do BIAN deixa isso visível: cada URL toca um crId.

Agora a lista do que o YAML não resolve e que é sua responsabilidade escrever no OpenAPI que vai para o gateway:

- **Autenticação:** o esquema de segurança (OAuth 2, mTLS) não está no YAML.
- **Autorização:** quem pode chamar Execute em qual conta. Isso é regra de negócio e de regulação.
- **Idempotência:** chave por chamada em Initiate e Execute, com resultado armazenado.
- **Versionamento:** no caminho ou no header, mas em algum lugar, porque a v14 não põe versão na URL.
- **Modelo de erro:** um formato único para todos os domínios; `problem+json` é a minha escolha padrão.
- **Paginação:** Retrieve de coleções precisa de cursor ou offset.
- **SLO:** latência e disponibilidade por operação, porque Retrieve e Execute não têm o mesmo custo de falha.

A analogia para quem programa: o BIAN entrega a interface; a classe que implementa é sua.

> **Na prática:** Na prática, eu uso o YAML do BIAN como gabarito de nomes e de fronteira, nunca como o arquivo que vai para o gateway. Copio o caminho, mantenho o action term e o método, e escrevo o meu OpenAPI por cima: security scheme, header de idempotência, versão e um único modelo de erro. Time que publica o YAML cru acaba com um modelo de erro por domínio e sem resposta para "quem pode chamar Execute". O custo não aparece na primeira entrega; aparece na auditoria.

## O que levar desta aula

- Todo caminho da v14 é /{ServiceDomain}/{crId}/{BehaviorQualifier}/{bqId}/{ActionTerm}, e cada segmento é uma camada do mapa.
- Retrieve é GET, Initiate é POST, Update, Execute e Exchange são PUT; PUT promete idempotência e você cumpre a promessa.
- Quatro sabores em dois eixos: REST ou assíncrono, Business Object Model ou ISO 20022. A semântica não muda.
- Service Domain é bounded context candidato; Control Record é o aggregate; o Behavior Qualifier vive dentro dele.
- Autenticação, autorização, idempotência, versão, erro, paginação e SLO não estão no YAML. São seus.

### 05. Pix no mapa do BIAN

_Um Pix de R$ 50 às 23h atravessando os Service Domains da v14._

São 23h e alguém paga R$ 50 pelo celular. Em poucos segundos o dinheiro sai de uma conta e aparece em outra, num banco diferente. Por trás desse gesto, nove Service Domains do BIAN 14 mudam de estado, e dois sistemas externos, o DICT e o SPI, entram na conversa. Esta aula segue esses R$ 50 passo a passo.

## A jornada em nove domínios

O BIAN 14 traz um cenário oficial chamado External Credit Transfer: uma transferência de crédito em que o dinheiro sai do seu banco e chega a uma conta em outra instituição. Pix é exatamente isso, só que em tempo real. Vou usar esse cenário como base e contar a história na ordem em que os domínios entram.

**Payment Order Initiation:** o cliente abre o app, informa a chave e os R$ 50. Nasce aqui a ordem de pagamento, com seu próprio Control Record.

**Payee Management:** antes de pagar, o banco precisa saber quem recebe. A chave Pix vira conta, agência e instituição. Como o DICT é operado pelo Banco Central, este domínio funciona como uma fachada: ele guarda a resolução, mas a fonte da verdade é externa.

**Payment Orchestration:** coordena os próximos passos e sabe em que ponto a ordem está.

**Payment Confirmation:** checa se a ordem pode seguir. Para pessoa física, o exemplo clássico é o limite noturno de R$ 1.000 após as 20h: às 23h, R$ 50 passam; R$ 1.500 não.

**Fraud Evaluation:** dá o veredito de fraude sobre a ordem.

**Payment Rail:** conversa com o trilho externo, o SPI, no formato que ele entende.

**Payment Settlement:** registra a liquidação confirmada pelo trilho.

**Current Account:** debita os R$ 50 na conta do pagador.

**Position Keeping:** registra a posição resultante para o financeiro do banco.

Se você lê artigos antigos e encontra Payment Execution, Payment Order ou Payment Instruction, pare: esses três domínios estão obsoletos na v14. O mapa acima é o atual.

## Um Pix de R$ 50 às 23h pelos nove domínios da v14

Fluxo da ordem dentro do banco pagador, com o DICT e o SPI como sistemas externos operados pelo Banco Central.

### 🏦 Banco pagador: ordem e recebedor

- Payment Order Initiation ordem nasce aqui (frontend)
- Payee Management fachada do DICT (compute)
- Payment Orchestration coordena os passos (compute)

### 🔐 Banco pagador: controles

- Payment Confirmation limite noturno R$ 1.000 (security)
- Fraud Evaluation veredito de fraude (security)

### 📡 Banco pagador: trilho e liquidação

- Payment Rail fala ISO 20022 (messaging)
- Payment Settlement liquidação confirmada (data)

### 📒 Banco pagador: contas e posição

- Current Account débito de R$ 50 (storage)
- Position Keeping posição registrada (storage)

### 🌐 Banco Central: sistemas externos

- DICT diretório de chaves (external)
- SPI liquidação bruta em tempo real (external)

### Fluxos

- cliente -> poi: 1. chave + R$ 50
- poi -> orch: 2. ordem criada
- orch -> payee: 3. resolver recebedor
- payee -> dict: consulta a chave
- orch -> conf: 4. checar limites
- orch -> fraud: 5. veredito
- orch -> rail: 6. enviar ao trilho
- rail -> spi: pacs.008
- spi -> rail: pacs.002 (status)
- rail -> settle: 7. liquidado
- settle -> ca: 8. debitar conta
- ca -> pk: 9. registrar posição

## Por que o mapa ajuda: cada passo tem dono

A pergunta útil não é "o Pix funciona?", é "quando ele falha às 23h, quem é o dono do passo que falhou?". É aqui que o mapa paga a conta.

Cada domínio da jornada tem um Control Record próprio, aquele registro que vimos na aula 02. A ordem vive em Payment Order Initiation. A resolução da chave vive em Payee Management. O estado da coordenação vive em Payment Orchestration. O veredito vive em Fraud Evaluation. Nenhum deles precisa olhar dentro do outro: cada um expõe o seu estado pela Semantic API e pronto.

Pense em um pipeline de deploy. Você não grava o resultado do teste dentro do artefato de build; cada etapa tem seu log e seu status. Se o deploy quebra, você sabe em qual etapa olhar. A jornada do Pix é a mesma ideia aplicada a dinheiro.

O que isso muda na operação:

- **Incidente:** "o Pix não caiu" vira "a ordem foi aceita, a chave resolveu, o trilho devolveu `pacs.002` de rejeição". Cada frase aponta um domínio.
- **Fronteira de sistema:** quando dois times discutem quem implementa o limite noturno, a resposta está no mapa: Payment Confirmation.
- **Auditoria:** cada decisão tem registro próprio, com dono. Não existe uma "tabela de pagamentos" gigante onde tudo se mistura.

O custo de manter isso não é o de desenhar o mapa, é o de respeitar a fronteira todos os dias. Um atalho que grava saldo dentro do orquestrador parece inofensivo no sprint e vira dívida permanente em dois anos.

> **Na prática:** Na prática, o erro que mais vejo em mapeamentos de Pix é colocar o DICT "dentro" de Payee Management, como se o banco fosse dono da chave. Não é. Modele a fachada como fachada: cache com validade, chamada externa explícita e registro de quem consultou o quê. Quando o Banco Central mudar uma regra do DICT, você quer saber em um lugar só onde isso bate.

### A jornada do Pix de R$ 50 às 23h

Ordene os domínios do pedido do cliente até o registro da posição.

1. Payment Order Initiation
2. Payee Management
3. Payment Orchestration
4. Payment Confirmation
5. Fraud Evaluation
6. Payment Rail
7. Payment Settlement
8. Current Account
9. Position Keeping

## O que é Brasil e o que é igual no mundo

Dois sistemas da história são externos ao banco e são brasileiros: o DICT e o SPI, ambos operados pelo Banco Central.

O DICT é o diretório de chaves. Em muitos países, o equivalente a uma chave Pix fica dentro de cada banco ou num consórcio privado. Aqui, a chave resolve numa fonte central. Por isso Payee Management vira fachada: ele cuida de cache, auditoria e política de uso, mas quem responde "quem é o dono desta chave" é o DICT.

O SPI é o trilho. Segundo o Banco Central, ele faz liquidação bruta em tempo real, transação por transação, e as Contas PI dos participantes não podem ficar com saldo negativo. Isso define o comportamento de Payment Rail e de Payment Settlement: não existe "lote da noite" para compensar depois. Cada Pix liquida sozinho, ou é rejeitado.

As mensagens seguem ISO 20022, e três delas bastam para entender o fluxo:

- `pacs.008`: o pagamento em si, enviado pelo banco pagador.
- `pacs.002`: o status, dizendo se o trilho aceitou ou rejeitou.
- `pacs.004`: a devolução, quando o dinheiro precisa voltar.

E o que é igual em qualquer pagamento instantâneo do mundo? A jornada dos nove domínios. Iniciar, resolver o recebedor, orquestrar, confirmar limites, avaliar fraude, falar com o trilho, liquidar, debitar e registrar posição: esse esqueleto não muda. Muda o trilho, muda o diretório, mudam os limites regulatórios. Se você mapear um sistema de pagamentos fora do Brasil, troque os nós externos do diagrama e mantenha o resto.

## O que levar desta aula

- O cenário base é o External Credit Transfer da v14; Pix é uma instância em tempo real dele.
- Nove domínios, nove donos, nove Control Records: ninguém grava estado dentro do vizinho.
- Payee Management é fachada do DICT; Payment Rail é quem fala `pacs.008`, `pacs.002` e `pacs.004` com o SPI.
- Liquidação bruta em tempo real e Conta PI sem saldo negativo tiram o lote noturno do desenho.
- Payment Execution, Payment Order e Payment Instruction estão obsoletos na v14. Se o artigo usa esses nomes, ele é antigo.

### Checagem rápida

1. **Qual destes nomes NÃO deve aparecer num mapeamento para a v14?**
- [x] Payment Execution, _Obsoleto na v14; Payment Settlement é o substituto anunciado._
- [ ] Payment Orchestration, _É novo na v14._
- [ ] Payee Management, _É novo na v14._
- [ ] Payment Rail, _É o nome atual (antes Payment Rail Operations)._

## Dúvidas frequentes

### O limite noturno de R$ 1.000 é regra do BIAN?

Não. O BIAN diz onde a checagem mora (Payment Confirmation), não qual é o valor. O limite é contexto regulatório brasileiro e é usado aqui só como exemplo de regra que vive nesse domínio.

### E a devolução, onde entra no mapa?

Esta aula não cobre o fluxo completo de devolução. O que importa saber: ela chega como `pacs.004` pelo trilho e passa pelos mesmos donos, Payment Rail, Payment Settlement, Current Account e Position Keeping, agora com crédito em vez de débito.

### Posso simplificar e juntar Orchestration com Confirmation num serviço só?

Pode implementar os dois no mesmo deploy, se o time é um só. O que não pode é misturar os Control Records: o estado da coordenação e a decisão de limite têm ciclos de vida e auditoria diferentes. Fronteira lógica fica; fronteira de deploy é escolha sua.

### 06. Open Finance, SCR, LGPD e Banco Central no mapa

_O que da regulação vira domínio e o que vira restrição de implantação._

Toda norma nova chega à mesa do arquiteto com a mesma pergunta: "onde isso entra no sistema?". A pergunta certa é outra: essa regra cria uma responsabilidade de negócio com ciclo de vida próprio, ou só muda onde e como o que já existe pode rodar? A primeira vira Service Domain no mapa. A segunda vira restrição de implantação. Confundir as duas é como modelar "estar em conformidade" como um microsserviço.

## O teste das duas perguntas

Na aula 02 você viu que um Service Domain existe porque tem um Control Record: uma instância de negócio que nasce, muda de estado e é consultada. É esse o teste que eu aplico a cada norma.

**Primeira pergunta: a regra cria algo que precisa ser instanciado e acompanhado?** Um consentimento tem início, finalidade, prazo e revogação. Uma remessa regulatória tem período, conteúdo, envio e aceite. Isso é Control Record, logo é domínio, e quase sempre o BIAN já tem um com esse nome.

**Segunda pergunta: a regra muda como algo existente opera, sem criar instância nova?** Exigir que o dado fique numa região, que o fornecedor de nuvem tenha contrato com cláusulas específicas, que exista plano de saída. Nada disso é um objeto de negócio. É restrição que se aplica a todos os domínios ao mesmo tempo, no nível da implantação.

Existe um terceiro caso, mais sutil: a regra não cria domínio nem é só infraestrutura, ela muda o comportamento de um domínio que já existe. O direito à revisão de decisão automatizada é o exemplo clássico, e volto nele adiante.

A regra prática: se você consegue escrever "um X foi criado para o cliente Y em Z", X é candidato a domínio. Se a frase sai "o sistema precisa ser Z", é restrição.

## Open Finance: o consentimento tem ciclo de vida

A Resolução Conjunta nº 1/2020 define o consentimento do Open Finance como livre, informado, prévio e inequívoco, com finalidade determinada e revogável a qualquer tempo. Leia essa frase como engenheiro: cada adjetivo é um estado ou uma validação.

**Prévio** significa que nenhum dado sai antes de o registro existir. **Finalidade determinada** significa que o registro carrega escopo, e a consulta precisa checar o escopo, não só a existência. **Revogável a qualquer tempo** significa que o estado muda por iniciativa do cliente, a qualquer hora, e tudo que depende dele precisa reagir.

Isso é a descrição de um Control Record. Na versão 14 ele ganhou domínio próprio: **Customer Consent**. Antes, cada banco espalhava consentimento entre cadastro, canais e API gateway, e revogação virava uma caça ao tesouro.

Ao redor dele entram dois vizinhos. **Party Authentication** prova quem está consentindo. Para a iniciação de pagamento, o pedido autorizado vira ordem em **Payment Order Initiation**, o mesmo domínio que você viu no Pix na aula 05: o Open Finance não cria um "pagamento diferente", cria uma origem diferente para a mesma ordem.

A escala muda a conversa. Em maio de 2026 havia cerca de 116 milhões de autorizações de compartilhamento ativas. Com esse volume, revogação não é exceção que se trata na mão: é fluxo de primeira classe, com evento, consumidor e prazo de propagação medido.

## A regulação em duas colunas: o que vira domínio e o que vira restrição

Cada norma brasileira ligada ao Service Domain que a absorve. À esquerda, regras que criam um Control Record. À direita, regras que mudam como um domínio existente opera ou onde ele pode rodar.

### 📜 Regulação: vira domínio

- Res. Conjunta 1/2020 consentimento Open Finance (external)
- Res. CMN 5.037/2022 SCR (external)
- MED devolução no Pix (external)

### 🔒 Regulação: vira restrição

- LGPD art. 20 revisão de decisão automatizada (security)
- Res. CMN 4.893/2021 alterada pela 5.274/2025 (security)

### 🧩 BIAN 14: Service Domains

- Customer Consent novo na v14 (data)
- Party Authentication (security)
- Payment Order Initiation (compute)
- Regulatory Reporting (data)
- Fraud Resolution (compute)
- Customer Case (frontend)
- Domínios Assess / Analyse ex.: Customer Credit Rating (ai)

### ☁️ Implantação: onde e como roda

- Nuvem, região, contrato, plano de saída (network)

### Fluxos

- res1 -> consent: ciclo de vida do consentimento
- res1 -> auth: quem consente
- res1 -> poi: iniciação de pagamento
- scr -> regrep: remessa e consulta
- med -> fraud: composição
- med -> case: composição
- lgpd -> assess: requisito: caminho de revisão humana
- assess -> case: pedido de revisão
- r4893 -> deploy: restringe todos os domínios

## SCR e LGPD art. 20: remessa é domínio, revisão é requisito

O SCR, Sistema de Informações de Crédito, é regido pela Resolução CMN 5.037/2022. O banco remete ao Banco Central as operações de crédito dos seus clientes e consulta o histórico que outras instituições enviaram. No mapa isso não ganha domínio novo: entra em **Regulatory Reporting**, que já existe para toda remessa ao regulador. A remessa é a instância: período, conteúdo, envio, aceite ou rejeição. O que muda é a configuração, não a caixa.

A LGPD é o terceiro caso do teste. O art. 20 dá ao titular o direito de pedir revisão de decisão tomada só com base em tratamento automatizado. Nenhum domínio novo nasce daí. O que nasce é um requisito dentro dos domínios de padrão Assess e Analyse que decidem sobre a pessoa: avaliação de crédito, avaliação de fraude, qualquer caixa cujo action term devolve um veredito sobre alguém.

Na prática o requisito tem três partes: a decisão precisa guardar o que a produziu (versão do modelo, variáveis, limiar), precisa existir um caminho de revisão humana, e esse caminho precisa estar ligado ao atendimento, que no BIAN é **Customer Case**. Se o seu modelo de crédito decide em 200 ms e ninguém consegue reconstruir por quê, você tem um Service Domain funcionando e uma obrigação legal descoberta.

Esse ponto volta com força na aula 09, quando o avaliador for um agente e não um modelo de score.

### Regulação e lugar no mapa

- **Consentimento do Open Finance** → Customer Consent
- **DICT** → Payee Management (fachada para a fonte externa)
- **SCR** → Regulatory Reporting
- **LGPD art. 20** → Requisito nos domínios que decidem (Assess, Analyse)
- **Resolução CMN 4.893** → Restrição de implantação, não domínio
- **MED** → Composição: Fraud Resolution + Customer Case

## 4.893, nuvem e o que o Brasil tem de diferente

A Resolução CMN 4.893/2021, sobre segurança cibernética e contratação de serviços de nuvem, segue em vigor, alterada pela 5.274/2025. Aplique o teste: ela não cria nenhuma instância de negócio. Ela diz como o que já existe pode ser contratado, onde pode rodar e o que precisa estar documentado e comunicado. No mapa, portanto, não é domínio: é restrição de implantação que pesa sobre todos os domínios ao mesmo tempo. O lugar dela é no heatmap da aula 07, como atributo de cada sistema, não como caixa.

Onde o Brasil é igual ao mundo e onde não é? O mapa de domínios é o mesmo: consentimento, autenticação, ordem de pagamento e remessa regulatória existem em qualquer país. O que muda é quem opera o quê e quais composições existem.

**O DICT é central**, operado pelo Banco Central. O banco não tem um "domínio de diretório" próprio; ele consome um diretório externo e precisa modelar essa dependência como parceiro, não como caixa interna.

**O MED não tem domínio próprio.** O Mecanismo Especial de Devolução é um procedimento com prazos e papéis definidos, mas no BIAN ele vira composição: **Fraud Resolution** conduz a investigação e a devolução, **Customer Case** registra a contestação do cliente. Quem cria um "MED Service Domain" está duplicando dois domínios que já existem e vai pagar a manutenção em dobro.

> **Na prática:** O erro que mais vi em mapeamentos foi tratar norma como caixa. Alguém cria um domínio "LGPD" ou "Compliance" e, seis meses depois, ele virou o lugar onde todo requisito mal entendido vai parar. Minha regra: só crio domínio quando consigo nomear o Control Record. Se o nome que sai é o número da resolução, não é domínio, é restrição ou requisito dentro de um domínio que já existe.

## O que levar desta aula

- Norma vira domínio quando cria uma instância de negócio com ciclo de vida; vira restrição quando muda onde e como o existente roda.
- Consentimento do Open Finance (Resolução Conjunta nº 1/2020) é Control Record de Customer Consent, com Party Authentication ao lado e Payment Order Initiation para iniciação de pagamento.
- SCR (Resolução CMN 5.037/2022) é configuração de Regulatory Reporting, não domínio novo.
- LGPD art. 20 é requisito dentro dos domínios Assess e Analyse que decidem sobre a pessoa: rastro da decisão, revisão humana e ligação com Customer Case.
- Resolução CMN 4.893/2021 (alterada pela 5.274/2025) é restrição de implantação sobre todos os domínios, e mora no heatmap, não no mapa.
- DICT é diretório central do Banco Central, modelado como dependência externa; MED é composição de Fraud Resolution + Customer Case.

## Perguntas que aparecem no mapeamento

### O Open Finance precisa de um domínio de "compartilhamento de dados"?

Não. O dado compartilhado pertence ao domínio que já é dono dele (uma conta, um cartão, um empréstimo) e sai pelo action term de consulta desse domínio. O que o Open Finance acrescenta é a verificação de Customer Consent antes de responder e a autenticação em Party Authentication. Um domínio de "compartilhamento" só duplicaria dados que já têm dono.

### O mesmo teste vale para regulação fora do Brasil?

Vale, porque o teste é sobre Control Record, não sobre país. O que muda é a resposta: cada jurisdição decide o que é central e o que fica no banco, como o DICT mostra. Os detalhes das normas estrangeiras não são cobertos neste curso.

## Módulo 3: O BIAN no trabalho

Heatmap, fronteiras, erros clássicos, mapeamento com IA e agentes com fronteira de domínio.

### 07. Heatmap, fronteiras e erros clássicos

_Usar o mapa para decidir manter, comprar, construir ou aposentar, e para desenhar serviços e eventos._

Depois de seis aulas lendo o mapa, chega a hora de usá-lo para decidir. Um Service Domain pintado de vermelho vale mais numa reunião de orçamento do que qualquer slide de "transformação". Nesta aula o BIAN vira ferramenta de trabalho: heatmap, fronteira de serviço, nome de evento e os erros que eu já vi se repetirem projeto após projeto.

## Cinco usos que pagam a leitura do mapa

O BIAN entra no meu dia a dia por cinco portas, e convém saber qual você está abrindo.

**Vocabulário comum:** quando produto, risco e engenharia chamam a mesma coisa de "conta", "contrato" e "posição", a reunião gasta metade do tempo traduzindo. Customer Agreement e Position Keeping encerram a discussão.

**Heatmap de sistemas:** o inventário de aplicações projetado sobre os Service Domains. É o uso que mais rende em comitê de investimento e o centro desta aula.

**Fronteiras de serviço:** o mapa sugere onde um serviço termina e outro começa. Sugere, não manda; volto a isso adiante.

**Desenho de APIs:** os padrões funcionais e os action terms da aula 03 dão nome e forma a recurso, operação e evento sem reinventar convenção a cada squad.

**Ferramentas de agentes:** cada Service Domain é um candidato natural a tool com escopo delimitado; a aula 09 trata disso.

Os cinco usos compartilham uma regra: o mapa descreve capacidades de negócio, não software. Quem esquece isso produz o primeiro erro clássico da lista que fecha a aula.

## Heatmap: pintar cada domínio e decidir com critério

O caso é fictício: uma emissora de cartões de porte médio que também operava adquirência e decidiu sair desse negócio. Pegue os Service Domains da área de cartões e, para cada um, registre três dados: quais sistemas o cobrem, quanta dor ele gera (incidentes, fila de mudanças, retrabalho) e quanto custa manter. A cor sai desses três dados, não da opinião do dono do sistema.

Pintado o mapa, a decisão por domínio segue um critério explícito, escrito no topo da planilha para ninguém discutir caso a caso:

- **Construir** quando o domínio é diferencial competitivo. Na emissora fictícia, Fraud Detection e Customer Offer: o modelo de risco e a oferta personalizada são o que o cliente percebe.
- **Comprar** quando é commodity de rede ou regulada. Card Clearing, Card Network Participant Facility e Payment Settlement: ninguém ganha cliente por liquidar melhor com a bandeira.
- **Manter** quando funciona bem e muda pouco. Card Authorization e Card Transaction Tracking rodam há anos com incidente raro; mexer ali é risco sem retorno.
- **Aposentar** quando o domínio saiu do negócio. Merchant Acquiring Facility e Card Terminal Administration deixam de existir na operação, e o plano de saída vira item de roadmap com dono e data.

O heatmap não entrega a decisão pronta, entrega a conversa certa: quatro verbos, um critério e um mapa que todo mundo lê.

## Heatmap fictício da operação de cartões: quatro decisões no mapa

Cada Service Domain do BIAN 14 leva a decisão na segunda linha. As setas seguem uma compra do portador até a cobrança; o tracejado marca apoio ou saída.

### 🔐 Autorização e posição

- Card Authorization manter: estável, muda pouco (security)
- Card Transaction Tracking manter: posição do cartão (data)

### 🛒 Compensação e faturamento

- Card Clearing comprar: commodity de rede (external)
- Card Network Participant Facility comprar: regra da bandeira (external)
- Payment Settlement comprar: novo no v14 (external)
- Card Billing comprar: fatura é commodity (compute)
- Card Collections manter: cobrança funciona (compute)

### 🤖 Risco e relacionamento

- Fraud Detection construir: diferencial (ai)
- Customer Offer construir: oferta personalizada (ai)

### 🗑 Adquirência (saindo do negócio)

- Merchant Acquiring Facility aposentar: plano de saída (storage)
- Card Terminal Administration aposentar: junto com a adquirência (storage)

### Fluxos

- holder -> auth: autorização em milissegundos
- fraud -> auth: score de risco
- auth -> ctt: evento de autorização
- ctt -> clearing: transações do dia
- clearing -> network: arquivo da bandeira
- clearing -> settle: valores a liquidar
- ctt -> billing: fatura mensal
- billing -> collections: atraso
- offer -> holder: limite e oferta
- acq -> clearing: desligar após a migração
- terminal -> acq: sai junto

> **Na prática:** Na prática, o heatmap que funciona cabe numa página e tem data. Eu pinto com o time de operação, não com o de arquitetura: quem atende o plantão sabe onde dói. E escrevo o critério de decisão antes de pintar, porque depois cada dono de sistema descobre um motivo para o seu domínio ser "diferencial competitivo".

### Heatmap do caso fictício de cartões

1. **A autorização de cartão é o diferencial do emissor fictício e o sistema atual não escala. Decisão para Card Authorization?**
- [x] Construir, _Diferencial competitivo com dor real justifica construir._
- [ ] Comprar, _Comprar faz sentido para commodity, não para o diferencial._
- [ ] Manter, _O sistema atual não escala._
- [ ] Aposentar, _A capacidade continua essencial._

2. **Customer Billing roda num pacote de mercado estável e barato. Decisão?**
- [x] Manter, _Funciona bem e não é diferencial: não mexa._
- [ ] Construir, _Construir commodity que funciona é custo sem retorno._
- [ ] Aposentar, _Faturar continua sendo necessário._
- [ ] Separar em 3 microsserviços, _Fronteira nova sem motivo de escala, falha ou auditoria._

3. **Qual é o erro do '340 microsserviços'?**
- [x] Tratar cada Service Domain como serviço obrigatório, _Troca um monólito por custo de rede, deploy e plantão._
- [ ] Usar menos serviços do que o BIAN recomenda, _O BIAN não recomenda número de serviços._
- [ ] Publicar eventos em vez de APIs, _Eventos e APIs convivem._
- [ ] Ignorar a ISO 20022, _É outro problema._

## Fronteiras candidatas e nomes de evento

Service Domain é fronteira candidata de serviço, não fronteira obrigatória. O BIAN desenha cada domínio para ser autônomo; isso o torna um bom ponto de corte, mas não quer dizer que cada corte deva virar um deploy separado.

Eu agrupo domínios por três eixos: **time** (quem opera junto implanta junto), **taxa de mudança** (o que muda toda semana não convive bem com o que muda uma vez por ano) e **risco** (o que derruba autorização não pode dividir processo com relatório gerencial). Na emissora fictícia, Card Authorization e Card Transaction Tracking podem viver no mesmo serviço: mesmo time, mesma cadência, mesmo plantão.

Separo quando um de três sinais aparece: **escala** diferente (autorização em milissegundos, faturamento em lote noturno), **falha** que precisa ser isolada (fraude fora do ar não pode travar a compra) ou **auditoria** que exige trilha própria (Customer Consent e tudo que a LGPD toca).

Para eventos, uma convenção só: Behavior Qualifier mais verbo no passado. `AmountBlockInitiated` diz qual qualificador mudou e qual action term aconteceu. Quem recebe o evento sabe onde ele nasceu no mapa sem abrir documentação. Aplique a mesma fórmula aos seus Behavior Qualifiers e evite verbos genéricos como `Updated` quando o action term existe.

## Quatro erros que eu vi se repetirem

**Tratar o mapa como planta:** o Service Landscape descreve capacidades, não componentes. Quem o lê como diagrama de implantação sai desenhando um sistema por caixa.

**Os "340 microsserviços":** o número é ilustrativo, a cena é real. Trocar um monólito por um serviço por Service Domain e descobrir que o custo mudou de lugar: latência de rede entre chamadas, uma pipeline de deploy por serviço e um plantão que não sabe mais onde começar a investigar. Agrupe primeiro, separe por sinal.

**Semantic API como contrato de produção:** a API semântica define recurso e operação, e para aí. Autenticação, idempotência de retry, formato de erro, paginação e versionamento são decisões suas. Publicar o YAML do BIAN como está é publicar um contrato pela metade.

**Mapear para domínio obsoleto:** Payment Execution, Payment Order e Payment Instruction não existem mais no BIAN 14. Mapeamento antigo precisa migrar para Payment Order Initiation, Payment Orchestration e os demais domínios novos, senão o heatmap nasce com fantasmas.

Fora do Brasil, o mesmo mapa ajuda a conversar: o T2 do Eurosistema usa ISO 20022 desde março de 2023; PSD3 e PSR foram propostos pela Comissão Europeia em 2023 e seguem em negociação; nos Estados Unidos o FDX é a referência de compartilhamento de dados. O domínio é o mesmo; o regulador e a mensagem mudam.

## Para levar

- Heatmap é cobertura, dor e custo por Service Domain, pintado com quem opera.
- Construir o diferencial, comprar a commodity, manter o que funciona, aposentar o que saiu do negócio. Critério antes da tinta.
- Service Domain é fronteira candidata: agrupe por time, cadência e risco; separe por escala, falha ou auditoria.
- Evento é Behavior Qualifier mais verbo no passado. Semantic API é ponto de partida, não contrato de produção.

### 08. IA Builder: mapeamento e contratos com grounding

_Mapeamento assistido por IA que não inventa domínio, e revisão de contratos contra a Semantic API oficial._

A IA é boa em um trabalho que todo arquiteto detesta: ler as definições de todos os Service Domains e lembrar qual faz o quê. E é péssima em outro: inventar um nome plausível quando não encontra o certo. Esta aula mostra como ficar com a primeira parte e eliminar a segunda, com recuperação sobre as definições oficiais da v14, escolha com citação, validador de lista fechada e um humano que decide. Acelerar sim, terceirizar o julgamento não.

## A regra: o modelo escolhe, nunca cria

Mapear um sistema no BIAN é um problema de classificação com catálogo fechado. A v14 tem um conjunto finito de Service Domains, cada um com papel, resumo e funções descritos em texto. O trabalho do mapeador é olhar uma capacidade do sistema ("calcula o limite rotativo do cartão") e apontar o domínio que a contém. Não há domínio novo a inventar: se o nome não está no catálogo, a resposta está errada.

Isso muda como se usa o modelo. Em vez de perguntar "qual Service Domain cuida de X?" e aceitar o que vier, o pipeline faz **RAG sobre as definições oficiais** da versão escolhida: cada domínio vira um documento (papel, resumo, funções, action terms), indexado por embedding. Para cada capacidade, recuperam-se os candidatos mais próximos, e só então o modelo entra, com uma instrução estreita: **escolha entre estes candidatos, cite o trecho da definição que justifica a escolha e, se nenhum serve, responda "nenhum"**.

A última defesa é mecânica: um **validador com lista fechada**, os nomes exatos da v14. Qualquer saída fora da lista é rejeitada antes de chegar ao humano. O ponto é não depender da obediência do modelo. Modelo bem instruído erra pouco; validador não erra. Em sistemas financeiros, é esse o padrão que vale a pena: a regra que importa mora fora do prompt, em código pequeno e testável.

## Pipeline de mapeamento com validador e fila humana

A IA só escolhe entre candidatos recuperados das definições oficiais; o validador rejeita qualquer nome fora da v14; o humano decide e cada decisão vira métrica.

### 📚 Grounding: definições oficiais v14

- Catálogo BIAN v14 papel, resumo, funções, YAML (storage)
- Ingestão e chunking um documento por Service Domain (data)
- Bedrock Knowledge Bases índice vetorial (ai)

### 🤖 IA: rascunho, nunca decisão

- Recuperar candidatos top-k por capacidade (ai)
- Escolher com citação trecho da definição ou 'nenhum' (ai)

### 🔐 Validação mecânica

- Validador de lista fechada nomes exatos da v14 (security)
- Script de contrato rascunho vs YAML oficial (security)

### 👤 Humano: julgamento

- Fila de revisão candidato + citação + divergências (messaging)
- Heatmap assinado fronteiras decididas (data)

### 📏 Medição

- Métricas aceito, corrigido, rejeitado (data)

### Fluxos

- catalog -> ingest: 1. ingerir
- ingest -> kb: embeddings
- inventory -> retrieve: capacidade
- kb -> retrieve: 2. candidatos
- retrieve -> choose: 3. escolher
- choose -> validator: 4. nome + citação
- validator -> choose: fora da lista: rejeita
- validator -> queue: nome válido
- contract -> queue: divergências de campo
- queue -> heatmap: 5. humano decide
- heatmap -> metrics: 6. medir

## O pipeline em seis passos

1. **Ingerir as definições da versão escolhida**: Um documento por Service Domain da v14: papel, resumo, funções, action terms. Versão fixada e registrada; misturar versões é a origem de metade dos erros.

2. **Recuperar candidatos**: Para cada capacidade do inventário, buscar os domínios mais próximos por similaridade. O modelo nunca vê o catálogo inteiro, só os candidatos.

3. **Escolher com citação**: O modelo escolhe um candidato e cita o trecho da definição que sustenta a escolha. Sem trecho, sem escolha. "Nenhum" é resposta aceita.

4. **Validar na lista fechada**: Comparação exata contra os nomes da v14. Nome inventado, obsoleto ou antigo é rejeitado e volta com o motivo.

5. **Revisar com humano**: O revisor vê candidato, citação e alternativas, e decide. Fronteira entre vizinhos e exigência regulatória ficam sempre aqui.

6. **Medir**: Taxa de aceite sem correção, taxa de rejeição do validador, domínios mais corrigidos. É o que diz se vale aumentar a confiança ou apertar o prompt.

## Os quatro modos de falha que o validador pega (e o que ele não pega)

Quatro erros aparecem em todo mapeamento assistido, e três deles passam em revisão visual porque parecem corretos.

**Nome inventado:** o modelo responde "Card Limit Management" porque soa como BIAN. Não existe na v14. Sem lista fechada, o nome entra no heatmap e vira caixa num diagrama que ninguém vai conferir.

**Versão velha:** "Payment Execution" aparece em muito material público sobre BIAN e, portanto, no treinamento de qualquer modelo. Na v14 ele é obsoleto, junto com Payment Order e Payment Instruction; o fluxo de pagamento hoje passa por Payment Order Initiation, Payment Orchestration, Payment Confirmation, Payment Settlement e Payment Rail. Um modelo sem grounding responde a versão que leu mais vezes, não a que você escolheu.

**Rename perdido:** "Credit Card Position Keeping" virou Card Transaction Tracking. O nome antigo é plausível, descreve bem a função e está errado. O mesmo vale para Payment Initiation (hoje Payment Order Initiation) e Payment Rail Operations (hoje Payment Rail).

**Vizinhos confundidos:** Fraud Evaluation dá um veredito pontual sobre uma transação; Fraud Diagnosis analisa um caso suspeito ao longo do tempo. Os dois existem, os dois passam no validador, e a escolha errada coloca a fronteira do serviço no lugar errado. Esse é o erro que só a citação da definição e o revisor humano pegam. É por isso que o pipeline exige o trecho citado, não só o nome: a citação é o que permite ao revisor discordar em um minuto, em vez de reabrir o catálogo.

> **Minha leitura:** Na prática, o ganho não está em o modelo acertar mais que o arquiteto; está em ele ler as definições inteiras toda vez, coisa que ninguém faz na terceira semana de mapeamento. Eu uso a IA para o rascunho e a justificativa de cada célula do heatmap, e reservo o julgamento para onde ele é insubstituível: fronteira entre vizinhos, o que fica fora do mapa e o que o regulador exige. Quem assina o heatmap sou eu, não o pipeline.

### O validador da v14

1. **O modelo sugeriu 'Payment Execution'. O validador da v14…**
- [x] rejeita: o domínio está obsoleto na v14, _Payment Settlement é o substituto anunciado._
- [ ] aceita: o nome é oficial, _Foi oficial em versões antigas._
- [ ] pede ao modelo que confirme, _Confirmação do próprio modelo não é fonte._
- [ ] cria um domínio próprio, _Criar nome fora do padrão é o que se quer evitar._

2. **O modelo sugeriu 'Credit Card Position Keeping'. O que fazer?**
- [x] Rejeitar: na v14 o domínio é Card Transaction Tracking, _Rename perdido é um modo de falha clássico._
- [ ] Aceitar, o nome parece oficial, _Parecer oficial não é estar na lista da v14._
- [ ] Aceitar e corrigir depois, _O erro se espalha para heatmap e contratos._
- [ ] Trocar de modelo, _Qualquer modelo erra sem grounding; o validador é a defesa._

3. **Quem decide manter, comprar, construir ou aposentar?**
- [x] O arquiteto, com o rascunho da IA como insumo, _A IA acelera o rascunho; a decisão tem dono humano._
- [ ] O modelo, com limiar de confiança, _Confiança decide o que vai para revisão, não a decisão de portfólio._
- [ ] O fornecedor do core, _Conflito de interesse._
- [ ] O BIAN, _O BIAN dá o vocabulário, não a decisão._

## Contratos: o rascunho contra o YAML oficial

O mesmo princípio vale para contratos. Quando um time rascunha a API de um serviço mapeado em Payment Order Initiation, a referência é o YAML oficial da Semantic API v14 desse domínio, não a memória do modelo. Um script simples carrega o contrato rascunhado e o oficial, alinha as operações pelo action term e compara os campos: no Payment Order Initiation, `PayerReference`, `PayeeReference`, `Amount` e `Currency` precisam estar lá, com o mesmo nome e no mesmo lugar. Campo renomeado, campo faltando, tipo diferente: o script aponta a divergência linha a linha, e o revisor decide se foi desvio proposital ou descuido.

Desvio proposital existe e é legítimo. A Semantic API define semântica, não a sua implementação: ela não diz qual é a chave de idempotência do seu endpoint. No Pix, quem define isso é o catálogo de serviços do SPI, por mensagem; a Semantic API não entra nesse detalhe. Então **idempotência é decisão sua**, registrada como extensão documentada do contrato, não como campo "que o BIAN pediu". O script deve conhecer essas extensões declaradas para não marcar como erro o que foi decidido.

Sobre a infraestrutura: a opção gerenciada de RAG na AWS é o Amazon Bedrock Knowledge Bases, que cuida de ingestão, chunking, embedding e recuperação. Use quando a equipe não quer operar índice vetorial próprio e as definições cabem em um fluxo de ingestão simples. O validador de lista fechada e o script de contratos continuam sendo código seu, pequeno e testável. É a parte que menos muda quando você troca de modelo, e a que mais protege o mapa.

## O que levar desta aula

- O modelo escolhe entre candidatos recuperados das definições oficiais da v14 e cita o trecho; ele nunca cria nome de domínio.
- O validador de lista fechada é código, não prompt: nome inventado, obsoleto (Payment Execution) ou antigo (Credit Card Position Keeping) não passa.
- Vizinhos como Fraud Evaluation e Fraud Diagnosis passam no validador; só a citação e o revisor humano resolvem.
- Contrato rascunhado se compara com o YAML oficial por script; idempotência é decisão sua, documentada como extensão.
- Meça aceite, correção e rejeição por domínio: é o que justifica confiar mais ou apertar o pipeline.

## Perguntas frequentes

### E se nenhum candidato recuperado serve para a capacidade?

"Nenhum" é uma resposta válida e deve ir para a fila humana com os candidatos descartados. Em geral significa uma de três coisas: a capacidade está descrita em termos de tecnologia e não de negócio, ela pertence a dois domínios e precisa ser dividida, ou está fora do escopo do BIAN. Forçar um encaixe é pior que deixar a célula em aberto.

### Posso deixar a IA preencher o heatmap inteiro e revisar só por amostragem?

Só para o rascunho. A amostragem serve para medir a qualidade do pipeline, não para substituir a decisão sobre fronteiras: o custo de uma fronteira errada é de anos de integração no lugar errado, não de uma célula pintada. Use a métrica de aceite para decidir onde a revisão pode ser mais leve, domínio por domínio.

### 09. Agentes com fronteira de domínio e avaliação

_Ferramentas do agente como Service Operations, com política, aprovação humana e avaliação contínua._

Nas oito aulas anteriores o BIAN serviu para ler o banco. Nesta última ele serve para dar limite a um agente de IA: cada ferramenta que o agente pode chamar é uma Service Operation de um Service Domain, com política antes, humano no meio quando há dinheiro e medição depois. Sem essa fronteira, o agente é só um script com acesso ao core bancário.

## Uma ferramenta por Service Operation

A regra que organiza tudo: **uma ferramenta, uma Service Operation**. O agente não recebe uma ferramenta chamada `banco` com dez parâmetros. Ele recebe `Retrieve` no Current Account para consultar saldo e `Initiate` no Payment Order Initiation para criar uma ordem de pagamento. O nome da ferramenta já diz qual domínio ela toca e qual action term ela executa, exatamente o vocabulário da aula 03.

Isso resolve três problemas de uma vez.

**Fronteira:** o agente só alcança os domínios que você expôs. Se não existe ferramenta em Customer Consent, ele não altera consentimento, por mais criativo que seja o prompt.

**Auditoria:** cada chamada de ferramenta vira uma linha de log com Service Domain, action term e Control Record afetado. Quem audita lê o mesmo mapa que o arquiteto desenhou.

**Contrato:** a ferramenta nasce do OpenAPI da Semantic API (aula 04). O schema que valida a requisição do canal valida também a requisição do agente. Não existe um segundo contrato, mais frouxo, só para a IA.

Na prática, a tentação é agrupar: 'uma ferramenta de pagamentos' que decide sozinha se consulta, inicia ou confirma. Resista. Ferramenta larga é fronteira larga, e fronteira larga é o que você passou o módulo 2 aprendendo a não desenhar. Lembre também que Payment Execution e Payment Instruction são obsoletos na versão 14: ferramenta com esses nomes é dívida de nascença.

## O laço do agente bancário

Caminho de um pedido do cliente até a Service Operation, com política, aprovação humana e auditoria no meio.

### 🤖 Agente: raciocínio e plano

- Agente escolhe a ferramenta e preenche os campos (ai)

### 🟧 AWS: Bedrock AgentCore

- AgentCore Gateway OpenAPI exposto como ferramentas MCP (network)
- Policy (Cedar) avalia a regra antes de cada chamada (security)

### 🔐 Controle humano

- Fila de aprovação toda movimentação de dinheiro (user)
- Revisão LGPD art. 20 decisão sobre a pessoa (user)

### 🏦 Banco: Service Domains BIAN 14

- Current Account Retrieve: saldo (data)
- Payment Order Initiation Initiate: ordem de pagamento (compute)
- Payment Confirmation confirma ao cliente (messaging)

### 📤 Auditoria e avaliação

- Trilha de auditoria domínio, action term, Control Record (storage)
- Golden set e métricas precisão, recall, regressão (ci)

### Fluxos

- client -> agent: pedido em linguagem natural
- agent -> gateway: chama a ferramenta
- gateway -> policy: regra Cedar antes da chamada
- policy -> ca: Retrieve permitido
- policy -> approval: Initiate exige humano
- approval -> poi: aprovado
- poi -> pc: ordem aceita
- pc -> client: resposta ao cliente
- approval -> review: negativa: direito de revisão
- gateway -> audit: registra cada chamada
- audit -> eval: alimenta a avaliação

## Gateway, política e aprovação humana

O desenho acima tem três camadas entre o agente e o banco, e nenhuma é opcional.

**Gateway:** o Amazon Bedrock AgentCore Gateway recebe a especificação OpenAPI da Semantic API e a expõe como ferramentas MCP. O agente enxerga `Retrieve` e `Initiate` como ferramentas; o banco continua enxergando a mesma API de sempre. Nenhum código de integração novo, nenhum contrato paralelo.

**Política:** o Policy in AgentCore avalia regras Cedar antes de cada chamada de ferramenta. A regra é declarativa: este agente, para este cliente, pode chamar `Retrieve` no Current Account; pode chamar `Initiate` no Payment Order Initiation só se houver aprovação registrada. A política vive fora do prompt. Prompt é sugestão; política é bloqueio.

**Aprovação humana:** toda movimentação de dinheiro passa por uma pessoa. Não é desconfiança do modelo, é desenho: o agente prepara a ordem com todos os campos preenchidos, o humano aprova em uma fila, e só então o `Initiate` acontece. Consulta de saldo não precisa disso; transferência precisa, sempre.

Há uma quarta camada que o diagrama marca e muita gente esquece: o **art. 20 da LGPD** dá ao titular o direito de pedir revisão de decisões tomadas unicamente com base em tratamento automatizado que afetem seus interesses. Se o agente nega um limite ou recusa uma operação, a pessoa pode pedir que um humano reveja. Então o laço precisa de um caminho de volta, com a decisão, o motivo e quem revisou.

### O laço do agente bancário

Ordene do pedido do cliente à auditoria.

1. Cliente pede para pagar uma conta
2. Agente consulta o saldo com Retrieve no Current Account
3. Política no gateway avalia a chamada
4. Cliente aprova o pagamento
5. Agente executa Initiate no Payment Order Initiation
6. Chamada e decisão ficam na auditoria

> **Na prática:** Na prática, o que separa um agente bancário de uma demo é a ordem das camadas. Já vi protótipo colocar a aprovação humana no prompt ('peça confirmação antes de pagar') e chamar isso de controle. Prompt não é controle. Controle é a regra Cedar que devolve negado quando não há aprovação registrada, e o log que prova isso seis meses depois. Monte a demo com a fronteira pronta: é mais lento no primeiro dia e muito mais barato em todos os outros.

## Avaliação: o agente também tem golden set

Na aula 08 a IA rascunhou mapeamentos e um humano decidiu. A pergunta que fecha o curso é outra: como você sabe que ela continua acertando?

**Golden set:** um conjunto de casos com a resposta certa, revisado por dois arquitetos, com a versão do BIAN fixada no próprio arquivo (14.0, e não 'a atual'). Dois revisores porque mapeamento é interpretação: onde os dois discordam, o caso vira discussão e, resolvido, vira o exemplo mais valioso do conjunto. Versão fixada porque um rename como Payment Rail Operations para Payment Rail muda a resposta certa sem mudar o sistema.

**Precisão e recall por domínio:** a média geral esconde o problema. Um agente pode acertar tudo em Current Account e errar sistematicamente em Payment Orchestration, que é novo na versão 14. Meça por Service Domain e olhe para os piores, não para a média.

**Limiar de confiança:** abaixo de um valor que você define, o caso não é decidido pelo agente; vai para a fila humana. O valor certo depende do seu conjunto e do custo de errar em cada domínio. O que não pode é não existir.

**Regressão:** a cada troca de modelo e a cada versão nova do BIAN, rode o golden set inteiro antes de promover. Modelo novo não é melhor por definição; é diferente, e diferente precisa de prova.

## Rotina de avaliação do agente

1. **Congele a versão**: BIAN 14.0 escrito no arquivo do golden set e no grounding do agente. Nome obsoleto na resposta conta como erro.

2. **Revise em dupla**: Dois arquitetos aprovam cada caso. Divergência fica registrada com a decisão final e o motivo.

3. **Meça por domínio**: Precisão e recall por Service Domain. Ordene do pior para o melhor e ataque o topo da lista.

4. **Rode a regressão antes de promover**: Troca de modelo ou de versão do BIAN só sobe depois do golden set inteiro. Queda em qualquer domínio bloqueia.

### Recapitulação do curso

- **Módulo 1**: O mapa: camadas, Control Record, padrões funcionais e action terms.
- **Módulo 2**: Do domínio à regulação: Semantic API, Pix e Open Finance no mapa.
- **Módulo 3**: No trabalho: heatmap, fronteiras, IA com grounding e agentes avaliados.

## Os três módulos em uma página, e o exame

Antes do exame, o caminho que você percorreu.

**Módulo 1, o mapa:** o BIAN é um mapa de capacidades, não um sistema (aula 01). As camadas organizam Service Domains, cada um com um Control Record que diz o que ele administra (aula 02). Padrões funcionais e action terms dão o verbo: Retrieve, Initiate, Update, Execute (aula 03). E o caminho segue do Service Domain até o OpenAPI da Semantic API (aula 04).

**Módulo 2, o Brasil no mapa:** Pix distribuído entre Payment Order Initiation, Payment Rail, Payment Settlement e Payment Confirmation, com os domínios novos da versão 14 no lugar dos obsoletos (aula 05). Open Finance, SCR, LGPD e Banco Central como obrigações que atravessam domínios, com Customer Consent como domínio próprio (aula 06).

**Módulo 3, o trabalho:** heatmap para ver onde os sistemas se sobrepõem e as fronteiras erradas que todo mundo desenha uma vez (aula 07). IA com grounding nas definições oficiais para rascunhar mapeamentos e contratos, humano decidindo e tudo medido (aula 08). E esta aula: agente com ferramentas por Service Operation, política, aprovação humana e avaliação contínua.

O exame final está na página do curso. Ele cobre os três módulos e, aprovado, libera o certificado. Faça sem consultar as aulas na primeira tentativa: a nota mostra o que ficou e o que pede releitura.

## Exame final

### Exame final: BIAN na prática

1. **Na versão 14 do BIAN, o que aconteceu com o Service Domain Payment Execution?**
- [ ] Continua registrado sem mudanças
- [ ] Foi renomeado para Payment Rail
- [ ] Foi fundido ao Current Account
- [ ] Foi marcado como obsoleto, com Payment Settlement como substituto anunciado

2. **Qual é o padrão funcional do Current Account?**
- [ ] Process
- [ ] Transact
- [ ] Fulfill
- [ ] Track

3. **O que é o Control Record de um Service Domain?**
- [ ] O registro que o domínio controla, resultado de padrão funcional aplicado a um tipo de ativo
- [ ] O contrato OpenAPI publicado pelo BIAN
- [ ] A tabela principal do banco de dados do sistema
- [ ] O log de auditoria exigido pelo regulador

4. **Quais action terms apenas leem, sem alterar estado?**
- [ ] Request e Exchange
- [ ] Retrieve e Evaluate
- [ ] Notify e Feedback
- [ ] Retrieve e Notify

5. **No Pix, qual Service Domain da v14 corresponde à resolução da chave consultada no DICT?**
- [ ] Payment Orchestration
- [ ] Payee Management
- [ ] Party Reference Data Directory
- [ ] Customer Consent

6. **Segundo o Banco Central, como o SPI liquida os pagamentos?**
- [ ] Por liquidação bruta em tempo real, transação por transação, sem saldo negativo nas Contas PI
- [ ] Em lotes compensados ao fim do dia
- [ ] Por liquidação diferida em D+1
- [ ] Pela bandeira do cartão

7. **Na Semantic API do BIAN, /CurrentAccount/{id}/DebitandCredit/{id}/Execute é:**
- [ ] Uma consulta, que usa GET
- [ ] Uma operação sobre o Behavior Qualifier DebitandCredit, que nos YAMLs v14 usa PUT
- [ ] Um evento assíncrono, sem método HTTP
- [ ] A criação de uma conta, que usa POST

8. **Qual afirmação descreve melhor a Resolução CMN 4.893 em outubro de 2026?**
- [ ] Está em vigor, com alterações posteriores, e no mapa vira restrição de implantação
- [ ] Foi revogada em 2025
- [ ] Criou o Service Domain de nuvem do BIAN
- [ ] Trata apenas do Pix

9. **Um modelo de linguagem sugeriu 'Credit Card Position Keeping' para um sistema de cartões. O que fazer?**
- [ ] Criar um domínio próprio com esse nome
- [ ] Rejeitar no validador, porque na v14 o domínio se chama Card Transaction Tracking
- [ ] Aceitar, porque o nome parece oficial
- [ ] Pedir ao modelo que confirme

10. **Qual é o erro do '340 microsserviços'?**
- [ ] Usar menos serviços do que o BIAN recomenda
- [ ] Tratar cada Service Domain como um serviço obrigatório, trocando um monólito por custo de rede, deploy e plantão
- [ ] Publicar eventos em vez de APIs
- [ ] Ignorar a ISO 20022