Natureza-morta pictórica em azul e vermelho. Duas chaves de geometrias diferentes encontram cadeados de latão sobre pedestais. Cada par representa uma ação cujo efeito depende do contrato correto para aquela responsabilidade.

Parte 2 de 9 da série BIAN e arquitetura bancária. Nesta série, vamos seguir jornadas bancárias para entender onde cada responsabilidade começa, termina e passa para outra equipe.

O serviço devolveu sucesso. Antes de comemorar, eu perguntaria o que esse sucesso permite prometer à pessoa do outro lado da tela.

Na oficina de contrato eu mostro uma resposta de sucesso e peço às três equipes que me digam o que acabou de acontecer. O canal diz «conta aberta». O serviço de abertura diz «pedido aceito». O núcleo ainda está processando a solicitação. Eu preciso escolher o que a próxima versão pode prometer para a cliente. Nesta parte da série de BIAN e arquitetura bancária, vou partir da intenção de iniciar uma abertura para desenhar a resposta, a repetição e a consulta de estado no nosso banco hipotético.

Eu usaria as APIs semânticas do BIAN para ajudar o time a definir o significado da interação. O guia associa operações a domínios de serviço e descreve termos de ação usados para expressar suas intenções. O cenário de referência da conta corrente ajuda a discutir o que é iniciado e qual responsabilidade de negócio executa a ação. Guia de APIs semânticas do BIAN · Operação de iniciação em Current Account

Da intenção de negócio ao contrato local

Antes de olhar os campos do JSON, eu sentaria com Produto, Operações, Riscos e as equipes do canal e da abertura de contas. Pediria que cada uma descrevesse o resultado que consegue comprovar. Elegibilidade consegue demonstrar a decisão e a política considerada. Oferta consegue demonstrar os termos aceitos. A abertura consegue demonstrar a situação da solicitação e, depois, a disponibilidade da conta. O canal reúne essas informações para orientar a cliente.

A expressão “iniciar abertura” admite uma execução que continua após a resposta ao canal. No contrato local deste exemplo, iniciar cria um registro rastreável de abertura e coloca o trabalho em andamento. Consultar recupera o estado atual. Disponibilizar a conta é um resultado que depende da confirmação pelo responsável pelo produto, com as condições locais que tornam a conta utilizável. Eu manteria essas três ideias visíveis nos exemplos e testes da API.

Fluxograma da abertura. Observe quais condições autorizam iniciar e qual confirmação permite apresentar a conta.

Figura 1. Fluxograma da abertura. Observe quais condições autorizam iniciar e qual confirmação permite apresentar a conta.

Gotas, discos e selos de cera ocupam posições sucessivas sobre uma pedra, com um carimbo ao centro.

Natureza-morta de luz baixa. Gotas, discos e selos de cera ocupam posições sucessivas sobre uma pedra, com um carimbo ao centro. A progressão material distingue registrar a intenção, aceitar o trabalho e confirmar o resultado.

Desenhe uma resposta que o consumidor consiga interpretar

Eu faria a operação assíncrona do exemplo retornar HTTP 202 quando a solicitação for aceita para processamento, junto de uma referência consultável. A semântica do HTTP 202 permite comunicar aceitação sem confirmar que o processamento terminou. A rota e os campos a seguir pertencem ao banco hipotético. IETF, RFC 9110 sobre HTTP 202

POST /aberturas-conta Idempotency-Key: abertura-req-80271 Content-Type: application/json { "solicitacaoId": "req-80271", "ofertaAceitaId": "of-314", "decisaoElegibilidadeId": "el-659" } HTTP/1.1 202 Accepted Location: /aberturas-conta/ab-217 Content-Type: application/json { "aberturaId": "ab-217", "estado": "EM_PROCESSAMENTO" } 

Com a referência em mãos, o canal pode consultar o registro e mostrar o último estado confirmado. Quando a abertura terminar, a consulta apresenta a conta disponível e uma referência apropriada para o próximo passo. Eu escreveria um exemplo de resposta para cada estado que exija comportamento diferente do canal. Em uma pendência de análise, por exemplo, a interface informa que a solicitação está em revisão. Uma oferta expirada pede nova confirmação antes de iniciar outra abertura. Essas mensagens ficam mais fáceis de revisar quando quem controla cada estado participa da conversa.

No aceite da chamada, o serviço de abertura verifica se a oferta identifica a mesma solicitação e se a decisão de elegibilidade ainda é válida. Se a política permitir que uma decisão expire após o início, eu pediria que o time especifique quem pode revogá-la e qual ação é esperada em cada ponto do processo. A regra precisa ser visível a quem atende o caso, sem expor documentos pessoais além do necessário. Para um pedido novo com formato válido e precondição de negócio não atendida, este contrato local retorna HTTP 422 com o motivo e a orientação para regularizar o pedido. Uma repetição idêntica de um pedido já aceito recupera o registro existente. IETF, RFC 9110 sobre HTTP 422

Diagrama de sequência do aceite. Compare a resposta com referência de consulta à confirmação posterior do núcleo.

Figura 2. Diagrama de sequência do aceite. Compare a resposta com referência de consulta à confirmação posterior do núcleo.

Faça a repetição encontrar o mesmo resultado

Se a resposta inicial se perder, o canal pode repetir a solicitação com a mesma chave no escopo acordado. Eu persistiria a chave, a referência da abertura e os dados relevantes do pedido na mesma transação que confirma seu registro local. A publicação do trabalho pode sair de uma tabela de saída transacional. Uma restrição de unicidade ajuda duas chamadas concorrentes a convergir para o mesmo registro.

Essa proteção local precisa de uma garantia correspondente na fronteira com o sistema central. Se o processo parar depois de enviar a instrução, a retomada deve poder consultar o resultado pela referência de origem ou repetir uma operação que o sistema central garanta como idempotente. Se uma consulta inconclusiva deixar dúvida sobre a gravação, eu enviaria o caso para conciliação e guardaria os sinais observados. Uma chave reutilizada com dados diferentes recebe tratamento de conflito e preserva o pedido original.

Diagrama de estados da abertura. Veja quais situações a consulta deve deixar claras para o consumidor.

Figura 3. Diagrama de estados da abertura. Veja quais situações a consulta deve deixar claras para o consumidor.

Uma mudança de significado precisa aparecer também no plano de evolução. Imagine que o banco oferece um produto para o qual a conta só pode ser usada depois de uma confirmação adicional de acesso. Eu pediria à equipe que registre essa precondição no domínio responsável e documente como ela aparece na consulta. Se o canal não consegue interpretar um estado novo, precisamos combinar uma versão de contrato ou uma transição compatível. Durante a migração, eu mediria quantas consultas passam por cada versão e que tipos de aplicativo ainda dependem do comportamento antigo.

Também combinaria o prazo em que a chave de repetição pode ser usada. Uma retomada depois desse prazo deve localizar o histórico pelo identificador de negócio ou abrir uma investigação. O contrato precisa permitir que atendimento e desenvolvimento deem a mesma orientação quando a cliente volta dias depois.

Teste o significado em conjunto

Eu marcaria uma sessão curta com desenvolvimento do canal e da abertura, testes e atendimento. Rodaria uma oferta válida, uma oferta vencida e uma solicitação cujo retorno foi perdido após a criação da conta. Em cada caso, pediria a alguém do canal que diga o que a cliente vai ver e a alguém da operação que encontre o resultado pela referência. Rodaria também duas chamadas concorrentes com a mesma chave e uma terceira com a mesma chave e dados incompatíveis. O resultado esperado é uma única solicitação efetiva e uma explicação clara para a divergência.

Durante o piloto, registraria o tempo entre recebimento da solicitação completa e disponibilidade real da conta. Acompanharia também pendências em conciliação e mensagens emitidas pelo canal. Assim, consigo relacionar o contrato ao compromisso de um dia útil. Se a conta permanece indisponível, o time sabe qual estado pode afirmar, em qual registro procurar e quem tem autoridade para agir.

Essa é a conversa que quero que uma API semântica facilite. Quando o produtor e o consumidor conseguem narrar o mesmo caso, inclusive quando a resposta se perde, o contrato virou uma ferramenta de trabalho para o banco.

Faça a oficina começar com os fatos que cada domínio consegue confirmar

Eu levaria à reunião três solicitações sintéticas. Na primeira, a oferta está válida e a política aceita a abertura. Na segunda, a pessoa aceitou os termos, mas a decisão exige revisão. Na terceira, a abertura já foi enviada ao sistema central e a confirmação está atrasada. Peça a cada área que diga o que pode confirmar e qual efeito está autorizada a provocar. Quando duas áreas usarem o mesmo verbo para acontecimentos diferentes, registre o assunto em linguagem de negócio e volte ao catálogo do BIAN para localizar o domínio e os termos das operações relacionados à discussão.

O exemplo fica mais fácil de testar depois de separarmos a solicitação, a oferta aceita, a decisão de elegibilidade, o pedido de abertura e a conta. A conta tem um ciclo de vida diferente do pedido que a originou. Há solicitações que não chegam à criação de conta e pode haver uma etapa de disponibilização depois da criação do registro. Eu pediria a cada equipe que esclarecesse qual identificador nasce na sua fronteira, o que permanece estável em novas tentativas e como uma pessoa consegue seguir a relação em caso de suporte. As referências são opacas para consumidores que não têm permissão sobre o domínio de origem.

Diagrama entidade-relacionamento da API local. Siga as relações entre solicitação, oferta, decisão, abertura e conta.

Figura 4. Diagrama entidade-relacionamento da API local. Siga as relações entre solicitação, oferta, decisão, abertura e conta.

Eu manteria o documento de mapeamento com a edição concreta da referência, o cenário adotado e o efeito local de cada operação. Caso uma operação do catálogo dê nome à intenção de início, use esse nome na conversa e deixe a rota, os estados e os códigos de resposta no contrato do banco. O mapeamento precisa registrar também os pontos em que usamos uma decisão local, como exigir oferta aceita antes do início e emitir uma resposta assíncrona. Quando o time atualiza a versão da referência, consegue verificar se um termo mudou e de que forma isso afeta o uso local.

Descreva o contrato que o atendimento vai conseguir usar

Imagine que a primeira mensagem ao consumidor traga a referência, a condição de processamento e o horário esperado para a próxima atualização. A consulta pode mostrar que a solicitação está em andamento mesmo quando o núcleo já aceitou a instrução. A discussão principal é qual evidência autoriza mudar o estado. Para a conta ficar disponível, o banco precisa confirmar a criação, a habilitação e o que a política local exige para aquela jornada. Eu incluiria esses critérios no catálogo de estados e nos testes com atendimento.

A seguir, um recorte em OpenAPI descreve uma interação local simplificada. Os estados da resposta foram escolhidos para ensinar quais ações a pessoa consumidora precisa executar. Uma implementação completa adicionaria autenticação, escopos, erros padronizados e requisitos de observabilidade. A tabela de transição da equipe precisa tratar também interrupções e revisões de política.

openapi: 3.1.0 info: title: Aberturas de conta do banco hipotético version: 1.0.0 paths: /aberturas-conta/{aberturaId}: get: operationId: consultarAbertura parameters: - name: aberturaId in: path required: true schema: type: string responses: "200": description: Estado conhecido pelo serviço de abertura content: application/json: schema: type: object required: [aberturaId, estado, atualizadoEm] properties: aberturaId: type: string estado: type: string enum: [EM_PROCESSAMENTO, EM_REVISAO, DISPONIVEL] atualizadoEm: type: string format: date-time "404": description: Abertura não encontrada no escopo consultado 

Eu levaria esse exemplo ao pessoal que conhece os chamados. Imagine uma usuária que vê «em revisão» por dois dias. O atendimento pode consultar o horário e identificar a próxima ação sem conhecer o texto da regra completa? Se houver diferença entre revisão que depende de um documento novo e revisão interna, descubra se os públicos precisam de um código de motivo ou de outro parâmetro. Em ambos os casos, avalie quais detalhes podem ser mostrados a cada pessoa. O contrato precisa orientar comportamento, preservar as evidências autorizadas e evitar que o aplicativo tente adivinhar uma decisão olhando só o tempo decorrido.

Diagrama de jornada do canal. Observe a pergunta que Atendimento ou Operações precisa responder em cada etapa.

Figura 5. Diagrama de jornada do canal. Observe a pergunta que Atendimento ou Operações precisa responder em cada etapa.

Preserve o significado diante de concorrência e indisponibilidade

Eu faria um exercício em que o aplicativo reenvia o mesmo pedido ao mesmo tempo que alguém do atendimento tenta confirmar o estado. Se duas chamadas usam a mesma chave e o mesmo conteúdo, precisam encontrar a mesma abertura. Se a chave aparece com conteúdo diferente, o serviço preserva o registro original e responde conforme o contrato de conflito. A comparação pode usar uma representação estável dos parâmetros com sua versão. Campos gerados a cada tentativa, como a hora do envio, precisam ser avaliados antes de entrar nessa representação.

O banco também deve definir por quanto tempo preserva uma referência de repetição. Uma expiração prematura pode deixar de reconhecer uma tentativa antiga que volta após uma demora longa. Uma retenção indefinida pode aumentar obrigações de armazenamento sem necessidade. Eu diria por quanto tempo o serviço garante a recuperação do resultado, o que o consumidor faz depois do prazo e quando uma pessoa precisa consultar o registro de origem. A decisão precisa incluir a conciliação com o sistema central, cuja referência pode ter ciclo de vida diferente.

CREATE TABLE abertura_local ( abertura_id uuid PRIMARY KEY, solicitacao_id text NOT NULL UNIQUE, escopo text NOT NULL, chave_idempotencia text NOT NULL, impressao_payload text NOT NULL, estado text NOT NULL CHECK (estado IN ( 'EM_PROCESSAMENTO', 'EM_REVISAO', 'DISPONIVEL' )), criada_em timestamptz NOT NULL, UNIQUE (escopo, chave_idempotencia) ); CREATE TABLE trabalho_de_abertura ( trabalho_id uuid PRIMARY KEY, abertura_id uuid NOT NULL UNIQUE REFERENCES abertura_local, proxima_tentativa_em timestamptz NOT NULL, finalizado_em timestamptz ); 

No recorte SQL, uma nova abertura e a publicação pretendida devem ser registradas com sucesso na mesma transação. A equipe ainda precisa implementar a distinção entre conflito de chave e conflito de solicitação e o tratamento da concorrência. Um conflito de unicidade sozinho não define uma resposta correta para o canal. Eu definiria quem lê o registro persistido, como ele verifica se a impressão coincide e quais detalhes pode compartilhar. Para a publicação, a restrição ajuda a evitar duas instruções locais para o mesmo registro. A execução externa segue sujeita ao contrato que o núcleo oferece.

Diagrama de sequência da repetição. Siga como a transação local permite devolver a mesma referência após a perda da resposta.

Figura 6. Diagrama de sequência da repetição. Siga como a transação local permite devolver a mesma referência após a perda da resposta.

O exemplo acima distingue a perda da resposta ao canal da perda da resposta do núcleo. Um teste para a primeira falha permite recuperar a referência local. Para a segunda, o banco consulta a operação externa. Se essa consulta não fizer parte do contrato, deixe previsto que uma pessoa autorizada deverá conciliar. Um estado provisório pode preservar a experiência sem ocultar um trabalho pendente. Eu levaria os dois casos à homologação e pediria a quem opera que descreva a diferença em termos usados no painel.

Revise a compatibilidade com um consumidor que já existe

Suponha que uma versão futura acrescente o estado «AGUARDANDO_HABILITACAO». Alguns consumidores aceitam valores desconhecidos e mostram uma situação genérica. Outros encerram a consulta com erro. Antes de divulgar uma nova versão, eu verificaria os leitores em produção e escolheria um plano de coexistência. O banco pode acrescentar um motivo detalhado mantendo os estados externos, ou publicar uma nova versão com um cronograma de migração. A escolha depende de quais comportamentos os consumidores precisam distinguir e de como a operação já usa a resposta.

Diagrama de estados da evolução do contrato. Veja a condição para aposentar a versão anterior depois da coexistência.

Figura 7. Diagrama de estados da evolução do contrato. Veja a condição para aposentar a versão anterior depois da coexistência.

Um caso hipotético de revisão usa cem solicitações distribuídas entre estados. Noventa e oito passam em ambas as versões. Duas ficam sem atualização porque um consumidor antigo interpreta um estado novo como terminal. Eu suspenderia a liberação para esse grupo e verificaria como o caso opera quando a atualização chega em atraso. A medida de compatibilidade inclui também se o atendimento recebe um sinal utilizável e se a situação apresentada ao cliente corresponde ao que o núcleo confirmou. As duas amostras ajudam a decidir entre trabalhar no consumidor, ajustar a exposição do novo estado ou manter uma versão de transição.

Canais dourados saem de uma entrada e alcançam cavidades azuis distintas.

Composição geométrica de inspiração em mosaico. Canais dourados saem de uma entrada e alcançam cavidades azuis distintas. Os ramais dão forma aos resultados que uma operação pode comunicar sem perder a responsabilidade pelo significado de cada um.

Confira responsabilidades na hora de autorizar uma mudança

No fim do piloto, eu pediria uma validação com Produto, Operações e as pessoas que assinam o contrato de integração. Primeiro mostre uma consulta que encontra o pedido depois de uma falha de rede. Segundo, demonstre que um pedido com oferta expirada entra no tratamento previsto quando ainda não existe abertura. Terceiro, confirme que uma conta aparece como disponível no canal apenas quando o resultado respeita a definição acordada. Esses três exemplos ajudam a documentar o significado com situações que cada área reconhece.

Para o caso mais demorado, prefiro que alguém do atendimento explique o que a pessoa pode fazer agora e quando terá nova informação. Se o contrato só ajuda a dizer «recebemos um 202», há trabalho a fazer no vocabulário do domínio e nos eventos que abastecem a consulta. Uma equipe pode escolher um resultado técnico válido em cada etapa e ainda precisar melhorar a forma como comunica a situação. A conversa sobre semântica termina quando as fronteiras, os comportamentos e as evidências ajudam as pessoas a agir da mesma forma diante da mesma solicitação.

Dê aos contratos de teste exemplos que tenham dono

Eu escreveria um contrato de consumidor com Produto e Atendimento para demonstrar o que muda quando alguém consulta um pedido em andamento. O cenário inicial responde com uma referência estável e o estado esperado. A consulta confirma que o mesmo identificador aparece depois da repetição. Um segundo teste começa com a habilitação confirmada e verifica que os dados apresentados correspondem ao mesmo caso. Um terceiro reproduz a recusa quando falta uma precondição. A ordem dos testes importa na preparação do ambiente. Cada conjunto de dados deve começar com sua própria referência para que o sucesso de um não esconda o estado de outro.

Funcionalidade: Consultar o estado da abertura Cenário: A indisponibilidade do canal não cria novo pedido Dado que a oferta foi aceita e a decisão é válida E que o serviço registrou a abertura antes de perder a resposta Quando o canal repetir a mesma chave e os mesmos parâmetros Então ele recebe a referência de abertura original E a consulta apresenta o estado conhecido da mesma referência Cenário: A aprovação ainda aguarda disponibilização Dado que existe uma abertura em processamento E que o núcleo ainda não confirmou a habilitação Quando o canal consultar a abertura Então a conta continua em processamento 

Se a equipe usar esse exemplo para automatizar a verificação, eu perguntaria o que acontece quando a regra do negócio muda. O cenário com aprovação pode estar correto para um produto e inadequado para outro que exige uma condição adicional. Os parâmetros do cenário indicam o produto e a versão da política. O contrato pode preservar o mesmo significado de «disponível» e variar as evidências internas que permitem chegar a ele. Isso evita discutir cada novo produto como se a API tivesse de adotar outra linguagem.

Revise o mapa de operações com uma mudança concreta

Imagine que o banco queira permitir que a titular escolha uma data de início futura. A decisão de elegibilidade já existe, e o aceite dos termos está guardado. Agora o início da abertura e o momento de enviar o trabalho ao núcleo deixam de coincidir. Eu pediria que as pessoas responsáveis revisassem as intenções e os registros antes de alterar o esquema. «Agendada», «aceita para processamento» e «disponível» podem ter implicações diferentes para o atendimento e para o compromisso de prazo. O contrato informa qual segmento usa a jornada de um dia útil e quando a contagem começa nessa condição.

Eu anotaria no documento quais resultados ficam sob responsabilidade do domínio de oferta, da abertura e do canal. A abertura pode registrar o pedido e a data pretendida. A oferta ainda precisa provar quais termos foram aceitos. A política pode aplicar uma revalidação perto da data. Em caso de mudança, preserve a evidência que motivou o novo estado e informe onde a cliente pode conferir a situação. Essa leitura ajuda a traduzir o catálogo de operações em escolhas que a equipe pode testar.

Por fim, eu guardaria um mapa simples do efeito da mudança. Um consumidor que depende de um estado terminal precisa verificar se a nova condição continua pendente para sua finalidade. O atendimento precisa saber a primeira ação que pode tomar. O núcleo precisa aceitar uma referência depois de um período maior do que no fluxo imediato. Se uma dessas respostas ainda não estiver clara, proponha uma observação antes de ampliar o contrato. A referência semântica ajuda a começar a conversa. A operação revela onde a equipe precisa torná-la mais precisa.

Observe a mudança depois da primeira liberação

Eu acompanharia quantas consultas acontecem antes e depois de cada transição e quantos casos a operação precisou explicar sem encontrar o próximo passo na resposta. Um aumento de consultas pode refletir que o aplicativo está repetindo a pergunta com frequência demais. Também pode indicar que as confirmações chegam tarde. Compare esses grupos com as marcas do núcleo e escolha qual espera tratar primeiro. Ao atualizar o contrato, mantenha um exemplo da situação anterior, para que as equipes consigam comparar o que ficou mais claro.

Ao levar o resultado para outra área do banco, eu pediria que ela descrevesse onde termina sua responsabilidade e onde começa a próxima. Um termo reconhecível ajuda a conversa, mas a prova está no que a equipe consegue demonstrar durante uma consulta ao pedido. A pessoa que trabalha com oferta pode provar os termos aceitos. A abertura precisa mostrar o estado e a evidência de seu próprio resultado. O canal precisa dizer o que a cliente pode fazer. Esse exercício também revela se alguma mudança exige revisão conjunta antes de ser considerada apenas uma nova versão técnica.

Dê ao consumidor uma maneira de interpretar a falta de resposta

Num cenário hipotético eu faria o canal perder a resposta inicial enquanto o serviço já confirmou o registro local. A cliente entra novamente pelo navegador. Se as duas sessões enxergarem referências diferentes, o atendimento terá de decidir qual estado explica o trabalho real. Eu pediria que os dois caminhos preservassem uma referência à mesma intenção válida, de acordo com a política de titularidade e autorização do banco. O teste comprova que a segunda resposta mostra a abertura existente e que a trilha local permite ver por que as duas chamadas pertencem à mesma solicitação.

Na revisão da documentação, eu leria também a resposta para uma consulta enquanto a confirmação ainda depende do núcleo. A previsão ou a instrução de aguardar pode mudar; o significado de «aceito» permanece. Quero que a pessoa consumidora possa atualizar a interface sem inferir sucesso definitivo pela duração da espera.

A preparação do texto e a criação das ilustrações tiveram apoio de IA generativa.