Este episódio é a versão em áudio de "System Design: As partes difíceis!". Mesmo argumento, outro formato: dá para ouvir no deslocamento, na academia ou enquanto o build roda.

Aqui eu preciso ser honesto sobre o método: o áudio foi gerado com apoio de IA, a partir do texto original do artigo. O argumento, os exemplos e as analogias são os mesmos que escrevi — a conversa é que é sintética. Se isso te incomodar, o texto continua inteiro no link lá embaixo.

O que você vai ouvir

• Resiliência de sistema: blindar o usuário do atrito entre o síncrono e o assíncrono.

• Rompendo silos: o contrato de integração (API First) como acordo único entre times que não se falam.

• Falando a língua do negócio: ROI de componente reutilizável contra prazo rígido de projeto.

• Gestão de mudança: evoluir a arquitetura sem quebrar o que já está em produção.

• Assimetria técnica entre squads: desenhar para o time que existe, não para o time ideal.

• Engenharia de conflitos: a PoC como atalho legítimo para a burocracia dos comitês.

O fio que costura os seis é o mesmo. Num ecossistema corporativo fechado, você não uniformiza os navios. Você padroniza o ponto de encaixe entre eles.

Pense comigo:

1. Quantos dos seus fluxos hoje são síncronos porque a regra de negócio exige, e quantos porque ninguém nunca reescreveu?

2. Se o squad vizinho precisasse integrar com o seu serviço amanhã, ele conseguiria fazer isso lendo só o contrato?

3. Qual foi a última decisão arquitetural do seu time que virou decisão porque alguém levou uma PoC, e não um slide?

O texto completo, com os trade-offs de cada frente e a parte sobre como comunicar cada uma delas, está em System Design: As partes difíceis!.

E aí: no seu contexto hoje, qual dos seis é o mais difícil — o legado, a burocracia dos comitês ou a assimetria entre os times? Responde nos comentários.

Se você nunca contratou um, consignado é o empréstimo em que a parcela é descontada direto do salário ou da aposentadoria, antes de o dinheiro chegar à conta. Quem entrega a parcela ao banco não é a dona Lurdes: é o INSS, que paga o benefício dela. Para o banco, isso quase elimina o risco de calote. Para ela, significa uma das taxas de juros mais baixas do mercado.

Só que, para o desconto acontecer, o banco precisa avisar ao INSS: "deste benefício, R$ 190 por mês agora são meus". Esse aviso tem nome, averbação1, e passa pela Dataprev2, a empresa que processa os dados da Previdência.

A proposta sai do sistema do banco em direção à Dataprev. A resposta demora. Depois de 30 segundos sem retorno, o sistema desiste de esperar, o famoso timeout, e faz exatamente o que foi programado para fazer: tenta de novo. A segunda tentativa também não volta. Aí entra a última regra do fluxo, escrita meses antes por alguém que queria evitar proposta travada no fim de semana: se a averbação não responder em duas tentativas, segue para o desembolso e concilia na segunda-feira.

Segunda-feira de manhã, o atendimento abre dois chamados. No primeiro, a margem da dona Lurdes aparece com duas parcelas reservadas e um único depósito de R$ 8.000 na conta: ela vai pagar R$ 380 por mês por um empréstimo cuja parcela é R$ 190. A Dataprev tinha recebido os dois pedidos e estava apenas lenta para responder.

No segundo chamado, outro cliente recebeu o dinheiro via Pix e a margem dele nunca foi reservada: ali os dois pedidos morreram no caminho, e a Dataprev nunca soube que existiram. Na folha seguinte, não vai haver parcela para descontar.

Ninguém escreveu um bug no sentido clássico. Os testes passavam. O código fazia o que dizia. O problema estava no modelo: ele não tinha onde guardar a pergunta "a Dataprev recebeu o meu pedido ou não?".

O contrato estava perfeito no banco de dados do banco e não existia no único lugar que importava.

Uma única regra de timeout, dois incidentes opostos. A diferença entre eles não estava no código: estava num fato que o código não tinha como saber, se o pedido chegou do outro lado ou não. Sem lugar para guardar essa dúvida, o sistema foi obrigado a chutar. Chutou duas vezes, e errou nas duas direções possíveis.

A cena é fictícia; os ingredientes, não. Este artigo é sobre por que isso acontece com consignado, com financiamento de carro, com antecipação de recebível e com praticamente qualquer produto de crédito no Brasil, e sobre por que todos eles quebram do mesmo jeito.

Ele foi escrito para dois tipos de leitor. Se você trabalha com tecnologia, vai encontrar modelagem, estados e código. Se não trabalha, vai entender por que o seu empréstimo às vezes demora a cair, e por que a taxa de um crédito é tão diferente da de outro. As partes técnicas vêm sempre com uma tradução ao lado.

Antes de tudo: o que é crédito?

Crédito é dinheiro de hoje trocado por uma promessa de amanhã.

A palavra vem do latim credere, acreditar. Quem empresta acredita que o dinheiro vai voltar. E essa crença tem preço: os juros3, que pagam duas coisas ao mesmo tempo. Uma é o tempo, porque o dinheiro emprestado deixa de render para quem emprestou. A outra é o risco de a promessa não ser cumprida.

Muita gente usa crédito sem chamar pelo nome. A compra parcelada no cartão é crédito. O carnê da loja é crédito. O cheque especial que entra sozinho quando a conta fica negativa é crédito, e dos mais caros. Até o "parcelado sem juros" é crédito: alguém está financiando aquela compra, e o custo foi embutido no preço ou pago pela loja.

As duas perguntas de quem empresta

Imagine que um conhecido te pede R$ 500 emprestados. Antes de responder, você faz duas perguntas, mesmo sem perceber:

1. Essa pessoa vai me pagar? Você pensa no que sabe dela: se trabalha, se costuma honrar o que promete, se já te deu calote.

2. E se não pagar, o que eu faço? Se ela deixar o celular com você até devolver o dinheiro, você empresta mais tranquilo. Se não deixar nada, você pensa duas vezes, ou empresta menos.

Essas duas perguntas são o mercado de crédito inteiro. A primeira os bancos respondem com informação: histórico de pagamentos, renda, dívidas em aberto. A segunda eles respondem com garantia4: alguma coisa que o banco pode segurar se a promessa falhar.

Por que existem tantos tipos de crédito?

Porque existem muitas respostas diferentes para a segunda pergunta. Cada tipo de crédito é, no fundo, uma resposta diferente para "o que o banco pode segurar?".

• No consignado, o banco segura a parcela antes de ela chegar ao cliente, porque ela sai direto do salário ou do benefício.

• No financiamento de veículo, o banco segura o próprio carro. Ele fica no nome do banco até a última parcela.

• No crédito imobiliário e no home equity5, o banco segura o imóvel.

• Na antecipação de recebíveis, que é crédito para empresas, o banco segura o dinheiro que a loja ainda vai receber das vendas no cartão.

• No crédito pessoal, no cheque especial e no rotativo do cartão6, o banco não segura nada. Só tem a informação da primeira pergunta.

E a regra geral é intuitiva: quanto mais o banco consegue segurar, menos risco ele corre, e menor tende a ser a taxa. Com uma correção que importa mais do que parece: o que pesa não é ter garantia, é poder executá-la rápido e barato. Garantia que leva anos no Judiciário para virar dinheiro entra no preço quase como se não existisse, e é por isso que o carro, que vale muito menos que o apartamento, sustenta uma taxa melhor que o home equity.

Agora vem a parte que quase ninguém percebe, e que dá título a este artigo. O que torna um crédito barato é a garantia — e, em quase todos os casos, ela não está com o banco. O salário está na folha do INSS ou da empresa. O carro está registrado no Detran. O imóvel, no cartório. Para o crédito sair mais barato, o banco precisa reservar alguma coisa dentro de um sistema que não é dele.

Vale a exceção, porque ela prova o ponto: existe crédito barato cuja garantia está dentro de casa. No empréstimo com garantia de investimento, o banco bloqueia um CDB do próprio cliente, e a reserva vira uma linha numa tabela sua, com transação e UNIQUE. Todo este artigo deixa de existir. O problema nunca foi a garantia: é a fronteira. O custo de engenharia nasce no instante em que o recurso escasso passa a morar do lado de fora.

É aí que a conversa vira engenharia.

Um restaurante que não é seu

Quando um banco oferece crédito com garantia, ele está tentando reservar algo que não mora no seu próprio banco de dados.

Pense numa reserva de restaurante feita por telefone. Você liga, pergunta se tem mesa para quatro às 20h, pede para reservar e desliga. A mesa não é sua. O caderno de reservas fica no restaurante. A única coisa que você tem é a lembrança de que ligou.

Agora imagine que a ligação caiu no meio da frase "então fica reservado no nome de...". Você reservou ou não? Se ligar de novo e disser "quero uma mesa para quatro às 20h", pode sair com duas mesas no seu nome. A pergunta certa é outra: "vocês têm alguma reserva no nome Rafael?"

Só que essa pergunta tem uma condição escondida, e ela é a parte que mais se esquece: você só pode perguntar "tem reserva no nome Rafael?" porque disse o seu nome antes de a ligação cair. Se não disse nada que identifique o pedido, não existe pergunta a fazer. Existe apenas pedir de novo, e torcer.

Guarde essa diferença entre repetir o pedido e perguntar pelo pedido. Ela é o artigo inteiro.

Todo crédito com garantia segue os mesmos quatro movimentos:

1. Consultar se o recurso escasso está livre: a margem do aposentado, o carro sem restrição, o recebível ainda não comprometido.

2. Reservar esse recurso junto a quem guarda o registro oficial dele.

3. Liberar o dinheiro. Só a partir daqui o contrato existe de verdade.

4. Devolver, se o contrato não nascer. Este é o movimento que quase ninguém desenha, e é dele que sai o incidente que ninguém abre.

O que muda de um produto para outro são três características da contraparte7:

• Quem guarda a verdade. Um sistema central, dezenas de sistemas diferentes, uma entidade de registro, ou ninguém.

• Quanto demora e quando fecha. Milissegundos, horas ou dias, e com quais janelas de indisponibilidade.

• Se dá para desfazer. Existe desaverbação, baixa de gravame, cancelamento de registro? Em quanto tempo?

Com essas três perguntas, os produtos de crédito brasileiros se agrupam em quatro famílias. Antes de visitar cada uma, vale resolver o problema da dona Lurdes, porque ele aparece em todas.

Compartilhar

O estado que quase ninguém modela

Entre pedir a reserva e saber o resultado existe um intervalo, e o seu modelo precisa ter um nome para ele.

Antes de nomear o intervalo, a condição técnica que o torna tratável. A pergunta "você recebeu o meu pedido?" só existe se o pedido levar um identificador estável, gerado e gravado pelo banco antes da primeira chamada e repetido em toda tentativa e em toda consulta. É o seu nome na reserva do restaurante. Essa chave de correlação é o que separa um estado de desconhecimento, que você resolve depois, de um beco sem saída, em que você sabe que não sabe e não tem como descobrir.

No artigo sobre modelagem de dados, vimos que estados intermediários são cidadãos de primeira classe: dinheiro em trânsito precisa de endereço. Com a garantia é igual. Veja uma máquina de estados8 para a originação, que é o nome técnico para o nascimento de um contrato de crédito.

Se você não programa, leia o bloco abaixo como uma lista de situações possíveis para o contrato, na ordem em que acontecem. As frases depois de // são comentários explicando cada uma.

public enum OriginationStatus {
    PROPOSAL_CREATED,
    COLLATERAL_CHECKED,       // a snapshot, not a reservation: it can go stale
    RESERVATION_REQUESTED,    // sent with our correlation key; no answer yet
    RESERVATION_CONFIRMED,    // has an expiry date: the counterparty may drop it
    RESERVATION_REJECTED,
    RESERVATION_UNKNOWN,      // timeout: we do not know. Bounded in time, not forever
    RESERVATION_EXPIRED,      // confirmed, then aged out before the money left
    MANUAL_REVIEW,            // UNKNOWN hit its ceiling: a human owns it now
    DISBURSEMENT_SENT,        // reachable only from RESERVATION_CONFIRMED
    DISBURSEMENT_FAILED,      // the money never left: the reservation must go back
    RESERVATION_RELEASED,     // margin returned. The only honest end for a dead proposal
    ACTIVE,
    SETTLED,
    CANCELLED
}

Os estados CONFIRMED e REJECTED todo sistema tem. O RESERVATION_UNKNOWN quase nenhum tem, e é ele que representa a ligação que caiu. Sem esse estado, o sistema só tem duas mentiras à disposição, e nada o impede de contar as duas em sequência:

• tratar o timeout como falha e pedir de novo, o que pode gerar reserva duplicada;

• tratar o timeout como sucesso e liberar o dinheiro, o que pode gerar dinheiro sem garantia.

Foi exatamente o que o fluxo da sexta-feira fez, nessa ordem: pediu de novo e, sem resposta, liberou o dinheiro. Os dois chamados da segunda-feira não foram dois bugs diferentes. Foram a mesma omissão, vista por dois clientes com sortes diferentes.

Repare também no COLLATERAL_CHECKED, que existe por um motivo específico: consultar disponibilidade é tirar um retrato, não reservar nada. Entre o retrato e a reserva, a margem pode ter sido tomada, e o concorrente mais provável não é outro banco. É a sua própria casa. Duas propostas do mesmo CPF entrando por canais diferentes na mesma tarde consultam a mesma margem livre, as duas passam na validação e as duas pedem reserva. Se a soma não couber, a contraparte recusa uma delas num dia bom; se couber, ela aceita as duas e o cliente descobre no extrato. Por isso a reserva começa dentro de casa, com um bloqueio local da margem, com prazo de validade, antes de qualquer chamada externa. A fila de quem liga para o restaurante também é sua.

A regra que sai disso cabe numa linha: timeout não é falha nem sucesso. É desconhecimento, e desconhecimento se resolve consultando, não repetindo.

O incidente que ninguém abre: a reserva que ninguém devolve

Os dois chamados da segunda-feira têm um irmão silencioso, e ele é mais comum que os dois juntos. Entre RESERVATION_CONFIRMED e DISBURSEMENT_SENT existe uma janela em que a margem já está comprometida e o dinheiro ainda não saiu. Se o desembolso falha, se a análise reprova numa segunda passada, se o cliente desiste, ou se a proposta simplesmente morre no backlog, aquela fatia da renda fica presa a um contrato que nunca existiu.

Do lado do banco ninguém abre chamado: nenhum real saiu, nenhum painel ficou vermelho. Do lado do cliente, é um dos atendimentos mais frequentes do consignado, "minha margem está presa e eu não consigo contratar em lugar nenhum". É o caso da dona Lurdes de novo, com o prejuízo do outro lado do balcão.

Daí saem duas consequências de modelagem. A primeira: desfazer é um estado, não um script de emergência. Todo caminho que não termina em contrato ativo precisa passar por uma liberação explícita, com protocolo de volta da contraparte, exatamente como a reserva teve. A segunda: reserva confirmada tem prazo. Boa parte das contrapartes derruba a reserva sozinha se o contrato não for concluído em alguns dias, o que significa que RESERVATION_CONFIRMED não é um estado permanente. Ele envelhece. Quem trata essa confirmação como definitiva vai, em algum dia movimentado, desembolsar contra uma garantia que já caiu.

A mesma régua vale para o desconhecimento. RESERVATION_UNKNOWN precisa de teto. Consultar com intervalo crescente é correto por algumas horas; depois disso, continuar consultando é só uma forma elegante de nunca decidir. Vencido o teto, o contrato vai para revisão humana, com dono e prazo, e alguém avisa o cliente, porque do lado dele a proposta está parada sem explicação desde sexta-feira.

Pense comigo

Se a contraparte cair entre o seu pedido e a resposta dela, em qual estado do seu modelo o contrato fica? Se a resposta for "depende do log que a gente olhar", está faltando um estado.

O seu retry pergunta antes de repetir? Se não pergunta, ele não é retry. É um segundo contrato esperando para acontecer. E o pedido original leva uma chave que torne essa pergunta possível, ou você só tem o seu próprio id interno, que a contraparte nunca viu?

Existe algum caminho no código em que o dinheiro sai sem a reserva estar confirmada? Vale procurar hoje, porque em produção ele aparece de qualquer jeito. E o caminho inverso, que ninguém procura: existe algum em que a proposta morre e a margem fica reservada?

Deixe um comentário

Quatro jeitos de guardar a verdade

Os produtos de crédito brasileiros cabem em quatro arquétipos, definidos por quem guarda o registro da garantia. Cada um exige uma coisa diferente do seu sistema.

Arquétipo 1: uma contraparte central, e o calendário dela

Quando toda a verdade mora num lugar só, a integração fica mais simples e você passa a viver no ritmo de outra organização.

O consignado de aposentados e pensionistas sempre passou pela Dataprev. Em 2025, o consignado dos trabalhadores com carteira assinada foi pelo mesmo caminho. A Lei 15.179/2025 criou o programa Crédito do Trabalhador e acabou com os convênios individuais entre empresas e bancos. Hoje a consulta de margem, a averbação e o controle dos contratos passam por uma plataforma central, integrada ao eSocial9, à CTPS Digital e ao FGTS Digital. Para o trabalhador CLT, a margem é de até 35% da remuneração disponível.

E tem um detalhe do Crédito do Trabalhador que quase não aparece nas análises de arquitetura: a garantia não é só a margem. O programa usa também o FGTS do trabalhador, até 10% do saldo da conta mais a multa rescisória, como lastro para o caso de demissão. São duas reservas, em dois registros que não são seus, com prazos e regras de baixa diferentes: a folha, pelo eSocial, e o fundo, pelo FGTS Digital. Pelo mesmo motivo, a antecipação do saque-aniversário é arquétipo 1 em estado puro, só com outro recurso escasso: a parcela anual do FGTS, e quem guarda a verdade dela é a Caixa.

Do ponto de vista de arquitetura, isso é trocar dezenas de integrações ponto a ponto por um hub10. Antes, cada banco precisava de convênio com cada empresa. Agora, todos falam com um lugar só. É uma padronização excelente, com dois custos que costumam ser subestimados.

Primeiro custo: a padaria fecha para contar o caixa

Pense na padaria do bairro que, no fim do mês, baixa a porta por algumas horas para fechar o caixa. Ninguém compra pão nesse intervalo, e isso não é defeito: é o jeito de a padaria saber quanto vendeu.

A Dataprev faz algo parecido em escala nacional. Todo mês acontece a virada de competência11, um processamento em que ela consolida os contratos para que os descontos saiam certos na folha. No consignado CLT, durante esses 3 a 4 dias, averbação, simulação e consulta de margem ficam suspensas. No INSS existe o equivalente, a chamada maciça: o processamento mensal que fecha a folha de todos os beneficiários e recalcula a margem do mês seguinte.

Para o seu sistema, isso significa uma coisa: indisponibilidade planejada é requisito, não incidente. Se o fluxo trata "proposta aceita" e "contrato averbado" como o mesmo estado, a virada de competência aparece no monitoramento como um apagão mensal. Se trata como estados separados, ela vira uma fila que volta a andar sozinha quando o balcão reabre.

Segundo custo: a regra muda por medida provisória

2026 entregou o melhor exemplo possível. Até maio, aposentados e pensionistas do INSS podiam comprometer 45% do benefício: 35% com empréstimos, 5% com cartão de crédito consignado e 5% com cartão consignado de benefício, as rubricas RMC e RCC12. Em 19 de maio, a Medida Provisória13 1.355/2026 reduziu o total para 40% e acabou com a divisão. Virou uma margem única, usada livremente entre empréstimo e cartões.

A MP não foi convertida em lei pelo Congresso. Perdeu a validade em 31 de agosto, a regra anterior voltou, e a Dataprev começou o recálculo na noite de 1º de setembro.

Agora a parte que interessa a quem modela dados. Quem contratou durante a MP, usando a margem única, voltou para uma regra em que empréstimo só cabe em 35%. Parte desses beneficiários passou a aparecer com margem negativa. O contrato era válido quando nasceu e, pela regra de hoje, não caberia. Os dois fatos são verdadeiros ao mesmo tempo.

E a história não parou aí: o TCU, no Acórdão 1.094/2026, suspendeu novas averbações de cartão consignado até nova deliberação. Mais uma mudança de regra vinda de fora, sem aviso ao seu backlog.

Isso só é administrável se o sistema souber responder "qual regra valia na data em que este contrato foi assinado?". A resposta de modelagem é simples: o percentual da margem não é uma constante, é um dado com vigência.

Para quem não programa: o bloco abaixo cria uma tabela em que cada regra fica guardada junto com a data em que começou e a data em que deixou de valer. A última consulta pergunta "qual regra valia no dia em que este contrato foi assinado?".

CREATE TABLE consignable_margin_rule (
    id           BIGSERIAL     PRIMARY KEY,
    segment      VARCHAR(20)   NOT NULL,  -- INSS, CLT, SIAPE, BPC
    bucket       VARCHAR(20)   NOT NULL,  -- LOAN, RMC, RCC, UNIFIED
    max_ratio    DECIMAL(5,4)  NOT NULL,  -- 0.3500 = 35%
    valid_from   DATE          NOT NULL,
    valid_to     DATE,                    -- NULL = still in force
    legal_basis  VARCHAR(120)  NOT NULL
);
-- INSS in 2026, as it actually happened
-- (earlier history and the RMC/RCC rows omitted for brevity)
INSERT INTO consignable_margin_rule
  (segment, bucket, max_ratio, valid_from, valid_to, legal_basis)
VALUES
  ('INSS', 'LOAN',    0.3500, '2026-01-01', '2026-05-18', 'Lei 10.820/2003'),
  ('INSS', 'UNIFIED', 0.4000, '2026-05-19', '2026-08-31', 'MP 1.355/2026'),
  ('INSS', 'LOAN',    0.3500, '2026-09-01', NULL,         'Lei 10.820/2003 (MP expired)');
-- which rule applied to this contract on the day it was signed?
SELECT bucket, max_ratio, legal_basis
FROM consignable_margin_rule
WHERE segment = 'INSS'
  AND :signed_on BETWEEN valid_from AND COALESCE(valid_to, DATE '9999-12-31');

Se o percentual estava como constante no código, 2026 custou dois deploys de emergência em quatro meses, e ainda deixou a pergunta sem resposta para os contratos antigos. Se estava numa tabela com vigência, custou dois INSERTs.

Arquétipo 2: muitas contrapartes, muitos dialetos

Quando o mesmo conceito de negócio mora em dezenas de sistemas diferentes, o problema deixa de ser integrar e passa a ser traduzir.

O consignado de servidores públicos é o caso-limite. Os servidores federais têm a folha processada pelo SIAPE14. Estados e municípios têm os próprios sistemas, muitas vezes operados por empresas contratadas, cada um com portal, protocolo, layout de arquivo e regra de reserva diferentes. Para o banco, "reservar margem" é uma coisa só. Do outro lado, são dezenas de jeitos de dizer a mesma coisa.

O financiamento de veículos tem o mesmo desenho. A garantia precisa ser registrada no Detran do estado onde o carro está emplacado e no SNG15, o Sistema Nacional de Gravames operado pela B3, em que a financeira inclui, consulta e dá baixa na restrição. São 27 Detrans, e cada um tem suas particularidades.

O adaptador de tomada

Quem já viajou para outro país com um carregador de celular conhece a solução. Você não troca de carregador a cada fronteira. Você leva um adaptador que encaixa na tomada local e, quando a tensão também muda, um conversor junto, e o seu aparelho continua recebendo sempre a mesma coisa.

Em arquitetura, esse adaptador tem nome: Anti-Corruption Layer16, que já discutimos aqui aplicado à integração entre o Pix e o core bancário. O seu domínio fala uma língua só, e cada contraparte ganha um adaptador que traduz o dialeto dela. E traduzir aqui não é converter formato de arquivo: é converter significado. Quando um estado chega como "em processamento" e outro como "pendente de confirmação", alguém precisa decidir se os dois querem dizer a mesma coisa no seu modelo. Essa decisão é a camada; deixá-la implícita é como importar o vocabulário de 27 órgãos para dentro do seu domínio.

Em linguagem comum: o código abaixo define as quatro perguntas que o banco sabe fazer a qualquer contraparte (reserve, qual o status, desfaça, o que você suporta), sem se importar com o jeito que cada uma responde por dentro. A segunda parte lista as quatro respostas possíveis para a pergunta de status: reservei, recusei, não tenho nada com essa chave, e não consigo responder agora.

public interface CollateralRegistry {

    // Ask the counterparty to reserve. The request carries OUR correlation key,
    // persisted before this call. A timeout here is not a failure.
    ReservationReceipt reserve(ReservationRequest request) throws TimeoutException;

    // "Do you have anything under this correlation key?"
    // Four answers, never two. "I cannot tell you now" is not the same as "nothing here".
    StatusAnswer status(CorrelationKey key);

    // Undo: cancel the payroll deduction, lift the lien, release the encumbrance.
    // Idempotent, and retried until acknowledged.
    void release(ReservationId reservationId);

    // Declared, not assumed: is status() authoritative or eventually consistent?
    // How long before a NOT_FOUND can be trusted? Maintenance windows?
    // Does it support file reconciliation, and how long may a reservation sit unused?
    CounterpartyCapabilities capabilities();
}

sealed interface StatusAnswer {
    record Reserved(ReservationReceipt receipt, Instant expiresAt) implements StatusAnswer {}
    record Rejected(String reason)                                 implements StatusAnswer {}
    record NotFound(Instant observedAt)                            implements StatusAnswer {}
    record Unavailable(Instant retryAfter)                         implements StatusAnswer {}
}

O detalhe que costuma faltar é o método status. Toda contraparte responde a um pedido de reserva. Nem toda oferece um jeito de perguntar "você recebeu isto?". Quando não oferece, o adaptador precisa de um plano B, geralmente conciliação17 por arquivo no dia seguinte. E esse plano precisa estar escrito no adaptador, não na cabeça de quem o construiu.

E tem um detalhe mais fino, que é onde eu já vi time competente escorregar depois de acertar tudo o resto: NOT_FOUND não é prova de que nada chegou. Se a contraparte grava de forma assíncrona, se a sua consulta cai numa réplica atrasada, ou se o pedido ainda está numa fila do outro lado, a resposta "não tenho nada com essa chave" é um falso negativo. Reenviar na hora reproduz exatamente a reserva duplicada que você estava tentando evitar, agora com a consciência tranquila de quem consultou antes.

A correção é barata: NOT_FOUND só autoriza reenvio depois de um intervalo mínimo declarado pela contraparte, ou depois de duas consultas consistentes separadas no tempo. É para isso que existe o capabilities(), que na maioria dos sistemas é um método decorativo: ele precisa responder se o status é autoritativo ou eventual, e quanto tempo é preciso esperar antes de acreditar numa ausência.

Vale o mesmo cuidado na forma da resposta. Se "não consigo responder agora" chega ao seu código do mesmo jeito que "não tenho nada", você voltou a ter duas opções onde existem quatro, e o desconhecimento desapareceu do modelo no último metro, justamente na fronteira em que ele nasce. Estado de primeira classe no banco de dados e ausência indistinta no contrato da integração é meio caminho.

Tem outra consequência: monitoramento agregado mente. "99% de sucesso na averbação" pode esconder um estado inteiro fora do ar. Cada adaptador precisa do próprio painel, do próprio SLA18 e do próprio alarme.

Pense comigo

Quantos lugares do seu código conhecem o nome de uma contraparte específica? Se for mais de um, a próxima mudança de layout vira projeto.

Se amanhã um Detran mudar o formato do retorno, quantos serviços você precisa publicar de novo? A resposta certa é um.O seu painel mostra a taxa de erro por contraparte ou só a média de todas? E alguma contraparte do seu catálogo declara, em código, se o status dela é confiável no mesmo instante, ou isso é conhecimento que vive na cabeça de duas pessoas?

Arquétipo 3: a garantia que só existe quando o mundo sabe

Em algumas garantias, o registro não é uma burocracia que vem depois do contrato. É o que faz a garantia valer.

Voltemos ao carro. Na alienação fiduciária19, o banco é o dono do veículo até a última parcela e o cliente é quem usa. Só que isso só vale perante terceiros depois que o gravame20 está registrado no órgão de trânsito. Sem o registro, alguém pode comprar o carro de boa-fé, ou outro banco pode aceitá-lo como garantia de um segundo empréstimo, e o seu contrato não impede nenhuma das duas coisas.

A analogia é o ingresso de show com QR code. O papel na sua mão não prova nada. O que prova é a catraca validar o código contra a base do organizador e barrar a segunda pessoa que aparecer com a mesma imagem.

Três catracas, três velocidades

• Veículo. Registro no Detran e no SNG, com resposta eletrônica em segundos ou minutos.

• Imóvel. Registro na matrícula, no Cartório de Registro de Imóveis. Desde a Lei 14.382/2022, os cartórios estão interligados pelo SERP21, mas o prazo continua em dias: 10 dias úteis para títulos de alienação fiduciária de imóveis, e 5 dias úteis quando o título eletrônico estruturado chega pelo sistema.

• Recebíveis22. Registradoras23 autorizadas pelo Banco Central, como CERC, TAG e Núclea, registram as agendas de cartão e as duplicatas24. O arcabouço começou com a Resolução CMN 4.734 e existe para dar publicidade e impedir que o mesmo recebível seja onerado25 duas vezes.

A mesma operação de reserva vai de segundos a semanas conforme o bem. Um sistema que trata as três com o mesmo timeout de 30 segundos não está simplificando; está errando em duas delas.

Mas a conclusão arquitetural importa mais que a escolha do número. Acima de alguns minutos, reserva deixa de ser chamada e passa a ser processo. Alguém precisa guardar o pedido, acordar sozinho depois, consultar ou receber o callback, e sobreviver a deploy, a reinício de serviço e a fim de semana. Timeout é a ferramenta errada para um prazo de 10 dias úteis: ali não existe "esperar a resposta", existe um protocolo em aberto, com dono, prazo e alarme no vencimento. A carteira monitorada do cartório não é zelo operacional de backoffice; é a consequência de ter modelado a reserva como processo de longa duração em vez de chamada demorada. Quem não faz essa troca acaba com um thread pool inteiro esperando um cartório, ou com um job que reenvia o mesmo título todo dia porque nunca soube que o primeiro envio continua válido.

A registradora é idempotência entre concorrentes

Este é o ponto que mais me interessa como engenheiro. No artigo de modelagem, defendi que a idempotência26 mora no schema: uma restrição UNIQUE impede que o mesmo lançamento entre duas vezes. Funciona muito bem dentro da sua casa.

Agora pense no lojista que vende R$ 100 mil no cartão por mês e tenta antecipar a mesma agenda com três bancos na mesma tarde. Nenhum deles enxerga o banco de dados do outro, e não existe UNIQUE possível entre instituições concorrentes.

A registradora é esse UNIQUE. É uma chave única compartilhada pelo mercado, mantida por um terceiro em quem todos precisam confiar. Quando o segundo banco tenta registrar a oneração de um recebível que o primeiro já registrou, a registradora recusa, do mesmo jeito que o seu banco recusa a segunda linha com a mesma chave.

Traduzindo o bloco abaixo: a primeira parte é a regra que o banco consegue impor dentro de casa ("esta chave só pode existir uma vez"). A segunda mostra a mesma regra oferecida como serviço pela registradora, que responde "já está comprometido" para quem chegar depois.

-- inside your walls: the database enforces one row per fact
ALTER TABLE ledger_entry
  ADD CONSTRAINT uk_idempotency UNIQUE (idempotency_key);
-- across the market nobody can write that constraint,
-- so a registry enforces it as a service:
--   POST /encumbrances { receivable_id, creditor_id }
--   -> 409 ALREADY_ENCUMBERED

Agora preciso estragar um pouco a minha própria analogia, senão quem trabalha com recebível para de confiar no resto do artigo. Esse UNIQUE não é um só. Existem várias registradoras autorizadas, e a unicidade é forte dentro de cada uma e historicamente frágil entre elas. O mesmo recebível aparecendo em duas registradoras diferentes é um problema conhecido do mercado, e a interoperabilidade entre elas vem sendo construída por regulação e convênio, não por um índice único que qualquer um possa consultar.

Então a imagem certa não é uma tabela com uma restrição UNIQUE. É um índice particionado em que as partições ainda estão aprendendo a conversar. E isso muda o que o seu sistema precisa fazer: consultar uma registradora não é consultar o mercado, e "não encontrei oneração" quer dizer "não encontrei onde eu olhei". Quem antecipa recebível tratando ausência de registro como ausência de ônus está confiando numa garantia de unicidade que não cobre o universo, o que é uma forma caríssima de aprender a diferença entre chave única e chave única por partição.

Com isso, o registro deixa de ser detalhe de backoffice e vira fato de primeira classe no seu modelo. Ele tem protocolo externo, a data em que passou a valer e a data em que você ficou sabendo: os três tempos que vimos no artigo de modelagem. Quando alguém perguntar daqui a três anos "essa garantia estava registrada no dia do inadimplemento?", a resposta precisa ser um SELECT.

Arquétipo 4: quando não há nada para reservar

No crédito pessoal, no cheque especial e no rotativo do cartão, não há garantia para reservar em lugar nenhum. O problema inteiro migra para a decisão.

Aqui a integração muda de natureza. Você não fala com quem guarda uma garantia; fala com quem guarda informação: o SCR27 do Banco Central, os bureaus de crédito e, cada vez mais, o Open Finance28. Nenhum deles reserva nada. Eles só reduzem a incerteza, e o que sobra de incerteza vira preço.

Os números mostram o tamanho disso: em abril de 2026, a taxa média do consignado INSS foi de 23,9% ao ano, contra 63% ao ano na média do crédito pessoal não consignado para pessoa física, segundo as séries de taxas de juros do Banco Central. Vale dizer de qual recorte se trata, porque ele muda muito: cheque especial e rotativo do cartão correm em outra ordem de grandeza e puxariam esse número para muito acima de 63%.

E aqui eu preciso ser honesto com o número, porque o jeito mais fácil de usá-lo é circular. A taxa do consignado INSS não é só preço de risco: ela tem teto, fixado pelo Conselho Nacional de Previdência Social e revisado de tempo em tempo. Não foi o mercado que chegou a 23,9% sozinho, olhando para a perda esperada.

O argumento não cai com isso; ele fica mais preciso. O teto não explica a taxa, ele é o que a integração torna sustentável. Em qualquer modalidade sem reserva na fonte, um teto nessa altura secaria a oferta, porque ninguém empresta a 24% ao ano contra risco de crédito pessoal puro. No consignado ele funciona porque a reserva na folha derruba a perda esperada a ponto de 24% ainda cobrir funding, operação e a inadimplência que sobra, que é basicamente morte do beneficiário e bloqueio de benefício. A integração não define o preço. Ela define qual preço é possível sem matar o produto.

No extremo em que não há nada para reservar em lugar nenhum, a taxa de juros é, em boa parte, o preço da integração que não existe.

Lembra das duas perguntas do começo, "vai me pagar?" e "se não pagar, o que eu faço?"? Neste arquétipo só existe a primeira. É o conhecido dos R$ 500 do começo do artigo, agora na escala de um sistema financeiro: sem o celular em cima da mesa, você empresta menos, cobra mais, ou não empresta. Consignado é o mesmo empréstimo feito por quem já tem a mão na folha de pagamento.

O cartão de crédito é um caso curioso, porque mistura os dois mundos. A autorização é uma microrreserva: a bandeira reserva limite em milissegundos. Depois vêm a captura, a liquidação em D+N29 e o faturamento, cada um com contraparte e prazo próprios. É a mesma forma, em miniatura, repetida milhões de vezes por dia.

Uma lição de modelagem fica deste arquétipo: se a decisão substitui a garantia, a decisão é um fato. Ela precisa ser guardada junto com o que a produziu, ou seja, quais dados foram consultados, quando, e qual versão do modelo decidiu. Esse tema merece um artigo só para ele.

E quando a contraparte não responde?

Cada arquétipo pede uma resposta diferente para o timeout, e escolher a resposta errada produz os dois incidentes da dona Lurdes.

1. Contraparte central. Consulte o status pela sua chave de correlação. Se ela estiver em janela planejada, estacione o contrato e retome quando reabrir.

2. Contrapartes fragmentadas. A mesma regra, mas cada adaptador precisa declarar se oferece consulta de status e se a resposta dela é autoritativa na hora. As que não oferecem entram em conciliação por arquivo.

3. Registro. Nunca considere a garantia constituída sem o protocolo de volta. Operações pendentes de registro entram numa carteira monitorada, com prazo e responsável.

4. Sem reserva. O risco do timeout está na liberação do dinheiro. O desembolso precisa ser idempotente, e o E2E ID30 do Pix é uma chave natural pronta para isso.

E, nos quatro, a mesma regra de saída, que é a metade esquecida de todas as listas desse tipo: proposta que não vira contrato devolve o que reservou, com protocolo de volta.

Em código, a regra geral cabe em poucas linhas.

Para quem não programa: quando a resposta não chega, o contrato vai para o estado "não sei" e o sistema agenda uma consulta. Na consulta, se a contraparte diz que reservou, segue; se diz que recusou, encerra; se diz que não consegue responder agora, espera e pergunta de novo. E se diz que nunca viu o pedido, ele só reenvia depois do tempo mínimo em que essa resposta pode ser levada a sério. Vencido o teto de tentativas, um humano assume. O último trecho é o caminho inverso, o que quase ninguém escreve: proposta que morre devolve a margem.

void requestReservation(Contract contract) {
    contract.moveTo(RESERVATION_REQUESTED);   // correlation key already persisted
    try {
        ReservationReceipt receipt = registry.reserve(contract.toReservationRequest());
        contract.confirmReservation(receipt);  // carries the expiry date. It is not forever
    } catch (TimeoutException e) {
        contract.moveTo(RESERVATION_UNKNOWN);  // never retry blindly
        resolver.scheduleCheck(contract.id(), Duration.ofMinutes(2));
    }
}

void resolveUnknown(Contract contract) {
    if (contract.unknownFor().compareTo(caps.unknownCeiling()) > 0) {
        contract.moveTo(MANUAL_REVIEW);        // stop asking. A human owns it now
        return;
    }
    switch (registry.status(contract.correlationKey())) {
        case Reserved r    -> contract.confirmReservation(r.receipt());
        case Rejected x    -> contract.moveTo(RESERVATION_REJECTED);
        case Unavailable u -> resolver.scheduleCheck(contract.id(), u.retryAfter());

        // NOT_FOUND is not proof that nothing arrived. Trust it only after the
        // settling window the counterparty itself declares, or we recreate
        // the very duplicate we were trying to avoid.
        case NotFound n    -> {
            if (caps.notFoundIsConclusive(n.observedAt())) requestReservation(contract);
            else resolver.scheduleCheck(contract.id(), backoffFor(contract));
        }
    }
}

// The mirror image, and the one almost nobody writes:
// a proposal that dies gives the margin back.
void abandon(Contract contract, Reason reason) {
    if (contract.holdsReservation()) {
        registry.release(contract.reservationId());  // idempotent, retried until acked
        contract.moveTo(RESERVATION_RELEASED);
    }
    contract.close(reason);
}

Por baixo de tudo, uma rede de segurança: conciliação diária entre o que você acha que reservou e o que a contraparte diz que foi reservado. E a conciliação tem duas direções, não uma: reserva que você acha que tem e a contraparte não reconhece, e reserva que a contraparte ainda segura para uma proposta que na sua base já morreu. Divergência encontrada ali é incidente, com dono e prazo, e nunca um ajuste silencioso.

Pense comigo

Quando foi a última vez que alguém do time leu o relatório de conciliação? Relatório que ninguém lê é só um arquivo ocupando espaço.

Se a contraparte ficar fora do ar por quatro dias, o que acontece com as propostas aceitas nesse período? Quem avisa o cliente?

Qual é o maior valor que já saiu do seu sistema com a reserva em estado desconhecido? Se ninguém sabe responder, esse é o primeiro painel a construir. O segundo é mais barato e dói mais: quantas margens o seu sistema está segurando agora para propostas que nunca viraram contrato?

Deixe um comentário

O contrato de sexta-feira

O contrato da dona Lurdes não quebrou por causa da Dataprev. A Dataprev fez o que qualquer sistema faz às vezes: demorou numa sexta-feira à tarde. Ele quebrou porque o modelo não tinha lugar para "eu pedi e ainda não sei".

Consignado, carro, imóvel, recebível, crédito pessoal. O produto muda de nome, de taxa e de prazo. A pergunta de engenharia é sempre a mesma: onde mora a verdade da garantia, e o que o seu sistema faz enquanto ela não responde. E o arquétipo 4 é a exceção que prova a regra: quando não existe nada para reservar em lugar nenhum, alguém paga a diferença, em taxa, em limite ou em porta fechada. Reservar num banco de dados que não é seu não é um detalhe de integração. É o que separa 24% ao ano de 63%.

Fica a pergunta para os comentários: na sua instituição, qual contraparte mais te acorda de madrugada? Dataprev, Detran, cartório ou registradora? E vocês têm um estado para "não sei"? E um para "devolvi"?

Fontes

• Correio da Manhã: fim de MP faz margem do consignado do INSS voltar a 45%

• Contábeis: consignado do INSS, margem volta a 45% após fim de MP

• Bevi: o que muda na margem do INSS e do SIAPE com o fim da MP 1.355

• Seu Crédito Digital: consignado INSS e cartões bloqueados (Acórdão TCU 1.094/2026)

• Serasa: quando a margem do consignado atualiza na Dataprev

• Celcoin: regras de APIs para crédito consignado privado em 2026

• Banco Mercantil: virada de competência no consignado CLT

• B3: Sistema Nacional de Gravames (SNG)

• Fórum de Desenvolvimento Imobiliário: prazos na Lei 14.382/2022 (nota técnica)

• Antecipa Fácil: registro de recebíveis, CERC e B3

• Planalto: Medida Provisória 1.355/2026, texto original (fonte primária)

• TCU: Acórdão 1.094/2026, íntegra (fonte primária)

• Planalto: Lei 15.179/2025, Crédito do Trabalhador (fonte primária)

• Banco Central: séries de taxas médias de juros por modalidade de crédito

• Conselho Nacional de Previdência Social: resoluções de teto de juros do consignado do INSS

Dados regulatórios verificados em 30 de setembro de 2026.

Obrigado por ler Crônicas de um Programador Pragmático! Inscreva-se gratuitamente para receber novas publicações e apoiar meu trabalho.

Segunda-feira, 8h40. O canal de atendimento ao cliente está pegando fogo… o clássico pesadelo matinal de qualquer operação! Será que tudo está perdido? Não… por enquanto não… 👀

A conversa percorre as escolhas que separam um modelo que responde o negócio de um que só grava entidade: por que a lista de perguntas vem antes da tabela, por que dias de atraso nunca deveriam estar gravados, por que CPF não pode ir na chave de partição, e por que um índice de agenda sobrecarregado é capaz de impedir o registro de um pagamento às 00h07.

No episódio:

• A reunião que ninguém quer marcar — e por que o ORM não pode representar o negócio nela

• Grave o fato, derive o estado: a diferença entre a data de nascimento e a idade

• Num BaaS, a chave de partição é uma decisão de isolamento

• Índice esparso: sair da régua é arrancar o post-it da geladeira

• O engarrafamento do estacionamento que tranca a rua da ambulância

• Onde o dinheiro realmente vaza — e por que não é armazenamento

O artigo completo traz os exemplos o catálogo dos doze padrões de acesso, a anatomia da chave passo a passo e a conta de custo dos dois modelos lado a lado: Engenharia de Cobrança: Modelando Dados no DynamoDB

Se você opera cobrança, crédito ou pagamentos em DynamoDB, me conta nos comentários: qual foi a pergunta que a sua tabela não soube responder?

Deixe um comentário

Quantos contratos viraram 31+2 no fim de semana? Quanto disso tem promessa de pagamento3 para esta semana? E por que o cliente do protocolo 88213 recebeu três SMS no domingo?

São perguntas absolutamente normais para quem opera uma carteira4. E o time descobre, ao vivo, que nenhuma delas tem resposta barata.

A primeira exige um Scan na tabela inteira com filtro por dias de atraso, e o campo daysPastDue foi atualizado pela última vez na madrugada de sexta, porque o job de recálculo falhou no sábado. A segunda depende de um array promises dentro do item do contrato, que ninguém consegue consultar sem ler todos os contratos. A terceira nem está no banco: tentativas de contato viraram linhas de log no CloudWatch, com retenção de trinta dias e sem nada que identifique o devedor.

Nenhuma das três falhas é bug de código. São decisões de modelagem que nunca foram tomadas. Alguém escolheu uma chave de partição num refinamento, alguém adicionou um array “só por enquanto”, alguém decidiu que contato “é log”. Cada escolha respondeu à pergunta de engenharia do momento, como eu gravo isso?, e ignorou a pergunta do negócio: quem vai perguntar o quê sobre esse dado, com que frequência, e o que acontece se a resposta vier errada?

Em dezembro do ano passado escrevi Um breve mergulho no DynamoDB, sobre a mecânica: partição e ordenação, particionamento vertical, a conta de RCU e WCU. Este texto sobe um andar. Ele não é sobre como a chave funciona; é sobre como um tech lead ou arquiteto decide qual chave existe, qual índice merece nascer, qual atributo deve ser gravado e qual deve ser calculado, e quanto cada uma dessas decisões custa em dólar, em latência e em risco jurídico.

O fio condutor é um motor de cobrança oferecido como BaaS5: uma plataforma que atende dezenas de instituições (SCDs6, varejistas com crediário próprio, fintechs de consignado7), cada uma com sua carteira, sua política de encargos e sua régua8. Vou chamá-la de Lastro. Ela não existe, mas cada problema descrito aqui existe.

1. Comece pela reunião que ninguém quer marcar

O guia de design NoSQL da AWS é direto num ponto que engenheiros formados no relacional subestimam: você não deveria começar o schema no DynamoDB antes de saber quais perguntas ele precisa responder. No relacional, você normaliza e deixa as perguntas para depois; o otimizador se vira. No DynamoDB, as estruturas são desenhadas sob medida para os casos de uso do negócio, e consultar fora deles é caro e lento.

A consequência organizacional é mais importante que a técnica. Se o schema é derivado das perguntas, então a lista de perguntas é o artefato de arquitetura mais importante do projeto. E ela não pode ser escrita só por engenheiros.

Imagine assim

Um banco relacional é um supermercado: tudo está em algum corredor, e você encontra qualquer coisa, desde que aceite andar. O DynamoDB é a cozinha de um restaurante com a mise en place pronta: cada ingrediente já está cortado e posicionado para os pratos do cardápio, e o prato sai em segundos.

Mas, se o cliente pedir algo que não está no cardápio, o cozinheiro precisa ir ao estoque e revirar prateleira por prateleira. Isso é o Scan. A lista de padrões de acesso é o cardápio, e cardápio não se define só na cozinha: define-se com quem conhece os clientes.

Em cobrança, as perguntas vêm de cinco atores com necessidades radicalmente diferentes: a mesa de cobrança9 (o operador buscando um devedor, a supervisora olhando a carteira por faixa de atraso), a régua automática (o scheduler que acorda e precisa saber o que fazer hoje), o próprio devedor (no app ou no portal de autoatendimento, querendo ver o que deve e fechar um acordo), a conciliação (o webhook de liquidação10 de Pix e boleto que precisa achar a cobrança em milissegundos) e o compliance (auditoria, ouvidoria, relatório regulatório).

A documentação pede que você entenda três propriedades de cada padrão de acesso: o tamanho do dado lido e gravado, a forma como ele precisa chegar e a velocidade, especialmente nos picos. Eu acrescento duas colunas que mudam tudo em cobrança: quem pergunta e qual é o custo de negócio se a resposta atrasar ou vier errada. O catálogo da Lastro ficou assim:

ID    QUESTION                                          ASKED BY            VELOCITY / SHAPE
AP01  Everything about one debtor (360 view)            operator, app       ~40 req/s, one debtor, < 50 ms
AP02  Open installments of a contract, oldest first     app, agreements     ~120 req/s, < 30 ms
AP03  Contracts with a dunning action due today         dunning scheduler   daily burst, ~2M items in < 20 min
AP04  Promises due today (and broken yesterday)         dunning scheduler   daily, ~80k items
AP05  Portfolio by delinquency bucket, largest first    supervisor desk     ~5 req/s, paginated, < 200 ms
AP06  Find the charge behind a Pix txid / boleto number settlement webhook  peaks ~800 req/s on paydays
AP07  Was this settlement already applied?              settlement webhook  every webhook, MUST BE EXACT
AP08  How many contacts did this debtor get today?      contact gateway     every attempt, MUST BE EXACT
AP09  Full audit trail of one installment               compliance, ombuds  rare, < 2 s
AP10  Contracts eligible for credit bureau reporting    dunning scheduler   daily
AP11  Monthly aging and roll rate of the portfolio      finance, BI         monthly  -> NOT IN DYNAMODB
AP12  Regulatory and accounting reports                 compliance          monthly  -> NOT IN DYNAMODB

Três leituras dessa lista valem mais que qualquer diagrama.

• A primeira está nas duas últimas linhas. A pergunta mais valiosa do workshop é “qual destas perguntas não vamos responder aqui?”. Aging, roll rate11 e relatórios regulatórios são perguntas analíticas, agregações sobre a carteira inteira. DynamoDB responde perguntas com chave; agregação sobre tudo é Scan, e Scan é o jeito mais caro de descobrir que você escolheu o banco errado para aquela pergunta. Essas perguntas vão para o S3 via export e são respondidas com Athena ou no lakehouse. Declarar isso no workshop evita que, seis meses depois, alguém crie um GSI sobre status (quatro valores possíveis, cardinalidade de catástrofe) para alimentar um dashboard.

• A segunda: velocidade não é média, é forma. AP03 não é “25 requisições por segundo”; é dois milhões de itens numa janela curta e quase nada no resto do dia. AP06 não é uniforme: ele explode no quinto dia útil, no dia do pagamento do INSS12, na véspera de feriado. São esses picos, não a média, que vão definir sharding e capacidade.

• A terceira: as linhas marcadas como exatas. AP07 e AP08 não toleram leitura eventualmente consistente. Uma liquidação aplicada duas vezes é dinheiro errado no saldo do cliente; um contato a mais pode ser uma ligação que a lei proíbe. Isso já diz, antes de qualquer desenho, que essas perguntas não podem ser respondidas por GSI, que só oferece leitura eventualmente consistente. Voltaremos a isso na seção 4.

Ferramenta para o workshop

A AWS mantém o NoSQL Workbench, que permite desenhar o modelo com dados de exemplo e executar as queries antes de existir uma linha de código. Use na reunião, com a supervisora de cobrança presente: ver o próprio “devedor de teste” aparecer inteiro numa única query convence mais do que qualquer slide.

Pontos altos

1. Em DynamoDB, a lista de perguntas vem antes da tabela. Ela é o cardápio que organiza a cozinha, e se escreve junto com o negócio.

2. Para cada pergunta, anote quatro coisas: quem pergunta, em que formato a resposta precisa chegar, qual é o pico de uso (não a média) e o que acontece se a resposta vier errada.

3. Decida em voz alta o que a tabela não vai responder. Relatórios que olham a carteira inteira vão para o S3, não para um Scan.

4. Perguntas que não podem errar nunca, como pagamento aplicado em dobro ou contato acima do limite legal, não podem depender de índice secundário.

Compartilhar

2. Cada atributo é uma afirmação sobre o mundo

Um item no DynamoDB não tem schema imposto além da chave. Isso é liberdade para o código e perigo para o negócio: nada impede que o mesmo conceito exista com três nomes, em três formatos, em itens diferentes. A disciplina que o banco não impõe precisa vir do modelo.

A regra que uso: cada atributo deve ser uma afirmação verificável sobre a realidade do negócio, com significado único, unidade explícita e dono claro. Vamos aos dois itens centrais da Lastro, o cabeçalho do contrato e a parcela.

// CONTRACT header: one per contract, inside the debtor's item collection
{
  "PK": "T#t042#D#9f2c1a7e4b0d3e61",
  "SK": "CT#C-2026-004512",
  "type": "CONTRACT",
  "tenantId": "t042",
  "contractId": "C-2026-004512",
  "productCode": "CREDIARIO_12X",
  "currency": "BRL",
  "chargesPolicy": "CP#v3",
  "status": "IN_COLLECTION",
  "statusReason": "OLDEST_INSTALLMENT_OVERDUE",
  "oldestOverdueDueDate": "2026-08-10",
  "bucket": "D031_060",
  "outstandingCents": 292740,
  "nextActionDate": "2026-09-24",
  "nextAction": "SMS_D45",
  "shard": 7,
  "version": 22,
  "updatedAt": "2026-09-23T03:12:44Z"
}

// INSTALLMENT: one per installment, sorted under its contract
{
  "PK": "T#t042#D#9f2c1a7e4b0d3e61",
  "SK": "CT#C-2026-004512#IN#007",
  "type": "INSTALLMENT",
  "seq": 7,
  "originalDueDate": "2026-08-10",
  "dueDate": "2026-08-10",
  "principalCents": 41230,
  "interestCents": 7560,
  "fineCents": 0,
  "lateInterestCents": 0,
  "paidCents": 0,
  "status": "OVERDUE",
  "version": 9
}

A primeira linha dos dois itens, "PK": "T#t042#D#9f2c1a7e4b0d3e61", parece críptica, e é de propósito. Por ora, leia assim: “instituição t042, devedor cujo CPF, embaralhado, virou o código 9f2c1a7e4b0d3e61”. Na seção 3 desmonto essa chave peça por peça e mostro como se chega a ela.

Nada nesses dois itens está ali por acaso. Vamos por partes.

Atraso é do contrato; vencimento é da parcela

A primeira decisão é puramente de negócio: dias de atraso não pertencem à parcela. No mercado, o atraso de um contrato é medido pela parcela mais antiga em aberto, e é esse número que define faixa, régua, provisão13 e negativação14. Por isso oldestOverdueDueDate e bucket moram no cabeçalho do contrato, e a parcela guarda apenas o próprio vencimento e o próprio status.

Se você colocar faixa de atraso em cada parcela, o contrato do João aparece três vezes na carteira da supervisora (uma por parcela vencida) e, cedo ou tarde, alguém soma o saldo em triplo num relatório para a diretoria.

Grave o fato, derive o estado

Repare no que não está no item: daysPastDue. Dias de atraso mudam todo dia, para todo contrato inadimplente, sem que nada tenha acontecido no mundo. Gravar esse número exige uma escrita por contrato por dia. Chamo isso de escrita sem evento, e ela é o vazamento de custo e de risco mais comum que já vi em motores de cobrança.

O fato é oldestOverdueDueDate. Ele só muda quando algo acontece: um pagamento quita a parcela mais antiga, um acordo reestrutura o contrato. Dias de atraso são derivados na leitura, hoje menos essa data. No exemplo, em 24 de setembro o contrato está com 45 dias, exatamente o gatilho do SMS_D45. É um cálculo de uma linha que nunca fica desatualizado porque o job da madrugada falhou.

Já bucket é estado derivado gravado, e a exceção é deliberada. Ele precisa existir como atributo porque é chave de um índice (a carteira por faixa, que veremos adiante) e muda raramente: no máximo uma vez a cada trinta dias por contrato. A regra geral fica assim: estado derivado só merece virar atributo quando é necessário numa chave e muda muito menos do que é lido. Na seção 5 essa decisão vira dinheiro.

O vencimento original é um fato; o vencimento vigente é uma decisão

originalDueDate nunca muda. dueDate muda quando há prorrogação15. Parece redundante até alguém do risco perguntar quanto da carteira de agosto foi prorrogada e quantas dessas prorrogações acabaram pagas. Se você sobrescreveu, perdeu a resposta. Pense numa passagem aérea remarcada: o bilhete precisa mostrar o voo original e o novo, senão ninguém sabe depois se o passageiro se atrasou ou se a companhia mudou o horário. É o mesmo princípio do artigo sobre modelagem de dados: você guardou o resultado e jogou fora a causa.

E vencimento é data civil, não instante: "2026-08-10", nunca "2026-08-10T00:00:00Z". Meia-noite UTC é 21h do dia anterior em Brasília; um vencimento gravado como timestamp vai, em algum relatório, aparecer um dia antes. Pior: a regra de mercado que permite pagar sem encargos no próximo dia útil um boleto que vence em feriado é uma regra de calendário, não de relógio. Modele o conceito que o negócio usa.

Dinheiro tem unidade, e encargo tem origem

Valores em centavos inteiros, com a moeda explícita no contrato. O tipo Number do DynamoDB é decimal de alta precisão, então o problema não está no banco; está no caminho: JSON parseado como double num cliente JavaScript, uma biblioteca que converte para float no meio de um mapper. Inteiro em centavos não tem ambiguidade em nenhuma camada.

A decomposição em principalCents, interestCents, fineCents e lateInterestCents não é preciosismo. Ela existe porque o negócio precisa provar duas coisas: a ordem de imputação do pagamento16 (o art. 354 do Código Civil manda imputar primeiro nos juros vencidos e depois no capital, salvo estipulação em contrário) e o respeito ao teto da multa moratória17 em relações de consumo, de 2% pelo art. 52, §1º, do CDC. Um único amountCents não prova nenhuma das duas.

Note que multa e juros de mora aparecem zerados na parcela vencida. Não é esquecimento. Encargo de atraso é calculado quando vira fato (na liquidação ou no fechamento de um acordo18) a partir da política vigente, referenciada no contrato por chargesPolicy: "CP#v3". A política é um item versionado na própria tabela. Quando o tenant mudar a regra em março, os contratos antigos continuam apontando para a versão sob a qual foram assinados. Recalcular encargo todo dia seria, de novo, escrita sem evento.

Regra de negócio é dado versionado, não um if que alguém alterou num PR de sexta-feira.

O estado não carrega contexto

status e statusReason são atributos separados, pelo mesmo princípio que defendi no artigo sobre máquinas de estado em crédito: IN_COLLECTION é um estado; o motivo é atributo. Criar IN_COLLECTION_BY_OVERDUE e IN_COLLECTION_BY_BROKEN_AGREEMENT gera explosão combinatória na máquina, nos índices e nos relatórios.

A régua e o pagamento vão correr um contra o outro

Às 00h07 o scheduler está reagendando a próxima ação do contrato. Às 00h07 o webhook de Pix está aplicando um pagamento no mesmo contrato. Sem controle de concorrência, o último a escrever vence, e o contrato quitado ganha um nextAction de SMS. O atributo version, com toda escrita condicionada a version = :expected, transforma essa corrida num erro explícito e retentável em vez de um dado silenciosamente errado. Imagine dois atendentes editando a mesma ficha em papel: quem entrega por último apaga, sem saber, o que o outro escreveu. O version é o número da página no rodapé da ficha: se ele mudou desde que você a pegou, devolva e pegue a versão nova.

Nome de atributo custa bytes, mas legibilidade custa mais

O nome do atributo entra no tamanho do item; a AWS documenta isso nas restrições do serviço. Esse fato levou muita gente a nomes como a1, dd, pc. Não faça isso. O item precisa ser legível por quem vai investigar um incidente às 3h da manhã direto no console. O equilíbrio é nome curto e semântico: dueDate, e não installmentCurrentDueDateLocal nem dd. Na seção 5 fica claro que a economia de bytes que importa vem de outro lugar.

Chaves sintéticas estão saindo dos índices

Até novembro de 2025, um GSI tinha exatamente um atributo de partição e um de ordenação. Isso obrigava a concatenar valores em strings como GSI1PK = "T#t042#ACT#2026-09-24#07" e, pior, a fazer backfill da tabela inteira toda vez que um índice novo exigia uma chave nova. Desde então, GSIs aceitam até quatro atributos na partição e quatro na ordenação, usando os atributos naturais do item, sem custo adicional.

Isso é mudança de modelagem, não só de sintaxe: índices novos podem nascer a partir de atributos que já existem, e o item deixa de carregar strings que só servem ao banco. É por isso que tenantId aparece duas vezes no contrato, dentro da PK e como atributo próprio: é o preço, barato, de índices com chaves naturais. A chave primária da tabela base continua com um atributo de cada, então PK e SK sintéticos continuam existindo ali. Antes de adotar, confira se o seu SDK e o seu mapper já suportam o recurso.

Pense comigo

Em 2029, uma ação judicial pergunta por que a parcela 7 do contrato C-2026-004512 foi liquidada com R$ 9,75 de multa. Qual atributo responde?

Se a resposta for “a gente recalcula com a regra atual”, você não tem uma resposta. Tem uma estimativa, e estimativa não se defende.

Pontos altos

1. O atraso pertence ao contrato e é medido pela parcela mais antiga em aberto. O vencimento pertence a cada parcela.

2. Grave a data de nascimento, não a idade: guarde o que muda quando algo acontece e calcule o que muda só porque o dia virou.

3. Um valor calculado só vira campo gravado quando organiza um índice e muda raramente, como a série escolar.

4. Vencimento é data do calendário, não hora do relógio. Dinheiro é número inteiro em centavos, separado pela origem: principal, juros, multa.

5. Regras de encargo são versionadas, e cada contrato aponta para a versão sob a qual foi assinado.

6. Toda escrita que pode concorrer com outra confere o número da versão. Nomes de campo curtos, mas que qualquer pessoa entenda no console.

3. Num BaaS, a chave de partição é uma decisão de isolamento

A documentação da AWS descreve um bloco de multi-tenancy em que todos os dados de um tenant ficam na mesma coleção de itens, com o tenant como chave de partição. Funciona muito bem para muitos tenants pequenos e parecidos, e oferece de brinde uma exclusão barata quando o tenant vai embora.

Num BaaS de cobrança, é uma armadilha. O maior tenant da Lastro tem 60% dos contratos. Toda a escrita da régua dele cairia numa única chave, sujeita ao limite físico de throughput por partição (mil unidades de escrita por segundo). As alternativas óbvias também falham. CPF puro como PK mistura tenants: a mesma pessoa pode dever para o varejista e para a SCD, e cada instituição é controladora¹⁹ do próprio dado perante a LGPD, então a coleção do devedor não pode ser compartilhada. Contrato como PK fragmenta o devedor: a visão 360 vira N consultas.

A escolha: PK = "T#" + tenantId + "#D#" + debtorKey. O tenant garante isolamento; o devedor garante cardinalidade.

Não coloque CPF na chave

Minha proposta de dezembro usava o CPF na chave. Hoje eu não faria isso, e a razão é operacional, não teórica: chaves vazam. Elas aparecem nas mensagens de erro que vão para o log, nos registros do stream que alimentam outros sistemas, nos payloads da DLQ e no CloudWatch Contributor Insights, cuja função é justamente listar as chaves mais acessadas. CPF em chave é CPF em todo lugar.

debtorKey é um HMAC-SHA256 do documento, com um segredo por tenant, truncado:

import { createHmac } from "node:crypto";

// Same CPF, different tenants -> different keys. No index needed to find a debtor.
export function debtorKey(tenantSecret: Buffer, document: string): string {
  const normalized = document.replace(/\D/g, "");
  return createHmac("sha256", tenantSecret)
    .update(normalized)
    .digest("hex")
    .slice(0, 16);
}

Três propriedades importam. É determinístico: o operador digita o CPF, o serviço calcula a chave e faz uma Query direta, sem índice por CPF. Não é reversível sem o segredo. E o mesmo CPF gera chaves diferentes em tenants diferentes, o que impede correlacionar carteiras. Funciona como a ficha da chapelaria de um restaurante: o número encontra o seu casaco na hora, mas não revela o seu nome a quem olha a ficha, e outro restaurante daria outro número para a mesma pessoa. O documento em si fica como atributo, criptografado no cliente; o AWS Database Encryption SDK faz criptografia por atributo exatamente para esse cenário.

Anatomia da chave, peça por peça

Com as duas decisões tomadas (tenant mais devedor, e CPF nunca em claro), a chave se monta em quatro passos. Vamos seguir um CPF fictício, 123.456.789-09, de um devedor do tenant t042:

step 1  normalize the document         "123.456.789-09"  ->  "12345678909"
step 2  HMAC-SHA256 with t042's secret  ->  "9f2c1a7e4b0d3e61a84c…e07b"   (64 hex chars)
step 3  keep the first 16 characters    ->  "9f2c1a7e4b0d3e61"             (debtorKey)
step 4  add tenant and entity prefixes  ->  "T#" + "t042" + "#D#" + "9f2c1a7e4b0d3e61"

PK = "T#t042#D#9f2c1a7e4b0d3e61"

Do geral para o específico, como um endereço. Você escreve um endereço começando pelo estado, depois a cidade, a rua e o número, e o carteiro vai estreitando a busca a cada pedaço. A chave faz o mesmo: primeiro a instituição, depois o tipo de coisa, depois quem. Essa ordem não é estética. É ela que permite dizer ao IAM “este papel só pode tocar chaves que começam com T#t042#“, porque prefixo é a única coisa que uma regra de acesso consegue comparar.

Prefixos dizem o que vem depois. A mesma tabela guarda famílias de chave diferentes, e o prefixo é o que impede que elas se confundam:

T#t042#D#9f2c1a7e4b0d3e61       debtor item collection (profile, contracts, installments...)
T#t042#CHG#<txid>               charge lookup           (section 4)
T#t042#STL#<settlementId>       settlement idempotency  (section 4)

Sem o D#, CHG# e STL#, nada impediria que o identificador de uma liquidação coincidisse, por acaso, com o código de um devedor. Com o prefixo, a colisão entre famílias é impossível por construção, e quem abre o console às 3h da manhã sabe o que está olhando sem ler o código.

Por que # como separador? Porque esse caractere nunca aparece nos identificadores do negócio, e porque é a convenção que a própria documentação da AWS usa nas chaves compostas. Qualquer caractere que não apareça nos valores serviria; o importante é escolher um e nunca mais mudar.

Por que letras tão curtas? A chave se repete em todos os itens da coleção e em todos os índices que a projetam, e o tamanho dela entra na conta de cada item. T e D bastam, desde que o time tenha o dicionário por escrito, no README ou no ADR:

T        tenant                 CT       contract
D        debtor                 IN       installment
CHG      charge (Pix / boleto)  AG       agreement
STL      settlement             EV       event (audit trail)
PROFILE  debtor profile         LIMIT    daily contact counter
CONTACT  contact attempt        PROMISE  payment promise

Uma chave curta só é legível se existir o dicionário. Sem ele, T#t042#D# vira hieróglifo no primeiro rodízio do time.

Por que o tenant aparece em claro e o devedor não? O identificador da instituição não é dado pessoal e precisa estar legível para a regra de acesso e para a operação. Quando o Contributor Insights mostrar uma chave quente, T#t042 diz na hora qual cliente está gerando a carga, enquanto o código do devedor esconde quem é a pessoa. Você sabe qual cliente está pegando fogo sem saber o nome de ninguém.

Por que só 16 caracteres do hash? Dezesseis caracteres hexadecimais são 64 bits, um espaço de 18 quintilhões de valores. Para um tenant com 10 milhões de devedores, a chance de dois CPFs diferentes gerarem o mesmo código fica na ordem de uma em algumas centenas de milhares: baixa, mas não zero. Por isso o cadastro do devedor grava o item PROFILE com o documento criptografado e, ao criar um devedor novo, confere se o documento bate com o que já está lá. Uma colisão improvável vira um erro detectável, e nunca dois devedores misturados na mesma pasta. Se você preferir não conviver com esse cenário, use 20 caracteres (80 bits): a chance cai para algo desprezível, ao custo de quatro bytes a mais por item.

Isolamento no IAM, não só no código

Com o prefixo do tenant na chave, o isolamento pode ser imposto pela política de acesso. A condição dynamodb:LeadingKeys restringe quais valores de partição um papel pode tocar. A camada de API assume um papel com o tenant como tag de sessão, e a política só aceita chaves que comecem com o prefixo daquele tenant:

{
  "Effect": "Allow",
  "Action": ["dynamodb:GetItem", "dynamodb:Query", "dynamodb:PutItem", "dynamodb:UpdateItem"],
  "Resource": "arn:aws:dynamodb:*:*:table/collections",
  "Condition": {
    "ForAllValues:StringLike": {
      "dynamodb:LeadingKeys": ["T#${aws:PrincipalTag/tenantId}#*"]
    }
  }
}

Um bug que monte a chave do tenant errado vira AccessDeniedException, não vazamento de dados entre instituições. Num BaaS regulado, essa diferença cabe inteira num parecer de segurança.

O preço dessa escolha: offboarding

Nenhuma chave é grátis. Com o tenant como partição, apagar um tenant seria uma Query seguida de deletes. Com o devedor como partição, os dados de um tenant estão espalhados por milhões de coleções. Quando um tenant encerra o contrato e pede exclusão, você precisa enumerá-los: um export filtrado, ou um GSI esparso com projeção KEYS_ONLY sobre os itens PROFILE, particionado por tenantId. Registre esse custo no ADR. Trade-off não documentado é dívida com data de vencimento desconhecida.

A coleção do devedor

Tudo o que a plataforma sabe sobre um devedor, num tenant, mora na mesma coleção de itens, ordenado pela sort key. Pense numa pasta suspensa de arquivo com abas separadoras em ordem alfabética: puxar a pasta inteira é a visão 360; abrir direto na aba das parcelas é um begins_with.

Os prefixos da sort key não são estética: são o plano de consultas. Cada faixa contígua é uma pergunta de negócio respondida com uma única Query.

A visão 360 (AP01) é uma Query na partição, sem filtro. As parcelas do contrato (AP02) são uma Query com begins_with no prefixo #IN#. A trilha de auditoria da parcela 7 (AP09) é outra, no prefixo #EV#007#. Os prefixos foram escolhidos para que a ordem alfabética coincida com a necessidade de leitura: eventos ficam antes das parcelas porque E vem antes de I, e por isso o prefixo das parcelas nunca devolve eventos por acidente.

Um detalhe que já gerou chamado em produção: a sort key é string, então a sequência precisa de zeros à esquerda. Sem eles, IN#10 vem antes de IN#2, e o app mostra a parcela dez antes da segunda. Ordem lexicográfica é regra de negócio disfarçada de detalhe técnico.

Histórico não mora dentro do item

A tentação é óbvia: um array statusHistory dentro da parcela. O problema técnico é que, numa atualização, o DynamoDB cobra a escrita pelo maior tamanho entre o item antes e depois da mudança. Cada update na parcela passa a pagar pelo histórico inteiro. É como levar o álbum de família completo ao cartório toda vez que você só precisa trocar a foto do documento. Uma parcela com dezoito meses de eventos passa de 1 KB e dobra o custo de toda escrita futura, inclusive a do pagamento. O problema de negócio é que o array não é consultável: a auditoria vira “baixar tudo e procurar”.

A saída é o particionamento vertical que a própria AWS recomenda: eventos como itens irmãos (#EV#), append-only. Cada evento custa uma escrita pequena, uma única vez, e só é lido quando alguém pergunta.

Cuidado com LSI

Um índice secundário local só pode ser criado junto com a tabela e, quando existe, impõe um limite de 10 GB a cada coleção de itens. A coleção de um devedor antigo, com anos de contatos e eventos, é exatamente o tipo de coisa que cresce sem ninguém olhar. Prefira GSI, que pode nascer depois e não impõe esse teto.

Pense comigo

Se o seu maior tenant dobrar de tamanho amanhã, qual chave esquenta primeiro? Se a resposta for “a do tenant”, o seu modelo tem um teto de crescimento que ninguém escreveu em lugar nenhum, e ele vai ser descoberto no pior dia possível.

Pontos altos

1. Num BaaS, a chave junta instituição e devedor: cada inquilino no seu andar, cada devedor no seu armário.

2. Documento pessoal nunca vai na chave. Use um código derivado (HMAC), como a ficha da chapelaria: encontra o casaco sem expor o nome.

3. O isolamento entre instituições é garantido pela política de acesso da AWS, e não só pelo cuidado do código.

4. Toda chave tem um preço. O desta é o trabalho de remover um tenant inteiro; escreva isso no ADR.

5. A ordem das abas da pasta é planejada: prefixos pensados para as perguntas e números com zeros à esquerda.

6. Histórico vira folhas novas na pasta, nunca um anexo que cresce dentro do mesmo item.

4. Índices secundários são respostas, não atalhos

Cada GSI é uma cópia parcial da tabela, com capacidade, custo de escrita e custo de armazenamento próprios. Por isso cada índice deve nascer com o nome da pergunta que responde. Na Lastro, são dois índices de negócio e dois tipos de item de lookup, e a escolha entre um e outro diz muito sobre maturidade de modelagem.

GSI1: a régua do dia é um índice esparso

GSI1  dunning-agenda          sparse: only items that have nextActionDate
  partition key   tenantId (S) + nextActionDate (S) + shard (N)
  sort key        nextAction (S) + contractId (S)
  projection      INCLUDE debtorKey, bucket, outstandingCents, channelPrefs

A AWS descreve o índice esparso como um bloco de construção: só entram no GSI os itens que possuem os atributos de chave. Com chaves de múltiplos atributos vale a mesma regra; se faltar qualquer componente, o item fica de fora. Na Lastro, apenas contratos em cobrança ativa e promessas pendentes têm nextActionDate.

O efeito é elegante. Quando um pagamento cura o contrato, a mesma transação que baixa a parcela remove nextActionDate e nextAction, e o contrato sai da régua. Não existe “job para limpar a régua”. Sair da régua é remover um atributo. A modelagem está dizendo, em estrutura de dados, uma regra de negócio: régua só existe para quem deve.

Promessas de pagamento usam o mesmo índice, com nextAction = PROMISE_CHECK na data prometida. A elegibilidade para negativação (AP10) também: BUREAU_REPORT é só mais uma ação agendada, na data em que o contrato passa a ser elegível pela política do tenant. Um índice, três perguntas, porque as três têm a mesma forma: o que precisa acontecer para este tenant nesta data. E, como o sort key começa por nextAction, o worker que só envia SMS consulta só os SMS.

Há ainda um benefício de custo que a documentação destaca: um índice esparso só cobra escrita e armazenamento dos itens que entram nele. A régua indexa os 25% da carteira em cobrança, não os 100%.

O shard é a unidade de paralelismo do seu batch

Primeiro, a palavra. Shard, em inglês, é caco, fragmento, o pedaço de algo que se partiu. Em banco de dados, fazer sharding é dividir de propósito um volume grande em pedaços menores, guardados em lugares diferentes, para que nenhum pedaço receba trabalho demais sozinho. Na Lastro, o shard é apenas um número de 0 a 15 gravado no contrato, que diz em qual dos dezesseis pedaços do índice aquele contrato mora.

Sem o atributo shard, a partição do índice seria apenas tenant e data. Toda madrugada, depois de executar as ações do dia, o scheduler reagenda a próxima ação de cada contrato. Mudar nextActionDate é mudar a chave do índice, e para o GSI isso significa remover o item de uma posição e inseri-lo em outra. No maior tenant, são cerca de 1,2 milhão de contratos convergindo na mesma chave de “amanhã”.

E aqui mora o detalhe que transforma um problema de performance num incidente de negócio. A AWS avisa que throttling de escrita num GSI devolve back-pressure para a tabela base: quando o índice não aguenta, as escritas na tabela falham. Quem mais escreve na tabela base às 00h07? O webhook de liquidação.

O cliente que pagou o Pix à meia-noite para “limpar o nome” gera um webhook que toma throttling, os retries se esgotam, a mensagem cai na DLQ e a baixa só entra às 9h30, no reprocessamento manual. Às 8h, a régua mandou SMS de cobrança para quem já tinha pago. Reclamação no Procon, post no Reclame Aqui, risco de dano moral. Tudo porque um índice de agenda estava quente.

A saída é o write sharding com sufixo calculado: shard = hash(contractId) mod N. O N sai de uma conta simples, o pico de escritas por segundo esperado no índice dividido por mil, com folga para crescimento. O sufixo é calculado, não aleatório, para que qualquer contrato saiba sempre em que shard está.

O insight que costuma passar despercebido: o shard não é gambiarra de banco. É exatamente a unidade de paralelismo que o seu batch já queria. Às 8h, dezesseis workers fazem, cada um, uma Query paginada no próprio shard. Sem coordenação, sem locks, sem a eterna pergunta “quem pegou este contrato?”. O desenho que protege a partição é o mesmo que distribui o trabalho. Pense nos caixas de um supermercado: com uma fila única, tudo trava; com dezesseis caixas e uma regra fixa para escolher o caixa (o final do número do contrato, digamos), a fila anda, e cada caixa já tem o seu operador.

Sobre a projeção: INCLUDE apenas com o que o worker precisa para decidir e agir. Cada atributo projetado é armazenamento replicado e custo extra em toda escrita que o altere. Projetar ALL “por garantia” duplica a tabela.

GSI2: a carteira da supervisora

GSI2  portfolio-by-bucket     sparse: only CONTRACT items that have bucket
  partition key   tenantId (S) + bucket (S)
  sort key        outstandingCents (N) + contractId (S)
  projection      INCLUDE debtorKey, oldestOverdueDueDate, productCode, lastContactAt

Uma Query com ScanIndexForward = false devolve os maiores saldos primeiro; os dias de atraso são calculados na tela a partir de oldestOverdueDueDate. É aqui que a decisão da seção 2 aparece com clareza. Se daysPastDue fosse chave de ordenação, cada contrato inadimplente mudaria de posição no índice todos os dias. Com a faixa na partição, o contrato se move no máximo uma vez por mês. Nunca coloque numa chave de índice um atributo que muda com o calendário.

outstandingCents na ordenação muda com pagamento parcial, o que é raro e até desejável: o contrato desce na lista. A partição tem baixa cardinalidade (poucas faixas por tenant), e a documentação recomenda considerar sharding também em GSIs assim. Aqui o volume de escrita é baixo, então a decisão foi começar sem shard e alarmar as métricas de throttling do índice. Nem todo índice precisa de shard; todo índice precisa de alarme.

Onde GSI não serve: exatidão

GSI só oferece leitura eventualmente consistente. Na maior parte do tempo a propagação é rápida, mas “na maior parte do tempo” não é contrato. O GSI é o quadro de avisos que uma secretária atualiza copiando do livro oficial: quase sempre em dia, mas, quando o assunto é dinheiro, você consulta o livro. No Pix, o QR Code é gerado e pago em segundos. Se o webhook procurar a cobrança pelo txid19num GSI, existe uma janela em que a cobrança recém-criada ainda não chegou ao índice. “Cobrança não encontrada” num webhook de liquidação é dinheiro sem dono.

Por isso AP06 e AP07 são respondidos por itens de lookup na tabela base, lidos com consistência forte:

// Written in the same transaction that creates the charge
PK = "T#t042#CHG#<txid or boleto number>"     SK = "CHG"
     -> debtorKey, contractId, seq, amountCents, expiresAt

// Written in the same transaction that applies the payment
PK = "T#t042#STL#<settlementId>"              SK = "STL"
     -> amountCents, receivedAt, appliedTo

O item de liquidação é a idempotência. Pense no carimbo de PAGO num boleto de papel: se a mesma via voltar ao caixa, o carimbo já está lá, e ninguém recebe duas vezes. O webhook vai chegar duas vezes: o provedor reenviou, o consumer reprocessou, alguém rodou o replay da DLQ. A transação que aplica o pagamento inclui um Put condicionado à inexistência desse item. Na segunda tentativa, a transação inteira é cancelada e o saldo não é baixado duas vezes.

import { TransactWriteCommand } from "@aws-sdk/lib-dynamodb";

// Settlement webhook: apply a payment exactly once
await doc.send(new TransactWriteCommand({
  TransactItems: [
    {
      // 1. Idempotency: the settlement id IS the key
      Put: {
        TableName: TABLE,
        Item: {
          PK: `T#${tenantId}#STL#${settlementId}`,
          SK: "STL",
          type: "SETTLEMENT",
          amountCents,
          receivedAt,
          appliedTo: `${contractId}#${pad3(seq)}`,
        },
        ConditionExpression: "attribute_not_exists(PK)",
      },
    },
    {
      // 2. Installment: optimistic lock on version
      Update: {
        TableName: TABLE,
        Key: { PK: debtorPk, SK: `CT#${contractId}#IN#${pad3(seq)}` },
        UpdateExpression:
          "SET paidCents = paidCents + :amt, #status = :newStatus, version = version + :one",
        ConditionExpression: "version = :expected",
        ExpressionAttributeNames: { "#status": "status" },
        ExpressionAttributeValues: {
          ":amt": amountCents,
          ":newStatus": installmentTransition.to, // decided by the state machine, not here
          ":one": 1,
          ":expected": installmentVersion,
        },
      },
    },
    // 3. Contract header: new balance and delinquency fact.
    //    When cured: REMOVE oldestOverdueDueDate, #bucket, nextActionDate, nextAction
    //    -> the contract leaves the dunning agenda and the bucket portfolio in the same commit.
    { Update: contractUpdate(contract, installmentTransition, expectedContractVersion) },
  ],
}));

Limite de contato: a data na chave garante a regra; o TTL só faz a limpeza

No artigo sobre resiliência em sistemas de cobrança, falei do “guarda de trânsito” da régua: um limite diário de contatos por devedor, independentemente do canal. Na Lastro, ele é um item na coleção do devedor, incrementado de forma atômica e condicional:

import { UpdateCommand } from "@aws-sdk/lib-dynamodb";

// Contact gateway: atomically claim one of today's allowed contacts
await doc.send(new UpdateCommand({
  TableName: TABLE,
  Key: { PK: debtorPk, SK: `LIMIT#${localDate}` }, // civil date in America/Sao_Paulo
  UpdateExpression: "SET expiresAt = if_not_exists(expiresAt, :ttl) ADD attempts :one",
  ConditionExpression: "attribute_not_exists(attempts) OR attempts < :max",
  ExpressionAttributeValues: {
    ":one": 1,
    ":max": policy.maxDailyContacts,
    ":ttl": toEpochSeconds(addDays(localDate, 8)), // housekeeping only
  },
}));
// ConditionalCheckFailedException => do NOT contact. It is not "retry later".

Dois detalhes carregam o negócio. Primeiro, a data na chave é local, no fuso de São Paulo: o limite legal é por dia civil do devedor, não por dia UTC. Segundo, o TTL. Deletes por TTL são gratuitos, mas assíncronos, e a documentação avisa que podem levar mais de 48 horas. Se a correção dependesse do TTL (um único item LIMIT que “expira” à meia-noite), o devedor poderia ficar bloqueado por dois dias, ou o contador poderia zerar tarde demais. Com a data na chave, o contador de amanhã é outro item, e o TTL só varre o lixo. TTL é ferramenta de custo, nunca de correção. O TTL é o caminhão de lixo, que passa sem horário fixo. Ninguém espera o caminhão para saber se o leite venceu: a data está impressa na embalagem. Aqui, a data está na chave.

Cada tentativa também grava um item CONTACT#{timestamp} com canal, template e resultado. É prova, não log. A pergunta “por que ele recebeu três SMS no domingo?” deixa de ser uma investigação e vira uma Query.

A imagem acima é o mapa que deveria estar anexado a todo ADR de modelagem em DynamoDB: pergunta de um lado, estrutura do outro, e nenhuma linha solta.

Pense comigo

Qual dos seus índices, se ficasse lento amanhã às 00h07, impediria um cliente de pagar?

Se você não sabe responder, abra agora o painel de métricas dos seus GSIs. Não depois do incidente.

Pontos altos

1. Cada índice existe para responder uma pergunta com nome e dono.

2. Índice esparso é o post-it na geladeira: sair da régua é arrancar o post-it, não rodar um job de limpeza.

3. Um índice sobrecarregado trava as escritas da tabela principal. A régua, que pode esperar, pode impedir o registro de um pagamento, que não pode.

4. O shard espalha a carga como os caixas de um supermercado e, de brinde, define quantos workers o batch usa.

5. Nunca use como chave de índice um valor que muda só porque o calendário andou.

6. O que precisa ser exato (pagamento aplicado uma única vez, limite legal de contatos, cobrança recém-criada) fica na tabela principal, lido com consistência forte.

7. O TTL é o caminhão de lixo: limpa, mas não decide o que venceu. A regra mora na data da chave.

8. Quando a operação quer filtrar por qualquer coisa, a resposta é um motor de busca, não mais índices.

5. Custo: onde o dinheiro realmente vaza

Vamos dimensionar a Lastro com números redondos e premissas explícitas: 8 milhões de contratos ativos, em média 10 parcelas por contrato, 25% da carteira em cobrança (2 milhões de contratos), quarenta tenants, o maior deles com 60% do volume.

Primeiro, a verdade que desmonta metade das discussões de revisão: armazenamento quase nunca é a conta. Contratos, parcelas, eventos, contatos e itens de lookup somam algo em torno de 95 GB. A US$ 0,25 por GB-mês na classe Standard, são cerca de US$ 24 por mês. Discutir abreviação de nome de atributo por causa de armazenamento é otimizar o centavo errado.

O dinheiro, e principalmente o risco, vaza em três lugares.

Vazamento 1: escrita sem evento

Compare dois modelos para o mesmo requisito, “saber o atraso de cada contrato”, a US$ 0,625 por milhão de unidades de escrita (on-demand):

MODEL A: store daysPastDue, recompute nightly, daysPastDue in GSI2 sort key
         contract item at 1.1 KB (embedded promises and history)
  2M delinquent contracts x 30 nights            = 60M updates / month
  base table: 1.1 KB rounds to 2 KB -> 2 WRU     = 120M WRU
  GSI2 key change: delete + insert (~0.4 KB)     = 120M WRU
  total                                          = 240M WRU  ~ US$ 150 / month

MODEL B: store oldestOverdueDueDate, derive days past due at read time
         contract item under 1 KB, bucket changes at most once a month
  ~2M bucket moves / month x (1 base + 2 index)  = 6M WRU    ~ US$ 4 / month

Quarenta vezes mais caro. E, sendo honesto, ninguém é demitido por US$ 150 por mês. O custo real do modelo A não está na fatura; está no formato da carga. Ele cria, por design, um pico diário de escrita proporcional à inadimplência, concentrado em poucas chaves de baixa cardinalidade, na mesma janela em que a régua reagenda as ações. No modo on-demand, a tabela acomoda instantaneamente até o dobro do pico anterior; um salto além disso pode gerar throttling enquanto a capacidade se ajusta.

Agora pense no que acontece numa crise de crédito. A inadimplência sobe, o pico noturno do modelo A cresce junto, e o risco de throttling aumenta exatamente quando a cobrança mais importa. Um bom modelo não aumenta a própria carga com notícia ruim. No modelo B, a carga cresce com eventos (pagamentos, contatos, acordos), não com o calendário.

Vazamento 2: ler o que você não precisa

A primeira versão da tela de carteira quase sempre é um Scan com FilterExpression. O filtro dá a sensação de que você só paga pelo que volta. Não é assim: a capacidade consumida é calculada sobre os itens lidos, não sobre os devolvidos. É uma biblioteca que cobra por cada livro que o bibliotecário tirou da estante procurando o seu, e não pelo único livro que você levou para casa.

Eventually consistent Scan over 95 GB
  95 GB / 4 KB x 0.5                             ~ 12.5M RRU  ~ US$ 1.56 per scan
Supervisor screen opened hourly by 40 tenants
  40 x 24 h x 30 days = 28,800 scans / month     ~ US$ 45,000 / month

Same screen on GSI2, 100 contracts per page (~0.3 KB each)
  30 KB / 4 KB x 0.5                             ~ 4 RRU per page  -> cents per month

Esse é o único número do artigo que realmente assusta, e ele não vem de um recurso caro do DynamoDB. Vem de uma pergunta sem estrutura para respondê-la.

Vazamento 3: fronteiras de tamanho e transações por reflexo

Escritas são cobradas em blocos de 1 KB; leituras, em blocos de 4 KB. Um cabeçalho de contrato com 1,02 KB paga duas unidades em toda atualização, para sempre, como na tabela dos Correios, em que um pacote de 1,02 kg paga a tarifa de 2 kg. Por isso o histórico sai do item (seção 3), e por isso a projeção dos índices é enxuta.

Transações custam o dobro: cada item é preparado e confirmado. É o reconhecimento de firma em cartório: vale quando o documento exige, e é desperdício quando uma assinatura simples resolve. Use-as apenas quando a invariante atravessa itens, como na liquidação (item de idempotência, parcela e contrato precisam mudar juntos, ou nenhum muda). O contador de contatos não precisa de transação; um ADD condicional num único item já é atômico. E lembre que escrita condicional que falha também consome capacidade: cada webhook duplicado custa uma escrita. É um seguro barato, mas entra na conta.

Modo de capacidade e classe de tabela

O perfil da Lastro (picos em dia de pagamento, lote noturno, vales no resto do dia) favorece on-demand, cujo preço caiu pela metade em novembro de 2024. Provisionado com auto scaling fica em torno de três vezes mais barato por requisição quando a utilização é alta e estável, então revisite a decisão quando o tráfego amadurecer. Antes de picos previsíveis, como o dia do INSS, a AWS permite pré-aquecer a capacidade de tabelas e índices (warm throughput).

Para o histórico, a documentação de fundamentos é clara: uma tabela que mistura dado operacional e histórico não aproveita bem a classe Standard-Infrequent Access. Contratos encerrados, eventos antigos e evidências de contato com mais de alguns meses vão para uma tabela separada em Standard-IA, com armazenamento a US$ 0,10 por GB-mês contra US$ 0,25, e requisições cerca de 25% mais caras. O caminho natural é TTL na tabela quente, stream configurado com imagem antiga, e uma Lambda que reconhece o delete feito pelo próprio serviço e arquiva no destino frio. Tabelas separadas também permitem políticas de backup e de recuperação diferentes para dados de criticidade diferente.

A pergunta de unit economics

Num BaaS, o número que importa não é a fatura do DynamoDB; é o custo por contrato ativo por mês, porque é ele que entra na precificação para o tenant. Somando escrita (régua, contatos, liquidações, eventos), leitura, armazenamento, PITR e o export mensal, a Lastro fica na casa de US$ 200 por mês em us-east-1. Algo como dois centavos de dólar por mil contratos.

Agora compare com o custo operacional da própria cobrança: 2 milhões de contratos em cobrança, dez tentativas de contato por mês, metade por SMS a R$ 0,05, são R$ 500 mil por mês só em SMS. O banco custa menos do que algumas horas de disparo.

A conclusão não é “DynamoDB é barato, relaxa”. É que o valor do modelo está nas decisões de negócio que ele torna corretas: o contador que impede o quarto contato economiza mais, em SMS e em processo judicial, do que qualquer otimização de byte.

Pense comigo

Você sabe quanto custa, em unidades de escrita, aplicar um pagamento na sua plataforma?

Se não sabe, também não sabe quanto vai custar o próximo quinto dia útil, nem se ele vai caber na capacidade que você tem.

Pontos altos

1. Guardar dado custa pouco. O que custa é escrever sem motivo e ler o que não precisava.

2. A carga do banco deve crescer com o que acontece (pagamentos, contatos, acordos), não com a passagem dos dias, nem com o aumento da inadimplência.

3. Scan com filtro cobra cada livro tirado da estante, não os que você levou.

4. Transação custa o dobro, como reconhecer firma: use só quando vários itens precisam mudar juntos ou nenhum muda.

5. As faixas de 1 KB e 4 KB funcionam como a tabela de peso dos Correios. Ponha no CI um teste que mede o consumo de cada operação de negócio.

6. O histórico vai para uma tabela própria, na classe mais barata para dado pouco acessado.

7. Meça o custo por contrato ativo e compare com o custo de uma decisão de cobrança errada.

6. A tabela é o estado; o stream é a história

A tabela responde “como está agora”. O resto da plataforma quer saber “o que aconteceu”: negativação, contabilidade, notificações, o motor de busca da mesa, o lakehouse. O DynamoDB Streams, consumido por Lambda com filtros de evento, publica as transições como eventos de domínio (InstallmentOverdue, PromiseBroken, AgreementSigned, SettlementApplied) em EventBridge ou Kafka.

No single-table design, toda mudança de todo tipo de item passa pelo mesmo stream. A documentação lembra que, com os filtros de evento da Lambda, isso não pesa na fatura; com outros consumidores, pesa. Filtre por type na borda.

O cuidado de modelagem aqui é sutil: o stream mostra o antes e o depois, mas não o porquê. Ele é a câmera de segurança da portaria: grava que a porta abriu às 14h02, mas não se foi o morador, o entregador ou o síndico. O motivo precisa estar no livro de registro. Se o contrato mudou de IN_COLLECTION para ACTIVE, foi pagamento, acordo ou estorno? O consumer não tem como saber, a menos que o item carregue essa informação. É mais um motivo para statusReason existir: ele não serve só para a tela, serve para que o evento derivado da mudança tenha significado.

E as perguntas analíticas da seção 1 nunca tocam a tabela. O export incremental para o S3 é cobrado por GB de dado da tabela e não consome capacidade de leitura; aging, roll rate e relatórios regulatórios rodam em Athena ou no lakehouse, sobre dados que o time de dados pode consultar livremente sem acordar ninguém de plantão.

Pontos altos

1. A tabela guarda o agora, o stream conta o que aconteceu, e o S3 atende as análises.

2. O stream é a câmera da portaria: mostra que a porta abriu, não por quê. O motivo precisa estar gravado no item.

3. BI nunca faz Scan na tabela que atende a operação; usa o export.

7. A revisão de design que eu faria no seu PR

Se você é tech lead ou arquiteto e vai revisar um modelo em DynamoDB, estas são as perguntas que eu levaria para a sala. Nenhuma delas é sobre sintaxe.

1. Onde está a lista de padrões de acesso, e quem do negócio a validou?

2. Qual pergunta vocês decidiram não responder na tabela, e para onde ela vai?

3. Qual atributo muda sem que nada aconteça no negócio? Por que ele está gravado em vez de derivado?

4. Alguma chave, da tabela ou de índice, contém dado pessoal?

5. Qual será o maior tenant daqui a dois anos, e qual chave ele esquenta primeiro?

6. Qual GSI, se sofrer throttling, bloqueia uma escrita crítica na tabela base?

7. Quais perguntas exigem leitura forte, e por que nenhuma delas depende de GSI?

8. Onde mora a idempotência de cada comando externo, e qual é a janela real de retry do provedor?

9. Quanto custa, em unidades de capacidade, cada operação de negócio, e existe teste para isso?

10. Qual é o plano para histórico, retenção, rotação do segredo de chave e offboarding de tenant?

Voltando à segunda-feira, 8h40

Com o modelo da Lastro, as três perguntas da head de cobrança têm dono.

• “Quantos contratos viraram 31+ no fim de semana?” Operacionalmente, uma Query na faixa D031_060 do tenant no GSI2, restrita por oldestOverdueDueDate, que lê a faixa e não a tabela. Analiticamente, a contagem dos eventos de mudança de faixa que o stream já publicou.

• “Quanto disso tem promessa para esta semana?” Consultas no GSI1 com nextAction = PROMISE_CHECK, uma por dia da semana, em cada shard, pelos mesmos workers que já leem a régua.

• “Por que ele recebeu três SMS no domingo?” Uma Query na coleção do devedor com o prefixo CONTACT#2026-09-20, ao lado do contador LIMIT#2026-09-20. Se foram três, a prova está ali, e o limite respeitado (ou violado) também.

No relacional, o schema descreve o dado, e as perguntas se resolvem depois. No DynamoDB, o schema descreve as perguntas. Em cobrança, as perguntas são o negócio: quem deve, desde quando, quanto, o que foi prometido, o que foi feito e o que a lei permite fazer a seguir. Um modelo que responde a isso com uma Query por pergunta não é só rápido e barato. É auditável, explicável e defensável.

Toda chave é uma pergunta. Garanta que alguém do negócio a tenha feito.

Se você opera cobrança, crédito ou pagamentos em DynamoDB, me conta nos comentários: qual foi a pergunta que a sua tabela não soube responder?

Guarde duas coisas desse parágrafo. A primeira é a palavra média: ela é a mentira mais cara do capacity planning. A segunda é que o recorde não foi surpresa — ele estava no calendário. Volte a esse detalhe quando chegarmos à seção 04.

Aquele mesmo minuto de pico foi visto de três lugares diferentes. O usuário viu uma tela de confirmação em dois segundos e não pensou mais no assunto. O SRE de plantão viu um gráfico subindo e uma métrica de saturação chegando perto de um limiar. E o Banco Central viu um número que, no fim do mês, vira nota do participante — com peso, com histórico e com consequência.

Este artigo é sobre tudo o que existe entre essas três visões. E ele parte de duas assimetrias que quase nenhum material sobre Kubernetes menciona, porque quase nenhum material sobre Kubernetes foi escrito pensando em um arranjo de pagamentos regulado:

01 / FUNDAMENTOS

Vocabulário sem vergonha

Se você já opera EKS há cinco anos, leia esta seção mesmo assim — não pelas definições, mas pela terceira, sobre a palavra provisionar, que é onde a maioria das reuniões de arquitetura descarrilha.

Cluster

Pense num condomínio residencial. Ele tem duas metades que quase nunca se confundem: a administração e os prédios.

A administração guarda a planta do empreendimento, decide qual apartamento vago vai receber qual morador, mantém o cadastro de quem está onde e passa o dia conferindo se a realidade bate com a planta. Ela não mora em lugar nenhum e não carrega móvel. Ela decide. Os prédios, por sua vez, não decidem nada — eles têm parede, encanamento, elevador e capacidade finita. É neles que a vida acontece.

Um cluster Kubernetes é exatamente isso. O control plane é a administração: API server, etcd, scheduler e controller manager. Ele guarda o estado desejado — “quero 28 réplicas deste serviço” — e trabalha sem parar para que a realidade se pareça com esse desejo. O data plane são os prédios: os nós, que no seu caso são instâncias EC2, com CPU e memória finitas, rodando a carga de verdade.

No EKS, a AWS opera a administração do condomínio por você, com escritórios em bairros diferentes da cidade — múltiplas zonas de disponibilidade. Você não vê essa administração, não a ajusta e não a demite às três da manhã. O que é seu, o que você dimensiona e o que você eventualmente derruba são os prédios.

Nó, pod, container, réplica

A analogia que funciona bem em treinamento interno: o nó é o prédio, o pod é o apartamento (com seu próprio endereço de rede), o container é o morador, e a réplica é a quantidade de apartamentos idênticos que você alugou. Escalar horizontalmente é alugar mais apartamentos. Escalar verticalmente é derrubar a parede e fazer um apartamento maior — com o inquilino dentro.

Provisionar (a palavra que causa confusão)

O mercado usa “provisionar” para três coisas diferentes, e o mal-entendido custa horas de reunião:

• Provisionar infraestrutura — criar capacidade física: subir nós, aumentar o node group, pedir instâncias à AWS. Leva minutos.

• Provisionar alocação — reservar CPU e memória para um pod dentro de um nó que já existe. É o campo resources.requests. É contabilidade do scheduler, não capacidade real. Leva milissegundos.

• Provisionar atendimento — decidir quantas réplicas do serviço existem. É o replicas ou o HPA. Leva segundos.

Quando alguém diz “o serviço está mal provisionado”, pergunte qual dos três. Na prática, a maioria dos incidentes de capacidade em banco é do tipo 1 chegando atrasado para atender o tipo 3 — e voltaremos a isso na seção 05.

EKS, ECS ou Fargate

Três opções, três conversas diferentes. A comparação honesta não é sobre qual é melhor, é sobre o que cada uma cobra de você:

EKS — Kubernetes gerenciado

• Ganha em: ecossistema maduro (HPA, KEDA, Karpenter, service mesh), portabilidade e facilidade de contratar gente que já conhece.

• Custa em: complexidade operacional real e a necessidade de um time de plataforma dedicado — não é algo que um time de produto opera nas horas vagas.

• Onde os bancos usam: core transacional. Iniciação, liquidação, consumidores do SPI.

ECS sobre EC2 — orquestração nativa da AWS

• Ganha em: simplicidade operacional e integração direta com IAM, ALB e CloudWatch, sem camadas de tradução.

• Custa em: acoplamento ao provedor e menos primitivas de escalonamento avançado quando o cenário aperta.

• Onde os bancos usam: serviços de apoio, backoffice e integrações internas.

Fargate — computação sem gestão de nó

• Ganha em: zero gestão de instância e isolamento por task.

• Custa em: prêmio por vCPU, tempo de partida de task maior e — o ponto que pega — ausência de DaemonSet.

• Onde os bancos usam: jobs, cargas esporádicas e ambientes de teste.

02 / DIMENSIONAMENTO

Horizontal e vertical: qual custa mais, qual derruba o cluster

Todo mundo sabe a definição. Poucos times sabem a consequência.

Vertical (scale-up): o pod fica maior

Você aumenta CPU e memória da mesma instância do serviço. Três problemas:

• Teto físico. Existe uma maior instância disponível, e depois dela não há mais para onde ir.

• Custo superlinear e ocioso. Você paga o tamanho do pico durante os vales. Às três da manhã, quando o Pix cai para uma fração do volume, aquela instância gigante continua na fatura.

• Reinício. Este é o ponto crítico. Aplicar um novo tamanho a um pod significa recriar o pod. O VPA em modo Auto mata e recria pods para redimensioná-los. Em um serviço que participa da liquidação de pagamentos, isso é matar processos no meio de transações — e o resultado não é um erro 500, é uma inconsistência contábil.

Horizontal (scale-out): mais réplicas do mesmo pod

É a única forma de escala que também entrega tolerância a falha: se você tem 28 réplicas em três zonas, perder uma zona é perder um terço da capacidade, não o serviço. Por isso é a escolha padrão. Mas ela tem custos escondidos que ninguém coloca no slide:

• Cada réplica é mais um pool de conexões contra o banco de dados.

• Cada réplica é mais um heap de JVM — o overhead de memória por instância é duplicado, não dividido.

• Cada réplica é mais um handshake mTLS a ser negociado com a infraestrutura do Banco Central.

• Cada réplica é mais um endereço IP consumido da sua subnet.

E qual delas custa mais?

O título desta seção faz duas perguntas, e a primeira tem resposta mais curta do que parece: depende de qual custo você está olhando, e a maioria dos times olha só um.

Na fatura da nuvem, a vertical costuma custar mais, por dois motivos que se somam. Instâncias grandes raramente têm preço proporcional — o salto de uma família para a seguinte cobra prêmio por densidade. E, pior, você paga o tamanho do pico vinte e quatro horas por dia, inclusive nas seis horas em que o Pix roda a uma fração do volume. A escala horizontal devolve capacidade quando o tráfego cai; a vertical não devolve nada.

No custo total de propriedade, a conta às vezes se inverte. Vinte e oito réplicas significam vinte e oito pools de conexão, vinte e oito heaps de JVM com seu overhead fixo, vinte e oito conjuntos de conexões TLS e vinte e oito vezes o custo do sidecar de malha, se você usa um. Em serviços com overhead fixo alto por instância, chega um ponto em que espalhar sai mais caro do que adensar — e esse ponto aparece na conta de memória antes de aparecer na de CPU.

A regra útil: a vertical desperdiça capacidade, a horizontal desperdiça overhead. Você escolhe qual desperdício prefere pagar. Mas só uma das duas pode te deixar sem serviço às onze da manhã de uma sexta-feira — e é essa a pergunta que realmente importa.

E qual delas derruba o cluster?

A resposta contraintuitiva: a horizontal. E quase nunca por esgotar CPU. Ela derruba por efeito de segunda ordem — o autoscaler funcionou perfeitamente e quebrou outra coisa. As mortes reais, em ordem de frequência:

Cinco formas de o autoscaling derrubar sua plataforma

1. Exaustão de IP no VPC CNI. No EKS, cada pod consome um IP real da subnet. O HPA sobe de 28 para 200 réplicas, o bloco CIDR acaba, e os pods ficam presos em ContainerCreating. Não é só o seu serviço: nenhum pod novo sobe no cluster. Mitigação: planejamento de CIDR desde o dia zero, prefix delegation, subnets dedicadas por cluster.

2. Exaustão do pool de conexões. 28 réplicas × 20 conexões = 560. Escalou para 90 réplicas: 1.800 conexões contra um banco que aceita 800. O autoscaling derrubou o banco de dados, e o banco de dados derrubou tudo. Mitigação: pooler externo, ou pool por réplica dimensionado em função do máximo de réplicas, não do atual.

3. Limite de ENI e de pods por instância. Cada tipo de instância EC2 suporta um número finito de interfaces de rede e, portanto, de pods. Escalar réplicas sem conferir esse teto gera pods pendentes com nós aparentemente vazios.

4. Thundering herd de inicialização. Quarenta pods Java subindo simultaneamente, cada um fazendo warmup de JIT, carregando cache e abrindo conexões. O pico de CPU da partida é maior que o pico do tráfego que motivou a escala. O cluster entra em espiral: mais carga → mais escala → mais partidas → mais carga.

5. HPA sem maxReplicas sensato. Combinado com Cluster Autoscaler, isso escala até estourar a quota da conta AWS ou o orçamento do trimestre. O incidente não é técnico; é uma ligação da área financeira.

Compartilhar

03 / TRÁFEGO

O que você escala e o que você não escala

Aqui está a diferença entre dimensionar um e-commerce e dimensionar um participante do Pix.

A frase para levar da seção: você pode enfileirar o que sai; não pode enfileirar o que entra. Se o Pix recebido não é processado dentro do tempo, isso não é uma fila crescendo — é um indicador regulatório sendo violado, com nome e CNPJ.

E há um detalhe de engenharia que muda completamente o modelo mental de quem vem do mundo web: a comunicação com o SPI não é push, é pull.

O Banco Central não bate na porta do seu servidor quando chega um Pix para o seu cliente. Em vez disso, o SPI mantém uma fila de saída por participante — uma caixa postal onde as mensagens destinadas a você se acumulam — e a responsabilidade de drenar essa caixa é inteiramente sua. Você inicia a leitura dessa fila com uma requisição GET, e a interface devolve no máximo dez mensagens por vez, em formato multipart. Se você parar de buscar, nada avisa ninguém: a caixa simplesmente enche, e o tempo continua correndo contra o seu indicador.

Além disso, a própria interface aplica controle de tráfego com saldo de tokens individualizado por participante — se o saldo zera, você recebe HTTP 429 com o cabeçalho Retry-After.

04 / A CONTA

Do volume nacional ao número de réplicas

Até aqui: vocabulário e restrições. Daqui em diante, a conta.

Esta é a parte que quase nunca é escrita, e é a única que separa dimensionamento de adivinhação. Vamos usar um banco fictício com 5% de participação no volume nacional, num dia nacional de 300 milhões de transações — números redondos e inventados, escolhidos para você refazer a conta com os seus.

Aqui está a cadeia inteira, de uma vez. Os oito degraus que separam um número público do Banco Central de um valor no seu repositório de infraestrutura. As subseções seguintes justificam cada um deles.

DEGRAU                                     OPERAÇÃO              RESULTADO
──────────────────────────────────────────────────────────────────────────
1. Volume nacional do dia                                    300.000.000
2. Participação do banco                   × 5%               15.000.000 tx/dia
3. TPS médio do dia                        ÷ 86.400                  174 tps
4. Fator intradiário (vale da madrugada)   × 2,5                     434 tps
5. Fator de calendário (5º dia útil)       × 1,5                     651 tps
6. Fan-out interno (8 chamadas por Pix)    × 8                     5.208 rps
7. Capacidade medida por pod               ÷ 250 rps                20,8 pods
8. Margem operacional                      + 33%             28 RÉPLICAS
──────────────────────────────────────────────────────────────────────────
Nenhum desses números é meu. Todos são seus — e todos devem estar
versionados junto com a infraestrutura, com a data da última revisão.

Repare no que essa tabela permite. Quando o volume nacional crescer 20%, você não refaz o dimensionamento: você troca o degrau 1 e lê o resultado. Quando alguém adicionar uma chamada nova ao fluxo de pagamento, o degrau 6 vira 9 e o número de réplicas sobe sozinho. É isso que separa um dimensionamento de um chute com aparência de rigor.

Agora, degrau por degrau.

Degraus 4 e 5: os dois fatores de pico

Um erro comum é multiplicar tudo por um número mágico. São dois fatores distintos, medem coisas diferentes e se compõem:

• Fator intradiário (degrau 4) — a razão entre o pico do dia e a média daquele mesmo dia. Existe por causa do vale da madrugada que você acabou de ver na curva. Tipicamente entre 2× e 3×; usei 2,5 na conta.

• Fator de calendário (degrau 5) — a razão entre um dia excepcional e um dia comum. Janela de salário, dia 10, sexta-feira, véspera de feriado, Black Friday, dezembro com décimo terceiro. Tipicamente 1,5× a 2×; usei 1,5.

Volte agora aos dois recordes do primeiro parágrafo, porque eles ensinam a parte difícil do degrau 5. Em dezembro de 2025, o prazo legal de salário caiu na sexta, dia 5, e o pico foi no dia 5. Em setembro de 2026, o mesmo prazo caiu num sábado, as empresas anteciparam, e o pico foi na sexta, dia 4 — que não era o quinto dia útil por contagem nenhuma. Some ainda o feriado da Independência na segunda seguinte, e um contador ingênuo de dias úteis apontaria para o dia 8.

A leitura maior é essa: isso não é volatilidade, é sazonalidade. E sazonalidade se coloca no calendário, não no relatório de incidente.

Degrau 6, o que todo mundo pula: fan-out

Um Pix não é uma requisição. É uma orquestração. Quando o time de produto diz “651 transações por segundo”, o time de plataforma precisa traduzir isso para o número real de chamadas que atravessam a malha interna. No fluxo de envio, cada transação costuma disparar algo próximo destas oito:

1. Consulta da chave no DICT

2. Motor antifraude e verificação de limites

3. Consulta e reserva de saldo

4. Envio da ordem de pagamento ao SPI (pacs.008)

5. Recebimento e processamento do retorno (pacs.002)

6. Efetivação e lançamento contábil

7. Notificação ao usuário

8. Publicação de evento para consumidores internos e webhooks

Daí o multiplicador 8 do degrau 6 — e daí os 5.208 requisições por segundo que o resto do dimensionamento usa. Oito é o número deste exemplo, não uma constante do mercado: o seu pode ser seis ou catorze, e a única forma de saber é medir. Cada uma dessas chamadas, além disso, precisa do seu próprio cálculo de capacidade, porque elas não têm a mesma latência nem o mesmo custo. E uma delas — a primeira — não pode ser dimensionada por este método de jeito nenhum, pelo motivo que a Parte 2 explica.

Lei de Little, em uma frase

concorrência = throughput × latência. Se você processa 5.200 requisições por segundo e cada uma leva 120 ms, existem cerca de 624 requisições vivas ao mesmo tempo dentro do seu sistema. É esse número — não o de requisições por segundo — que dimensiona threads, tamanho de pool de conexões e filas internas. E note a implicação perversa: se a latência dobrar por causa de uma dependência lenta, a concorrência dobra sem que o tráfego mude. É assim que uma lentidão externa vira esgotamento de thread pool interno.

Degrau 7: quanto um pod aguenta

Este é o único degrau que não se calcula — se mede. Você sobe um pod isolado, aplica carga crescente e encontra o ponto onde o percentil 99 começa a subir antes de a CPU saturar. No exemplo, esse ponto ficou em 250 requisições por segundo com p99 de 90 ms, num pod de 1 vCPU e 2 GB. Daí 5.208 ÷ 250 = 20,8 pods.

Se você pular esse teste e chutar a capacidade do pod, todos os sete degraus anteriores viram decoração. É o elo que transforma a cadeia em engenharia.

Degrau 8: a margem, e por que ela é 33% e não outra coisa

Vinte e um pods atendem o pico se nada der errado. Como algo sempre dá errado, a margem cobre três riscos distintos, e vale explicitar cada um em vez de esconder todos atrás de um número redondo:

• Erro de estimativa. Os degraus 4, 5 e 6 são aproximações. Se o fan-out real for 9 em vez de 8, você precisa de 23 pods, não 21.

• Tempo de reação. Como a seção 05 vai mostrar, o HPA leva segundos e o provisionamento de nó leva minutos. A margem é o que sustenta o serviço durante esse intervalo.

• Falha parcial. Pods morrem, nós são reciclados, um rolling update está sempre acontecendo em algum lugar.

Somando: 21 × 1,33 ≈ 28 réplicas.

Pense comigo

Você sabe qual é o fan-out real do seu fluxo de pagamento? Não o desenhado no diagrama de arquitetura — o medido, com trace distribuído, em produção, no horário de pico.

Na maioria dos times em que perguntei, o número medido era entre 30% e 100% maior que o número desenhado. Retries, chamadas de enriquecimento esquecidas, uma consulta de saldo feita duas vezes por dois serviços diferentes. Cada ponto percentual disso é hardware na fatura e latência no percentil 99 que o regulador lê.

05 / EXECUÇÃO

Do número ao YAML

Agora os 28 pods viram configuração. Cada valor abaixo vem de uma conta, não de um exemplo copiado da documentação.

# Serviço de iniciação de Pix — dimensionado para 5.208 rps de pico
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pix-iniciacao
spec:
  replicas: 28                       # degrau 8: 20,8 pods + 33% de margem
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 0              # 24x7x365: nunca reduzir capacidade durante deploy
  template:
    spec:
      terminationGracePeriodSeconds: 60   # > transação mais longa do fluxo
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels: { app: pix-iniciacao }
      containers:
        - name: app
          resources:
            requests:
              cpu: "800m"            # medido: 250 rps por pod a 800m
              memory: "1536Mi"
            limits:
              memory: "1536Mi"       # sempre. OOMKill > nó instável
              # cpu: deliberadamente ausente — ver nota sobre CFS
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-XX:MaxRAMPercentage=70.0 -XX:+UseG1GC"
          startupProbe:              # cobre o warmup da JVM
            httpGet: { path: /health/startup, port: 8080 }
            periodSeconds: 5
            failureThreshold: 24     # até 120s para subir
          readinessProbe:            # NÃO consulta dependência externa
            httpGet: { path: /health/ready, port: 8080 }
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sh","-c","sleep 15"]   # drenar antes de morrer

Por que não há limite de CPU

O limite de CPU no Kubernetes é implementado como cota do CFS do kernel: o container é throttled quando estoura a cota da janela, mesmo que haja CPU sobrando no nó. Em um serviço sensível a latência, isso significa introduzir pausas artificiais exatamente no percentil que o Banco Central mede. A prática dominante em plataformas transacionais: defina requests de CPU para garantir escalonamento justo, e não defina limits de CPU — ou defina com folga grande. Memória é o oposto: sempre limite, porque memória não é compressível e um pod vazando derruba o nó inteiro.

A armadilha do readinessProbe

Se o seu readinessProbe verifica a saúde de uma dependência externa — o DICT, por exemplo — uma instabilidade momentânea do Banco Central marca todos os seus pods como não prontos ao mesmo tempo. O balanceador remove todo mundo. Você acabou de converter uma degradação parcial de terceiro em indisponibilidade total sua, por conta própria, e o indicador que vai para o regulador é o seu.

Readiness responde: “este processo consegue atender?”. Liveness responde: “este processo precisa ser reiniciado?”. Nenhum dos dois responde “minhas dependências estão bem?” — isso é trabalho de circuit breaker e de painel, não de sonda.

A métrica de escala certa

CPU é uma péssima métrica de HPA para serviço que passa a maior parte do tempo esperando I/O — que é exatamente o caso de qualquer serviço de pagamento. Um pod pode estar com 30% de CPU e saturado de threads bloqueadas. As duas opções que funcionam:

• Métrica custom via Prometheus Adapter — requisições por segundo por pod, ou latência no percentil 95, para os serviços de entrada síncrona.

• KEDA com lag de fila — para os consumidores do SPI e para qualquer coisa orientada a evento. Como vimos na seção 03, o modelo do SPI é pull; a profundidade da fila é o sinal honesto.

behavior:
  scaleUp:
    stabilizationWindowSeconds: 0    # subir imediatamente
    policies:
      - type: Percent
        value: 100                   # dobrar
        periodSeconds: 30
  scaleDown:
    stabilizationWindowSeconds: 600  # descer só após 10 min estáveis
    policies:
      - type: Percent
        value: 10
        periodSeconds: 60

A regra é assimétrica de propósito: subir rápido, descer devagar. O custo de uma réplica a mais por dez minutos é centavos. O custo de uma réplica a menos durante um pico é um indicador.

O gap de dois minutos

Este é o problema que separa quem leu a documentação de quem operou o cluster num quinto dia útil.

Os números, em sequência. O HPA avalia métricas a cada 15 segundos e, com a janela de estabilização zerada, decide escalar em algo entre 15 e 30 segundos. Ele cria os pods imediatamente — e é aí que o problema começa, porque criar um pod não é o mesmo que ter onde colocá-lo. Se não há nó com espaço, o pod fica em Pending. Provisionar um nó novo leva cerca de 40 a 60 segundos com Karpenter e tipicamente 2 a 3 minutos com o Cluster Autoscaler clássico, somando decisão, chamada à API da AWS, boot da instância, registro no cluster e download de imagem.

Ou seja: entre o tráfego subir e a capacidade nova existir de verdade, passam-se de um a três minutos. Nesse intervalo, os pods novos existem no etcd e não existem em lugar nenhum. O pico do Pix não espera três minutos.

As três respostas usadas em produção para fechar esse intervalo:

• Pods de headroom. Um Deployment de pods que não fazem nada, com priorityClass de valor negativo, ocupando espaço em nós já provisionados. Quando o serviço real precisa escalar, o scheduler preempta os pods de headroom instantaneamente e usa a capacidade que já estava quente. Você paga capacidade ociosa em troca de tempo de reação — e em pagamento, tempo de reação é o produto.

• Pré-escala por calendário. Um CronJob que aumenta minReplicas do HPA antes das janelas conhecidas: último dia bancário antes do prazo de salário, dia 10, sextas, véspera de feriado, Black Friday, dezembro. Repare que a primeira dessas janelas é calculada, não é uma data fixa — como a seção 04 mostrou, uma regra ingênua de “quinto dia útil” erra o dia justamente nos meses em que o pico é maior. Sazonalidade previsível não deveria ser tratada como surpresa.

• Karpenter com node pools pré-aquecidos e diversidade de tipos de instância, para não depender de um único tipo estar disponível na AZ no momento exato do pico.

Morrer direito

Um detalhe que só aparece quando o dinheiro é real. Quando o Kubernetes decide encerrar um pod, ele envia SIGTERM e, em paralelo, remove o pod dos endpoints do serviço. Essas duas coisas não são atômicas: existe uma janela em que o pod já recebeu o sinal de término e ainda está recebendo tráfego. Daí o preStop com uma pausa — ele dá tempo para a remoção propagar antes de a aplicação começar a se desligar. Depois disso, o terminationGracePeriodSeconds precisa ser maior que a transação mais longa em voo.

Sem isso, um rolling update rotineiro às 14h de uma sexta-feira interrompe liquidações no meio. E o efeito não é um erro que o usuário reenvia — é uma transação em estado indeterminado que alguém vai conciliar manualmente na segunda-feira.

06 / FECHAMENTO

O que a Parte 1 comprou

Se você seguiu a escada, agora existe uma cadeia auditável entre um número público do Banco Central e um valor no seu repositório de infraestrutura. Quando alguém perguntar “por que 28 réplicas?”, a resposta não é “foi o que a gente configurou”. São oito degraus, cada um com uma premissa nomeada, revisável quando o volume mudar — e ele vai mudar, todo trimestre. Dois recordes nacionais em nove meses deveriam bastar como aviso.

Um checklist do que revisar segunda de manhã:

• Qual é o fan-out medido do seu fluxo de pagamento, não o desenhado?

• Alguém já mediu quantos rps um pod seu aguenta, ou o degrau 7 é um chute?

• A sua margem do degrau 8 cobre a perda de uma zona no pico — e, se não cobre, isso está escrito em algum lugar com data e responsável?

• Seu maxReplicas multiplicado pelo tamanho do pool de conexões cabe no seu banco de dados?

• Seu bloco CIDR suporta o número máximo de pods que o HPA pode criar?

• Seu readinessProbe depende de terceiro?

• Existe headroom, ou o pico vai esperar o nó?

• O terminationGracePeriodSeconds é maior que a sua transação mais longa?

Pense comigo

Toda a matemática desta Parte 1 assume que capacidade é algo que você compra. Você calcula, provisiona, escala e o problema cede.

Na Parte 2 nós vamos encontrar o componente do ecossistema Pix onde essa premissa simplesmente não vale — onde adicionar réplicas não aumenta nada, porque o limite não é o seu hardware, é uma cota definida em norma. E onde a decisão entre um microserviço dedicado e uma função Lambda deixa de ser preferência arquitetural e vira uma conta de custo e de percentil.

Na Parte 2: como a API do DICT realmente funciona, o algoritmo de baldes e fichas do Banco Central, por que consulta de chave não escala como serviço normal, microserviço dedicado versus Lambda com a conta feita, a régua de disponibilidade por categoria de participante e o que muda no dia a dia dos times de engenharia e de SRE quando o SLO vem do regulador.

Fontes primárias para quem quiser conferir os números: Manual de Tempos do Pix, Manual Operacional do DICT e Manual das Interfaces de Comunicação, todos publicados pelo Banco Central; estatísticas do Pix no portal do BCB; repositórios bacen/pix-api e bacen/pix-dict-api no GitHub. Os manuais são revisados com frequência — sempre confira a versão vigente antes de usar um número em decisão de arquitetura.

Obrigado por ler até o final, até o próximo!

O DBA foi embora e deixou a chave com você

Em 2013, o fluxo era claro. Você recebia um documento — quase sempre um PDF com um DER exportado do Erwin — e implementava. As tabelas já existiam. Os nomes das colunas já tinham sido decididos por alguém que passou os últimos quinze anos brigando por integridade referencial. Se você quisesse um índice, abria um chamado. Se quisesse uma coluna nova, abria um chamado e esperava o comitê de mudanças da quinta-feira.

Aquilo era lento, burocrático e frequentemente irritante. Mas havia ali uma coisa que perdemos sem perceber: existia um adulto na sala cuja única função era proteger os dados de nós.

Hoje, o fluxo é outro. A squad é autônoma. Você provisiona o banco com Terraform, escolhe entre PostgreSQL e DynamoDB numa thread do Slack que dura quinze minutos, define a chave de partição no meio de um refinamento e sobe a migration junto com o PR da feature. O DBA virou SRE de plataforma, ou virou “time de dados” que cuida do lakehouse, ou simplesmente não existe mais no organograma. Ninguém revisa seu modelo. Ninguém pergunta por que aquele campo é VARCHAR(255) guardando um valor monetário.

Nós ganhamos velocidade — muita. E ganhamos também uma responsabilidade que a maioria de nós nunca foi treinada para exercer: traduzir requisito de negócio em estrutura de dados. Não é uma tarefa acessória do desenvolvimento. É a decisão de arquitetura mais duradoura que um engenheiro toma.

É por isso que a régua da modelagem precisa ser mais alta que a régua do código. Código ruim você reescreve. Dado ruim você carrega.

O pecado original: quando orientação a objetos vira modelagem de dados

Antes dos princípios, precisamos falar de um viés que a nossa formação instalou e que atrapalha ativamente o raciocínio sobre dados.

A maioria de nós aprendeu a modelar objetos antes de aprender a modelar dados. E aprendeu que a classe é o ponto de partida. Então o caminho natural virou: escrevo a entidade, anoto com @Entity, deixo o Hibernate gerar o DDL, e pronto — “o modelo está feito”.

Só que não está. O que existe ali é uma projeção acidental de decisões de código sobre uma estrutura de armazenamento permanente. Ninguém decidiu nada sobre os dados. O schema foi um efeito colateral.

Objetos e dados são coisas diferentes

Comece pelo tempo de vida. Um objeto existe por milissegundos: nasce numa requisição, é serializado, morre no garbage collector. O dado que ele representa existe por décadas — vai sobreviver ao serviço que o criou, à linguagem em que foi escrito e provavelmente à empresa que o gerou na forma atual.

Depois, a identidade. Objeto tem identidade por referência: dois objetos com os mesmos atributos podem ser coisas distintas, e você resolve isso sobrescrevendo equals(). Dado tem identidade por chave, e essa chave precisa ser estável, única e significativa para o mundo externo — porque outros sistemas vão apontar para ela.

Vem então a inversão mais importante, e a que quase ninguém enuncia: objeto existe para esconder estado; dado existe para expor estado. Encapsulamento é a virtude central da orientação a objetos — o mundo lá fora não deve saber como o saldo é calculado. Mas o banco de dados tem a função oposta: ele precisa ser consultável, auditável, agregável por gente que nunca vai ler o seu código. Aplicar reflexo de encapsulamento na modelagem de dados produz esquemas opacos, com campos crípticos1 cujo significado só o serviço dono conhece.

Some a isso a quantidade de consumidores. O seu objeto tem exatamente um consumidor: o seu código. O seu dado tem N — o time de BI, o relatório regulatório, o serviço de antifraude, o pipeline do lakehouse, o analista que vai abrir um cliente SQL às onze da noite para investigar um incidente, e o próximo time daqui a quatro anos. Modelar para um consumidor conhecido é fácil; modelar para consumidores que você nunca vai conhecer exige outro tipo de rigor.

E, por fim, o critério de otimização. Objeto é otimizado para comportamento: coesão, baixo acoplamento, facilidade de mudança. Dado é otimizado para verdade e para perguntas: integridade, rastreabilidade, latência de consulta. São eixos diferentes — e otimizar um deles não melhora o outro por acidente.

O object-relational impedance mismatch não é um detalhe de mapeamento. É um sintoma de que os dois mundos respondem a perguntas diferentes. Quando você deixa o modelo de objetos ditar o modelo de dados, três estragos previsíveis acontecem:

1. O UPDATE destrutivo. Este é o mais caro de todos. Em OO, mutar estado é natural:

// parece limpo. É uma bomba-relógio.
public class Conta {
    private BigDecimal saldo;

    public void debitar(BigDecimal valor) {
        this.saldo = this.saldo.subtract(valor);
    }
}

Mapeado direto, isso vira UPDATE conta SET saldo = ? WHERE id = ?. E aí, três meses depois, chega uma contestação de MED sobre um Pix de R$ 4.200 e alguém pergunta: “qual era o saldo dessa conta às 14h32 do dia 12?”. A resposta honesta é: não sabemos. Nós sobrescrevemos.

2. A herança que vaza para a tabela. SINGLE_TABLE produz aquela tabela com 60 colunas onde 40 são nulas dependendo da linha. JOINED produz JOINs em toda leitura para servir uma hierarquia que só existe porque queríamos reaproveitar código. Herança é ferramenta de reúso de comportamento. Ela raramente descreve uma verdade do negócio.

3. O modelo anêmico invertido. A classe vira um saco de getters e setters, a regra vaga nos services — e como a classe não tem semântica, a tabela também não tem. Fica um status genérico, um tipo genérico, um valor sem moeda. O domínio desaparece dos dois lados ao mesmo tempo.

Ajuste de mentalidade

Não é “OO é ruim”. É que o modelo de domínio e o modelo de persistência são dois artefatos distintos, com propósitos distintos, e é saudável que eles não sejam idênticos. O objeto responde “o que esse conceito faz?”. O dado responde “o que aconteceu, e como eu provo?”. Quando você aceita que são perguntas diferentes, os cinco princípios abaixo deixam de ser teoria.

Os cinco princípios

1. O modelo de dados é o modelo do negócio

2. Fatos são imutáveis; estado é derivado

3. Modele para as perguntas, não para os dados

4. Consistência tem fronteiras — e você as desenha

5. Todo schema evolui; schema-less é uma mentira confortável

Compartilhar

Princípio 01: O modelo de dados é o modelo do negócio

Se o pessoal de operações diz “devolução”, o jurídico diz “devolução”, o Bacen diz “devolução” — e a sua tabela chama TB_MOV_CAD_02 com uma flag TP_MOV = 'D' —, você não modelou dados. Você criou um dicionário paralelo que existe na cabeça de três pessoas, das quais duas já pediram demissão. 🙃

Modelagem começa nos substantivos e verbos do domínio, não nos tipos de coluna. E isso não é preciosismo estético: nome é a interface de leitura do seu dado, e ela dura mais que qualquer API.

Lição 1.1 → Nome de coluna é contrato permanente, não variável local

Renomear uma variável é Shift+F6. Renomear uma coluna em produção é: migration, dual-write, atualizar as views, avisar o time de BI, atualizar os DAGs do lakehouse, atualizar o relatório regulatório, descobrir que existe um SELECT * num job COBOL de 2008 e negociar a janela de mudança.

Na prática, ninguém renomeia. O nome errado fica. E o pior: o nome errado ensina errado. Todo desenvolvedor que chegar nos próximos oito anos vai aprender o domínio lendo o seu schema, e vai aprender torto.

Escreva o nome pensando em quem vai ler daqui a cinco anos, não em quem está digitando agora.

Lição 1.2 → Não ache conceitos distintos sob um nome genérico

Este é o erro mais comum e o mais destrutivo em sistemas financeiros. A palavra “transação” parece cobrir tudo — então cria-se tb_transacao com um tipo e um status, e enfia-se o mundo inteiro lá dentro.

Só que num cartão de crédito, quatro coisas absolutamente diferentes acontecem com o mesmo dinheiro:

• Autorização — a bandeira reserva limite. Não há dinheiro se movendo. Pode expirar sozinha.

• Captura — o lojista confirma a venda. Agora existe uma obrigação.

• Liquidação — o dinheiro efetivamente troca de mãos entre instituições, em D+N.

• Faturamento — a obrigação entra num ciclo de cobrança do portador.

Cada uma tem ciclo de vida próprio, prazo próprio, efeito contábil próprio e regra de estorno própria. Achatar as quatro em uma tabela com status IN ('AUTORIZADA','CAPTURADA','LIQUIDADA','FATURADA') parece elegante no dia 1 e vira um inferno no dia 400 — porque uma autorização pode ser parcialmente capturada, uma captura pode ser liquidada em duas parcelas de agenda, e o modelo não tem onde colocar isso.

Regra prática: se dois “estados” de uma entidade têm ciclos de vida independentes, cardinalidade diferente entre si, ou donos diferentes no negócio — eles não são estados. São entidades diferentes.

Lição 1.3 → Seu modelo precisa passar no teste do auditor

Pegue o seu DER e mostre para um analista de negócio, um contador ou alguém de compliance. Não explique nada. Se a pessoa não conseguir apontar onde está a devolução de um Pix, onde está o bloqueio judicial e onde está o saldo disponível versus o saldo bloqueado, o modelo falhou — mesmo que o código funcione perfeitamente.

Isso não é sobre documentação bonita. É que num domínio regulado, o seu banco de dados é a evidência. Quando o regulador pedir a trilha de uma operação e a resposta exigir um JOIN de seis tabelas mais o conhecimento tácito de que flag_ctrl = 3 significa “estornado por MED”, você não tem um problema técnico. Tem um problema de negócio com prazo.

Pense comigo — antes de nomear qualquer coisa

• Esse nome existe no vocabulário de quem opera o negócio? Se você inventou o termo, provavelmente inventou também o conceito — e conceito inventado não sobrevive à primeira conversa com o jurídico.

• Quando eu digo “transação”, o especialista de domínio entende a mesma coisa que eu? Pergunte assim, literalmente: “para você, o que é uma transação aqui?”. Se ele começar a responder com “depende”, você acabou de descobrir que são várias entidades.

• Esses dois campos que eu estou juntando têm o mesmo dono e o mesmo ciclo de vida? Se um muda por decisão do cliente e o outro por evento do Bacen, eles não pertencem à mesma linha.

• Se eu sumir amanhã, alguém entende esse schema sem me perguntar nada? Essa é a única métrica de qualidade de nomenclatura que importa.

Princípio 02: Fatos são imutáveis; estado é derivado

Este é o princípio mais poderoso do artigo, o mais violado na prática, e o único que a contabilidade resolveu no século XIV — enquanto nós ainda escrevemos UPDATE saldo SET ... em 2026.

Luca Pacioli formalizou as partidas dobradas em 1494 sobre uma ideia simples: você não altera o passado. Você registra um novo lançamento. O razão é append-only, e o saldo nunca é armazenado como verdade — ele é calculado. É a arquitetura de dados mais bem-sucedida da história da humanidade, e ela é anterior ao computador.

Lição 2.1 → O UPDATE destrutivo apaga a única evidência que você tinha

Compare as duas modelagens de uma transferência de R$ 100 entre contas internas.

Modelo mutável (o que a maioria faz):

UPDATE conta SET saldo = saldo - 100 WHERE id = 'A';
UPDATE conta SET saldo = saldo + 100 WHERE id = 'B';

Funciona. É rápido. E destruiu a informação. Não existe mais como saber por que o saldo mudou, quando, por ordem de quem, ou qual era antes. Você guardou o resultado e jogou fora a causa.

Modelo de fatos (razão append-only):

id     conta   natureza   valor     origem
─────────────────────────────────────────────────
9001   A       DEBITO     100,00    TRANSF#7712
9002   B       CREDITO    100,00    TRANSF#7712

Nada foi sobrescrito. Duas linhas novas, apontando para a mesma ordem de transferência — e a soma das duas é zero, que é exatamente a garantia das partidas dobradas.

-- saldo deixa de ser um campo. Vira uma pergunta.
SELECT SUM(CASE WHEN tipo = 'CREDITO' THEN valor ELSE -valor END)
FROM lancamento
WHERE conta = 'A' AND data_movimento <= :data_corte;

Repare no ganho que caiu de graça: aquele :data_corte significa que você consegue responder “qual era o saldo em qualquer instante do passado” — sem nenhuma estrutura adicional. No modelo mutável, essa pergunta é impossível a qualquer preço.

“Mas isso não é lento?”

É a objeção padrão, e ela tem resposta madura: snapshot. Você materializa o saldo consolidado em pontos de corte (fechamento diário, por exemplo) e soma apenas o delta desde o último snapshot. O snapshot é cache, não verdade — pode ser descartado e reconstruído a qualquer momento a partir dos fatos. O caminho errado é o inverso: guardar o saldo como verdade e tentar reconstruir os fatos depois. Isso não tem volta.

Lição 2.2 → O fato precisa carregar o “porquê”, não só o “quanto”

Muitos times chegam na metade do caminho: criam uma tabela de histórico com saldo_anterior e saldo_novo. Isso é melhor que nada, mas ainda não é história — é o diff sem o commit message.

Um fato bem modelado responde: o que aconteceu, quando, por causa de quê, por ordem de quem, e sob qual referência externa.

lancamento
├─ id
├─ conta_id
├─ natureza          DEBITO | CREDITO
├─ valor             DECIMAL(18,2) — nunca float, nunca varchar
├─ evento_origem     PIX_RECEBIDO | DEVOLUCAO_MED | TARIFA_TED | ...
├─ referencia_externa E2E ID do Pix, NSU, ID do contrato
├─ lancamento_estornado_id aponta para o fato que este reverte
├─ data_movimento    quando o dinheiro se moveu
├─ data_competencia  a que período isso pertence
└─ data_registro     quando NÓS soubemos

E note a linha de estorno: no modelo de fatos, você nunca apaga nem edita um lançamento errado. Você lança o contrário e aponta para o original. É exatamente o que a contabilidade chama de lançamento de retificação, e é o que permite que a resposta para “esse cliente foi debitado indevidamente?” seja SELECT, e não arqueologia em log de aplicação.

Lição 2.3 → Tempo é dimensão do dado, não metadado de auditoria

Quase todo modelo carrega um created_at e acha que resolveu o tempo. Não resolveu. Em sistemas financeiros existem, no mínimo, três tempos independentes, e confundi-los gera divergência contábil real:

• Data de movimento — quando o dinheiro efetivamente se moveu.

• Data de competência — a que período o fato pertence economicamente.

• Data de registro (ou conhecimento) — quando o seu sistema tomou ciência.

Um exemplo que todo mundo que trabalha com fechamento reconhece: em 3 de agosto, chega uma devolução referente a uma operação de 28 de julho. Movimento: 3/8. Competência: julho. Registro: 3/8. Se o seu modelo tem uma data só, você é obrigado a escolher entre mentir para a contabilidade ou mentir para o extrato do cliente.

E há a pergunta que separa modelo maduro de modelo ingênuo: “me mostre o balancete como ele estava em 31/07, do jeito que nós o víamos naquele dia”. Isso é modelagem bitemporal — tempo do fato × tempo do conhecimento. Se você fez UPDATE, essa pergunta não tem resposta. Se você guardou fatos com as três datas, é um WHERE.

Pense comigo — antes de escrever qualquer UPDATE

• Isso que eu vou sobrescrever é um estado ou é um fato? “Endereço do cliente” é estado (talvez). “Saldo”, “status de pagamento”, “limite aprovado” quase sempre são consequências de fatos — e fato não se sobrescreve.

• Se alguém perguntar daqui a dois anos por que esse valor mudou, eu consigo responder só com dados? Se a resposta envolve “olha o log da aplicação”, o modelo está incompleto. Log expira; dado permanece.

• Eu consigo reconstruir esse valor do zero se ele for corrompido? Se sim, ele é derivado e não deveria ser a fonte da verdade. Se não, ele é fato e não deveria ser mutável. Uma das duas coisas — nunca as duas.

• Quantos tempos diferentes esse fato tem? Pergunte ao negócio: “quando isso aconteceu” e “a que mês isso pertence” são a mesma data? Se hesitarem, você precisa de duas colunas.

Deixe um comentário

Princípio 03: Modele para as perguntas, não para os dados

Aqui mora a discussão relacional × não relacional — e ela é muito menos religiosa do que a internet faz parecer. Normalização otimiza escrita e integridade. Desnormalização otimiza leitura. Nenhuma das duas é “certa” no vácuo. A pergunta correta nunca foi “qual banco eu uso?”, e sim “quais perguntas esse dado precisa responder, com que latência, e quantas vezes por segundo?”.

Lição 3.1 → Normalização e desnormalização são estratégias, não moral

A terceira forma normal existe para garantir que cada fato seja afirmado em exatamente um lugar — o que torna impossível ter duas verdades contraditórias. É uma proteção de escrita. Você paga por ela em JOINs.

Desnormalizar é o movimento contrário: aceitar redundância controlada para comprar latência de leitura. Você paga por ela em risco de divergência.

O erro não é escolher um dos dois. O erro é escolher sem saber qual dos dois custos você está pagando. Um sinal claro de que a decisão foi automática: o time normalizou até a última gota uma tabela que só é lida por um dashboard uma vez por dia — e desnormalizou o cadastro de cliente, que é escrito por seis fluxos diferentes.

Lição 3.2 → No NoSQL, o padrão de acesso vem antes da entidade — e é quase irreversível

Esta é a diferença prática que muita gente descobre tarde demais.

No relacional, você modela entidades e relacionamentos primeiro; se uma consulta nova aparecer daqui a um ano, você cria um índice e segue a vida. O modelo perdoa.

Num banco de chave-partição — DynamoDB, Cassandra —, a chave é a arquitetura. Ela determina onde o dado fisicamente mora, e mudá-la depois significa reescrever a tabela inteira. O modelo não perdoa.

// extrato: "os lançamentos da conta X no período Y, mais recentes primeiro"
PK = "CONTA#00219-4"
SK = "LANC#2026-08-19T14:32:11Z#a3f9"

// a pergunta vira uma única leitura sequencial, sem JOIN, sem scan:
Query(PK = "CONTA#00219-4", SK between "LANC#2026-08-01" and "LANC#2026-08-31")

Isso é lindo — para essa pergunta. Agora tente responder “todos os lançamentos com E2E ID X, em qualquer conta”, ou “soma de tarifas por agência no mês”. Sem um índice secundário planejado desde o início, essas perguntas custam um scan da base inteira.

Portanto: em NoSQL, listar os padrões de acesso antes de desenhar a chave não é boa prática opcional. É a modelagem inteira.

Lição 3.3 → Um dado pode ter vários modelos — mas só uma fonte da verdade

A saída madura para o falso dilema é aceitar que o mesmo fato bancário quer formas diferentes para consumidores diferentes:

• Razão contábil — relacional, normalizado, consistência forte, transacional. É a fonte da verdade. Precisa fechar até o centavo e sobreviver a auditoria.

• Extrato do app — documento desnormalizado, particionado por conta e período, leitura em milissegundos, consistência eventual tolerável (o cliente aceita ver o lançamento com 300 ms de atraso; não aceita esperar 4 segundos pela tela).

• Base analítica — colunar, orientada a agregação, atualizada por batch.

Três modelos, um fato. Isso é CQRS na prática — e não é sofisticação: é reconhecer que “consultar” e “registrar” são atividades com requisitos opostos.

A regra que não pode ser quebrada

Projeções derivam; nunca escrevem por conta própria. No instante em que dois caminhos de escrita alimentam duas cópias do mesmo fato de forma independente, você não tem duas visões — tem duas verdades. E quando elas divergirem (e vão divergir), não existirá critério técnico para decidir qual está certa.

Pense comigo — antes de escolher a tecnologia

• Quais são as cinco perguntas que esse dado vai responder em produção? Escreva as cinco antes de abrir o Terraform. Se você não consegue escrever nem três, você ainda não entendeu o requisito — e nenhum banco resolve isso.

• Qual dessas perguntas é feita 10.000 vezes por minuto, e qual é feita uma vez por mês? Modele para a primeira, tolere a segunda. Otimizar o caminho frio é a forma mais comum de desperdiçar complexidade.

• Quem é o dono da verdade desse dado? Se você não consegue apontar um lugar, você já tem um problema de consistência — só ainda não sabe.

• O que quebra se essa leitura estiver 500 ms atrasada? Se a resposta for “nada”, você acabou de ganhar liberdade arquitetural enorme. Se for “o saldo pode ficar negativo”, você acabou de descobrir onde precisa de consistência forte.

Princípio 04: Consistência tem fronteiras — e você as desenha

Todo engenheiro sabe recitar ACID. Poucos percebem que o desenho do modelo é o que decide onde o ACID pode ser aplicado. A fronteira transacional não é uma configuração de infraestrutura: é uma consequência direta de como você agrupou os dados.

Lição 4.1 → O agregado define o que cabe em um commit

Um agregado é o conjunto de dados que precisa mudar junto para que uma invariante do negócio se mantenha. “O saldo da conta nunca pode ficar abaixo do limite” é uma invariante — logo, conta e seus lançamentos do momento precisam ser consistentes no mesmo instante.

O sintoma de agregado mal desenhado é conhecido: você se pega precisando de uma transação que atravessa três serviços. Nesse ponto há exatamente duas saídas honestas — ou a fronteira está errada e esses dados deveriam viver juntos, ou eles são realmente independentes e você precisa de saga com compensação. O que não existe é a terceira: transação distribuída em dois bancos diferentes via @Transactional e fé.

Lição 4.2 → Estados intermediários são cidadãos de primeira classe

Um Pix atravessa a fronteira da sua instituição. Entre a ordem do cliente e a confirmação do SPI existe um intervalo em que o dinheiro precisa estar contabilmente em algum lugar. Ele não está mais totalmente disponível para o pagador e ainda não é do recebedor.

Modelo ingênuo:

conta.saldo -= valor;          // e se o SPI recusar?
conta.processado = true;       // processado significa o quê, exatamente?

Modelo honesto: o valor sai do saldo disponível e entra numa posição transitória explícita — bloqueio, provisão, conta de trânsito —, e só sai de lá quando existe um fato terminal: liquidação confirmada, devolução, ou expiração de prazo.

Isso muda a modelagem por completo. Você deixa de ter um boolean e passa a ter uma máquina de estados com transições registradas como fatos: ORDEM_RECEBIDA → RESERVADA → ENVIADA_SPI → LIQUIDADA, com ramos para DEVOLVIDA e EXPIRADA. Cada transição é uma linha. O estado atual é a última linha — ou seja, derivado (Princípio 2 outra vez).

Teste rápido no seu modelo: se existe um campo booleano chamado processado, enviado ou ok em algo que atravessa rede, você tem um estado intermediário não modelado. E ele vai aparecer — geralmente às duas da manhã, na forma de dinheiro que “sumiu”.

Lição 4.3 → Idempotência mora no schema, não no if

Sistemas de mensageria sérios entregam at-least-once. Isso significa que a mesma mensagem vai chegar duas vezes — não é hipótese, é garantia. E a defesa contra isso não é código defensivo; é uma restrição de banco.

-- a defesa real cabe em uma linha
ALTER TABLE lancamento
  ADD CONSTRAINT uk_idempotencia UNIQUE (chave_idempotencia);

Um SELECT antes do INSERT para “verificar se já existe” não protege nada: entre a leitura e a escrita cabem duas instâncias do seu serviço fazendo exatamente a mesma coisa. Só a restrição no banco é atômica. O código apenas trata a violação e devolve sucesso — porque receber duas vezes o mesmo pedido e produzir um efeito só é o comportamento correto.

No Pix, esse pensamento fica evidente: o E2E ID identifica unicamente a operação ponta a ponta. Ele é uma chave natural de idempotência que o próprio arranjo te entrega de graça. Times que a ignoram e criam um UUID interno próprio descobrem, na primeira reapresentação de mensagem, que duplicaram crédito.

Pense comigo — antes de desenhar a fronteira

• Qual invariante do negócio essa operação precisa manter no mesmo instante? Só o que a invariante exige entra na transação. Todo o resto pode ser eventual — e provavelmente deveria ser.

• Se isso falhar no meio, o dinheiro está em que lugar do meu modelo? Se a resposta for “em lugar nenhum” ou “no ar”, falta uma entidade. Dinheiro em trânsito precisa de endereço.

• Se essa mensagem chegar três vezes, quantos efeitos eu produzo? Se a resposta depende de timing, você tem uma condição de corrida esperando volume para se manifestar.

• Existe uma chave natural que o domínio já me dá? E2E ID, NSU, número de contrato, chave da nota. Chave natural do domínio quase sempre é melhor guardiã de unicidade do que qualquer UUID que você gerar.

Princípio 05: Todo schema evolui; schema-less é uma mentira confortável

Não existe dado sem schema. Existe schema não declarado. Quando alguém diz “nosso banco é schema-less”, o que aconteceu de fato foi: o schema saiu do banco — onde era validado, versionado e visível — e foi para dentro do código, onde ninguém valida nada e onde existem, agora, quatro versões diferentes rodando ao mesmo tempo em produção.

Lição 5.1 → O schema não sumiu; ele apenas trocou de dono

No relacional, se você tentar inserir texto numa coluna numérica, o banco recusa. É chato e é maravilhoso: o erro acontece na escrita, com o culpado ainda em cena.

Num documento livre, o dado entra. O erro acontece meses depois, na leitura, quando alguém tenta somar uma coleção onde 3% dos registros gravaram valor como string porque uma versão antiga do serviço serializava diferente. Aí o culpado não está mais em cena — e o dado ruim já está em backup, em réplica e no lakehouse.

Escolher NoSQL é legítimo. Escolher NoSQL e abrir mão de validação é abrir mão de qualidade de dado. Use schema validation2, use contratos de dados versionados, use um registry — mas declare o schema em algum lugar onde ele seja verificável por máquina, não pela boa vontade do próximo desenvolvedor.

Lição 5.2 → Migração é prática de engenharia contínua, não evento traumático

O padrão que torna evolução de schema um não-evento é o expand / contract:

1. Expandir — adicionar a nova estrutura, sempre opcional/nulável. Nada quebra; a versão antiga do código ignora o campo novo.

2. Escrever nos dois — o serviço passa a gravar no formato antigo e no novo.

3. Backfill — job idempotente e reprocessável converte o histórico, em lotes, com controle de progresso.

4. Migrar a leitura — consumidores passam a ler o campo novo, um a um.

5. Contrair — só então o campo antigo morre.

Cada passo é reversível isoladamente, e em nenhum momento existe uma janela em que o sistema precise ficar fora do ar. Compare com o modelo tradicional — “migration na madrugada de sábado, com rollback plan e todo mundo acordado” — e fica claro qual dos dois escala num time que faz deploy todo dia.

Lição 5.3 → Saiba, no dia 1, quais mudanças serão baratas e quais serão caras

Nem toda evolução custa igual. Vale ter o mapa na cabeça:

• Barato: adicionar campo opcional; adicionar índice; adicionar novo valor a um enum aberto.

• Médio: tornar um campo obrigatório; extrair uma entidade nova; alterar precisão numérica.

• Caro: mudar o tipo de um campo com histórico; mudar a chave de partição; quebrar uma linha em várias; retroagir semântica (”a partir de agora valor passa a ser líquido, não bruto”).

O exemplo canônico: um campo valor DECIMAL(18,2) parece perfeito — até o dia em que a instituição opera câmbio, ou cripto, ou pontos de fidelidade. Transformar valor em { montante, moeda } em 400 milhões de registros é um projeto de trimestre, com dual-write, backfill e reconciliação.

Daí uma heurística que envelhece muito bem: todo dado que tem unidade deve carregar a unidade desde o primeiro dia — moeda com valor, fuso com timestamp, base com taxa. Custa uma coluna hoje. Economiza um trimestre depois.

Cuidado com o inverso

Isso não é licença para generalizar tudo “porque um dia pode mudar”. Modelo excessivamente genérico — o famoso EAV, com chave e valor em texto para “flexibilidade” — é a forma mais eficiente já inventada de não modelar nada e transferir o problema para todo mundo que vier depois. Antecipe unidades e dimensões reais do domínio, não hipóteses.

Pense comigo — antes de criar o primeiro campo

• Onde esse schema está declarado de forma que uma máquina consiga verificar? Se a resposta é “na classe Java”, pergunte: qual das quatro versões em produção?

• Se eu precisar mudar isso com 300 milhões de registros, qual é o plano? Faça a pergunta hoje, enquanto a tabela está vazia e a resposta ainda é barata.

• Esse campo tem unidade implícita? Valor sem moeda, data sem fuso, percentual sem base. Toda unidade implícita é uma migração futura já agendada.

• Consigo adicionar um campo aqui sem coordenar deploy com mais ninguém? Se não consigo, o acoplamento não está no código — está no dado, e é muito mais caro de desfazer.

O adulto na sala agora é você

Os cinco princípios têm uma raiz comum, e ela é bem simples: dados descrevem a realidade; código apenas a manipula. Por isso o código é descartável e os dados não são. Framework é opinião — e opinião muda. Um lançamento contábil de 2019 é um fato, e fato não muda nunca.

O DBA não vai voltar. Aquele documento com o DER pronto não vai chegar. A responsabilidade de fazer as perguntas certas antes de escrever a primeira linha de DDL caiu no colo de quem escreve o código — e a boa notícia é que ela cabe em quinze minutos de conversa com quem entende do negócio, desde que sejam os quinze minutos certos.

Cartão de bolso — as 15 lições

1. Nome de coluna é contrato permanente, não variável local.

2. Não ache conceitos distintos sob um nome genérico.

3. Seu modelo precisa passar no teste do auditor.

4. O UPDATE destrutivo apaga a única evidência que você tinha.

5. O fato carrega o “porquê”, não só o “quanto”.

6. Tempo é dimensão do dado, não metadado.

7. Normalizar e desnormalizar são estratégias, não moral.

8. Em NoSQL, o padrão de acesso vem antes da entidade.

9. Vários modelos, uma única fonte da verdade.

10. O agregado define o que cabe em um commit.

11. Estados intermediários são cidadãos de primeira classe.

12. Idempotência mora no schema, não no if.

13. O schema não sumiu; trocou de dono.

14. Migração é prática contínua, não evento traumático.

15. Saiba desde o dia 1 quais mudanças serão caras.

Uma última provocação, para levar para o próximo refinamento. Antes de aceitar a próxima história com um status novo, faça a pergunta que resume o artigo inteiro:

Se a resposta depender do log da aplicação, da memória de alguém do time ou de uma planilha no drive de alguém, o modelo ainda não está pronto. E vale a pena gastar mais quinze minutos hoje — porque o código que você vai escrever depois disso é descartável de qualquer jeito.

Leitura densa (~30 min) · Para quem escreve código que move dinheiro

Você tem gateway, rate limit, mTLS e motor antifraude — e ainda assim a distância entre uma credencial vendida num bar e as contas reserva do Banco Central é feita de decisões que passaram pelo seu pull request. Sete tópicos sobre como o ataque funciona de verdade.

Março de 2025. Um homem sai de um bar no Jaraguá, zona norte de São Paulo. Alguém o aborda na rua e faz uma pergunta simples: “você trabalha no TI?”

Ele trabalhava. Era programador júnior terceirizado numa empresa que a maioria dos brasileiros nunca ouviu falar, mas por onde passavam ordens de pagamento de seis instituições financeiras. A oferta inicial foi de R$ 5 mil, entregues em dinheiro por um motoboy. Depois vieram mais R$ 10 mil, e com eles a tarefa de inserir comandos nos sistemas da empresa a mando de gente que ele nunca viu pessoalmente. Ele passou a trocar de chip e de aparelho a cada 15 dias.

Na madrugada de 30 de junho para 1º de julho de 2025, por volta das 4h da manhã, essas credenciais entraram no sistema. Durante aproximadamente três horas, transferências saíram das contas reserva mantidas no Banco Central1. O prejuízo estimado ficou entre R$ 800 milhões e R$ 1 bilhão. Uma parte virou criptoativo antes que alguém percebesse. E quem percebeu, aliás, não foi a empresa atacada nem a vítima direta: foi uma terceira instituição que estranhou o fluxo e ligou avisando.

Não houve zero-day. Não houve estouro de buffer, injeção de SQL, desserialização insegura, nada que caiba num relatório de pentest. Houve uma credencial legítima usada dentro do horário e do protocolo. A própria empresa afirmou, em nota, que “não houve invasão direta aos sistemas”. Tecnicamente correto. E é exatamente por isso que essa frase é a mais perigosa do setor.

Este artigo é uma tentativa de responder, com honestidade técnica, três perguntas que quase nunca aparecem juntas: como o crime pensa, onde a engenharia falha e o que a regulação passou a cobrar de nós, programadores — não do CISO, não do jurídico, de nós. Porque em todos os casos dos últimos dois anos, quando você desce a pilha o suficiente, encontra uma decisão de design.

O que vem por aí

• O inimigo tem crachá. Anatomia do vetor interno: C&M, Sinqia e o padrão do “não invadiram, logaram”.

• De fora para dentro. Como criminosos selecionam alvo, planejam, executam e sacam — inclusive no celular do seu cliente.

• Onde o código falha. APIs, autenticação, autorização, segredos, assinatura e limites: a parte que é culpa nossa.

• O que o Bacen exige. Do discurso de política à evidência auditável: PSTI, 14 controles mínimos, MFA, isolamento, pentest.

• SSDLC. Onde a norma vira código, teste, pipeline e pull request.

• Como o ataque funciona na prática. RCE, deserialização, SSRF, a mentira do “estou seguro na minha linguagem” e o mito do Kali Linux. Para arquitetos e programadores.

• As próximas brechas. Pix Automático, aproximação offline, parcelado, garantia, internacional, split: cada funcionalidade é uma superfície nova.

Tópico 01: O inimigo tem crachá: anatomia do vetor interno

Vamos começar pelo desconfortável. Os dois maiores ataques ao ecossistema Pix não foram invasões no sentido hollywoodiano. Foram abusos de acesso legítimo.

Caso 1 — C&M Software (julho de 2025)

A C&M é um PSTI: um provedor de tecnologia que funcionava como ponte entre instituições financeiras e o Sistema de Pagamentos Brasileiro, incluindo o ambiente do Pix. Instituições que não têm conexão própria com as infraestruturas do Banco Central contratam alguém assim. É infraestrutura crítica com aparência de fornecedor de TI.

O alvo não foram as contas correntes dos clientes finais. Foram as contas reserva das instituições no Banco Central — o dinheiro institucional, não o do correntista. A BMP sozinha reportou prejuízo de R$ 541 milhões. Credsystem e Banco Paulista também foram atingidos. O Banco Central determinou o desligamento do acesso das instituições às infraestruturas operadas pela C&M.

Meses depois, um grupo criminoso publicou na dark web cerca de 392 GB de dados supostamente obtidos da empresa. A Polícia Federal, segundo seu diretor-geral, mapeou a cadeia criminosa, prendeu 25 pessoas e recuperou mais de R$ 500 milhões.

Repare no custo do ataque para o crime: R$ 15 mil.

Caso 2 — Sinqia / Evertec (agosto de 2025)

Menos de dois meses depois, a mesma classe de vetor. A Sinqia — provedora de tecnologia comprada pela porto-riquenha Evertec — detectou atividade não autorizada no seu ambiente Pix em 29 de agosto. Resultado: R$ 710 milhões em transações B2B não autorizadas, sendo cerca de R$ 669 milhões do HSBC e R$ 41 milhões da SCD Artta. O Banco Central conseguiu bloquear a maior parte — algo em torno de R$ 589 milhões.

O relatório enviado pela Evertec à SEC americana traz a linha que interessa a nós: os resultados preliminares da forense indicaram acesso por meio de credenciais legítimas comprometidas de fornecedores de TI da Sinqia. A empresa informou que “já encerrou o acesso” dessas contas. Depois. Sempre depois.

E não parou aí

Em janeiro de 2026, o Banco do Nordeste suspendeu o Pix após um incidente originado em prestador de serviço de tecnologia, envolvendo uma conta bolsão de empresa terceirizada. O impacto apareceu no balanço do 1º trimestre como item não recorrente: R$ 146,6 milhões. A FictorPay teve recursos desviados após a invasão da Diletta, empresa que desenvolvia seu aplicativo e a camada de comunicação com a instituição autorizada a operar o Pix em seu nome. Em março de 2026, o BTG identificou atividade suspeita e suspendeu operações preventivamente.

O padrão é tão consistente que dá para escrever como uma assinatura:

// Assinatura comum dos incidentes de 2025–2026
alvo        : elo de infraestrutura, não o banco
acesso      : credencial válida (interna, terceirizada ou de fornecedor)
técnica     : uso legítimo de função legítima
janela      : madrugada / fim de semana / baixa observabilidade
alvo do $   : conta reserva ou conta bolsão, não conta de cliente
detecção    : por terceiro, por conciliação, ou tarde demais
saída       : pulverização → contas de passagem → cripto/OTC → fachada

O que ninguém quer admitir

“Não houve invasão direta aos sistemas” é uma frase de defesa jurídica, não de engenharia. Do ponto de vista do sistema, não existe diferença entre uma credencial roubada e uma credencial vendida. As duas produzem requisições perfeitamente válidas. Se a sua arquitetura só sabe se defender de requisições inválidas, ela não sabe se defender.

Existe uma expressão que descreve bem o fenômeno: insider as a service. O crime organizado descobriu que comprar um humano com acesso é ordens de grandeza mais barato, mais rápido e mais confiável do que financiar pesquisa de vulnerabilidade. E ele não precisa comprar um arquiteto sênior. Basta comprar alguém cujo perfil de acesso foi definido por conveniência operacional, e não por necessidade — o que, sejamos honestos, descreve boa parte dos acessos que existem na sua empresa agora.

Aqui é onde a engenharia entra. Uma credencial vendida só vale R$ 800 milhões se, do outro lado dela, existir um caminho em que um único ator consegue originar, aprovar e liquidar uma ordem de pagamento de altíssimo valor, fora de horário, para um destino nunca visto, sem que nada dispare. Cada “e” dessa frase é um controle que faltou. Cada controle que faltou é uma decisão de design que alguém tomou — ou deixou de tomar — num refinamento de sprint.

Pense comigo

Quantas pessoas na sua empresa conseguem, sozinhas, com uma única credencial, fazer o sistema emitir uma mensagem de pagamento válida para o SPI? Não a resposta da política. A resposta real, incluindo terceirizados, contas de serviço herdadas, o acesso de emergência que ninguém revogou e o script que roda com a credencial de alguém que saiu em 2023.

Se você não consegue produzir essa lista em cinco minutos, o atacante vai produzir por você.

Tópico 02: De fora para dentro: como o crime pensa, planeja e executa

Para defender bem, é preciso parar de imaginar o atacante como um gênio de capuz e começar a enxergá-lo como uma operação com orçamento, prazo, divisão de trabalho e análise de retorno. O que descrevo abaixo é a estrutura recorrente nas investigações públicas dos últimos dois anos.

Fase 1 — Seleção do alvo: procurar o elo, não o cofre

Nenhum grupo racional ataca o Itaú de frente. Ele ataca quem se conecta ao Itaú. A lógica é de custo: o banco grande tem SOC 24×7, red team, orçamento de nove dígitos; o fornecedor que faz a ponte tem uma equipe enxuta, um contrato apertado… mas acesso privilegiado. Como resumiu um advogado que acompanhou o caso C&M, o ataque expôs que a empresa prestava serviço de tecnologia a instituições financeiras sem ser ela própria regulada, o que permitiu a um elo não supervisionado comprometer contas reserva de várias instituições ao mesmo tempo.

O número que sustenta essa escolha é constrangedor: entre 606 instituições avaliadas pelo Banco Central, apenas 37,3% faziam avaliação periódica de risco dos seus prestadores de serviço, e menos da metade mantinha inventário atualizado de fornecedores. O criminoso não precisa de sorte para achar um elo fraco. Ele precisa de paciência para escolher qual.

Fase 2 — Reconhecimento: OSINT é barato e legal

Antes de qualquer acesso, vem o mapeamento. E ele é feito, em boa medida, com informação que nós mesmos publicamos:

• Vagas de emprego. “Vaga para pessoa desenvolvedora Java/Spring com experiência em SPI, ISO 20022 e integração com Bacen.” Você acabou de entregar a stack, o domínio e a superfície.

• LinkedIn. Quem é o time, quem é júnior, quem é terceiro, quem acabou de entrar (e ainda não sabe o que é estranho), quem está insatisfeito.

• Repositórios e pacotes públicos. Nomes internos de serviços, endpoints, formatos de payload, ocasionalmente um segredo esquecido no histórico do Git.

• Marketplaces de credenciais. Logs de infostealer vendidos aos milhares, com sessões de VPN, cookies e senhas corporativas. Não é ficção: o Banco Central passou a exigir formalmente ações de inteligência cibernética com monitoramento de credenciais e chaves na internet, deep e dark web — justamente porque é ali que a sua senha aparece antes de aparecer no seu SIEM.

• Documentação pública do Pix. As especificações do Bacen são abertas, e isso é bom. Mas significa que o atacante conhece o protocolo tão bem quanto você. A vantagem competitiva dele é conhecer o seu desvio em relação ao protocolo.

Fase 3 — Acesso inicial: quatro portas, todas legítimas

Nos casos recentes, o acesso inicial veio por uma destas rotas:

1. Recrutamento humano. Abordagem direta, valor baixo, alvo de baixa senioridade e alto acesso. O caso C&M é o manual.

2. Credencial de fornecedor comprometida. O caso Sinqia. Você endureceu a sua autenticação; a do seu fornecedor de banco de dados, não.

3. Comprometimento do desenvolvedor do aplicativo. O caso FictorPay/Diletta: quem escreveu a camada de integração vira o ponto de entrada.

4. Conta de serviço e integração esquecida. O acesso que ninguém revogou porque ninguém sabia que existia.

Fase 4 — Aprender o negócio, não o sistema

Este é o ponto que mais me impressiona e o que mais deveria nos assustar. No caso C&M, o funcionário confessou que vinha inserindo comandos desde maio — o ataque só aconteceu no fim de junho. Semanas de permanência silenciosa.

Por quê? Porque o atacante não estava quebrando nada. Ele estava aprendendo o fluxo: qual conta tem saldo, em que horário a conciliação roda, qual valor não dispara alarme, quanto tempo demora até alguém olhar, qual mensagem o SPI aceita sem devolver erro. É reconhecimento de domínio, não de infraestrutura.

Fase 5 — Execução: a janela

4h da manhã de uma segunda-feira. Três horas de operação. Não é coincidência: é escolha de janela de baixa observabilidade humana. E aqui mora a característica que torna o Pix estruturalmente diferente de qualquer meio de pagamento anterior — a liquidação é final e irreversível em segundos, 24×7. No cartão existe chargeback, no boleto existe compensação, no TED existe horário. No Pix, quando a mensagem é liquidada, o dinheiro é do outro lado.

Isso muda a matemática da defesa de uma forma que muita gente ainda não internalizou: qualquer controle antifraude que rode em lote, no dia seguinte, é arqueologia. Ele documenta o crime; não o impede. O tempo de decisão precisa ser da ordem da própria transação. E, aqui, veja o detalhe cruel do caso C&M apontado pelos especialistas: as instituições identificaram as movimentações fraudulentas quando os recursos já estavam em fase de conversão para criptoativos.

Fase 6 — Saída: o problema mais difícil do crime

Roubar é fácil; sacar é caro. A cadeia de saída usa pulverização em muitas contas, contas de passagem, contas bolsão (que agregam recursos de vários usuários sem identificação individualizada — instrumento historicamente explorado para lavagem), empresas de fachada e conversão em criptoativos. Na Operação Cofre Digital, que desmontou o grupo do caso Sinqia, o Ministério Público de São Paulo e a Polícia Federal descreveram exatamente isso: empresas de fachada convertendo o valor roubado em cripto para simular origem legítima.

É por isso que boa parte da resposta regulatória recente mira o cash-out, e não só o acesso: bloqueio de chaves Pix ligadas a fraudes, rejeição obrigatória de pagamentos destinados a contas usadas em fraude, encerramento compulsório de contas usadas para movimentar recursos de terceiros, regulação das prestadoras de serviços de ativos virtuais. Se você seca o ralo, o roubo perde o sentido econômico.

O outro “de fora para dentro”: o celular do seu cliente

Tudo o que descrevi até aqui é o ataque à infraestrutura. Existe um segundo front, muito maior em volume e muito menor em ticket: a fraude no endpoint do usuário.

O Brasil desenvolveu uma indústria própria de trojans bancários voltados ao Pix. O PixPirate, documentado pela Cleafy e depois pela IBM Trusteer, pertence a uma geração de malware Android capaz de ATS — Automatic Transfer System: ele automatiza a inserção de uma transferência Pix maliciosa a partir do próprio aparelho da vítima. Abusa do serviço de acessibilidade para ganhar capacidade de RAT, monitora a atividade, rouba credenciais e — o detalhe que quebra a premissa de meio mundo — acessa, edita e apaga as mensagens SMS, inclusive as do banco, quando o segundo fator é necessário. E aprendeu a esconder o próprio ícone de um jeito novo depois que o Android 10 fechou a técnica antiga.

Do lado do desktop, o GoPix abusa de um recurso legítimo do navegador para substituir chave Pix, código de boleto ou endereço de carteira no momento da transação, com certificados forjados exibindo o cadeado de conexão segura.

A escala: entre janeiro e setembro de 2025, o Brasil registrou 28 milhões de fraudes envolvendo o Pix, segundo levantamento da ADDP. Relatório da ACI Worldwide com a GlobalData projeta perdas com golpes do Pix chegando a R$ 11 bilhões até 2028. E o Banco Central reportou crescimento de 183% nos ataques cibernéticos em dois anos, com incidentes subindo cerca de 29% entre 2024 e 2025.

Pense comigo

Se um ator com acesso legítimo de um dos seus serviços operasse por três horas às 4h de um domingo, qual seria o teto de dano? Some limites por transação, por conta, por janela, por contraparte, por destino novo. Se você não conseguir chegar a um número, é porque o teto é o saldo.

E a segunda parte da pergunta, mais dura: quem seria acordado, em quantos minutos, por qual alerta — e esse alerta já disparou alguma vez em simulação?

Tópico 03: Onde o código falha: APIs, autenticação, autorização e segredos

Chegamos à parte que é nossa. Não do compliance, não do jurídico: nossa, de quem abre o editor e escreve o método. Vou listar os padrões de falha que, na minha experiência com integrações de core banking e Pix, aparecem com mais frequência — e que explicam tecnicamente como “credencial legítima” vira “R$ 800 milhões”.

1. Autenticar não é autorizar

É a falha número um do OWASP API Security Top 10 (Broken Object Level Authorization) e a número cinco (Broken Function Level Authorization), e continua sendo a campeã em revisão de código no setor financeiro. O serviço valida o token com rigor, confirma assinatura, expiração, emissor — e então usa o identificador de conta que veio no corpo da requisição.

// O padrão que mata
@PostMapping(”/pagamentos”)
ResponseEntity<Void> pagar(@AuthenticationPrincipal Cliente c,
                           @RequestBody OrdemPix ordem) {
    // token válido ✔  cliente autenticado ✔
    // e a conta de origem? veio do payload. de quem?
    pixService.iniciar(ordem);
}

A pergunta que precisa ser feita em toda revisão de PR de endpoint monetário: quem provou que a conta de origem pertence ao principal autenticado? Se a resposta é “o front-end só manda a conta certa”, você tem um controle de segurança implementado em JavaScript rodando no dispositivo do atacante.

A variação institucional do mesmo erro é pior: o serviço de integração aceita o ISPB de origem no payload e não valida contra a identidade do certificado ou do canal mTLS que originou a chamada. Ou seja: um participante consegue emitir em nome de outro.

2. Confiança implícita dentro do perímetro

“Está dentro da VPC2, é confiável.” Essa frase construiu a maior parte das arquiteturas de microsserviços que existem hoje em bancos brasileiros, e é exatamente a premissa que o vetor interno destrói. Se o atacante entra com credencial legítima, ele já está dentro da VPC. Toda chamada serviço-a-serviço sem autenticação mútua, sem identidade de carga de trabalho e sem autorização própria é um degrau grátis.

Não à toa, a nova regulação passou a exigir isolamento físico e lógico dos ambientes Pix e STR dos demais sistemas, com instâncias dedicadas e apartadas em nuvem. Traduzindo para arquitetura: o ambiente que fala com o SPI não compartilha rede, credencial, plano de controle nem imagem base com o resto da casa. E, sim, isso quebra a sua conveniência de deploy.

3. Segredos: a chave privada é o sistema

Num arranjo em que mensagens são assinadas digitalmente, quem controla a chave de assinatura controla o dinheiro. Perguntas que doem:

• A chave privada de assinatura de mensagens do SPI está em HSM3 — o hardware dedicado que assina sem nunca deixar a chave sair de dentro dele— ou num arquivo .p12 num volume montado?

• Quantos humanos conseguem extrair essa chave? E quantos fornecedores?

• Existe rotação automatizada de certificados, ou o processo é “abre um chamado 30 dias antes do vencimento”?

• Se um certificado precisar ser revogado às 4h da manhã, quanto tempo leva? Minutos ou o próximo dia útil?

A resolução mais recente do CMN foi cirúrgica aqui: monitoramento de credenciais e certificados digitais, especialmente no SPI/Pix, com vedação de acesso de terceiros às chaves privadas associadas à assinatura de mensagens. Isso não é burocracia: é a descrição literal do que faltou nos incidentes de 2025.

4. A janela entre autorizar e assinar

Este é o ponto mais sutil do tópico, e o que mais gera aquele olhar de “peraí, como assim?” quando explico em revisão de código. Vou por partes, porque a sutileza é justamente onde mora o perigo.

Comece pela pergunta: o que a assinatura digital realmente garante? Ela garante que a mensagem não foi alterada depois de assinada e que veio de quem detém a chave. Repare no “depois de assinada”. A assinatura é uma fotografia: ela congela o conteúdo no exato instante em que é tirada. Tudo o que aconteceu com a mensagem antes desse instante, ela fotografa fielmente — inclusive uma adulteração. A assinatura não sabe distinguir o valor certo do valor trocado; ela só certifica que “este foi o conteúdo no momento da foto”.

Agora o fluxo real de um pagamento no seu sistema, do clique à liquidação. Entre duas etapas específicas existe uma janela que quase ninguém protege:

Fluxo de uma ordem de pagamento — onde mora o risco

  [1] Cliente autentica e pede o Pix
       │
  [2] DOMÍNIO AUTORIZA  ← aqui o valor é R$ 100, chave = padaria@cpf
       │                   (esta é a “verdade” do negócio)
       │
       ▼
  ╔═══ JANELA DE RISCO ═══════════════════════════════╗
  ║  a ordem viaja por: fila, enricher, mapeador ISO,  ║
  ║  interceptador, retry, aquele “ajuste” de última   ║
  ║  hora... cada salto pode tocar no conteúdo         ║
  ╚════════════════════════════════════════════════════╝
       │
       ▼
  [3] MENSAGEM É ASSINADA  ← e se aqui o valor virou R$ 100.000
       │                      e a chave virou conta@laranja?
       │
  [4] Enviada ao SPI → liquidada → irreversível

O ataque é este: entre o passo [2] (o domínio autoriza “R$ 100 para a padaria”) e o passo [3] (a mensagem é assinada), a ordem viaja. Ela passa por uma fila, por um serviço que a enriquece com dados, por um mapeador que a converte para o formato ISO 20022, talvez por um interceptador, talvez por um retry. Cada um desses saltos é código que toca na mensagem. Se qualquer um deles — comprometido por um atacante, ou simplesmente mal escrito — trocar o valor para R$ 100.000 e a chave de destino para uma conta laranja, o que acontece no passo [3]?

A mensagem adulterada é assinada. Com perfeição criptográfica. O SPI recebe uma ordem impecável: assinatura válida, emissor legítimo, formato correto. Ele liquida. E o dinheiro foi. A assinatura fez exatamente o trabalho dela — certificou o conteúdo no instante da foto. O problema é que, naquele instante, o conteúdo já estava errado, e a assinatura não tem como saber disso. Ela protege contra alteração depois de assinar; ninguém a projetou para proteger contra alteração antes.

A frase que resume o buraco

Assinar garante que ninguém mexeu na mensagem depois da assinatura. Não garante que ela chegou íntegra até a assinatura. Se o atacante troca o valor no meio do caminho, você não assina uma fraude por acidente — você assina uma fraude com autoridade, e entrega a ela o seu selo oficial.

É exatamente esse buraco que a nova regra do Bacen fecha ao exigir validação de integridade fim a fim antes da assinatura digital. A implementação, na prática, é mais simples do que parece:

Selo de integridade — a defesa

  [2] DOMÍNIO AUTORIZA
       │  gera um selo: hash(valor + chave_destino + ISPB + ...)
       │  o selo viaja GRUDADO na ordem, calculado na FONTE da verdade
       ▼
  ╔═══ JANELA DE RISCO ═══╗  ← se alguém alterar o valor aqui,
  ╚═══════════════════════╝    o hash não vai mais bater
       │
       ▼
  [3] ANTES DE ASSINAR:
       recalcula hash(valor + chave + ISPB) dos campos atuais
       ┌─ bate com o selo?  → assina e envia  ✔
       └─ divergiu?         → ABORTA. não assina nada.  ✖

No passo [2], o ponto onde o domínio autoriza — a fonte da verdade do negócio —, você calcula um selo: um hash dos campos financeiros que não podem mudar (valor, chave de destino, ISPB, identificador da ordem). Esse selo viaja grudado na ordem por toda a janela de risco. No passo [3], imediatamente antes de assinar, você recalcula o hash dos campos como eles estão agora e compara com o selo original. Se bateu, os campos financeiros são idênticos aos que o domínio autorizou: assina e envia. Se divergiu, alguém mexeu no caminho: aborta, não assina nada, e dispara alerta.

É barato, é determinístico, e transforma a janela de risco de um espaço cego numa zona vigiada. E, mesmo sendo simples de descrever, é raríssimo de encontrar implementado — porque exige que alguém, lá no refinamento, tenha enxergado que o intervalo entre autorizar e assinar era um lugar onde o dinheiro podia ser trocado. Que é, no fim, o assunto do artigo inteiro.

5. Ausência de limites: o cofre sem porta

Antes dos detalhes, o conceito — porque “limite” soa como uma configuração chata de produto, e é na verdade um dos controles de segurança mais poderosos que existem em pagamento.

Todos os outros controles deste tópico tentam impedir que o ataque aconteça: autorização impede o acesso indevido, integridade impede a adulteração, isolamento impede o movimento lateral. Limite é diferente. Limite parte de uma premissa humilde e realista: um dia um deles vai falhar. Alguém vai vender uma credencial, uma dependência vai ter um CVE, um endpoint vai passar sem revisão. Quando isso acontecer, o limite é o que decide se você vai ter um problema ou uma manchete.

Ele não pergunta “esta operação é legítima?”. Ele pergunta “quanto dano esta operação pode causar antes que alguém perceba?”. É contenção, não prevenção. É a porta corta-fogo do prédio: não impede o incêndio, impede que ele consuma tudo.

E é aqui que está o ponto que dá título ao trecho: se você não define um teto explícito, o seu sistema tem um teto implícito — o saldo disponível. Nenhum sistema é ilimitado; ele só descobre o próprio limite quando a conta zera. Foi literalmente o que aconteceu nas contas reserva: não havia nada dizendo “esta instituição não movimenta mais que X por hora de madrugada”, então o teto foi o que havia na conta. Um cofre sem porta não é um cofre com segurança fraca. É uma sala.

O erro de posicionamento: o limite está no lugar errado

Quase todo time responde “claro que temos rate limit” — e tem mesmo, no API gateway, contando requisições por IP ou por token. Isso é throttling de infraestrutura: protege o serviço de cair, evita abuso de força bruta. É útil e não é do que estamos falando.

O atacante dos casos de 2025 não faria dez mil requisições. Ele faria algumas dezenas de operações perfeitamente válidas, dentro de qualquer rate limit de gateway, cada uma com um valor alto, para destinos diferentes, às 4h da manhã. O gateway vê tráfego normalíssimo — porque o gateway conta requisições, e o crime acontece em reais.

Daí a regra de arquitetura: limite de infraestrutura mora no gateway; limite de dano mora no domínio. O gateway não conhece conta, saldo, contraparte, histórico nem perfil de risco — e são exatamente essas as dimensões que importam. Se todo o seu controle de limite está na borda, você tem proteção contra volume e nenhuma contra valor.

O que o Bacen passou a exigir — e por quê

Vale entender que o regulador chegou nessa conclusão pelo caminho mais caro possível: vendo o dano acontecer. Boa parte do pacote de 2025–2026 é, na prática, o Banco Central impondo por norma os limites que os sistemas não tinham por design. Os principais:

• Teto de R$ 15 mil por transação de Pix e TED (Resoluções BCB nº 496, 497 e 498) para instituições de pagamento não autorizadas e para as que se conectam à RSFN via PSTI. Repare no raciocínio: o regulador não conseguia garantir a maturidade de segurança daquele grupo, então limitou o dano possível de cada operação. É contenção pura — e é exatamente o tipo de trava que deveria ter existido no código.

• Limites por transação conforme perfil de risco e comportamento do cliente (Resolução BCB nº 506). Note a mudança de filosofia: não é mais um teto único para todo mundo, é um teto que a instituição precisa calcular com base em quem é o cliente e como ele costuma operar. Isso deixou de ser uma configuração e virou um requisito de sistema — alguém precisa modelar perfil, manter histórico e aplicar a decisão em tempo de transação.

• Limitação de dispositivo não cadastrado, regra mais antiga e ainda válida na sua lógica: transações a partir de aparelho desconhecido têm teto reduzido, justamente para conter fraude de endpoint — aquele malware ATS que descrevi no Tópico 02 opera do dispositivo da vítima.

• Bloqueio e rejeição por destino (Resoluções BCB nº 501 e 506): obrigação de rejeitar pagamentos destinados a contas marcadas como usadas em fraude, e de bloquear chaves de fraudadores. É um limite baseado em para onde o dinheiro vai, não em quanto.

• Sistema de alerta de movimentações atípicas no SPI, desenvolvido pelo próprio BC, e o MED 2.0 (Resolução BCB nº 493) com rastreio e bloqueio em camadas sucessivas de contas — reconhecimento explícito de que o dinheiro precisa ser contido enquanto ainda está em trânsito.

• Exclusão do Pix em casos de maior potencial lesivo e reincidência (Resolução BCB nº 507): o limite último, aplicado ao participante inteiro.

Traduzindo o recado regulatório em uma frase: o Bacen deixou de confiar que cada instituição calibraria sozinha o próprio raio de dano. Quem já tinha limites bem desenhados sentiu pouco. Quem não tinha, descobriu os seus por decreto — e com números escolhidos por outra pessoa.

Como a engenharia implementa isso de verdade

Agora a parte prática. Um sistema de limites maduro trabalha em camadas cumulativas — cada uma respondendo a uma pergunta diferente sobre a mesma operação:

As camadas de contenção — todas avaliadas ANTES de autorizar

 valor      → esta transação sozinha passa do teto da conta/perfil?
 acúmulo    → somada às últimas 1h / 24h, passa do teto da janela?
 velocidade → quantas operações esta conta fez nos últimos N minutos?
 destino    → chave criada há minutos? contraparte nunca vista?
 contexto   → horário atípico p/ este cliente? dispositivo novo?
 agregado   → e o PARTICIPANTE? quanto saiu da instituição nesta hora?
                └── a camada que faltou nas contas reserva

Alguns pontos de implementação que fazem diferença entre um limite decorativo e um limite real:

• Janela deslizante, não janela de calendário. Um limite “por dia” que zera à meia-noite entrega ao atacante uma janela dobrada: ele opera das 23h às 01h e usa dois dias de cota em duas horas. Janela deslizante (as últimas 24 horas corridas) elimina essa brecha. E vale ter janelas noturnas mais apertadas: o comportamento legítimo às 4h da manhã é raro, e foi exatamente esse horário que os atacantes escolheram.

• O limite agregado do participante é o que ninguém implementa. Todo mundo limita o cliente. Quase ninguém limita a instituição — quanto pode sair, no total, por hora, daquele ambiente. É a camada que teria transformado R$ 800 milhões em um alerta na primeira dezena de milhões. Se você opera contas reserva ou conta bolsão, esse é provavelmente o item mais valioso desta lista inteira.

• Falha fechada, não aberta. Se o serviço que avalia limites estiver indisponível, o que o seu código faz? Se a resposta for “deixa passar para não derrubar o produto”, você tem um bypass de segurança que o atacante pode induzir derrubando aquele serviço. Operação de alto valor com motor de limite fora do ar deve ser recusada, não liberada.

• Contador com estado consistente. Limite avaliado sobre dado desatualizado (réplica com atraso, cache velho) é limite que autoriza duas vezes o mesmo teto quando as requisições chegam em paralelo. Contador atômico e transacional, com a mesma disciplina que você aplica a saldo.

• Alçada e segunda pessoa. Acima de certos valores, o controle não deveria ser “bloqueia ou libera”, mas “exige aprovação adicional”. Dupla custódia é o controle bancário mais antigo que existe, e continua sendo o mais eficaz contra ator único — inclusive contra credencial comprada.

• Limite ultrapassado é evento de segurança. Recusar não basta: precisa gerar alerta correlacionado. Uma conta batendo no teto repetidamente às 4h não é um cliente frustrado, é um sinal. Se o seu sistema recusa em silêncio, você jogou fora a informação mais valiosa que tinha.

6. Logs que não servem para nada

Quase todo mundo loga. Quase ninguém consegue responder, em quinze minutos, a pergunta “o que essa credencial fez nas últimas seis horas, ponta a ponta?”. Os defeitos clássicos:

• Log sem identificador de correlação que atravesse todos os saltos (o endToEndId existe exatamente para isso — use como chave de correlação e não só como campo de negócio).

• Log de aplicação separado de log de acesso, separado de log de infraestrutura, sem tempo sincronizado nem consulta unificada.

• Retenção curta demais para uma forense que descobre o incidente semanas depois. A norma agora manda guardar resultados de teste de intrusão e planos de ação por cinco anos; a sua trilha de auditoria precisa ter a mesma ambição.

• Detecção baseada em relatório, não em fluxo. Se o alerta nasce de um job das 6h, você tem um sistema de história, não de defesa.

7. A porta dos fundos operacional

Todo sistema financeiro tem endpoints administrativos: reprocessar, estornar manualmente, forçar conciliação, ajustar saldo, liberar bloqueio. Eles nascem no calor de um incidente, entram sem revisão de segurança, ficam para sempre e frequentemente não têm MFA, não têm dupla aprovação, não têm limite e não têm trilha. É o presente perfeito para uma credencial comprada.

Por isso a exigência de autenticação multifatorial para acessos administrativos aos ambientes Pix e STR não é detalhe operacional: é reconhecimento regulatório de que a porta dos fundos é a porta preferida.

8. O domínio como controle de segurança

Fecho o tópico com a parte que costuma ser tratada como “modelagem” e que, na verdade, é defesa. Os estados são a sua rede de proteção. Estados terminais precisam ser de fato terminais e imutáveis; transições precisam ser explícitas e verificáveis; a fonte da verdade do que foi liquidado é o extrato do SPI, não a sua tabela.

Um número de exemplo: conciliação contínua contra a infraestrutura oficial detecta divergência em minutos. Conciliação em D+1 detecta em horas — depois da conversão em cripto. A escolha entre as duas parece uma decisão de eficiência. É uma decisão de segurança.

Pense comigo

Abra agora o endpoint de iniciação de pagamento do seu serviço. Percorra o caminho de cima para baixo e marque, linha por linha, onde estão: (a) a validação de que a origem pertence ao autenticado; (b) o teto de valor; (c) o selo de integridade que sobrevive até a assinatura; (d) o identificador de correlação; (e) o ponto onde uma anomalia dispararia alerta em tempo real.

Se faltar mais de dois desses cinco, você pode ter sérios problemas no futuro!

Deixe um comentário

Tópico 04: Governança fraca é dívida técnica com juros: o que o Bacen passou a exigir

Até 2024, o arcabouço de segurança cibernética do sistema financeiro brasileiro girava em torno de duas normas de 2021 — a Resolução CMN nº 4.893 (para instituições financeiras) e a Resolução BCB nº 85 (para instituições de pagamento). Eram normas principiológicas: exigiam política, governança, plano de resposta a incidentes, gestão de terceiros. Boas normas. Auditáveis por documento.

Depois de 2025, o regulador mudou de idioma. Saiu do “você tem política?” e entrou no “me mostre o controle funcionando”. Vale a pena entender o pacote, porque cada item dele vira, mais cedo ou mais tarde, um card no seu board.

A resposta ao ponto cego: os PSTIs entram no radar

A lição mais dura do caso C&M foi que uma empresa não regulada podia comprometer contas reserva de várias instituições simultaneamente. A resposta veio na Resolução BCB nº 498/2025, endurecida pela Resolução BCB nº 547/2026, que disciplina o credenciamento dos Provedores de Serviços de Tecnologia da Informação para acesso à Rede do Sistema Financeiro Nacional. O que ela trouxe:

• Capital mínimo de R$ 15 milhões e exigências ampliadas de governança e gestão de riscos.

• Comprovação de capacidade técnico-operacional segundo padrões do Deinf/BCB.

• Certificação técnica das soluções usadas por instituições para integrar, por interfaces eletrônicas, aos serviços do provedor.

• Ações de inteligência cibernética, incluindo monitoramento de informações de interesse — clientes, chaves, credenciais, vulnerabilidades — na internet aberta e fechada.

• Sujeição a medidas cautelares e ao descredenciamento em caso de descumprimento.

O efeito de mercado foi imediato e vale registrar sem romantismo: o segmento encolheu. Stark Infra e Topaz (Stefanini) oficializaram a saída; ABBC, C&M Software e a própria Sinqia/Evertec entraram em processo de saída ordenada. A barreira de entrada subiu, e com ela a concentração. Segurança tem custo, e o custo aparece em algum lugar.

Em paralelo, as Resoluções BCB nº 496, 497 e 498 impuseram limite de R$ 15 mil por transação de Pix e TED para instituições de pagamento não autorizadas e para aquelas conectadas à RSFN via PSTI — uma trava de dano aplicada por regulação, exatamente do tipo que o código deveria ter e não tinha. E a Resolução BCB nº 494 antecipou de dezembro de 2029 para maio de 2026 o prazo para que IPs não autorizadas peçam autorização de funcionamento.

Os controles mínimos: o que virou obrigatório para todos nós

Em 18 de dezembro de 2025, a Resolução CMN nº 5.274/2025 (alterando a 4.893) e a Resolução BCB nº 538/2025 (alterando a 85) reescreveram a política de segurança cibernética com prazo de adequação em 1º de março de 2026. Elas detalham controles mínimos mandatórios: autenticação; criptografia; prevenção e detecção de intrusão; prevenção de vazamento de informações; proteção contra software malicioso; rastreabilidade; gestão de backup; avaliação e correção de vulnerabilidades; controles de acesso; perfis de configuração segura (hardening); proteção de rede; gestão de certificados digitais; requisitos de segurança para integração por interfaces eletrônicas (APIs); e ações de inteligência no ambiente cibernético.

Repare que dois desses itens são explicitamente sobre o que fazemos no editor: hardening e segurança de APIs. E há um detalhe que muda o escopo de forma decisiva: os controles se aplicam também a sistemas de terceiros executados com recursos computacionais da própria instituição. Aquele componente do fornecedor que roda no seu cluster agora é problema seu, formalmente.

Os reforços específicos de Pix e STR

Esta é a parte que qualquer pessoa que escreve código de pagamento deveria saber de cor:

• MFA obrigatório para acessos administrativos aos ambientes Pix e STR.

• Isolamento físico e lógico dos ambientes Pix e STR dos demais sistemas; em nuvem, instâncias dedicadas e apartadas.

• Monitoramento de credenciais e certificados digitais, especialmente no SPI, com vedação de acesso de terceiros às chaves privadas de assinatura de mensagens.

• Validação de integridade fim a fim antes da assinatura digital das transações.

• Comunicação eletrônica na RSFN qualificada como “serviço relevante” para fins de contratação, elevando o nível de gestão de risco e supervisão.

• Teste de intrusão anual por profissionais independentes, com documentação de resultados e planos de ação mantidos à disposição do BC por cinco anos.

• Cyber Threat Intelligence como controle mínimo — não mais “apoio técnico”, mas requisito formal conectado ao SOC/CSIRT e à gestão de credenciais.

E do lado do dinheiro: fechar o ralo do cash-out

O outro eixo do pacote, apresentado pelo presidente do Banco Central ao Senado em maio de 2026, ataca a saída dos recursos: sistema de alerta de movimentações atípicas no SPI; MED 2.0 (Resolução BCB nº 493), que amplia a identificação de contas usadas em fraude e a devolução às vítimas; botão de contestação do MED (Instrução Normativa BCB nº 589), para acelerar o bloqueio na conta do fraudador; bloqueio de chaves Pix de fraudadores e rejeição obrigatória de pagamentos destinados a contas usadas em fraude (Resoluções BCB nº 506 e 501); limites por transação conforme perfil e comportamento do cliente; encerramento compulsório de contas usadas para movimentar recursos de terceiros — o cerco às contas bolsão; BC Protege+ (Resolução BCB nº 475), que impede abertura de conta ou inclusão de titular sem autorização prévia; e multas dosadas por capacidade econômica, com exclusão do Pix em casos de maior potencial lesivo e reincidência.

O alerta que fecha o círculo

Em novembro de 2025, o Comitê de Estabilidade Financeira do Banco Central colocou na ata algo que soa como um code review do setor inteiro: preocupação com a “crescente dependência” de serviços de terceiros e com o “uso disseminado” de APIs, em muitos casos sem avaliação periódica de riscos nem monitoramento operacional adequado.

Os números que sustentam o alerta: 72,6% das instituições usam integrações por API, mas apenas cerca de 29% revisam regularmente os riscos associadas a essas conexões. É a distância entre construir e sustentar, expressa em percentual.

A tradução para quem escreve código

Não existe mais “requisito de segurança” como categoria separada de “requisito funcional”. MFA em rota administrativa, isolamento de ambiente, integridade antes da assinatura, rastreabilidade ponta a ponta e limite por perfil de risco são comportamentos do sistema — com dono, teste automatizado, evidência e data. Se um deles não tem um teste que falha quando alguém o remove, ele não existe: existe uma frase num documento.

Pense comigo

Pegue a última funcionalidade de Pix que o seu time entregou. Quais dos 14 controles mínimos ela tocou? Consegue apontar o pull request em que cada um foi endereçado, ou o teste que o cobre?

E a versão executiva da mesma pergunta, que é a que o Bacen faz: se o supervisor pedir a evidência amanhã, você entrega um log ou uma apresentação?

Tópico 05: SSDLC: onde a norma vira código

Chegamos ao ponto do artigo em que preciso ser direto sobre uma coisa: SSDLC não teria impedido que aquele funcionário vendesse a credencial. Nenhum ciclo de desenvolvimento seguro impede a fraqueza humana, o aliciamento, a necessidade financeira.

O que o SSDLC faz é diferente e mais importante: ele determina quanto vale a credencial vendida. Num sistema com privilégio mínimo, segregação real, limites explícitos, integridade fim a fim e detecção em tempo de transação, aquela mesma credencial valeria uma consulta a extrato e um alerta imediato. Num sistema sem isso, valeu R$ 800 milhões. O ataque é o mesmo. O design é que decide o resultado.

Vamos por fase, com o que dá para começar na segunda-feira.

Requisitos: escreva o caso de abuso junto com a história de usuário

Para cada “como pagador, quero iniciar um Pix por chave”, escreva a irmã gêmea maligna: “como fraudador com credencial válida, quero iniciar um Pix por chave a partir da conta de outro cliente”, “…de madrugada, para uma chave criada há dois minutos”, “…mil vezes em sessenta segundos”.

Caso de abuso não é paranoia: é requisito. E ele tem uma propriedade excelente — vira teste automatizado quase sem tradução. Uma história de usuário produz um teste de caminho feliz; um caso de abuso produz um teste que precisa falhar com 403.

No mesmo movimento, amarre requisito regulatório ao backlog com identificador. “RN-Pix-014: integridade fim a fim antes da assinatura (CMN 5.274)”. Assim a rastreabilidade regulatória não é um exercício arqueológico de auditoria: ela nasce no seu backlog.

Design: modelagem de ameaças no fluxo, não no diagrama bonito

Aplique STRIDE4 ao fluxo real de iniciação e liquidação, com as fronteiras de confiança desenhadas explicitamente — incluindo a fronteira com o PSTI, com o BaaS, com o app desenvolvido por terceiro. Nos casos de 2025, era exatamente essa fronteira que estava implícita.

// Modelagem de ameaças aplicada ao fluxo Pix
S  Spoofing        → serviço A se passa por serviço B?  mTLS + identidade de carga
T  Tampering       → alguém altera valor/destino entre autorizar e assinar?  selo de integridade
R  Repudiation     → dá para reconstruir quem fez o quê?  endToEndId como correlação
I  Info disclosure → chave privada / chaves Pix / dados cadastrais expostos?
D  Denial          → esgotamento de conexão com o SPI derruba o produto?
E  Elevation       → operador vira originador? conta de serviço vira admin?

Duas perguntas de design que valem mais que uma semana de ferramenta:

• Onde está o ponto único em que um ator consegue fechar o ciclo sozinho?

• E o que acontece se este componente for hostil?

Faça a segunda pergunta apontando para o seu próprio serviço de integração. É desconfortável, e é o exercício certo.

Codificação: autorização centralizada, tudo mais é detalhe

• Autorização como componente, não como if espalhado. Um ponto de decisão, testável isoladamente, chamado por todos os fluxos monetários. Espalhar autorização por controllers é garantir que um deles ficará para trás.

• Negar por padrão. Rota nova nasce fechada. Perfil novo nasce sem permissão. Campo novo no payload nasce rejeitado por validação de esquema estrita — nada de schema permissivo aceitando propriedades desconhecidas em mensagem financeira.

• Idempotência de verdade. Chave de idempotência com escopo, TTL e persistência; reenvio devolve o mesmo resultado, não um segundo pagamento. Em sistema irreversível, idempotência é controle de segurança.

• Segredos fora do código e fora do humano. Cofre com credencial dinâmica, chave de assinatura em HSM, nenhum segredo estático em variável de ambiente de longa duração.

• Dependências são superfície. SCA e SBOM no pipeline. A cadeia de suprimentos do software merece o mesmo rigor que passamos a exigir da cadeia de fornecedores — e é o mesmo tipo de risco.

Revisão de código: alguém precisa olhar com a lente errada

Revisão de código no Brasil, na média, verifica legibilidade, cobertura e regra de negócio. Quase nunca verifica autorização. Uma mudança pequena e barata: em repositórios que tocam dinheiro, exija revisor de segurança designado (via CODEOWNERS) para qualquer alteração em rota monetária, em autorização, em assinatura ou em limites. E dê ao revisor uma lista curta, do tipo: “esta mudança altera quem pode fazer o quê? altera um teto? altera o que é assinado? altera o que é logado?”.

Pipeline: onde o discurso encontra o bloqueio

• SAST, DAST, SCA5 e secret scanning bloqueantes nas rotas críticas — não informativos, não “corrige depois”.

• Segregação de função no deploy: quem faz o merge não é quem aprova a promoção para o ambiente Pix. Isso é o equivalente, na engenharia, à dupla custódia que os bancos exigem no caixa há um século.

• Acesso a produção efêmero e sob demanda, com justificativa e trilha. Acesso permanente de desenvolvedor a produção de pagamento é a versão institucional da credencial vendida no bar.

• Assinatura e proveniência de artefatos, para que o binário que roda seja comprovadamente o que saiu do repositório revisado.

Testes: os que quase ninguém escreve

Além de unidade e integração, três famílias que deveriam ser obrigatórias em qualquer sistema Pix:

1. Teste de autorização negativa — o “teste do vizinho”: o token do cliente A tentando operar a conta do cliente B precisa retornar 403, e isso precisa ser um teste automatizado que roda em toda build. Cada objeto sensível, cada função administrativa.

2. Teste de limite e velocidade — o sistema precisa recusar a operação 101 na janela, o valor acima do teto, o destino recém-criado acima do valor de alçada. Se não existe teste, o limite vai ser removido por alguém, em produção, num incidente, e ninguém vai notar.

3. Teste de detecção — este é o mais esquecido. Injete um padrão anômalo em ambiente controlado e verifique que o alerta dispara, chega ao destino certo e aciona quem deve. Alerta que nunca foi testado é alerta que não existe.

Observabilidade e contenção: detecção é requisito funcional

Se há uma lição operacional dos casos recentes, é esta: a detecção chegou tarde e veio de fora. Na C&M, o aviso partiu de uma terceira instituição. Em vários casos, a percepção veio quando o dinheiro já virava cripto.

O que precisa existir, e ser código:

• Correlação por endToEndId atravessando todos os serviços e chegando ao painel.

• Detecção em tempo quase real de anomalia de volume, horário, contraparte, destino novo e concentração — no domínio, não só no gateway.

• Kill switch por produto, por participante, por tipo de operação — implementado, documentado e ensaiado. O Banco Central desligou o acesso da C&M à infraestrutura em horas. A pergunta é: quanto tempo o seu desligamento leva?

• Conciliação contínua contra a fonte oficial, com alarme por divergência.

• Revogação de credencial e certificado em minutos, automatizada. “Já encerramos o acesso” precisa ser um botão, não um projeto.

E o pedaço cultural, que é o mais difícil

O programador júnior terceirizado da C&M tinha aquele acesso porque, em algum momento, foi mais fácil conceder do que desenhar. Ninguém acordou querendo criar um risco de R$ 1 bilhão; alguém só precisava destravar um chamado numa sexta-feira à noite.

Privilégio mínimo não é uma decisão de arquitetura que alguém precisa tomar no refinamento, defender no planning e sustentar quando o prazo apertar. E é aí, exatamente aí, que a mentalidade de conformidade que o Bacen exige deixa de ser burocracia e vira ofício: entender que o requisito regulatório é a codificação de um dano real que já aconteceu com alguém, escrito por quem teve que pagar a conta.

A tese do tópico, em uma frase:

O SSDLC não impede que vendam uma credencial. Ele impede que uma credencial vendida valha oitocentos milhões de reais.

Pense comigo

Quando foi a última vez que uma build do seu repositório falhou por motivo de segurança — um teste de autorização quebrado, um segredo detectado, um limite removido, uma dependência vulnerável barrando o merge?

Se a resposta for “nunca”, existem duas explicações possíveis: o seu código é perfeito, ou o seu pipeline não está olhando. Uma delas é muito mais provável que a outra.

Tópico 06 · “Mas o que isso tem a ver comigo?” Como o ataque funciona na prática…

Se você chegou até aqui trabalhando diretamente com sistemas que operam Pix, é bem provável que uma objeção esteja formada na sua cabeça: “tá, mas eu não tenho o problema da C&M. Meu ecossistema tem camadas. API gateway na borda, rate limit, WAF, motor antifraude, mTLS entre serviços. Um atacante que não trabalha aqui dentro simplesmente não passa.”

É uma objeção legítima, e é exatamente a que eu quero desmontar — não com retórica, mas mostrando o mecanismo. Porque o Pix, você sabe melhor que ninguém, não é uma simples transferência instantânea. É um sistema distribuído, com integração síncrona a uma infraestrutura crítica, assinatura de mensagens, custódia de chaves e liquidação irreversível. Cada uma dessas propriedades é uma camada de proteção — e cada camada é software, e software tem defeito.

A pergunta honesta não é “minhas camadas me protegem?”. É “o que acontece quando uma delas tem uma falha crítica, e o atacante encontra essa falha antes de mim?”. Vou responder isso de forma transparente. O objetivo aqui é 100% defensivo: você não consegue defender um sistema contra um ataque que não entende.

Primeiro, mate uma ilusão: o gateway não é uma parede

API gateway, WAF e rate limit são redutores de ruído, não paredes. Eles filtram o óbvio: a injeção de SQL trivial, o scanner barulhento, o pico de requisições. O que eles não fazem — porque não conseguem — é entender a semântica do seu domínio. Um WAF não sabe que a conta de origem daquela ordem de pagamento não pertence ao token que a enviou. Para o WAF, é uma requisição HTTPS bem formada, com um JSON válido, dentro do rate limit. Ela passa.

Pior: WAF é regra, e regra se contorna. A própria comunidade de segurança documenta abertamente como ofuscar payloads para passar por WAF em vulnerabilidades famosas. Trate o gateway como o que ele é: um quebra-molas que reduz a velocidade do tráfego hostil. Não como o portão do cofre.

O frontend mobile não é seu. É do atacante.

Aqui mora um erro conceitual que sustenta metade das vulnerabilidades que vejo. O time trata o app como “nosso cliente confiável”. Não é. Assim que o APK é publicado, ele está na mão do adversário, para ser desmontado com calma.

O que um atacante extrai de um app mobile em uma tarde, com ferramentas públicas e gratuitas:

• Todos os endpoints que o app chama — a sua superfície de API, documentada de graça pelo seu próprio binário.

• Segredos hardcoded: API keys, tokens estáticos, credenciais de serviços de terceiros que alguém “só deixou aqui pra testar”.

• A lógica de negócio embutida — inclusive as validações que você achou que eram “de segurança” e que rodam no dispositivo dele.

E o certificate pinning, que muitos tratam como a defesa definitiva? É bypassável. Com o dispositivo sob controle do atacante (root/jailbreak, emulador, instrumentação dinâmica), o pinning cai. A lição de arquitetura é dura e inegociável: toda decisão de segurança que importa acontece no servidor. O app é uma sugestão de interface, não um guardião. Se a sua autorização depende de o cliente “se comportar”, ela não existe.

Agora o coração: o que é “acesso remoto por vulnerabilidade” (RCE)

Remote Code Execution é o santo graal do atacante: fazer o seu servidor executar código dele. Não roubar um dado, não burlar uma tela — rodar comandos dentro do seu processo, com os privilégios do seu processo. E o mecanismo, por trás de toda a mística, é quase sempre o mesmo princípio:

Você espera receber um dado (um nome, um valor, um cabeçalho, um objeto serializado). Mas em algum ponto do caminho, aquele dado é interpretado como código, ou usado para decidir qual código carregar. Toda a família RCE é variação disso. Vamos aos vetores reais, com o que você deve procurar no seu código — o sink, o ponto onde o dado perigoso é consumido.

Deserialização insegura. Um objeto serializado carrega, junto, o tipo dele. Se você desserializa dado que veio de fora e existe, no seu classpath, uma sequência de classes que pode ser encadeada (o que a comunidade chama de gadget chain), o simples ato de desserializar dispara execução. Você não chamou nenhum método malicioso; a máquina de desserialização chamou por você. O sink6 a caçar: qualquer readObject, ObjectInputStream, ou binder de JSON/XML configurado para instanciar tipos arbitrários a partir do payload.

Injeção de expressão / template. Frameworks modernos avaliam expressões (SpEL no Spring, OGNL no Struts, template engines em qualquer linguagem). Se entrada do usuário chega a um avaliador de expressão, ela deixa de ser texto e vira programa. Foi essa a natureza do Spring4Shell (CVE-2022-22965): manipulação de data binding alcançava o carregador de classes e permitia carregar código malicioso. O sink: parseExpression com string do usuário, template renderizado com input não confiável, Runtime.exec/ProcessBuilder alimentado por parâmetro.

Uma linha de log. O Log4Shell (CVE-2021-44228, CVSS 10.0) é o exemplo mais didático e mais assustador da história recente. A biblioteca de log processava strings controladas pelo usuário de forma insegura: uma expressão de lookup dentro de uma mensagem logada fazia o Log4j buscar e executar código de um servidor remoto. Como quase toda aplicação loga entrada do usuário — um cabeçalho HTTP, um User-Agent, um campo de formulário —, bastava enviar a string certa num header para comprometer o servidor. A vítima nem precisava clicar. E o ponto que importa para nós: ninguém escreveu código inseguro. A insegurança estava numa dependência transitiva que a maioria dos times nem sabia que tinha. Anos depois, em 2025, ainda há serviços vulneráveis por dependência oculta e remediação incompleta.

SSRF — o vetor que ama a nuvem. Server-Side Request Forgery: você faz o servidor da vítima realizar uma requisição para um destino escolhido pelo atacante. Parece inofensivo até você lembrar onde o seu serviço roda. Numa nuvem, existe um endpoint de metadados interno que entrega credenciais temporárias da identidade da máquina. Um SSRF bem posicionado transforma “meu serviço busca uma imagem nessa URL” em “meu serviço acabou de entregar as credenciais de nuvem dele para o atacante”. Dali, o adversário se move lateralmente — e é por isso que o isolamento de ambiente Pix que o Bacen passou a exigir não é firula: é a diferença entre um serviço comprometido e o ambiente de assinatura comprometido.

Como o “acesso remoto” realmente se estabelece

Suponha que o atacante conseguiu executar um comando via um desses vetores. Como isso vira uma sessão interativa, um “controle” do servidor? Vamos para o conceito — e, dentro dele, a sua melhor defesa.

Seu firewall provavelmente bloqueia conexões de entrada não autorizadas. Então o atacante inverte o fluxo: faz o seu servidor iniciar uma conexão de saída para uma máquina que ele controla, e usa esse canal para enviar comandos e receber respostas. É o conceito de reverse shell: o servidor comprometido “liga de volta” para o atacante. Ele funciona porque, na esmagadora maioria das arquiteturas, ninguém filtra o tráfego de saída. Entrada é paranoia; saída é festa aberta.

A pergunta que todo mundo faz: “no .NET/Node/Go estou livre?”

Não. E preciso ser direto sobre isso porque é uma crença perigosa. A vulnerabilidade não mora na linguagem; mora no padrão — na fronteira onde dado não confiável vira instrução, decisão ou requisição. Toda linguagem cruza essa fronteira. O que muda é o nome da falha, não a existência dela.

• Java / Spring. Deserialização (a família de gadgets é vasta), SpEL/OGNL, e a exposição gigantesca a dependências do ecossistema JVM — Log4Shell e Spring4Shell foram eventos de escala planetária. Uma análise da Veracode apontou que a maioria esmagadora das empresas com muitas aplicações usa Java, e uma fatia enorme rodava versões vulneráveis. Não porque programam mal; porque a superfície é imensa.

• .NET. “É Microsoft, é seguro.” A mesma família existe com outros nomes: desserialização perigosa (BinaryFormatter, TypeNameHandling permissivo no serializador JSON instanciando tipos do payload), abuso de view state quando a proteção de integridade está mal configurada, injeção de comando via Process.Start. Mesmo princípio, sotaque diferente.

• Node.js. A ausência de tipagem forte abre vetores próprios: prototype pollution — o atacante injeta propriedades no protótipo base dos objetos e altera o comportamento da aplicação inteira, às vezes escalando para RCE; eval e o módulo vm alimentados por input; injeção de comando via child_process. E o npm é o maior tapete vermelho de supply chain que existe: milhares de dependências transitivas, e ataques reais de pacote malicioso injetado numa biblioteca popular.

• Go. Este é o mais interessante porque carrega a fama de “seguro por design”. E é verdade em uma dimensão: por ser memory-safe, Go elimina classes inteiras de vulnerabilidade de corrupção de memória (buffer overflow e afins) que assombram C/C++. Mas segurança de memória não é segurança de lógica. Em Go você continua vulnerável a SSRF, path traversal, injeção de comando via os/exec, e a um clássico específico: usar text/template onde deveria usar html/template, abrindo injeção. E a cadeia de suprimentos morde igual — um módulo comprometido é um módulo comprometido, não importa a elegância da linguagem.

A conclusão que dói

Nenhuma linguagem te salva. Go reduz uma família de bugs; não reduz a família que mais importa em pagamento, que é a lógica de autorização e a confusão dado/instrução. Trocar de stack para “ficar seguro” é como trocar de fechadura numa porta que ninguém tranca. O trabalho é o mesmo em todas: identidade de carga de trabalho, entrada tratada como hostil, dependências vigiadas, saída filtrada, privilégio mínimo.

Então o atacante precisa de um Kali Linux?

Essa pergunta merece uma resposta honesta porque a mitologia atrapalha a defesa. Kali Linux é só uma distribuição Linux com um monte de ferramenta de segurança pré-instalada. Não é uma arma mágica; é conveniência. As mesmas ferramentas rodam em qualquer sistema. O que importa entender é a economia real do ataque em 2026, e ela é bem menos glamurosa que o imaginário do gênio de capuz:

• A maior parte é automatizada. Scanners de vulnerabilidade conhecida (os chamados n-days) varrem a internet inteira procurando serviços não corrigidos. Quando um CVE crítico sai, existe proof of concept público, em média, em duas semanas — e a exploração em massa começa antes de a maioria das empresas ter corrigido. O atacante não descobriu a falha; ele baixou o exploit e apontou para o seu IP.

• Descobrir o alvo é trivial. Existem motores de busca que indexam dispositivos e serviços expostos na internet. O atacante pesquisa “serviços rodando a versão X do framework Y” e recebe uma lista. O reconhecimento que antes levava semanas hoje é uma query.

• A barreira de entrada despencou. Ferramentas de interceptação e teste de API, frameworks de exploração e catálogos de templates de vulnerabilidade são gratuitos, documentados e cheios de tutorial. E a IA generativa reduziu ainda mais o custo de adaptar um exploit ou escrever o script de saída.

Ou seja: o atacante não precisa ser um especialista de sistemas — que era exatamente a sua intuição no começo deste tópico, e ela está certa pela razão oposta à que você imaginava. Ele não precisa ser gênio porque a genialidade foi commoditizada. O especialista descobre a falha uma vez e publica; mil operadores medianos a exploram em escala. O seu adversário mais provável não é um hacker brilhante mirando você especificamente. É um scanner automatizado que encontrou a sua dependência desatualizada às 3h da manhã, no meio de uma varredura de milhões de IPs, e um humano que, ao ver o alvo financeiro, resolveu olhar com atenção.

Fechando o circuito: por que isso é problema seu, e não do CISO

Junte as peças e veja como um caminho “de fora para dentro” alcança o mesmo lugar que a credencial comprada da C&M alcançou por dentro:

// A corrente — cada elo é uma decisão de engenharia
1. app mobile revela endpoint de integração (cliente não é confiável)
2. endpoint roda dependência com CVE crítico não corrigido
3. requisição forjada dispara RCE (dado vira instrução)
4. servidor abre conexão de saída — ninguém filtra egress
5. atacante lê identidade da carga de trabalho / material de chave
6. ambiente NÃO isolado → move lateral até o ponto de assinatura
7. agora ele emite mensagem VÁLIDA para o SPI
   → e você voltou ao Tópico 01: “não houve invasão”, só uso legítimo

Repare que o passo 7 é idêntico ao resultado do insider. Por isso os dois capítulos deste artigo — o de dentro e o de fora — convergem: ambos terminam com uma mensagem perfeitamente válida sendo assinada e liquidada. A diferença é só o caminho até a chave. E cada elo dessa corrente — do 1 ao 6 — é algo que você, arquiteto ou programador, tem o poder de cortar: tratar o mobile como hostil, corrigir dependência com SLA de horas, procurar os sinks no code review, filtrar a saída, dar identidade mínima à carga de trabalho, isolar o ambiente Pix.

O CISO define a política. Quem quebra a corrente é quem escreve a linha. É por isso que “o que isso tem a ver comigo?” tem uma única resposta honesta: tudo. A distância entre uma vulnerabilidade num pacote e uma mensagem fraudulenta no SPI é feita, elo por elo, das decisões que você toma antes do merge.

Pense comigo

Três perguntas concretas, para responder hoje:

(1) Você tem inventário das suas dependências — inclusive as transitivas — e um alerta que dispara quando uma delas ganha um CVE crítico? Se um novo Log4Shell sair amanhã, quanto tempo até você saber se está exposto?

(2) O seu ambiente de pagamento pode abrir conexão de saída para qualquer lugar, ou só para uma lista explícita?

(3) Se a sua aplicação for comprometida por RCE, a identidade que ela carrega alcança a chave de assinatura e o SPI — ou o raio de dano para na borda do serviço?

Se você não gostou de nenhuma das três respostas, boas notícias: as três são código e configuração. Nenhuma delas é sorte.

Tópico 07: Cada funcionalidade nova é uma superfície nova

O Pix não é um produto pronto. É uma plataforma em agenda evolutiva permanente, e cada item dessa agenda muda o modelo de ameaças de quem se integra a ele. O padrão histórico é implacável: toda funcionalidade que remove atrito para o usuário transfere a decisão para uma camada automática — e onde você tira um humano, precisa colocar um controle.

Vamos olhar o que vem e onde, na minha leitura, mora o risco.

Pix Automático: o consentimento vira a nova credencial

Pagamentos recorrentes com autorização única e débitos subsequentes sem autenticação transação a transação. É débito automático democratizado — e é, tecnicamente, a criação de um mandato de longa duração. Já é obrigatório nos casos em que o recebedor de autorização de débito interbancário é pessoa jurídica ou entidade não autorizada pelo BC, e a partir de outubro de 2026 alcança contas salário.

O risco muda de lugar: deixa de ser “roubar uma transação” e passa a ser “obter ou adulterar um mandato”. As perguntas de design que o seu time precisa responder antes de subir isso:

• Qual o escopo do consentimento — valor máximo, periodicidade, prazo, contraparte fixa? Um mandato sem teto é um cheque em branco recorrente.

• Quem pode alterar um mandato existente, e isso exige nova autenticação forte? Alterar é mais perigoso que criar.

• Como se revoga, em quanto tempo, e o que acontece com a cobrança em voo?

• Existe proteção contra replay de autorização e contra reuso de consentimento em contexto diferente do original?

• O consentimento é auditável ponta a ponta — quem, quando, de qual dispositivo, com qual evidência?

Pix por aproximação e o modelo offline: a premissa síncrona quebra

O Pix por aproximação (NFC, via carteiras digitais) já está disponível. O que vem depois é mais interessante do ponto de vista de risco: o QR pagador / Pix offline, previsto de 2027 em diante, em que o pagador consegue concluir a operação sem conexão com a internet no momento.

Isso quebra a premissa que sustenta boa parte da defesa atual: a validação síncrona contra a infraestrutura antes da liquidação. Numa operação offline, alguma coisa é gerada e apresentada localmente, e a reconciliação acontece depois. As perguntas ficam evidentes: como se previne duplicidade e replay de um token gerado no dispositivo? Qual a janela de validade? Quem assume o risco de saldo insuficiente entre a apresentação e a liquidação? Como se detecta um dispositivo comprometido gerando tokens em série — lembrando que já existe malware brasileiro fazendo fraude no próprio aparelho da vítima?

Pix Parcelado padronizado: pagamento vira crédito

Quando o Bacen padronizar o Pix Parcelado, o instrumento deixa de ser só liquidação e passa a carregar originação de crédito. Isso importa muito para o modelo de ameaças: entra fraude de originação, entra KYC como superfície de ataque, entra o golpe de engenharia social que convence a vítima a “parcelar” um valor que ela não deve. Times que hoje tratam Pix como transporte vão precisar herdar controles de crédito — análise, alçada, política, contestação.

Pix em garantia: recebíveis futuros como colateral

Usar recebíveis futuros de Pix como garantia de empréstimo cria uma nova classe de objeto sensível: o vínculo entre o fluxo futuro e o credor. Integridade e imutabilidade desse registro passam a ter valor econômico direto, e todo novo intermediário na cadeia de registro e trava é um novo elo — com tudo o que aprendemos sobre elos nos últimos dois anos.

Pix Internacional: dois modelos de confiança se encontrando

A ambição para 2027 é interligar o Pix a sistemas de pagamentos instantâneos de outros países. Toda ponte entre esquemas com modelos de confiança, requisitos de identidade e regimes de sanção diferentes é, historicamente, o lugar onde a fraude se instala — porque a diferença de premissas entre os dois lados vira ambiguidade, e ambiguidade vira exploração. Some a isso jurisdição, prevenção à lavagem, listas restritivas e resolução de disputa transfronteiriça.

Intermediários, split e duplicata: dinheiro sendo dividido dentro da mensagem

A agenda prevê especificações para identificar múltiplos recebedores numa mesma transação (o caso dos marketplaces), o split tributário separando automaticamente a parcela de tributos no momento do pagamento, a cobrança híbrida com QR obrigatório em boletos digitais e a duplicata liquidada via Pix.

Traduzindo para risco: lógica de divisão de valores passa a viver dentro da mensagem de pagamento. Todo lugar em que o sistema calcula percentuais, arredonda centavos e decide quem recebe o quê é um lugar onde manipulação de um único campo desvia dinheiro sem parecer uma fraude — parece um erro de cálculo. E erro de cálculo é a fraude que menos dispara alarme.

O campo de descrição, que ninguém trata como entrada não confiável

O Bacen já sinalizou que criará regras para inibir o uso do campo “Descrição” do Pix para ameaças e mensagens ofensivas. Do nosso lado, esse campo é o que sempre foi: entrada controlada pelo atacante que trafega entre instituições e chega a interfaces de terceiros. Injeção, XSS armazenado em painéis internos, phishing por conteúdo, abuso de canal. Se o seu extrato renderiza descrição sem sanitização, você tem um vetor.

IA nos dois lados do balcão

O Banco Central trabalha em ferramentas antifraude com inteligência artificial, indicador de probabilidade de fraude no Pix, alerta de golpe e melhorias no bloqueio cautelar. Do outro lado, deepfake já aparece em golpes de identidade e a automação reduz o custo marginal do ataque a quase zero. A corrida vai ser entre modelos, e o lado que perder será o que tiver pior telemetria — porque modelo bom com dado ruim é chute com sotaque estatístico.

O gráfico que ninguém desenha

Coloque num mesmo eixo duas curvas: a velocidade com que a superfície do Pix cresce (agenda evolutiva do Bacen, trimestre a trimestre) e a velocidade com que a maturidade de segurança do seu time cresce (sprints com item de segurança entregue). Se a primeira sobe mais rápido que a segunda, você não está estagnado — está regredindo em termos relativos, que é o único termo que importa quando existe um adversário.

Pense comigo

Quando o Pix Automático entrou no roadmap da sua empresa, quem escreveu o modelo de ameaças do mandato de consentimento? Quem definiu escopo, revogação, proteção contra replay e trilha de auditoria da autorização?

Se a resposta for “ninguém, a gente implementou a especificação”, esse é o próximo ticket. Especificação define o que o sistema deve fazer. Modelo de ameaças define o que ele não pode permitir — e é sempre a segunda lista que o atacante lê.

Para fechar: o ataque não começou num terminal

Volto ao bar no Jaraguá, porque é ali que está a lição.

O maior ataque cibernético da história do sistema financeiro brasileiro começou com uma conversa de calçada e R$ 5 mil em espécie entregues por um motoboy. Não começou com um exploit. Começou com uma pergunta — “você trabalha no TI?” — feita a uma pessoa cujo nível de acesso tinha sido definido por conveniência.

Entre aquela conversa e as contas reserva no Banco Central havia uma distância inteira de sistema: autenticação, autorização, segregação, limites, integridade, trilha, detecção, contenção. Cada uma dessas camadas era uma chance de transformar R$ 800 milhões em um alerta de madrugada. Cada uma delas foi, em algum momento, um card que alguém priorizou ou despriorizou.

É por isso que insisto: segurança em pagamentos não é um departamento, é uma propriedade emergente do jeito como o sistema foi construído. Ela emerge de decisões pequenas, tomadas por gente como nós, em reuniões que ninguém lembra, sobre coisas que pareciam detalhes de implementação.

Três perguntas para levar para a segunda-feira:

1. Qual é o teto de dano de uma credencial legítima comprometida no seu sistema, expresso em reais? Se você não sabe o número, esse é o primeiro trabalho.

2. Quanto tempo entre o primeiro comportamento anômalo e o primeiro humano acionado? Se a resposta depende de um relatório matinal, você está fazendo arqueologia.

3. Onde está o ponto único em que um ator fecha o ciclo sozinho — originar, aprovar, liquidar? Ele existe. Ele sempre existe. A questão é se você o encontrou antes.

O Bacen fez a parte dele: transformou dano real em norma verificável, e norma verificável em prazo. Os criminosos fizeram a parte deles: profissionalizaram o recrutamento, mapearam a cadeia de fornecedores e descobriram que o elo mais fraco quase nunca é apenas o banco. Mas sim humano.

Fico por aqui neste artigo e até o próximo! ❤️

Fontes e leituras

• Banco Central do Brasil — Resoluções BCB nº 493, 494, 495, 496, 497, 498, 501, 505, 506, 507, 517, 518, 538 e 547; Resoluções CMN nº 4.893, 5.251, 5.261 e 5.274; Instruções Normativas BCB nº 589 e 661.

• Banco Central do Brasil — 63ª Ata do Comitê de Estabilidade Financeira (Comef), novembro de 2025, sobre dependência de terceiros e uso disseminado de APIs.

• Finsiders Brasil — “Um ano após ataque à C&M: o que mudou na segurança do setor financeiro?” e “BC alerta para uso disseminado de APIs no setor financeiro”.

• Grant Thornton Brasil — análise dos controles mínimos da Resolução CMN nº 5.274/2025 e da Resolução BCB nº 538/2025.

• Evertec — comunicado à SEC sobre o incidente no ambiente Pix da Sinqia (agosto de 2025).

• CNN Brasil, Estadão/IstoÉ Dinheiro, Seu Dinheiro, InfoMoney, Exame e Agência Brasil — cobertura dos casos C&M Software, Sinqia, Banco do Nordeste e Operação Cofre Digital.

• IBM Trusteer e Cleafy — análises técnicas do PixPirate e da geração de trojans Android com capacidade ATS.

• Kaspersky — relatório sobre o trojan GoPix e substituição de chaves Pix e códigos de boleto no navegador.

• ACI Worldwide e GlobalData — Relatório Scamscope, projeções de perdas com fraudes em pagamentos em tempo real.

• OWASP — API Security Top 10 e Application Security Verification Standard (ASVS).

A explicação confortável para o que aconteceu é que a diretoria não entende de tecnologia. A explicação honesta é mais desconfortável: o pedido foi feito numa moeda que ninguém do outro lado da mesa sabe converter.

O problema raramente é indiferença. Executivos aprovam investimentos difíceis o tempo todo — trocam o core bancário, compram empresa, aceitam três anos de payback. O que eles não fazem é aprovar algo que chega descrito em qualidade de código, cobertura de teste e framework depreciado, sem nenhuma tradução para receita, custo, risco ou posição competitiva. E há uma falha ainda mais comum: apresentar um caso genérico e único para todo mundo ao mesmo tempo, obrigando cada executivo a fazer a tradução sozinho — o que, na prática, termina em decisão nenhuma.

A escala do problema não é anedota. Numa pesquisa da McKinsey com 50 CIOs de instituições financeiras e empresas de tecnologia com receita acima de US$ 1 bilhão, os entrevistados estimaram que a dívida técnica representa entre 20% e 40% do valor de todo o parque tecnológico antes da depreciação, e relataram que de 10% a 20% do orçamento nominalmente destinado a produtos novos acaba desviado para resolver problemas decorrentes dela. Do outro lado da régua, o CISQ estimou o custo da má qualidade de software nos Estados Unidos em US$ 2,41 trilhões, com a dívida técnica acumulada em torno de US$ 1,52 trilhão.

Pilar 01: Recupere o significado da metáfora antes de usá-la

Você não consegue precificar um conceito que cada pessoa na sala entende de um jeito. E “dívida técnica” virou exatamente isso: um guarda-chuva onde cabe desde uma falha arquitetural que impede a empresa de lançar produto até o desgosto de alguém com o nome de um pacote.

Lição 1.1 → A metáfora nasceu num banco, e nasceu para falar com executivos

Ward Cunningham cunhou o termo em 1992, num relatório de experiência apresentado na OOPSLA sobre o WyCash — um sistema de gestão de portfólio. Ele estava cercado de gente de finanças, precisava justificar tempo investido em melhorar código existente, e escolheu deliberadamente uma linguagem que aquela audiência já dominava.

Repare na ironia: a metáfora foi inventada como ferramenta de comunicação com o C-level, dentro de uma empresa financeira. Nós é que a sequestramos e transformamos em jargão interno de engenharia.

E há uma segunda perda, mais séria. Numa entrevista de 2009, Cunningham voltou ao tema para dizer que a metáfora nunca foi sobre código bagunçado, e sim sobre o custo de operar com um entendimento incompleto do domínio. Michael Feathers formulou isso da maneira mais útil que já vi: dívida técnica é a distância acumulada entre o seu entendimento do problema e o entendimento que o sistema reflete. Você começa codificando o que entendeu; depois aprende mais; se o código não acompanha o aprendizado, você passa a tropeçar num descompasso conceitual toda vez que mexe ali.

Essa definição é infinitamente mais defensável numa reunião do que “o código está ruim”. Porque ela é verificável: quantas vezes, no último trimestre, uma regra de negócio nova exigiu contornar o modelo em vez de usá-lo?

Lição 1.2 → Classifique a dívida antes de cobrá-la

Nem toda dívida tem a mesma origem, e a origem muda completamente quem deve responder por ela.

Steve McConnell, num artigo da IEEE Software de 2007, propôs a primeira taxonomia séria: dívida não intencional, produzida por desconhecimento ou processo falho; dívida de curto prazo, assumida deliberadamente por um ganho imediato; e dívida de longo prazo, acumulada pela evolução natural do sistema. Foi ele também quem tornou explícito o par principal/juros.

Martin Fowler foi além em 2009 com o quadrante de dívida técnica, cruzando dois eixos:

                    PRUDENTE              IMPRUDENTE
                ┌─────────────────────┬─────────────────────┐
   DELIBERADA   │ "Entregamos agora,  │ "Não temos tempo    │
                │  refatoramos no     │  para desenhar       │
                │  próximo ciclo"     │  isso direito"       │
                ├─────────────────────┼─────────────────────┤
   INADVERTIDA  │ "Agora entendemos   │ "O que é camada     │
                │  como deveria       │  de domínio?"        │
                │  ter sido feito"    │                      │
                └─────────────────────┴─────────────────────┘

Por que isso importa numa conversa com gestão? Porque muda o pedido. Dívida deliberada e prudente é uma promessa que a empresa fez a si mesma e agora precisa honrar — você está cobrando uma decisão anterior, não pedindo um favor. Dívida inadvertida e prudente é aprendizado do domínio; é o quadrante mais honesto e o mais fácil de defender, porque ninguém errou. Já dívida imprudente, deliberada ou não, é um problema de processo ou de capacitação — e apresentá-la como se fosse trade-off estratégico é desonesto e, pior, não resolve, porque a mesma dívida vai voltar em seis meses pela mesma porta.

Lição 1.3 → Diga em voz alta qual dívida você não vai pagar

Este é o movimento mais contraintuitivo do artigo e talvez o de maior retorno.

Quem chega no fórum de arquitetura pedindo para zerar a dívida está pedindo para não ser levado a sério — porque zerar dívida significaria alocar todo o recurso disponível em remediação, sem construir nada que diferencie a empresa. A própria McKinsey é explícita ao dizer que o objetivo não é chegar a zero, e a orientação prática é que raramente compensa reduzir abaixo de algo em torno de 10%: parte da dívida simplesmente nunca vale o custo de pagar.

Então inverta. Leve uma lista de três itens que o seu time decidiu conscientemente não corrigir, com a razão de cada um: “esse módulo é feio mas não é tocado há dois anos e não é caminho crítico”, “essa duplicação é intencional para desacoplar dois times”, “esse serviço vai ser desligado em 2027, não vamos investir nele”.

O efeito prático

No instante em que você mostra o que decidiu não fazer, o seu pedido deixa de ser preferência estética e passa a ser priorização. Você para de ser o engenheiro que sempre quer reescrever tudo e vira a pessoa que já filtrou o ruído antes de ocupar o tempo da liderança. Isso não é técnica de retórica — é o subproduto natural de ter feito o trabalho de análise de verdade.

Pense comigo — antes de dizer a palavra “dívida”

• Isso atrapalha o negócio ou atrapalha a mim? A pergunta honesta é: se ninguém mais mexer nesse código nos próximos dois anos, alguma coisa acontece? Se a resposta é não, você tem uma preferência, não uma dívida.

• Em que quadrante isso está? Se for deliberada e prudente, quem prometeu pagar? Quando? Está registrado em algum lugar, ou só na memória de quem estava na sala?

• Qual é a distância entre o sistema e o meu entendimento atual do domínio? Conte as vezes em que uma regra nova precisou de gambiarra em vez de encaixar no modelo. Esse número é a sua evidência.

• O que eu vou dizer que NÃO vamos corrigir? Se você não consegue nomear três itens, você ainda não priorizou — só listou incômodos.

Pontos altos do Pilar 1

1. A metáfora nasceu para conversar com executivos, dentro de uma empresa financeira. Nós a transformamos em jargão de engenheiro.

2. Dívida é a distância entre o sistema e o entendimento atual do domínio — não a feiura do código.

3. Levar uma lista do que você decidiu não corrigir transforma o pedido de preferência em priorização.

Pilar 02: Traduza para a moeda de quem decide

O diretor não precisa entender o problema técnico. Precisa entender a unidade de medida. E, felizmente, a unidade certa já existe e é justamente a que ele usa todos os dias.

Lição 2.1 → Separe principal de juros — e apresente os dois

A referência aqui é o livro de Philippe Kruchten, Robert Nord e Ipek Ozkaya, Managing Technical Debt: Reducing Friction in Software Development (SEI Series, 2019), que dedica um capítulo inteiro à distinção entre principal e juros, custo e valor, dívida potencial e dívida efetiva.

A tradução é direta:

• Principal — o custo de remediar. É um número único, em horas ou reais, com data.

• Juros — o arrasto recorrente que você paga todo mês por não ter remediado. É um número por período.

Quase todo engenheiro apresenta só o principal: “são seis semanas de duas pessoas”. E é exatamente por isso que o pedido é arquivado — porque, isolado, o principal é puro custo. Sem os juros ao lado, você está pedindo para a empresa gastar seis semanas em troca de nada visível.

Com os juros, a conversa muda de natureza. Deixa de ser “quero gastar” e passa a ser “estamos gastando, só que parcelado e sem abater o saldo devedor”.

Lição 2.2 → Os juros são invisíveis por natureza — o seu trabalho é dar rosto a eles

Juros de dívida técnica não aparecem em nenhuma linha de orçamento. Eles se escondem dentro de custos que já foram normalizados pela organização: plantão, conciliação manual, retrabalho, incidente, prazo de entrega que ninguém mais questiona porque “sempre foi assim”.

Vamos a um caso concreto do nosso mundo. Motor de cobrança sem reprocessamento idempotente:

PRINCIPAL
  6 semanas × 2 engenheiros ................... R$  96.000

JUROS (por ano, hoje)
  Conciliação manual pós-falha
    4h/semana × 52 × R$ 120/h ................. R$  24.960
  Plantão acionado por reprocesso duplicado
    ~2 incidentes/mês × 5h × 2 pessoas ........ R$  28.800
  Retrabalho de atendimento (estorno indevido)
    ~35 casos/mês × 40 min × R$ 45/h .......... R$  12.600
  Janela de entrega travada
    3 iniciativas adiadas no ano (ver adiante)
  ─────────────────────────────────────────────────────────
  Subtotal mensurável ......................... R$  66.360/ano

Duas coisas acontecem quando você apresenta assim. Primeiro, o principal deixa de ser caro: R$ 96 mil contra R$ 66 mil por ano é payback em pouco mais de dezoito meses, e todo diretor sabe ler payback. Segundo — e mais importante — você acabou de tornar visível um gasto que a empresa já vinha fazendo sem saber que fazia.

A frase que funciona

Não é retórica. É a descrição literal do que está acontecendo.

Lição 2.3 → Quantifique o custo de atraso — porque a intuição alheia sobre ele é péssima

Repare que na conta acima ficou uma linha em aberto: “3 iniciativas adiadas no ano”. Essa linha costuma ser a maior de todas, e quase ninguém a preenche.

O conceito é o Custo de Atraso, formulado por Donald Reinertsen em The Principles of Product Development Flow (2009). Ele mede o impacto econômico do tempo sobre a realização de valor: receita não realizada, custo de oportunidade e riscos que se acumulam enquanto algo espera na fila. O conselho dele é célebre — se você só puder quantificar uma coisa, que seja o custo de atraso.

E há dois dados no trabalho de Reinertsen que valem ouro numa reunião:

• Cerca de 85% dos gestores de produto não conhecem o próprio custo de atraso.

• Quando estimam por intuição, as estimativas divergem entre si numa proporção de até 50 para 1.

Traduzindo: quem chega com esse número calculado tem uma vantagem informacional enorme sobre todo mundo que chega com sensação — inclusive sobre pessoas hierarquicamente acima. Não porque seja mais inteligente, mas porque fez uma conta que os outros presumiram impossível.

O caso mais citado é o da Maersk Line: uma funcionalidade que ficou 38 semanas parada em filas, com custo de atraso superior a US$ 200 mil por semana — perto de US$ 8 milhões em receita não realizada por algo que ninguém percebia como custo, porque fila não aparece em relatório.

Para ordenar iniciativas concorrentes, Reinertsen propõe o CD3: custo de atraso dividido pela duração. É a régua que responde à pergunta que o seu gestor realmente tem — não “isso é importante?”, mas “isso é mais importante do que as outras sete coisas que estão na minha mesa?”.

Aplicando ao domínio bancário

Uma integração de Pix travada por um mês não custa “um mês de time”. Custa a receita de tarifa não capturada nesse mês, mais o custo de aquisição dos clientes que abriram conta em outro lugar, mais o risco de multa se houver prazo regulatório envolvido. Quando você monta essa conta, descobre com frequência que o custo de atraso é uma ordem de grandeza maior do que o custo do trabalho — e essa é a informação que muda a decisão.

Pense comigo — antes de apresentar um número

• Eu estou apresentando principal, juros, ou os dois? Se for só o principal, você está pedindo custo puro. Sem os juros, a resposta racional do outro lado é não.

• Onde os juros estão escondidos hoje? Plantão, conciliação manual, retrabalho de atendimento, prazo inflado. Procure em orçamentos que já existem e ninguém questiona.

• Quanto custa cada semana de atraso? Receita não capturada, custo de oportunidade, exposição regulatória. Se você nunca fez essa conta, faça uma vez — o resultado costuma surpreender você antes de surpreender o gestor.

• Isso é mais importante do que as outras coisas na mesa dele? Essa é a pergunta real. Responder a ela com CD3 é mais honesto do que responder com convicção.

Pontos altos do Pilar 2

1. Principal e juros é a estrutura mental que a área financeira já domina. Use a linguagem dela em vez de inventar a sua.

2. Juros de dívida técnica se pagam parcelados e invisíveis — dar rosto a eles é metade do trabalho de convencimento.

3. Quantifique o custo de atraso: a intuição alheia sobre ele erra por ordens de grandeza, e quem calculou tem vantagem informacional real.

Pilar 03: Meça sem fingir precisão

Vamos para o pilar que separa o profissional maduro do vendedor interno. Porque o Pilar 2 tem um efeito colateral perigoso: quando você aprende a produzir números, fica tentador produzi-los com uma confiança que os dados não sustentam.

E diretor experiente detecta falsa certeza. Uma vez detectada, tudo que você disser depois entra com desconto — inclusive o que era verdade.

Lição 3.1 → Medir é reduzir incerteza, não eliminá-la

A referência é Douglas Hubbard, How to Measure Anything: Finding the Value of “Intangibles” in Business. A tese central liberta o engenheiro do impasse mais comum: “não dá para medir isso”.

Hubbard trata medição como redução de incerteza baseada em observação — não como obtenção de certeza. E faz questão de distinguir as duas coisas: reduzir incerteza é possível, eliminá-la não é, porque o mundo é complexo demais. A consequência prática é enorme: mesmo uma redução modesta de incerteza já tem valor econômico, e organizações deixam muito valor na mesa ao operar por intuição quando técnicas simples dariam clareza suficiente para escolher melhor.

Ele também é direto sobre por que as pessoas acham que algo não pode ser medido, e nenhuma das razões tem a ver com o objeto: ou a definição de medição está mal compreendida, ou o objeto da medição não foi bem definido, ou os métodos disponíveis são desconhecidos. Na esmagadora maioria dos casos em engenharia, o problema é o segundo — “a dívida do motor de cobrança” não é mensurável, mas “horas de plantão por mês atribuíveis a reprocesso duplicado” é trivial.

Lição 3.2 → Decomponha, depois fale em faixas de 90%

Duas técnicas específicas, ambas do arsenal de Hubbard, e ambas aplicáveis na próxima segunda-feira.

Decomposição. Só quebrar uma estimativa muito incerta em componentes menores já produz uma melhora substancial na estimativa — antes mesmo de coletar qualquer dado novo. Foi o que fizemos na tabela de juros do Pilar 2: ninguém sabe responder “quanto custa essa dívida”, mas todo mundo consegue estimar horas de plantão, número de incidentes e custo-hora.

Intervalo de confiança de 90%. Em vez de um número, você declara uma faixa que tem 90% de chance de conter o valor real. E há um teste simples para calibrar os limites: um intervalo de 90% implica 5% de chance de o valor real estar acima do teto e 5% abaixo do piso. Então pergunte-se se você está 95% seguro de que o valor real fica abaixo do teto que escreveu. Se não estiver, suba o teto. Faça o mesmo com o piso.

✗  "Isso vai economizar R$ 480 mil por ano."

✓  "Entre R$ 320 mil e R$ 700 mil por ano, com 90% de confiança.
    A maior fonte de incerteza é o volume de incidentes —
    trabalhamos com 18 a 30 por trimestre; se ficar perto de 18,
    o retorno vai para a ponta de baixo da faixa."

A segunda versão parece mais fraca. Não é. Ela é a única das duas que sobrevive a uma auditoria dos números daqui a um ano — e, portanto, a única que constrói credibilidade em vez de gastá-la.

Há ainda um efeito que vale mencionar: pessoas não são naturalmente boas em produzir intervalos calibrados, mas essa é uma habilidade treinável, com melhora mensurável por repetição e feedback. Vale exercitar em time, comparando estimativas passadas com resultados reais.

Lição 3.3 → Use evidência de sistema, não evidência de opinião — e pare de medir o que não muda a decisão

Números que você produziu sozinho, sobre o seu próprio pedido, têm um problema óbvio de credibilidade. Por isso vale ancorar parte do argumento em métricas que o time já coleta e que não foram inventadas para essa reunião.

As métricas DORA — lead time para mudança, frequência de deploy, taxa de falha de mudança e tempo de restauração de serviço, popularizadas em Accelerate, de Nicole Forsgren, Jez Humble e Gene Kim — funcionam bem porque descrevem o comportamento do sistema ao longo do tempo, não a sua opinião sobre ele. “A taxa de falha de mudança nesse serviço é 3× a média dos demais, há seis trimestres” é um fato observável.

Com uma ressalva que aumenta a sua credibilidade justamente por ser dita em voz alta: DORA é indicador de sistema e de time, não instrumento de avaliação individual. Se você não disser isso, alguém em algum momento vai usar o seu gráfico para avaliar pessoas, e o dano será atribuído a você.

Por fim, o critério que economiza semanas de análise, também de Hubbard: se a informação não tem influência sobre a decisão, ela não tem valor. Antes de o time gastar duas sprints instrumentando algo, pergunte qual o limiar em que aquele número mudaria a escolha. Se não existe limiar — se o “sim” ou “não” será o mesmo em qualquer resultado — a medição é curiosidade, não evidência.

Pense comigo — antes de dizer que tem certeza

• Eu consigo decompor isso em três coisas que eu de fato observo? Se não consigo, o problema não é falta de dado — é que a variável ainda não foi definida direito.

• Estou 95% seguro de que o valor real fica abaixo do meu teto? Se hesitei, o teto está baixo demais. Suba antes que a realidade suba por mim.

• O que eu explicitamente não sei aqui? Declarar isso primeiro tira do outro lado o trabalho de descobrir depois — e é a diferença entre ser corrigido e ser desacreditado.

• Se esse número der o contrário do que eu espero, a minha recomendação muda? Se não muda, eu não estou medindo. Estou procurando munição.

Pontos altos do Pilar 3

1. Medir é reduzir incerteza, não eliminá-la — e reduzir já é suficiente para decidir melhor.

2. Fale em faixas de 90%. Ponto único é promessa disfarçada de análise, e ela vence com juros.

3. Declarar o que você não sabe aumenta, não diminui, o peso do que você sabe.

Pilar 04: Classifique a decisão antes de pedir a decisão

Grande parte da fricção entre engenharia e gestão vem de um erro de enquadramento: tratamos decisões muito diferentes com o mesmo protocolo. Coisas triviais viram reunião de arquitetura; coisas irreversíveis são resolvidas numa thread de Slack de quinze minutos.

Lição 4.1 → Porta de uma via ou porta de duas vias

A formulação mais útil que o mercado produziu sobre isso está na carta de acionistas da Amazon. Decisões Tipo 1 são portas de uma via: consequentes e irreversíveis ou quase, e devem ser tomadas com método, lentidão, deliberação e consulta. Decisões Tipo 2 são portas de duas vias: reversíveis, e podem — devem — ser tomadas rapidamente por indivíduos ou grupos pequenos.

O diagnóstico que acompanha a ideia é o que interessa: à medida que organizações crescem, elas tendem a aplicar o processo pesado de Tipo 1 à maioria das decisões, inclusive às de Tipo 2. O resultado é lentidão, aversão a risco irrefletida, experimentação insuficiente e, por consequência, menos invenção.

Aplicando ao nosso ofício, com a nuance honesta: em software, quase nada é porta de uma via de verdade, porque quase tudo pode ser mudado com trabalho suficiente. A pergunta prática não é “é reversível?”, e sim “é reversível a que custo?”.

PORTA DE UMA VIA (ou quase)          PORTA DE DUAS VIAS
─────────────────────────────        ─────────────────────────────
Modelo de dados do razão             Biblioteca de cliente HTTP
Chave de partição no DynamoDB        Estratégia de cache
Provedor de core banking             Formato de log
Contrato de API pública              Ferramenta de observabilidade
Esquema de chaves de idempotência    Framework de teste

E aqui está o movimento que muda a reunião: declare a classificação antes de pedir a decisão. “Essa é reversível, sugiro decidirmos hoje e revisarmos em 60 dias” devolve poder ao gestor e elimina o teatro de aprovação. “Essa é de uma via, custa aproximadamente X para reverter, e por isso trouxe três alternativas com as consequências de cada uma” comunica seriedade sem drama.

Lição 4.2 → Instrumente a decisão: ADR, registro de dívida e pre-mortem

Três ferramentas concretas que transformam conversa de corredor em evidência auditável.

ADR — Architecture Decision Record. Formato proposto por Michael Nygard: contexto, decisão, consequências. O campo que quase todo mundo esquece é o das alternativas descartadas e por quê. É esse campo que protege você da pergunta “por que ninguém pensou nisso?” dois anos depois, feita por alguém que não estava na sala. Um ADR de meia página é o registro mais barato de responsabilidade compartilhada que existe.

Registro de dívida técnica. Kruchten, Nord e Ozkaya recomendam manter um registro explícito, com os itens de dívida armazenados nas mesmas ferramentas de trabalho do time e dentro de um único backlog. A lógica é simples e boa: dívida, assim como defeito e funcionalidade, representa trabalho a ser feito — então precisa ser visível e planejável, não viver numa planilha paralela que só engenheiro abre.

Isso resolve, de quebra, o problema da Lição 1.2: quando a dívida deliberada é registrada no momento em que é contraída, cobrar o pagamento depois deixa de ser opinião e passa a ser conferência.

Pre-mortem. Técnica de Gary Klein: reúna o time, declare que estamos um ano no futuro e o projeto fracassou, e peça a autópsia. Funciona porque inverte o incentivo social — em vez de precisar ter coragem para levantar um risco na frente do patrocinador, a pessoa é convidada a fazê-lo. Numa cultura em que ninguém quer ser o pessimista da sala, isso muda o que chega à mesa.

Lição 4.3 → Saber perder é parte da técnica

Você vai perder discussões. Vai apresentar a conta certa, com a faixa calibrada e o custo de atraso, e mesmo assim a decisão vai ser outra — por razões que talvez nem lhe contem, porque nem toda informação é sua para ter.

O complemento indispensável dos Tipos 1 e 2 é o disagree and commit: seguir adiante mesmo sem consenso, especialmente quando a decisão é reversível e o custo de estar errado é baixo. Mas a prática exige duas coisas que costumam ser omitidas:

• Registrar a discordância sem sabotar a execução. Um parágrafo no ADR — “esta opção foi escolhida contra a recomendação da engenharia, pelas razões X; o risco identificado é Y; sugerimos revisar em Z” — é registro, não é passivo-agressividade. O que é passivo-agressivo é executar mal para provar o ponto.

• Não cobrar a fatura depois. Quando o risco se materializa, a tentação de dizer “eu avisei” é enorme e o retorno é zero. O profissional que ganha autoridade de verdade é o que aparece com a solução e deixa o registro falar sozinho — ele está lá, datado, e todo mundo sabe.

Perder bem é o que compra o direito de ser ouvido na próxima. E vai haver próxima.

Pense comigo — antes de marcar a reunião

• Essa porta é de uma via ou de duas — e reverter custa quanto? Se for barata de reverter, talvez você não precise de aprovação nenhuma. Precise de um prazo para reavaliar.

• Estou pedindo decisão ou pedindo cobertura? São coisas diferentes, e misturá-las é o que faz reuniões de arquitetura durarem duas horas sem concluir nada.

• Se isso der errado em um ano, qual será a explicação? Faça o pre-mortem antes de a decisão sair, não depois do incidente.

• Se eu perder essa, eu executo bem mesmo assim? Se a resposta honesta for “não com vontade”, o problema deixou de ser técnico.

Pontos altos do Pilar 4

1. Diga se a porta é de uma via ou de duas antes de pedir aprovação — isso define o processo inteiro e devolve poder a quem decide.

2. Tratar decisão reversível como irreversível é a forma mais cara de parecer prudente.

3. ADR, registro de dívida e pre-mortem convertem memória de corredor em evidência datada.

Pilar 05: Construa crédito antes de precisar dele

Vamos ser explícitos sobre o que este pilar não é. Não é sobre puxar conversa no cafezinho, não é sobre virar amigo do diretor, não é sobre política de corredor. É sobre uma coisa só, e ela é mensurável: histórico de previsões cumpridas.

Há uma leitura incômoda que sustenta o pilar inteiro: dívida técnica não é, na origem, um problema técnico. Ela se manifesta como rigidez no sistema, mas é subproduto de problemas de processo e comunicação, com raiz na cultura da organização. Empresas muito siladas — onde engenharia, produto e design trabalham isolados — acumulam muito mais dívida, porque decisões de trade-off tomadas no código ficam a camadas de distância da necessidade real do cliente. Onde falta confiança, sobra dívida.

Lição 5.1 → Um caso por interlocutor, não um caso genérico para todos

Este é o erro mais caro e o mais fácil de corrigir. O mesmo problema técnico precisa de argumentos diferentes conforme quem está do outro lado:

• CFO / diretor financeiro — risco financeiro quantificado, payback, custo evitado. Fale em principal, juros e prazo de retorno.

• Diretor comercial / de receita — churn, capacidade do time de vendas continuar vendendo, prazo de entrega prometido a cliente.

• Produto — proteção do roadmap. O argumento vencedor é: quantas entregas suas eu destravo, e quando.

• Risco e compliance — exposição regulatória, rastreabilidade, prazo de resposta a demanda de auditoria. Num banco, esse costuma ser o interlocutor mais poderoso e o menos procurado por engenheiros.

Apresentar um único caso genérico para todos ao mesmo tempo obriga cada pessoa a traduzir sozinha para a própria realidade — e o resultado quase sempre é decisão nenhuma. Não porque discordem, mas porque ninguém se sentiu diretamente endereçado.

Lição 5.2 → Pense em campanha, não em reunião única — e volte com o número prometido

Ninguém aprova investimento estrutural na primeira exposição ao tema. Vale pensar como publicitário pensa: alcance e frequência. Quantas pessoas o argumento atinge, e quantas vezes.

Na prática, isso significa que o tema aparece em três ou quatro contextos antes de virar pedido formal — uma menção no relatório mensal, um dado no pós-mortem de um incidente, uma conversa de dez minutos com produto, um slide de contexto numa apresentação sobre outra coisa. Quando o pedido formal chega, ele não é novidade para ninguém. É a conclusão de algo que a organização já vinha percebendo.

A parte que quase todo mundo pula

Se você pediu aprovação prometendo “reduzir em 40% o tempo de resposta a incidente de liquidação”, volte em 90 dias com esse número exato, na mesma linguagem, mesmo que ele tenha ficado em 22%.

Sem isso, a próxima proposta parte do zero — e a organização aprende que investimento em engenharia é um lugar para onde recursos vão e do qual nenhuma notícia volta. Ter entregado 22% e reportado honestamente constrói mais crédito do que ter entregado 40% e nunca ter contado.

Lição 5.3 → Não use medo como alavanca — e reconheça que parte da desconfiança é merecida

O apelo catastrofista funciona uma vez. “Se não fizermos isso, o sistema vai cair” produz atenção imediata na primeira ocorrência. Na segunda, você é o engenheiro que grita lobo. Na terceira, o risco real que você trouxer vai ser descontado exatamente como os anteriores — e o custo desse desconto não é seu, é da empresa.

Existe uma versão mais honesta e mais eficaz: apresentar probabilidade e consequência separadas. “A chance de isso causar indisponibilidade no próximo semestre é baixa, algo entre 10% e 20%. Mas, se acontecer durante fechamento, o impacto é alto e não temos plano de contingência.” Isso é informação. O outro é chantagem emocional com sotaque técnico.

E cabe uma dose de honestidade coletiva para fechar o pilar. Parte da resistência que encontramos não é preconceito contra tecnologia — é histórico. Nós já pedimos reescrita completa que não entregou nada. Já chamamos preferência de arquiteto de necessidade de negócio. Já estimamos três meses para algo que levou onze e nunca voltamos para explicar por quê. Se formos honestos, temos uma parcela real de responsabilidade pela dificuldade que temos hoje em ser levados a sério.

A boa notícia é que crédito se reconstrói exatamente do mesmo jeito que se perde: uma previsão por vez.

Pense comigo — antes de pedir qualquer coisa

• Qual foi a última previsão que eu fiz para essa pessoa, e ela se cumpriu? Se você não lembra, ela lembra. Essa é a sua linha de crédito.

• Estou falando com o interlocutor certo, na moeda dele? Em banco, risco e compliance frequentemente têm mais poder de destravar orçamento do que tecnologia — e quase nunca são procurados.

• Esta é a primeira vez que essa pessoa ouve falar disso? Se for, o pedido é prematuro. Primeiro o tema precisa existir; depois ele vira decisão.

• Estou usando risco como informação ou como pressão? Se a frase precisa de tom dramático para funcionar, o número por trás dela provavelmente é fraco.

Pontos altos do Pilar 5

1. Credibilidade é ativo acumulado, não argumento apresentado. Ela se constrói muito antes da reunião em que você vai precisar dela.

2. Um caso por interlocutor. O caso genérico obriga cada um a traduzir sozinho, e o resultado é decisão nenhuma.

3. Voltar com o número prometido — mesmo quando ele decepciona — vale mais do que superar a meta em silêncio.

O que muda na segunda-feira

Os cinco pilares não são cinco assuntos. São uma sequência única, e ela cabe em cinco perguntas feitas na ordem certa, antes de abrir qualquer slide:

A linha de raciocínio, em cinco perguntas

1. O que é essa dívida, na definição precisa? Distância entre o sistema e o entendimento atual do domínio — não estética. E em que quadrante ela está.

2. Qual é o principal e quais são os juros, em reais e por período? Incluindo o custo de atraso das iniciativas que ela trava.

3. Qual é a minha faixa de 90%, e o que eu explicitamente não sei? Ponto único é promessa; faixa é análise.

4. Essa porta é de uma via ou de duas, e reverter custa quanto? Isso define quem decide e com que velocidade.

5. Eu tenho crédito para pedir isso — e vou voltar com qual número, em quanto tempo?

Repare no que essas perguntas têm em comum: nenhuma delas é sobre convencer. Todas são sobre fazer o trabalho de análise antes de ocupar o tempo de outra pessoa. A persuasão, quando aparece, é consequência — não método.

E vale terminar situando isso no momento que estamos vivendo. Se a IA de fato funciona como amplificador — acelerando quem tem fundamento e multiplicando o caos de quem não tem —, então a capacidade de traduzir risco técnico em decisão de negócio deixou de ser um diferencial de senioridade. Virou requisito. Times vão produzir código mais rápido do que a organização consegue avaliar, e a pessoa capaz de dizer, com número e com faixa de confiança, onde vale a pena desacelerar, passa a ser a mais valiosa da sala.

Quem só souber descrever o problema em termos de engenharia vai continuar tendo o pedido arquivado. Só que agora mais rápido.

A boa notícia — e é uma notícia boa de verdade — é que nada aqui exige talento especial. Exige uma planilha, uma conversa de minutos com quem entende do negócio, e a disciplina de voltar em noventa dias com o resultado. É trabalho, não dom.

Para ir além

• Kruchten, Nord & Ozkaya — Managing Technical Debt: Reducing Friction in Software Development (SEI Series, 2019). A referência definitiva sobre principal, juros e registro de dívida.

• Donald Reinertsen — The Principles of Product Development Flow (2009). Custo de atraso e CD3.

• Douglas Hubbard — How to Measure Anything. Decomposição, intervalos calibrados e valor da informação.

• Forsgren, Humble & Kim — Accelerate. As quatro métricas e a evidência empírica por trás delas.

• Kim, Behr & Spafford — The Phoenix Project. Romance sobre um líder de TI que aprende justamente a traduzir problema de tecnologia em termo de negócio. Boa porta de entrada.

• Michael Feathers — Toward a Galvanizing Definition of Technical Debt (ensaio). A definição que salva a metáfora.

• Martin Fowler — TechnicalDebtQuadrant (bliki) e Steve McConnell — Managing Technical Debt (IEEE Software, 2007).

• Relatórios — DORA 2025 (State of AI-assisted Software Development), CISQ 2022 (Cost of Poor Software Quality), McKinsey (Tech debt: Reclaiming tech equity).

O saldo dele já foi debitado. O irmão não recebeu nada. O suporte não sabe dizer se o dinheiro saiu. E o time de plantão abre o dashboard e encontra uma linha no banco de dados com status = 'PENDENTE' e um updated_at de quarenta minutos atrás.

A pergunta que todo mundo faz nesse momento é a errada. A pergunta errada é “qual foi o bug?”. A pergunta certa é: “o que o meu sistema sabe, o que o SPI sabe, e por que essas duas coisas divergiram?”

Porque na esmagadora maioria das vezes não há bug nenhum. Há um sistema distribuído funcionando exatamente como especificado, e um código local que foi escrito assumindo garantias que o arranjo do Pix nunca ofereceu.

Este artigo é sobre essas garantias — as que existem, as que não existem, e o que o Banco Central exige que você faça no meio do caminho.

Pense comigo: se o seu código não respeita isso…

Se o seu sistema representa uma transação Pix como uma linha com um campo status que sofre UPDATE, você já perdeu antes de começar. Não porque seja feio, mas porque você acaba de destruir a única coisa que te salva numa auditoria ou num incidente: a capacidade de responder quando e por causa de qual mensagem aquela transação mudou de estado.

Um campo status é uma fotografia. O que o Pix exige de você é um filme. E filme se guarda em log de transições, não em coluna sobrescrita.

Assincronismo não é escolha de arquitetura — é imposição do arranjo

Existe um mal-entendido confortável que circula em muito time: o de que o Pix “é assíncrono porque o banco escolheu processar em fila”. Não é. O assincronismo está na especificação, não na sua implementação.

O fluxo interbancário funciona assim: o PSP do pagador envia uma ordem de pagamento ao SPI. Em algum momento — que pode ser em 200 milissegundos ou pode não acontecer nunca — chega de volta uma outra mensagem, independente, com o veredito. Não existe um HTTP 200 que signifique “liquidado”. Não existe BEGIN TRANSACTION … COMMIT atravessando três instituições e a rede do Banco Central. Não existe rollback.

Vale a analogia do correio registrado. Você não liga para o destinatário e espera na linha até ele confirmar que recebeu. Você posta a carta, recebe um comprovante de postagem, e dias depois chega um aviso de recebimento — ou não chega. O comprovante de postagem prova que você postou. Não prova que entregou. Confundir os dois é a origem da maior parte dos incidentes graves de Pix.

Há ainda um detalhe do catálogo que costuma pegar times desprevenidos: a granularidade da mensagem não é necessariamente a granularidade da transação. Uma mesma mensagem de ordem de pagamento pode carregar múltiplas operações agregadas, e o mesmo vale para a mensagem de resposta. Qualquer modelo mental que assuma “uma mensagem = um pagamento” vai quebrar no primeiro cenário de agregação.

Pense comigo: se o seu código não respeita isso…

Se você escreveu um service que chama o gateway do SPI e faz await na resposta esperando o resultado final da liquidação, o seu código tem uma premissa embutida que a rede não honra. O que vai acontecer, inevitavelmente:

• a thread vai estourar timeout antes do arranjo;

• o seu catch vai capturar uma exceção de rede e traduzir como “falhou”;

• o seu código vai estornar o débito do cliente;

• e três segundos depois o SPI vai confirmar a liquidação daquela transação, que realmente aconteceu.

Resultado: o cliente recebeu o dinheiro de volta e o beneficiário recebeu o valor. Você acabou de criar dinheiro. Isso não é um bug de borda — é a consequência lógica e previsível de tratar ausência de resposta como negativa de resposta.

Regra que vale gravar: em sistema de pagamento, timeout não é resultado. Timeout é ausência de informação, e ausência de informação exige consulta, não decisão.

As três pacs: o vocabulário completo do Pix

Aqui está o fato que quase todo conteúdo sobre Pix apresenta de forma difusa, e que na verdade é enxuto a ponto de caber em um parágrafo.

O SPI usa o padrão internacional ISO 20022, e a família pacs — de Payments Clearing and Settlement — tem exatamente três mensagens no arranjo do Pix. Três. O próprio SPI expõe um endpoint de catálogo que lista as versões de mensagem vigentes, e na família pacs aparecem pacs.002, pacs.004 e pacs.008. Nada além disso.

pacs.008 — a intenção

FIToFICustomerCreditTransfer. É a ordem de pagamento: o PSP do pagador declarando ao SPI que quer transferir um valor de uma conta para outra. Carrega o identificador fim a fim da transação, os dados de pagador e recebedor, o valor, a finalidade, e — detalhe operacionalmente importante — um campo de prioridade de liquidação.

O que ela é: uma declaração de intenção assinada digitalmente.
O que ela não é: prova de que o dinheiro saiu.

Um ponto que rende decisão de arquitetura: a prioridade preenchida nessa mensagem determina por qual canal de transmissão a operação vai trafegar, e essa escolha se propaga para todas as mensagens seguintes da mesma operação. Ou seja, a decisão tomada no momento da iniciação amarra o comportamento do ciclo inteiro. Não é um parâmetro cosmético.

pacs.002 — o veredito

FIToFIPaymentStatusReport. É a mensagem que efetivamente muda o estado do mundo. Ela referencia a mensagem original e carrega o status: aceito e liquidado, ou rejeitado com um código de motivo padronizado.

É a operária da rede, e por dois motivos que costumam confundir:

1. Ela aparece em mais de um fluxo. Responde à ordem de pagamento, mas também responde à mensagem de devolução. Se o seu handler assume que toda pacs.002 se refere a um pagamento original, ele vai processar errado o retorno de uma devolução.

2. Os códigos de rejeição não são todos iguais. O padrão ISO define motivos de naturezas muito diferentes: conta encerrada, conta bloqueada, transação proibida para aquele tipo de conta, liquidação abortada por timeout, transação interrompida por timeout no agente do credor, agente do credor fora do ar.

Colocar tudo isso num único if (status != OK) marcarComoFalha() é jogar fora a informação mais cara que o arranjo te entrega. “Conta encerrada” é erro de negócio definitivo — você informa o cliente e encerra. “Timeout no agente do credor” é erro de infraestrutura de terceiro — pode ser retentável, pode não ser, e a decisão depende de você saber se houve liquidação. São dois mundos.

pacs.004 — o arrependimento

PaymentReturn. É a devolução. Segundo o Catálogo de Serviços do SFN, quando o usuário recebedor identifica que a transferência foi feita de forma indevida e quer devolver o valor ao pagador, entram em cena a pacs.004 e a pacs.002 correspondente.

E aqui está a assimetria mais importante do arranjo inteiro, aquela que sustenta a tese deste artigo:

Não existe mensagem de cancelamento no Pix. Você não desfaz um pagamento. Você faz outro, no sentido inverso, com vínculo ao original.

Em vocabulário de engenharia: o Pix não tem rollback, tem evento compensatório. Quem já trabalhou com Event Sourcing reconhece o padrão na hora — você não apaga o evento errado do log, você emite um evento que o compensa, e ambos ficam registrados para sempre. O Bacen desenhou o arranjo assim de propósito: em sistema financeiro, apagar história é pior do que registrar erro.

Há ainda uma restrição operacional específica dessa mensagem. A devolução sempre trafega pelo canal primário de transmissão, mesmo tendo campo de prioridade — e as respostas decorrentes dela também. Isto é, mesmo que a operação original tenha ido pelo canal secundário, a devolução não vai. Se a sua camada de transporte roteia mensagem por prioridade de forma genérica, ela vai violar essa regra sem avisar ninguém.

As vizinhas que ninguém apresenta

Falar só das três pacs dá uma visão incompleta do ciclo. Ao redor delas existe um conjunto que costuma ser implementado às pressas, e é exatamente onde moram os incidentes silenciosos:

• admi.002 — erro não terminativo. Comunicação de erro que não encerra a transação. Se o seu código trata isso como rejeição, você marca como morta uma transação que ainda está viva. Analogia: o garçom voltou à mesa dizendo que não entendeu o pedido. Isso não significa que a cozinha recusou o prato.

• admi.004 — avisos sobre a operação do SPI. É a mensagem que fala do sistema, não da sua transação.

• Família camt — conciliação e conta. A camt.060 vai do PSP para o SPI como requisição, e a resposta vem em camt.052, camt.053 ou camt.054, conforme a natureza do que se pediu. Há ainda camt.014 para avisos de alteração de dados cadastrais de participante e camt.025 para resultado de gravação. Este é o material bruto da sua conciliação — e, como veremos mais pra frente, é também o único lugar de onde você consegue descobrir o que realmente aconteceu com uma transação.

• Família REDA — gestão de participantes indiretos. REDA.014 e REDA.031 do PSP para o SPI, REDA.016 e REDA.017 no sentido inverso. Se você opera como liquidante ou depende de um, esse é o vocabulário que descreve a sua relação com ele.

• pibr.001 e pibr.002 — teste de ECO. Mensagens proprietárias brasileiras, o heartbeat da sua conexão com a rede. Elas respondem à pergunta “o canal está vivo?”, que é diferente de “minha transação foi processada?”.

• Família LPI — mensagens proprietárias de movimentação de saldo da Conta PI.

E onde é que a pacs não aparece

Ponto de confusão frequente, principalmente em quem entrou no Pix pela porta de um BaaS: as pacs só existem entre o participante e o SPI.

O DICT — o diretório de chaves — é REST/JSON. A API Pix que você usa para gerar cobrança, consultar um pix recebido ou receber webhook também é REST/JSON. Não há uma linha de ISO 20022 ali. Quem integra com um provedor nunca vê uma pacs na vida: vê o JSON que alguém traduziu por ele.

Isso significa que existe, obrigatoriamente, uma camada de tradução entre o vocabulário do arranjo e o vocabulário do seu domínio. Se essa camada não for explícita e isolada — uma Anti-Corruption Layer de manual —, ela existe assim mesmo, só que espalhada por dezenove classes do seu core.

Pense comigo: se o seu código não respeita isso…

Suponha que o seu handler de mensagens tenha esta forma, que é a forma mais comum que existe:

if (mensagem.status == "ACSC") { confirmar(); }
else { falhar(); }

Esse else está engolindo, no mínimo:

• rejeições de negócio definitivas (conta encerrada) — que deveriam informar o cliente com mensagem específica;

• rejeições de infraestrutura de terceiro (agente do credor fora do ar) — que podem ser reapresentáveis;

• abortos por timeout de liquidação — que exigem consulta, não conclusão;

• erros não terminativos que nem sequer são rejeição.

Quatro tratamentos radicalmente diferentes, achatados em uma palavra. Toda vez que alguém pergunta “por que nosso Pix tem tanto estorno indevido?”, a resposta costuma estar nesse else.

A máquina de estados que o arranjo exige de você

Agora podemos montar o modelo. Do lado do PSP pagador, o ciclo de vida mínimo honesto de uma transação é:

INICIADA
   → VALIDADA
   → DEBITADA / SALDO_RESERVADO
   → ENVIADA_AO_SPI
   → { LIQUIDADA | REJEITADA | INDETERMINADA }
   → [ DEVOLVIDA ]

Três observações que transformam isso de diagrama bonito em decisão de engenharia.

1. Os estados finais não são dois, são três. Todo mundo modela sucesso e falha. Quase ninguém modela o terceiro, que é o único que realmente dói. Voltaremos a ele no próximo tópico.

2. LIQUIDADA não é estado terminal. Uma transação liquidada pode receber devolução depois — por erro operacional, por acordo entre as partes ou por mecanismo regulatório. Quem modelou liquidação como estado absorvente vai precisar reabrir o modelo, e reabrir máquina de estados em produção é caro.

3. Terceira: transições precisam ser fatos registrados, não mutações. Cada mudança de estado deve guardar: o estado anterior, o estado novo, o identificador da mensagem que causou a mudança, o timestamp do arranjo e o timestamp local. Sem isso você não consegue responder à única pergunta que importa numa apuração de incidente: “em que instante nós soubemos disso, e por quê?”

A analogia que costuma destravar a conversa com o time de produto é a do livro-razão contábil. Contador nunca apaga lançamento errado — ele faz um lançamento de estorno. O livro cresce, nunca encolhe, e o saldo é sempre derivado da soma dos lançamentos. Se contabilidade descobriu isso há seiscentos anos e o Bacen desenhou o Pix sobre esse mesmo princípio, talvez o seu UPDATE transacao SET status = 'OK' mereça uma segunda olhada.

Pense comigo:

Imagine o cenário real: chega uma pacs.002 de confirmação e, dois segundos depois, chega uma segunda cópia da mesma mensagem — o que, como veremos mais pra frente, é comportamento previsto do canal de comunicação, não anomalia.

Com um campo status mutável, as duas execuções são indistinguíveis. Com máquina de estados e transições registradas, a segunda mensagem encontra uma transição já existente para aquele identificador, é reconhecida como reentrega e descartada. Não é elegância arquitetural — é a diferença entre creditar o cliente uma vez ou duas.

E o corolário, que é o coração do tópico seguinte: a sua máquina de estados precisa ter uma transição legítima para “eu não sei”. Se o único caminho que sai de ENVIADA_AO_SPI vai para sucesso ou falha, você forçou o sistema a mentir quando ele não sabe. E sistema que mente sobre dinheiro cria prejuízo contábil.

O estado indeterminado — o que fazer quando a resposta não vem

Este é o tópico que separa quem já operou Pix em produção de quem leu sobre Pix.

O SPI opera controle de timeout em dois pontos distintos do fluxo. O primeiro cobre o intervalo entre o PSP pagador receber a ordem do cliente e efetivamente enviá-la ao SPI — e é o próprio PSP quem declara esse valor na mensagem. O segundo cobre o intervalo entre o SPI receber a ordem e a liquidação efetiva, o que inclui a validação e o retorno por parte do PSP recebedor. Quando o controle foi ativado, em 2020, esses valores foram estabelecidos provisoriamente em cinco e dez minutos, respectivamente. Os números vigentes devem ser conferidos no catálogo atual antes de qualquer implementação — o que não muda é a existência dos dois controles e o que eles significam para você.

Repare no escopo do segundo: ele engloba o comportamento de outra instituição. O seu relógio de incerteza depende da disponibilidade de um terceiro sobre o qual você não tem controle, visibilidade nem SLA contratual. Essa é a definição operacional de dependência distribuída.

A consequência é esta: existe um intervalo de tempo real, mensurável, em que a sua transação já saiu do seu domínio e você não sabe o desfecho. Não é falha. É o estado normal do sistema entre dois pontos.

A idempotência não é convenção sua — é norma, e tem janela

O Catálogo de Serviços do SFN estabelece que tanto o ciclo básico de transferência quanto o de devolução operam sob o princípio da idempotência, com janela de 24 horas.

Leia de novo, porque isso muda a política de retentativa do seu sistema inteiro. Reapresentar a mesma operação, com o mesmo identificador, dentro da janela, é comportamento previsto pela especificação — não é gambiarra e não gera duplicidade. Fora da janela, a mesma operação passa a ser uma transação nova, com efeito financeiro novo.

O que essa regra implica na prática:

• o identificador fim a fim é a sua chave de idempotência. Não invente outra, não use o seu ID interno como âncora com o arranjo;

• ele precisa ser gerado antes do envio e persistido junto com a intenção. Gerar identificador no momento do envio significa que uma queda entre a persistência e o envio te deixa sem chave para consultar;

• a sua política de retentativa precisa conhecer o relógio de 24 horas. Um job de reprocessamento que varre transações antigas sem essa noção é uma máquina de duplicar pagamento com pinta de rotina de manutenção.

Reentrega é comportamento especificado, não anomalia

O guia de implementação do canal de comunicação é explícito quanto a um ponto que muda a forma de escrever o consumidor: a ausência de confirmação de leitura no tempo adequado pode fazer com que a mesma mensagem seja disponibilizada novamente, onerando tanto os sistemas do Banco Central quanto os do próprio participante. O guia também trata do ritmo de leitura do endpoint de recepção, com tempo máximo recomendado na ordem de 200 milissegundos no canal primário e intervalo maior no canal secundário.

Traduzindo para o vocabulário que usamos todo dia: a entrega é at-least-once. Você vai receber mensagem repetida. Não ocasionalmente, não em cenário de desastre — no funcionamento normal, sempre que a confirmação atrasar.

Quem trabalha com Kafka, SQS ou qualquer broker moderno já sabe onde isso vai dar: exactly-once no transporte é ficção, e a única defesa real é processamento idempotente no consumidor. A diferença é que aqui o payload duplicado não é um evento de analytics. É trezentos e oitenta reais.

Compartilhar

A política que separa os times maduros dos demais

Diante de uma transação indeterminada, existem três condutas possíveis. Duas estão erradas:

• Errado — concluir como falha e estornar o cliente. Se a liquidação ocorreu, você criou dinheiro.

• Errado — reapresentar cegamente sem controle de janela. Fora das 24 horas, você paga duas vezes.

• Certo — consultar. Manter a transação em estado indeterminado explícito, com o cliente informado com honestidade, e resolver por reconciliação contra a fonte da verdade — que não é o seu banco de dados.

“Consultar” onde, exatamente?

Essa é a pergunta que separa o conselho bonito da engenharia de verdade. Falar “consulte o SPI” é fácil até alguém pedir o endpoint. Então vamos ao que existe de fato.

Primeiro fato, e ele reorganiza tudo: não existe uma consulta de situação de transação. A família pacs tem três mensagens — ordem, veredito e devolução — e nenhuma delas serve para perguntar “qual o status do meu identificador fim a fim?”. Não há o equivalente a um GET /transacao/{e2e}/status. Quem procura por isso no catálogo não vai achar, e isso não é omissão: é decorrência do desenho.

O que existe é a família camt, e o Catálogo de Serviços do SFN é preciso quanto ao papel dela: são mensagens que permitem consultas diversas relacionadas à Conta PI. A camt.060 é a requisição, enviada do PSP para o SPI, e pode ser respondida com camt.052, camt.053 ou camt.054, a depender da natureza do que foi pedido. O roteiro de participação direta no SPI detalha os três caminhos que o participante precisa demonstrar que sabe percorrer:

• camt.060 → camt.053: saldo de fechamento de um dia anterior;

• camt.060 → camt.054: detalhes de um lançamento específico;

• camt.060 → camt.052: indicação do arquivo que contém a relação de lançamentos, seguida do download desse arquivo.

A inversão mental que isso exige

Você não pergunta ao SPI “essa transação liquidou?”. Você pergunta “existe lançamento correspondente na minha Conta PI?”.

A diferença não é semântica, é de modelo. No Pix, liquidação é um fato contábil, e o status da sua transação é uma propriedade derivada desse fato — não o contrário. A mensagem de veredito é a notificação do fato; o lançamento na Conta PI é o fato. Quando as duas coisas divergem, o lançamento ganha, sempre.

A analogia do dia a dia: quando você não tem certeza se uma compra passou, você não liga para a loja perguntando o status do pedido. Você abre o extrato e olha se saiu do seu saldo. O extrato não é a opinião de ninguém sobre o que aconteceu — é o que aconteceu.

E aqui vem a parte que quebra a arquitetura ingênua

A consulta também é assíncrona. A camt.060 é uma mensagem postada no canal, não uma chamada REST síncrona. Você envia a pergunta e a resposta chega depois, por outra mensagem, pelo mesmo endpoint de recepção que já entrega as suas pacs. E no caminho da relação de lançamentos há ainda um passo adicional de download de arquivo.

A consequência é dura e vale escrever em negrito: não existe nenhuma forma de resolver uma transação indeterminada dentro do ciclo de requisição do cliente. Nenhuma. Se o seu desenho previa “se der timeout, consulta o SPI e responde ao app”, esse desenho não é implementável. A consulta é um segundo fluxo assíncrono, e o cliente vai precisar ser notificado depois.

Os quatro recursos, em ordem de uso

1. Esperar a reentrega. Antes de qualquer coisa, lembre que o canal reentrega mensagem não confirmada. Uma fatia relevante dos “sumiços” é, na verdade, consumidor que confirmou a leitura e falhou ao processar depois — o arranjo cumpriu a parte dele, você é que perdeu a mensagem. Confirmar leitura antes de persistir o fato é um dos bugs mais caros e mais comuns dessa integração.

2. Consultar o lançamento via camt.060, com resposta em camt.054. É a consulta cirúrgica, para uma transação específica.

3. Varrer a relação de lançamentos via camt.060 → camt.052 → download do arquivo. É a varredura em lote, base da conciliação transacional. É aqui que você descobre transações que existem no SPI e não existem na sua base — as órfãs, que a consulta cirúrgica jamais encontraria, porque você não sabe que elas existem para perguntar por elas.

4. O SPB-Web, módulo SPI. Interface humana, com autenticação de segundo fator e consultas tarifadas conforme a tabela de serviços do Sisbacen. Não serve ao seu microsserviço — serve ao analista de plantão às 3h da manhã. Mas precisa estar no runbook, com acesso provisionado antes do incidente, e não durante.

O que isso significa em desenho de serviço

Junte as peças e o formato aparece sozinho: a reconciliação não é um retry dentro do serviço de pagamento. É um serviço próprio, com responsabilidade única, que:

• consome transações que entraram em estado indeterminado e envelheceram além do limite do arranjo;

• emite camt.060 respeitando o custo e o volume dessas consultas — consulta não é grátis, nem em tarifa nem em capacidade;

• correlaciona a resposta assíncrona de volta ao identificador fim a fim original — o que exige guardar a correlação entre a sua requisição e a transação investigada, porque a resposta vai chegar desacoplada;

• emite um evento de resolução que reabre a máquina de estados naquele ponto exato;

• e expõe como métrica de negócio a quantidade e a idade das transações não resolvidas.

Quem tenta encaixar isso dentro do serviço que processa pagamento acaba com um componente que faz duas coisas com perfis de latência, criticidade e escala incompatíveis. Separar não é purismo de arquitetura — é a única forma de a reconciliação não competir por recurso com o caminho crítico justamente no pior momento, que é quando as duas coisas acontecem juntas.

Pense comigo: se o seu código não respeita isso…

Há uma regra de dimensionamento que decorre de tudo isso e que quase nenhum time aplica conscientemente: os seus timeouts internos precisam ser menores que os do arranjo, nunca maiores.

Se o seu circuit breaker abre depois do timeout do SPI, ele nunca protege nada — só te informa de um desastre que já aconteceu. Se o timeout do seu cliente HTTP interno é maior que o do arranjo, você segura threads esperando resposta de uma operação que o SPI já abortou. Em horário de pico, isso não degrada um serviço: derruba o pool de conexões e leva junto tudo o que compartilha aquele recurso.

Timeout, aqui, não é configuração de infraestrutura. É decisão de arquitetura derivada de norma.

O outro lado do balcão: onde fica a fronteira do irreversível

Trocamos de cadeira. Agora a mensagem chega até você.

Existe uma pergunta que aparece em toda discussão de arquitetura de Pix recebido, e que eu quero desarmar logo de início, porque ela está mal formulada: “a gente credita o cliente antes ou depois de responder ao SPI?”

Parece um dilema aberto, com dois lados defensáveis. Não é. O arranjo já respondeu essa pergunta por você, e quem trata isso como escolha livre normalmente está prestes a descobrir o motivo da forma cara.

Por que a ordem não é negociável

O PSP recebedor tem duas obrigações simultâneas: disponibilizar os recursos ao usuário e responder ao arranjo. A segunda é medida. O Manual de Tempos do Pix estabelece indicadores apurados por percentil, com apuração obrigatória por todos os participantes — diretos e indiretos —, e esses indicadores compõem o Índice Geral de ANS. A ordem de grandeza dos tempos é de poucos segundos: só para ilustrar o padrão de rigor, no ciclo de autorização do Pix Automático há indicador apurado a percentil de 95% com limite de três segundos.

Some a isso o índice mínimo de disponibilidade de 99,9% previsto no arcabouço da Resolução BCB nº 195, e o quadro fica claro: o seu compromisso com a rede é medido em segundos, na cauda da distribuição, e auditado.

Agora responda honestamente: o seu core bancário consegue creditar uma conta dentro desse orçamento de tempo, no percentil 99, às 20h de uma sexta-feira, durante um pico de volume, com o motor antifraude no caminho?

Se a resposta é “quase sempre”, você acabou de amarrar um compromisso regulatório medido por percentil à parte mais lenta e mais compartilhada da sua infraestrutura. E percentil não perdoa “quase sempre” — percentil é exatamente a métrica desenhada para capturar o “quase”.

O que o mercado convergiu a fazer

O padrão dominante entre bancos e provedores de BaaS não é um meio-termo diplomático. É este, e é bem definido:

1. Validação síncrona, rápida e determinística. A conta existe? Está apta a receber? Está bloqueada? O tipo de conta aceita aquela operação? As regras de antifraude que precisam ser síncronas passaram? É daqui que saem as rejeições legítimas, com o código de motivo específico que discutimos no anteriormente.

2. Aceite ao arranjo assim que a validação passa. Esse é o ponto de não retorno.

3. Crédito ao cliente como consequência garantida, disparado por mecanismo durável — outbox, fila com garantia de entrega, o que a sua stack oferecer — e não dentro do mesmo bloco transacional que processa a mensagem do arranjo.

Repare no que isso significa: entre o aceite e o crédito efetivo existe uma janela, curta mas real, em que a rede já considera o dinheiro entregue e o seu cliente ainda não o vê. Essa janela não é um defeito da implementação. É o preço estrutural de cumprir um SLA externo com um recurso interno mais lento — e todo participante do Pix paga esse preço, saiba ele disso ou não.

A pergunta certa, então, é outra

Se a ordem já está definida, o que sobra para você decidir? Sobra a única coisa que ainda importa: o que precisa estar verificado antes do aceite.

Vamos com um exemplo bem simples. Duas coisas que o seu sistema faz quando um Pix chega:

• verificar se a conta do destinatário existe;

• enviar a notificação no celular dele.

A primeira pode dizer “não”. Se a conta não existe, a operação não acontece. A segunda nunca diz “não” — ela só executa. Se a notificação falhar, o dinheiro entrou do mesmo jeito.

É essa a diferença que organiza o fluxo inteiro:

O que pode recusar vem antes do aceite. O que apenas executa vem depois.

O motivo é direto: aceitar é prometer. No instante em que você responde “aceito” ao arranjo, você assumiu uma dívida com o cliente. Tudo que você deixou para depois desse momento, você já prometeu — e não tem mais como voltar atrás.

Colocar uma regra que pode recusar depois do aceite cria uma situação sem saída. Você já disse sim para a rede e vai precisar dizer não para o cliente. A única forma de sair disso é devolver o dinheiro.

Na prática: o que fica de cada lado

Antes do aceite ficam as verificações que podem recusar. Elas precisam ser rápidas e ter resposta certa:

• a conta existe e está ativa;

• a conta não está bloqueada — por decisão judicial, administrativa ou cautelar;

• o tipo de conta aceita aquela operação;

• a operação não estoura limite cadastral ou regulatório do titular;

• as checagens de conformidade que não podem esperar, como listas restritivas.

Repare que os códigos de rejeição do padrão separam “conta encerrada” de “conta bloqueada”. Não é preciosismo: são situações diferentes, e o cliente do outro lado precisa ouvir coisas diferentes.

Depois do aceite fica tudo que é consequência do dinheiro que já entrou:

• notificação ao usuário;

• categorização do lançamento;

• atualização de extrato e das telas de saldo;

• contabilidade analítica;

• programa de pontos, atualização de limites, esteiras de análise.

Nenhuma dessas etapas pode recusar a operação. Se alguma delas puder, ela está no lado errado — e o seu sistema tem um problema esperando o dia certo para aparecer.

O teste de uma pergunta

Para cada regra do seu fluxo, pergunte:

“Se essa verificação falhar depois que eu já aceitei, o que eu faço?”

Se a única resposta for “devolver o dinheiro”, ela precisa ser síncrona. Ponto.

A devolução existe e é legítima. Mas ela é um mecanismo de exceção. Usar devolução como rotina, para compensar uma decisão de arquitetura, é transformar exceção em processo — e isso sempre cobra a conta quando o volume cresce.

É exatamente por isso que o antifraude síncrono é o assunto mais espinhoso desse fluxo. Ele é, por definição, uma regra que pode recusar. Ou ele cabe no tempo disponível, ou precisa ser redesenhado para atuar em outro momento, com outro mecanismo. Não existe uma terceira opção confortável.

O espelho do outro lado: o que fazer com o saldo de quem paga

Agora gire a cadeira de volta. A mesma lógica existe do lado de quem envia — só que ali tem uma complicação a mais: o dinheiro está saindo da conta de alguém antes de existir qualquer certeza.

Voltemos ao João, que quer mandar R$ 380. Ele tem saldo, e você já validou tudo. A pergunta é: o que você faz com esses R$ 380 no momento em que envia a ordem?

Existem três respostas possíveis, e duas delas dão errado.

Opção 1: não mexer no saldo agora

Você envia a ordem e deixa o saldo do João intacto até a confirmação chegar.

Problema: nos próximos segundos, nada impede que ele pague uma conta, faça outro Pix ou passe o cartão. Quando a confirmação chegar, o dinheiro pode não estar mais lá. Você mandou ao arranjo uma ordem sem lastro.

Opção 2: debitar de vez

Você tira os R$ 380 da conta, como pagamento efetuado, e envia.

Problema: se a operação for recusada, você precisa fazer um estorno. Estorno é um novo lançamento contábil, com rastro, com possibilidade de falha e com custo operacional. Agora multiplique isso pelo número de rejeições legítimas que uma instituição recebe por dia.

Opção 3: reservar o saldo — e é essa que funciona

Os R$ 380 saem da disponibilidade do João, mas ainda não viram pagamento. Ficam numa posição intermediária: ele não pode gastar, e você não contabilizou nada.

Depois, uma de duas coisas acontece:

• chegou a confirmação → a reserva vira pagamento efetivado;

• chegou a recusa → a reserva é liberada e o saldo volta a ficar disponível.

Simples assim. E o ponto elegante: na recusa não existe estorno. Não há lançamento de compensação, não há dinheiro que circulou e voltou. Contabilmente, aquele valor nunca chegou a sair da conta.

Três cuidados com a reserva

1. Reservar e registrar precisam acontecer juntos. Mesma transação de banco, mesma unidade de trabalho. Se você reserva e não registra, cria saldo preso sem dono. Se você registra e não reserva, envia ordem sem lastro. Os dois acontecem em produção; o segundo custa dinheiro.

2. A reserva vem antes do envio. A ordem correta é: validar, reservar, gravar a intenção com o identificador fim a fim, e só então enviar. Qualquer inversão abre uma janela em que o arranjo conhece uma operação que o seu sistema ainda não conhece.

3. Toda reserva tem dono e idade. Ela pertence a uma transação identificável e tem um relógio rodando. Reserva órfã, sem transação correspondente, é dinheiro do cliente preso por um bug silencioso. É um dos achados mais constrangedores que uma conciliação pode produzir.

Quando a recusa chega, a reserva se paga

A instituição do outro lado respondeu: conta encerrada, conta bloqueada, tipo de conta incompatível, agente indisponível. O que você faz?

Libera a reserva. Só isso.

E note uma coisa: a recusa é o melhor tipo de falha que existe. É informação clara, chegando em tempo, permitindo uma decisão certa. É o cenário que você quer.

Aqui aquela classificação de códigos de rejeição mostra o valor. “Essa conta não existe mais, confira os dados” é uma mensagem que o cliente consegue agir. “Erro ao processar” não é.

E quando não chega resposta nenhuma?

Este é o momento em que a reserva deixa de ser boa prática e vira proteção contra prejuízo.

Voltamos ao estado indeterminado. A tentação natural é liberar a reserva, afinal “não deu certo”. Não libere.

Enquanto você não souber se houve liquidação, aquele valor precisa continuar indisponível. A conta é simples:

• cliente com saldo bloqueado por alguns minutos → uma reclamação;

• cliente com saldo liberado numa transação que liquidou → prejuízo direto, sem contrapartida.

Daí sai uma regra que vale levar escrita para o refinamento:

Reserva só é liberada por recusa explícita ou por reconciliação conclusiva. Nunca por timeout. Nunca por decisão local. Nunca por rotina de limpeza.

Aliás, “job que limpa reservas antigas” é uma das rotinas mais perigosas que existem em sistema de pagamento. Ela parece higiene. É vazamento.

O saldo que quase ninguém verifica

Um último detalhe, que pega até gente experiente: existem dois saldos nessa história, não um.

Um é o saldo do João, no seu core bancário. O outro é o saldo da sua instituição na conta que ela mantém no Banco Central — e é de lá que a liquidação sai de fato.

São sistemas diferentes, áreas diferentes, controles diferentes. O João pode ter saldo de sobra e a operação ser recusada assim mesmo, porque o dinheiro que faltou não era o dele.

Esse assunto é grande o suficiente para merecer um texto próprio, e é um dos que ficaram para a sequência. Por ora, guarde a consequência prática: quando o seu Pix começar a recusar em massa sem que nada tenha mudado no seu código, esse é o segundo lugar para olhar.

E no BaaS, a assimetria é ainda mais forte

Vale um parágrafo específico, porque é onde mora o mal-entendido mais comum do mercado.

Quando você é cliente de um BaaS, o participante do arranjo é o provedor, não você. Quem valida, quem aceita e quem responde ao SPI é ele. O crédito na conta do seu cliente final acontece depois, por outro trilho, sob a sua responsabilidade contratual.

Consequência prática que derruba fintech: o webhook de Pix recebido não é uma solicitação de autorização. É a notificação de um fato já consumado por outra instituição. Não existe “recusar no webhook”. Times que desenham o fluxo assumindo que podem barrar um recebimento naquele ponto descobrem, geralmente em produção, que a decisão foi tomada em uma camada à qual eles não têm acesso.

Isso não é limitação do provedor — é o desenho do arranjo. E é mais um caso em que a camada de tradução entre o vocabulário do Pix e o vocabulário do seu domínio esconde uma diferença semântica profunda por trás de um JSON de aparência inofensiva.

Pense comigo: se o seu código não respeita isso…

Cenário concreto, e eu recomendo levá-lo tal e qual para o próximo refinamento:

O aceite foi enviado ao SPI. O crédito foi enfileirado. O core bancário fica indisponível por vinte minutos.

O que o seu sistema faz?

• Se a resposta é “a fila segura e reprocessa quando o core voltar” — ótimo, é exatamente para isso que ela existe. Mas confirme: a mensagem foi persistida antes da confirmação de leitura no canal? Ou você confirmou primeiro e perdeu o fato?

• Se a resposta é “as retentativas estouram e a mensagem vai para a fila de erro” — você tem um passivo silencioso. Alguém aceitou dinheiro em nome do cliente e o cliente nunca o recebeu. Isso não gera alarme, não gera exceção, não aparece em nenhum dashboard de erro. Só aparece na conciliação.

• Se a resposta é “não sei” — essa é a resposta mais comum e a mais honesta, e ela vale um item de backlog hoje.

A pergunta operacional que fecha o bloco: quem, no seu sistema, é o dono da decisão de crédito? Se o crédito acontece dentro do mesmo bloco que processa a mensagem do arranjo, sem separação, você amarrou o seu compromisso com o Bacen à disponibilidade do seu core. Um lock em tabela de saldo, uma indisponibilidade momentânea, um deploy mal cronometrado — e o que era problema interno vira descumprimento de indicador perante o arranjo.

Aceitar é irreversível. Creditar é garantido. São duas afirmações diferentes, e o seu código precisa saber disso.

A verdade mora no extrato, não na sua base

Chegamos à afirmação mais desconfortável do artigo, e a que dá título à tese:

O seu banco de dados não é a fonte da verdade sobre o dinheiro. A Conta PI, no SPI, é.

O seu banco de dados é uma réplica local, eventualmente consistente, de um estado que vive no Banco Central. Toda a engenharia de um participante do Pix é, no fundo, um exercício contínuo de convergência entre essas duas visões.

É por isso que o arranjo oferece mensagens específicas para isso: consulta de saldo da Conta PI e detalhamento de lançamentos via a família camt. Elas não são acessório. São o instrumento pelo qual você descobre o que realmente aconteceu.

Duas conciliações, não uma

Times maduros mantêm duas, e elas falham por motivos diferentes:

• Conciliação transacional: cada identificador fim a fim que existe do meu lado existe do lado do SPI, com o mesmo desfecho? Detecta transação órfã, estado divergente, mensagem perdida. É o que resolve o caso do cliente.

• Conciliação contábil: o saldo da minha Conta PI bate com o meu razão interno? Detecta erro sistêmico, lançamento duplicado, valor divergente. É o que resolve o problema do balanço.

A primeira pode estar perfeita e a segunda quebrada — basta um lançamento interno com valor errado numa transação que existe corretamente dos dois lados. E a segunda pode fechar com a primeira furada, se dois erros se compensarem. Quem roda só uma delas dorme tranquilo por motivo errado.

Pense comigo: se o seu código não respeita isso…

Se a conciliação no seu sistema é um script que alguém roda quando o financeiro reclama, ela não é conciliação — é arqueologia.

Conciliação em sistema de pagamento instantâneo precisa ser cidadã de primeira classe: rodando continuamente, com métrica de divergência exposta, com alerta quando o número de transações indeterminadas cresce acima da linha de base. A divergência entre o seu estado e o do SPI é, ela própria, um golden signal — e provavelmente o mais importante que o seu produto tem.

O teste ácido: se o SPI e a sua base discordarem agora, em quanto tempo você fica sabendo? Se a resposta for “quando o cliente ligar”, você tem um problema de arquitetura, não de suporte.

O que levar para o refinamento de amanhã

Vamos amarrar o raciocínio.

O Pix não é difícil por causa do certificado digital ou da assinatura. Isso é trabalho, e trabalho conhecido — qualquer time competente resolve em algumas sprints. O Pix é difícil por um motivo bem menos glamouroso e muito mais estrutural:

Ele é um sistema distribuído de altíssima criticidade, com entrega at-least-once, sem transação distribuída, sem rollback, com a fonte da verdade fora do seu domínio e com o estado do mundo chegando até você por mensagens que podem atrasar, duplicar ou não chegar.

Nenhuma dessas propriedades é acidental. Todas estão na especificação, e cada uma tem consequência direta no seu código.

O fio que costura tudo

Vamos revistar o que já conversamos:

• Não existe resposta síncrona — logo, o seu modelo precisa representar espera.

• Só existem três pacs, e nenhuma delas cancela nada — logo, o seu modelo precisa representar compensação, não desfazimento.

• Erro tem naturezas diferentes, incluindo erro que não encerra a transação — logo, o seu modelo precisa representar mais do que sucesso e falha.

• A resposta pode não vir, e a consulta também é assíncrona — logo, o seu modelo precisa representar o “eu não sei” como estado legítimo, e resolvê-lo em outro fluxo.

• Aceitar e creditar são compromissos distintos — logo, o seu modelo precisa representar a fronteira entre o que é irreversível e o que é apenas garantido.

• A verdade mora na Conta PI, não na sua base — logo, o seu modelo precisa representar a possibilidade de estar errado, e um processo contínuo que o corrija.

Um campo status não carrega. Ele não tem onde guardar “não sei”, não tem onde guardar “por qual mensagem”, não tem onde guardar “quando”, e não sobrevive à próxima norma que acrescentar um estado.

E vai acrescentar. Esse é o ponto que fecha o argumento: este é um domínio que evolui por norma externa, em cadência que você não controla. A agenda regulatória dos próximos anos vai continuar inserindo estados no ciclo de vida da sua transação, e a pergunta que decide o custo disso não é “quanto código vou escrever?”, e sim “acrescentar um estado no meu sistema é uma tarefa de meio dia ou um projeto de um trimestre?”.

Máquina de estados explícita, com transições declaradas e registradas, é o que mantém essa resposta em “meio dia”. Dezenove if espalhados por doze classes é o que a transforma em trimestre.

A jornada invisível — e por que alguém vai pedir para vê-la

Existe um argumento a favor da máquina de estados que raramente aparece em discussão técnica, porque ele não é sobre código. É sobre prova.

Pense no que o usuário final enxerga de uma transferência: uma tela dizendo “enviando” e outra dizendo “concluído”. Duas telas. Entre elas, aconteceram oito, dez, doze fatos distintos — validação, reserva de saldo, envio ao arranjo, liquidação, notificação, crédito, confirmação — cada um em um instante diferente, cada um podendo falhar por um motivo diferente.

Essa é a jornada invisível. Ela existe quer você a registre ou não. A única diferença é se ela fica recuperável depois.

Três pessoas vão bater na sua porta pedindo essa linha do tempo

O atendimento, hoje. O cliente ligou perguntando do dinheiro dele. A pergunta do atendente não é “deu erro?” — é “o que eu digo para ele agora?”. E a resposta correta depende inteiramente de onde a transação parou: “já saiu e o outro banco está processando” é uma conversa completamente diferente de “não chegamos a enviar”. Com um campo status = 'PENDENTE', as duas situações são indistinguíveis, e o atendente é obrigado a improvisar. Improviso em conversa sobre dinheiro do cliente é como se produz reclamação em ouvidoria.

O engenheiro, no incidente. Duzentas transações travadas. A pergunta útil não é “quantas falharam?”, é “todas elas pararam no mesmo ponto?”. Se pararam, você tem uma causa comum e uma correção. Se estão espalhadas por estados diferentes, você tem outro problema, provavelmente mais grave. Sem transições registradas, essa distinção — que é a diferença entre resolver em vinte minutos e resolver em seis horas — simplesmente não é obtível.

O auditor, meses depois. E esse é o mais implacável dos três, porque ele não aceita “acho que”.

Auditoria: o ônus da prova é seu

Em sistema financeiro regulado, a assimetria é essa: ausência de registro não é interpretada como ausência de problema, é interpretada contra você. “Não temos esse dado” e “fizemos errado” produzem, na prática, o mesmo desfecho.

E a demanda por essa prova não é hipotética. Ela é rotina do arranjo:

• Uma contestação via mecanismo de devolução exige demonstrar o que foi feito e quando — e, com o MED em sua versão atual, com prazos e etapas que são eles próprios medidos.

• Os indicadores do Manual de Tempos são apurados pelo participante e reportados. Você não é medido pelo que acha que levou: você é medido pelo que registrou. Sem marcação de tempo confiável em cada etapa, você não tem sequer como calcular o próprio indicador — muito menos defendê-lo.

• Uma apuração de fraude vai reconstituir o trajeto de um valor. A sua parte dessa reconstituição é a sua linha do tempo.

Há um detalhe técnico aqui que o próprio Manual de Tempos explicita e que vale internalizar: a diferença entre um instante medido de um lado e o seu espelho medido do outro decorre tanto dos relógios distintos dos dois agentes quanto da solução tecnológica adotada na comunicação, que determina os pontos de aferição. Traduzindo: o relógio do arranjo e o seu relógio não são o mesmo relógio, e a divergência entre eles é esperada e mensurável.

Daí a recomendação de guardar as duas marcações de tempo em cada transição — a do arranjo e a local. Uma serve para reconstruir a verdade externa; a outra, para reconstruir a sua. Quando divergirem, e vão divergir, você quer estar com as duas na mão, e não descobrindo naquele momento que só guardou uma.

A analogia

Máquina de estados com transições registradas é o prontuário médico da transação. Ninguém apaga uma entrada do prontuário porque o diagnóstico mudou — acrescenta-se uma nova entrada, datada, assinada, e a sequência inteira permanece legível. É essa sequência que permite a outro profissional, meses depois, entender o que foi feito e por quê.

O campo status sobrescrito é o oposto disso: é um prontuário com uma linha só, sempre atualizada, sempre no presente, sem memória. Serve para saber o estado atual do paciente. Não serve para absolutamente mais nada.

O bônus que ninguém pede e todo mundo usa

E há um efeito colateral generoso: uma vez que as transições existem como fatos datados, você ganha de graça o que teria custado caro construir depois. A contagem de transações em cada estado vira funil de negócio. A idade média em cada estado vira alerta operacional. O crescimento da fila de indeterminadas vira o golden signal de que falamos anteriormente. A taxa de rejeição por código vira o termômetro da saúde da sua integração.

Nada disso precisa ser instrumentado separadamente. Tudo isso já está no log de transições, esperando alguém consultar. É a mesma estrutura respondendo, simultaneamente, ao suporte, ao plantão, ao produto e ao regulador — e essa é, no fim, a melhor defesa que existe para o custo de implementá-la direito.

Deixe um comentário

O checklist

O que eu levaria para o próximo refinamento, na ordem em que eu levaria:

• Log de transições de estado, não campo status mutável. Cada transição guarda estado anterior, estado novo, a mensagem que a causou e as duas marcações de tempo — a do arranjo e a local. Os relógios são diferentes por natureza; guardar só um deles é abrir mão da metade da prova.

• Identificador fim a fim gerado e persistido antes do envio, usado como chave de idempotência com o arranjo — nunca o seu ID interno.

• Política de retentativa consciente da janela de 24 horas estabelecida pelo Catálogo. Dentro dela, reapresentar é seguro; fora dela, é pagamento novo.

• Consumidor idempotente por padrão. Reentrega de mensagem é comportamento previsto do canal, não anomalia.

• Confirmar leitura só depois de persistir o fato, nunca antes. Esse é o bug mais barato de evitar e o mais caro de descobrir.

• Timeout interno estritamente menor que o do arranjo. Circuit breaker que abre depois do SPI não protege nada.

• Códigos de rejeição classificados por natureza de tratamento — negócio definitivo, infraestrutura de terceiro, timeout, não terminativo — e nunca achatados em um else.

• Estado indeterminado explícito no modelo, resolvido por consulta à Conta PI e jamais por suposição.

• Reserva de saldo atômica com o registro da intenção, liberada apenas por rejeição explícita ou reconciliação conclusiva — nunca por timeout e nunca por job de limpeza.

• Reconciliador como serviço próprio, assíncrono, com correlação entre a requisição e a transação investigada.

• Fronteira do aceite documentada: tudo que pode gerar recusa é síncrono; tudo que é execução é assíncrono e garantido.

• Dupla conciliação — transacional e contábil — como processo contínuo, com a divergência exposta como métrica de negócio.

Fica para a próxima

Ficaram de fora três assuntos que merecem artigo próprio, e que são a continuação natural deste: a gestão de liquidez da Conta PI — o incidente de Pix que não tem uma linha de código quebrada; os indicadores do Manual de Tempos e o que muda quando você é medido por percentil e não por média; e o MED 2.0, que acrescentou à máquina de estados um caso que quase ninguém modelou: recurso liquidado, creditado e indisponível.

Se este texto foi útil, esses três vêm na sequência. Fico por aqui neste artigo! Até o próximo!

Fontes primárias para quem quiser se aprofundar: Catálogo de Serviços do SFN — Volume VI (Pagamentos Instantâneos); Manual das Interfaces de Comunicação; Manual de Tempos do Pix; Guia de Implementação do Canal Secundário de Transmissão de Mensagens; Roteiro para Participação Direta no SPI e Abertura de Conta PI; e os Informes SPI publicados pelo Banco Central. Os valores numéricos de timeout e os indicadores de tempo são revisados periodicamente — confira sempre a versão vigente antes de implementar.

Pra quem usa, é um toque e pronto. Pra quem constrói, é conciliar um protocolo de liquidação em tempo real, irrevogável, regulado pelo Banco Central, com um núcleo bancário que muitas vezes ainda pensa em lote, em ledger contábil, e às vezes nem tem autonomia total sobre a própria arquitetura. Este artigo é sobre o tradutor que existe entre esses dois mundos — e por que ele não é opcional.

Existem dois países vizinhos. Um é jovem, fala uma língua nova, padronizada, criada em comitê, com gramática rígida e sem exceções — tudo precisa ser dito de um jeito específico, ou a mensagem simplesmente não é aceita na fronteira. O outro é antigo, tem séculos de tratados, dialetos regionais, expressões que só fazem sentido se você souber a história por trás delas. Os dois precisam negociar dinheiro entre si, todos os dias, milhões de vezes por dia, em menos de dez segundos por negociação. Essa é a situação de qualquer banco que precisa fazer o Pix conversar com o seu core bancário.

Pix parece simples — até você olhar por trás do app

Em termos simples

Pra entender o Pix, primeiro lembre da TED

Se você tem mais de trinta anos, provavelmente já viveu isso: precisar mandar dinheiro pra alguém numa sexta-feira à tarde e torcer para o relógio cooperar. Antes do Pix existir, a TED — Transferência Eletrônica Disponível, criada em 2002 — era basicamente a única forma de mandar dinheiro entre bancos diferentes de forma eletrônica. E a TED, para quem não lembra mais ou nunca precisou lidar com ela, tinha um detalhe brutal: ela tinha hora para fechar.

Feita até por volta das 17h (no horário de Brasília, variando um pouco por instituição), o dinheiro chegava no mesmo dia útil — às vezes em minutos, às vezes em algumas horas. Passou desse horário, mesmo que fosse 17h01? A transferência ficava “engavetada” até o próximo dia útil. Numa sexta à tarde, isso significava esperar até segunda-feira. Um profissional autônomo que recebia o pagamento de um cliente numa sexta de manhã, mas cujo cliente só conseguia fazer a transferência à noite, simplesmente não via aquele dinheiro até a semana seguinte — mesmo o dinheiro já “existindo”, já tendo saído da conta de alguém.

Por que errar uma letra desfazia a transferência inteira

Tinha outro problema, tão irritante quanto o horário: para fazer uma TED, era preciso informar banco, agência, conta e CPF ou CNPJ do destinatário — e, em muitos casos, o nome precisava bater exatamente com o que o banco de destino tinha cadastrado. Não existia nenhum tipo de “atalho”: nenhuma chave curta, nenhum QR code, nenhum diretório central que resolvesse quem era quem. Bastava errar um dígito da agência, ou digitar o nome com uma abreviação diferente da que o banco de destino esperava, para a transferência ser recusada e devolvida — e o processo inteiro precisava recomeçar do zero, muitas vezes horas depois, arriscando cair fora da janela das 17h de novo.

A tecnologia por trás da TED — e por que ela tinha hora pra fechar

A TED era processada pelo STR — Sistema de Transferência de Reservas, a infraestrutura de liquidação do próprio Banco Central — ou, para valores menores, pela infraestrutura da CIP (Câmara Interbancária de Pagamentos), através de um sistema chamado SITRAF. O detalhe importante aqui: tanto o STR quanto o SITRAF foram desenhados para operar dentro de uma janela de expediente bancário — o SITRAF, por exemplo, funcionava historicamente só entre 6h30 e 17h, em dias úteis. Não é que o dinheiro “demorasse” tecnicamente para se mover; é que a própria infraestrutura de liquidação por trás da TED só ficava de portas abertas durante o horário comercial, replicando no sistema bancário eletrônico a mesma lógica de uma agência física que fecha as portas às 16h.

Ou seja: o problema nunca foi a internet ser lenta. Era a arquitetura de liquidação ter sido desenhada, décadas atrás, em torno do conceito de “expediente bancário” — um conceito que fazia todo sentido quando transferências eram físicas, feitas na boca do caixa, e que continuou entalado dentro da infraestrutura eletrônica muito depois de deixar de fazer sentido para o usuário final.

O que o Pix realmente resolveu

Comparar Pix com TED só como “ficou mais rápido” subestima o tamanho da mudança. O Pix resolveu os dois problemas na raiz, não na superfície: o DICT eliminou a necessidade de decorar banco, agência, conta e nome exato — uma chave (CPF, e-mail, telefone ou chave aleatória) resolve tudo isso automaticamente, direto no diretório do Banco Central, o que também elimina boa parte do erro humano que devolvia TEDs. E o SPI foi desenhado, desde o primeiro dia, para não ter janela de expediente — opera de fato 24 horas, 365 dias por ano, sem “fechar às 17h” e sem pausar no fim de semana ou feriado. Não é a mesma infraestrutura da TED, otimizada. É uma infraestrutura nova, desenhada para um pressuposto que a TED nunca teve: dinheiro não deveria ter horário de expediente.

Vale registrar também que o Pix não parou de evoluir depois do lançamento: o Pix Saque e o Pix Troco, criados posteriormente, levaram esse mesmo raciocínio para o dinheiro físico — permitindo sacar espécie em casas lotéricas, padarias e supermercados usando o mesmo protocolo. É mais uma pista de que o Pix não é uma funcionalidade fechada e estática; é uma plataforma regulatória em expansão constante — o que, como vamos ver mais adiante, é parte do motivo pelo qual conectar um core bancário a ela não pode ser um projeto “de uma vez só”.

Por trás do toque no app de hoje existe um protocolo de liquidação regulado pelo Banco Central — o SPI — operando em modelo RTGS (liquidação bruta em tempo real): cada transação é processada individualmente, de forma definitiva e irrevogável, 24 horas por dia, 365 dias por ano. Existe o DICT, o diretório que resolve uma chave Pix na conta de destino. Existe o ICOM, a interface pela qual as mensagens trafegam — em XML, seguindo o padrão internacional ISO 20022. E existe, do outro lado dessa cadeia inteira, o núcleo bancário — o sistema que efetivamente debita e credita a conta do cliente, sustenta o histórico, gera o extrato, e responde por cada centavo perante o regulador.

O problema é que esse núcleo, na maioria dos bancos, não nasceu pensando em nada disso. Nasceu pensando em lançamento contábil, em fechamento de expediente, em lote processado à noite — na mesma lógica de janela de operação que limitava a TED. É a colisão entre um protocolo desenhado do zero para o tempo real e um sistema que carrega décadas de decisões pensadas para um mundo que fechava às 16h.

🧠 Exercício de raciocínio

Antes de continuar, responda mentalmente duas coisas: primeiro, por que uma infraestrutura de liquidação (STR/SITRAF) precisaria ter “horário de expediente” se o dinheiro em si é só um registro eletrônico, sem nenhuma limitação física real? Segundo — e essa é a que vamos carregar pelo resto do artigo: quantos sistemas diferentes você imagina que uma única transação Pix atravessa hoje, entre o toque no app e o dinheiro efetivamente aparecer na conta do outro lado?

Sobre a primeira: o horário nunca foi uma limitação técnica real — era uma decisão de design herdada de um tempo em que “transferência” significava um funcionário de banco processando algo manualmente. Guarde sua resposta para a segunda pergunta — vamos revisitar ela no fechamento do artigo, depois de percorrer os dois idiomas envolvidos.

O que é, de fato, uma Anti-Corruption Layer

Em termos simples

Formalmente, uma Anti-Corruption Layer (ACL) é uma camada intermediária colocada entre dois Bounded Contexts — dois domínios com seus próprios modelos e linguagens — cuja função é traduzir o que atravessa essa fronteira, para que nenhum dos dois lados precise adotar os conceitos do outro dentro de casa. O nome não é acidental: “anti-corrupção” porque o papel dela é literalmente impedir que o modelo de domínio de um sistema seja corrompido — contaminado, distorcido — pelos conceitos e pela estrutura de dados do outro.

Repare que a definição não fala em “converter formato de dado” — fala em traduzir requisições entre dois mundos que não compartilham a mesma visão da realidade. Uma ACL entre Pix e core bank não troca só o nome de um campo; ela decide o que significa, dentro do vocabulário do core, um evento que nasceu com um significado específico no vocabulário do Banco Central.

🧠 Exercício de raciocínio

Pense num conceito do seu domínio atual — de qualquer sistema que você mantenha hoje — que, se fosse traduzido ao pé da letra pra outro sistema, mudaria de significado no caminho. Guarde esse exemplo: vamos usar esse tipo exato de armadilha no tópico, O que uma ACL faz exatamente, com um caso real do Pix.

De onde veio o conceito

A Anti-Corruption Layer não é invenção recente de arquiteto de fintech. Ela foi descrita formalmente por Eric Evans em 2003, no livro que fundou toda uma escola de pensamento em arquitetura de software: Domain-Driven Design: Tackling Complexity in the Heart of Software. Está na parte do livro dedicada a relações entre Bounded Contexts — ao lado de outras estratégias como Shared Kernel, Customer/Supplier, Conformist e Open Host Service, cada uma descrevendo um jeito diferente de dois domínios coexistirem.

O motivo de mencionar isso não é curiosidade histórica. É que Evans não propôs a ACL como a única opção — ele catalogou várias, cada uma adequada a uma relação de poder e confiança diferente entre os dois lados. Conformist, por exemplo, é quando um lado simplesmente aceita o modelo do outro sem tradução nenhuma — funciona quando você não tem escolha e o modelo externo é bom o suficiente para conviver com ele. A ACL é o oposto: você escolhe pagar o custo de traduzir porque não pode se dar ao luxo de deixar o modelo externo ditar as regras dentro de casa.

🧠 Exercício de raciocínio

Por que a relação Conformist — aceitar o modelo do Banco Central sem tradução nenhuma, direto dentro do core — não é uma opção segura para um banco, mesmo sendo tecnicamente mais barata de implementar?

Pense em quem regula o quê: o Banco Central pode mudar a especificação do Pix (e já mudou, várias vezes, com Pix Automático e Pix por Aproximação). O core do banco carrega obrigações contábeis e regulatórias que não nasceram do Pix e não podem depender do ritmo de mudança dele.

O que uma ACL faz exatamente

Tradução de modelo, não só de dado

Aqui está o caso real que prova por que “traduzir campo por campo” não é suficiente. O SPI opera em RTGS: toda liquidação é individual, definitiva e irrevogável. Isso tem uma implicação direta e pouco intuitiva — quando um Pix precisa ser devolvido, o sistema não desfaz a transação original. Ele cria uma transação nova, no sentido contrário. Devolução de Pix não é estorno; é um segundo pagamento.

Agora imagine um core bank cujo modelo contábil tradicional trata “devolução” como sinônimo de “estornar o lançamento original” — apagar ou reverter o que foi feito, como sempre se fez com outros meios de pagamento. Se a ACL simplesmente mapear o campo tipo_operação: devolução do Pix para tipo_lançamento: estorno do core, sem traduzir o conceito, o relatório de conciliação enviado ao Banco Central vai registrar dois lançamentos que deveriam ser positivos e distintos como se um deles nunca tivesse existido de verdade — e a conciliação regulatória simplesmente não bate.

É exatamente esse tipo de armadilha que a ACL existe para evitar: ela não troca o nome do campo, ela garante que o conceito “devolução Pix” chegue ao core como o que ele realmente é — um novo lançamento de crédito, não uma reversão — porque só assim o modelo contábil do banco continua correto.

“A camada anti-corrupção atua como mediadora, traduzindo e adaptando entre os dois sistemas — evitando que a complexidade de um vaze para dentro do outro.” - Paráfrase de Sam Newman, Monolith to Microservices (2019), sobre o uso da ACL na integração entre sistemas legados e novos serviços

🧠 Exercício de raciocínio

Se o core tratar uma devolução Pix como estorno contábil tradicional — desfazendo o lançamento original em vez de criar um novo — o que exatamente quebra no relatório de conciliação enviado ao Banco Central?

O volume total de transações reportado não bate com o volume real processado pelo SPI, porque uma operação que devia aparecer como dois lançamentos positivos (o Pix original + a devolução como novo pagamento) aparece como se o primeiro nunca tivesse acontecido.

Deixe um comentário

ACL não é Adapter

Em termos simples

✍️ Nota pessoal

Sendo sincero: essa diferença não foi óbvia pra mim da primeira vez que estudei DDD. Os dois nomes se pareciam demais, os dois “traduzem alguma coisa entre dois sistemas”, e por um bom tempo eu tratei os dois como sinônimos, só com nomes diferentes. Só entendi de verdade quando parei de pensar em “o que cada um faz” e comecei a pensar em “o que cada um protege” — e é esse o ângulo que eu quero te poupar de precisar descobrir sozinho, do jeito mais difícil, revisando código em produção.

É uma definição precisa, e propositalmente estreita: o Adapter resolve um problema de interface — assinatura de método, formato de chamada, tipo de dado esperado. É um padrão estrutural, quase sempre aplicado classe a classe, ou serviço a serviço, num escopo pequeno e bem definido. Ele responde uma pergunta simples: “esses dois pedaços de código conseguem trocar bytes entre si?”

A ACL opera em outro nível — mais alto, mais amplo, e por isso mais difícil de enxergar de primeira. Ela protege um Bounded Context inteiro: não só o formato do dado que entra, mas o que aquele dado significa depois que entra. Na prática, uma ACL quase sempre usa um ou mais Adapters por dentro — junto com Facades e Translators — mas a diferença que realmente importa não é técnica, é de propósito. Um Adapter garante que duas peças de software conseguem se falar. Uma ACL garante que essa conversa não distorce o significado do que está sendo dito.

O mesmo caso da devolução Pix, visto pelos dois padrões

Vale voltar ao exemplo do Tópico anterior para deixar a diferença concreta, não abstrata:

Só com Adapter

O código converte tipo_operação: devolução (Pix) em tipo_lançamento: estorno (core) sem erro nenhum. A chamada funciona, os tipos batem, os testes técnicos passam.

O problema: o Adapter não tem como saber que “devolução” e “estorno” significam coisas diferentes no mundo real — ele só sabe converter formato. A distorção de significado passa despercebida.

Com ACL

A camada reconhece que “devolução Pix” é um conceito de negócio específico — uma transação nova, nunca uma reversão — e traduz isso para o lançamento contábil correto: um crédito novo, não um estorno do lançamento original.

O resultado: o core recebe o conceito certo, a conciliação com o Banco Central bate, e ninguém precisa descobrir o erro três meses depois, numa auditoria.

Por que todo programador precisa saber diferenciar os dois

Não é purismo acadêmico de nomenclatura. A diferença muda três coisas concretas no seu dia a dia:

Primeiro, muda a falsa sensação de segurança. Se você constrói um Adapter e o chama de ACL, o código vai parecer perfeitamente saudável — compila, os testes passam, a chamada funciona. Mas o domínio não está protegido de verdade, porque ninguém traduziu o conceito, só o formato. É o mesmo tipo de bug silencioso que já vimos antes neste artigo: não gera erro, não gera exceção, só gera um dado errado que ninguém percebe até alguém comparar com a realidade.

Segundo, muda quem consegue revisar o código com segurança. Um Adapter pode ser revisado por qualquer pessoa que entenda as duas interfaces técnicas envolvidas. Uma ACL só pode ser revisada de verdade por alguém que entenda os dois domínios de negócio — nesse caso, tanto as regras do Pix quanto o modelo contábil do banco. Se sua revisão de código só valida “os tipos batem”, ela nunca vai pegar um erro de ACL.

Terceiro, muda o que você constrói quando o requisito parece simples. “Só precisamos traduzir esse campo” é, quase sempre, a frase que introduz um Adapter disfarçado de ACL — e o disfarce só é descoberto quando o conceito de um dos dois lados muda, e a tradução simplista, que nunca protegeu significado nenhum, desmorona silenciosamente.

🧠 Exercício de raciocínio

Se você trocar só a assinatura do método que chama o DICT — sem tocar em como “chave Pix” é modelada dentro do seu domínio de conta corrente — você resolveu um problema de Adapter ou de ACL? E se amanhã o conceito de “chave” mudar sutilmente pro Bacen (como já aconteceu com o Pix Automático, que introduziu recorrência), seu Adapter sozinho aguenta essa mudança sem vazar inconsistência pro resto do core?

Trocar a assinatura é Adapter. Mas o Adapter sozinho não tem onde guardar a decisão de “o que fazer quando o conceito muda” — essa decisão precisa morar na camada que entende o domínio dos dois lados, que é exatamente o papel da ACL.

Deixe um comentário

O idioma do Core Bank: contas, ledgers e o peso da história

Em termos simples

Alguns termos valem explicação, porque sustentam o resto do raciocínio. Ledger é o livro-razão — o registro definitivo de todos os lançamentos financeiros de uma conta, seguindo o princípio de partida dobrada (todo débito tem uma contrapartida de crédito em algum lugar). Lançamento é cada entrada individual nesse livro. Tradicionalmente, bancos processam em lote (batch): uma janela específica da madrugada onde o dia é fechado, os saldos são consolidados, e o sistema — muitas vezes ainda rodando sobre mainframe, em COBOL — assume que não há mais nada acontecendo até o próximo expediente.

A realidade de 2026 é mais confusa do que esse retrato sugere. Plataformas modernas de core banking vêm substituindo sistemas monolíticos legados por arquiteturas de microsserviços, nuvem e mensageria em tempo real — mas essa transição é gradual, e a maioria dos bancos vive hoje num estágio intermediário: parte do core já modernizada, parte ainda presa ao modelo antigo. Para complicar, muitas instituições — especialmente fintechs e bancos menores — nem operam seu próprio core: dependem de provedores de BaaS (Banking as a Service), o que significa que nem sempre têm autonomia total para mudar a arquitetura por conta própria, mesmo quando sabem exatamente o que precisaria mudar.

O idioma do Pix: SPI, DICT, ISO 20022 e liquidação sem volta

Em termos simples

O SPI opera em modelo RTGS — Real-Time Gross Settlement: cada transação é liquidada individualmente, no momento em que acontece, sem espera por lote nem compensação multilateral. Uma vez confirmada, a liquidação é definitiva e irrevogável — a infraestrutura do Banco Central não desfaz uma transação depois de liquidada. O DICT é o diretório que resolve uma chave Pix (CPF, e-mail, telefone, chave aleatória) na conta de destino, consultado antes de cada pagamento. E as mensagens entre participantes trafegam pela ICOM, seguindo o padrão internacional ISO 20022, em XML — o mesmo padrão usado por sistemas de pagamento em diversos países, o que abre a porta para interoperabilidade internacional no futuro.

A instituição que se conecta diretamente a essa infraestrutura — participante direto, o chamado “Pix Direto” — precisa cumprir requisitos técnicos rígidos de disponibilidade, latência e segurança. Não existe meio-termo: ou a mensagem está no formato certo, dentro do prazo certo, ou ela simplesmente não é aceita.

🧠 Exercício de raciocínio

O Bacen exige liquidação em menos de dez segundos, ponta a ponta. Se o seu core precisa de três segundos só para abrir uma transação tradicional de banco de dados relacional, quanto tempo sobra para todo o resto do fluxo — validação, DICT, ACL, resposta ao app?

Pouquíssimo — e é exatamente por isso que a integração não pode ser “chamar o core como se chama qualquer outra API interna”. A ACL, nesse contexto, também carrega a responsabilidade de decidir o que pode ser respondido de forma otimista ao SPI antes mesmo do core confirmar de verdade.

Onde a ACL entra: desacoplar, proteger e sobreviver às duas evoluções

A ACL senta exatamente na fronteira entre os dois idiomas descritos nos dois tópicos anteriores. Do lado do Pix, ela recebe eventos em ISO 20022, com semântica de liquidação irrevogável e restrições regulatórias específicas. Do lado do core, ela precisa entregar algo que o ledger entenda — um lançamento contábil coerente, respeitando partida dobrada, sem quebrar a lógica que o banco usa há anos. E o caminho inverso também existe: quando o core precisa responder algo ao Pix (confirmação, saldo, status), a ACL traduz de volta, sem expor os detalhes internos do ledger para fora dos muros do banco.

O ganho estratégico é que os dois lados passam a poder evoluir em velocidades diferentes, sem que uma mudança de um force uma reescrita imediata do outro. O Banco Central já mudou a especificação do Pix várias vezes desde 2020 — Pix Automático, Pix por Aproximação, Pix Parcelado — e cada mudança dessas bateria direto no core, sem aviso, se não existisse uma camada absorvendo o impacto. Do mesmo jeito, o banco pode modernizar seu core aos poucos — migrando de mainframe para microsserviços, por exemplo — sem que essa transição interna ponha em risco a conformidade regulatória do lado do Pix.

Antes de escrever a primeira linha: as perguntas que um arquiteto pragmático faz

Adicionar uma ACL não deveria ser reflexo automático só porque “é o padrão certo pra integração com sistema externo”. É uma decisão de investimento — toda ACL bem construída custa tempo de design, disciplina de manutenção, e mais um componente para alguém entender daqui a três anos. O arquiteto pragmático não pergunta “existe um padrão pra isso?” — pergunta se o problema específico que está na sua frente realmente exige essa proteção. Quatro perguntas ajudam a decidir com critério, não por reflexo:

1 · Quem é dono do modelo do outro lado?

O banco não escreve, não revisa e não vota na especificação do SPI, do DICT ou da ICOM — quem decide é o Banco Central, sozinho, e o banco só recebe a mudança quando ela já está definida.

Por quê isso importa: quando você não tem nenhuma influência sobre o modelo externo, aceitar esse modelo dentro de casa significa aceitar mudanças futuras que você nunca vai poder negociar. Isso é, sozinho, um sinal forte de que uma ACL vale o investimento.

2 · O que exatamente se perde se o conceito externo entrar sem tradução?

No caso do Pix, já vimos: tratar devolução como estorno quebra a conciliação regulatória. Esse é um custo real, mensurável, com consequência jurídica — não uma preferência estética de “código mais limpo”.

Por quê isso importa: se a resposta for “nada muito grave, só fica um pouco menos elegante”, talvez o problema não justifique uma ACL — só um Adapter simples já resolve, como vimos anteriormente.

3 · O ritmo de mudança dos dois lados é genuinamente diferente?

O Pix evolui no calendário regulatório do Banco Central. O core evolui no calendário de risco e investimento do banco. Nenhum dos dois espera o outro — cada mudança de um lado pode acontecer sem qualquer coordenação com o outro.

Por quê isso importa: quando dois sistemas mudam por razões diferentes, em ritmos diferentes, decididos por pessoas diferentes, é exatamente a definição de dois Bounded Contexts distintos que Evans descreveu — e é aí que uma fronteira explícita, traduzida, compensa o esforço de mantê-la.

4 · Existe irreversibilidade envolvida?

A liquidação Pix é definitiva. Não existe “desfazer” no protocolo — só uma nova operação no sentido contrário. Isso significa que um erro de tradução não é um bug que se corrige com um patch silencioso; ele já aconteceu no mundo real, com dinheiro de verdade, de forma irrevogável.

Reparar nessas quatro perguntas juntas explica por que, no caso específico do Pix, a resposta quase sempre aponta para o mesmo lugar: modelo controlado por terceiro regulador, custo real de tradução malfeita, ritmos de mudança desacoplados, e consequência irreversível em caso de erro. Não é o arquiteto “gostando” de DDD — é o próprio desenho técnico do sistema, com suas restrições de regulação e liquidação, empurrando a decisão nessa direção. É isso que significa dizer que o system design mostra a necessidade da camada: a decisão nasce das restrições reais do sistema, não de uma preferência de estilo de quem desenhou.

Quando você NÃO precisa de uma ACL

Em termos simples

Depois de um artigo inteiro argumentando a favor da ACL, é importante fechar com o contrapeso: nem toda integração externa precisa dela, e aplicar esse padrão por reflexo — “é boa prática, então uso sempre” — cria exatamente o tipo de complexidade acidental que a ACL deveria evitar, só que num lugar onde ninguém precisava dela.

1. Sinal de que talvez você não precise

   Os dois sistemas são mantidos pelo mesmo time, ou por times que se comunicam de perto e evoluem juntos por decisão consciente. Não existe fronteira real de propriedade — existe só uma separação técnica de deploy.

2. Sinal de que talvez você não precise

   O modelo externo já é bom o suficiente para conviver com ele sem tradução — é exatamente a relação que Evans chama de Conformist, mencionada no Tópico 3: você aceita o modelo do outro de propósito, porque traduzir custaria mais do que adotar.

3. Sinal de que talvez você não precise

   O erro de tradução, se acontecer, é barato de corrigir — um relatório interno que pode ser reprocessado, um dado que pode ser recalculado, nada com efeito jurídico ou financeiro irreversível.

4. Sinal de que talvez você não precise

   A integração é estreita e estável: um único endpoint, um formato que não muda há anos, sem sinal de que vai mudar. Nesse caso, um Adapter simples já resolve o problema todo — sem precisar de uma camada de proteção de domínio inteira por trás dele.

Um exemplo concreto, propositalmente mais simples que o resto do artigo: um banco constrói um painel interno, só para uso do próprio time de operações, que espelha alguns dados do Pix para fins de acompanhamento visual — sem escrever de volta em lugar nenhum, sem alimentar o ledger, sem nenhuma consequência regulatória se um campo estiver levemente desatualizado por alguns minutos. Nesse caso, um Adapter que converte o formato de resposta da API para o formato que o painel espera já é solução completa. Construir uma ACL inteira, com Facade, Translator e um modelo de domínio interno espelhando o do Pix, seria esforço de arquitetura para um problema que nunca teve o peso que justificasse esse esforço.

🧠 Exercício de raciocínio

Pense numa integração que você mantém hoje, ou já manteve, que tem uma camada de tradução “por precaução” — construída seguindo o padrão certo, mas que, olhando com honestidade, nunca precisou proteger nada de fato grave. Pelas quatro perguntas do Tópico 8, ela deveria continuar existindo do jeito que está, ou poderia ser simplificada para um Adapter comum?

Se a resposta genuína for “nunca vi essa camada realmente evitar um problema sério”, isso não é motivo de vergonha — é sinal de que o julgamento arquitetural na época pode ter pesado mais o padrão do que o risco real. Vale revisitar, não vale se cobrar por isso.

Voltando ao número que você guardou

Lá no inicio, pedi para você guardar um número — quantos sistemas uma única transação Pix atravessa entre o toque no app e o dinheiro chegar do outro lado. Depois de passar pelo SPI, pelo DICT, pela ICOM, pela ACL traduzindo nos dois sentidos, pelo core com seu ledger e sua partida dobrada, e frequentemente por camadas adicionais de prevenção a fraude e notificação — é provável que o número real seja maior do que o que você escreveu. A maioria das pessoas subestima, porque a experiência de dez segundos no app foi desenhada, de propósito, para esconder exatamente essa distância.

É esse o ponto central do artigo: Pix não é simples porque o problema é simples — é simples porque alguém, em algum lugar da arquitetura, está absorvendo toda a complexidade de duas línguas que não deveriam, por padrão, conseguir se entender. A Anti-Corruption Layer é essa peça. Não é burocracia arquitetural nem exagero de quem gosta de over-engineering — é a diferença entre um banco que sobrevive à próxima mudança regulatória do Pix sem reescrever o core, e um banco que descobre, na pior hora possível, que os dois mundos nunca estavam de fato traduzidos — só coincidentemente compatíveis, até deixarem de ser.

Duas línguas nunca vão virar uma só. O trabalho do arquiteto não é forçar essa fusão — é construir, e manter viva, a embaixada entre elas.

Guia rápido — os 8 pontos

• Simplicidade aparente: o app esconde SPI, DICT, ICOM e ISO 20022 atrás de um toque de dez segundos.

• ACL: camada que traduz entre dois Bounded Contexts, protegendo o modelo de domínio — não só o formato do dado.

• Origem: Eric Evans, Domain-Driven Design (2003) — uma entre várias estratégias catalogadas para relação entre contextos.

• O que ela faz: traduz conceito, não campo — devolução Pix é transação nova, nunca estorno.

• ACL ≠ Adapter: Adapter resolve interface; ACL protege semântica de um domínio inteiro.

• Core Bank: ledger, partida dobrada, lote, legado, e muitas vezes sem autonomia total (BaaS).

• Pix: RTGS, liquidação irrevogável, 24×365, sem tolerância a mensagem fora do padrão.

• A embaixada: a ACL permite que os dois mundos evoluam em velocidades diferentes, para sempre.

• Quando evitar: mesmo time, modelo externo já bom o suficiente (Conformist), erro barato de corrigir, ou integração estreita e estável — nesses casos, um Adapter simples já basta.

Arquitetura de software não é um diagrama bonito no Miro. É a disciplina de fazer sistemas legados e modernos coexistirem, tribos com prazos e apetite a risco diferentes cooperarem, e mudanças acontecerem sem derrubar o que já está em produção — sem esperar que a empresa inteira se alinhe de uma vez, porque isso nunca vai acontecer.

O contêiner é padronizado em portos marítimos — qualquer navio, de qualquer país, encaixa no mesmo guindaste. Ninguém precisa negociar o formato da carga toda vez que um navio novo atraca. Arquitetura de sistemas num ecossistema corporativo fechado busca exatamente isso: não uniformizar os navios, mas padronizar o ponto de encaixe entre eles.

Em bancos, isso é mais difícil do que parece. Não existe “uma arquitetura” — existem dezenas de squads, cada uma com seu histórico técnico, seu apetite a risco e seu calendário de entrega, quase nunca alinhados entre si. Os seis tópicos abaixo que vamos destacar, mapeiam como o engenheiro pragmático desenha para essa realidade, sem esperar um alinhamento geral que nunca vai vir.

Por que System Design continua sendo essencial

Código resolve o problema de hoje. System Design decide se o sistema de hoje ainda vai fazer sentido daqui a dois anos, quando o volume triplicar, quando três squads novas precisarem integrar com ele, ou quando a regra de negócio que parecia simples virar uma dezena de exceções que ninguém previu no desenho original. É a diferença entre escrever uma função e decidir onde essa função mora, quem pode chamá-la, o que acontece quando ela falha, e o que sobra do sistema se ela falhar de vez.

É também uma das poucas disciplinas de engenharia onde não existe resposta certa memorizável — só existem trade-offs bem ou mal avaliados para um contexto específico. Um desenho excelente para uma startup de dez pessoas pode ser irresponsável dentro de um banco regulado, e um padrão consolidado num banco pode ser exagero puro numa aplicação que nunca vai passar de mil usuários. É exatamente por isso que System Design não se aprende uma vez e fica pronto — se aprende revisitando decisões antigas, comparando o que o desenho previu com o que a produção realmente cobrou, e ajustando o julgamento a cada novo sistema.

As “partes difíceis” deste artigo não são as ferramentas ou os padrões em si — Gateway, Strangler Fig, Anti-Corruption Layer são só nomes para ideias relativamente simples. A parte difícil de verdade é decidir quando cada uma se aplica, o que ela custa em troca do que resolve, e como propor isso dentro de uma organização que não vai parar para esperar você ter certeza absoluta. É esse o tipo de julgamento que só se constrói estudando os erros — os seus e os de quem já passou por eles antes.

Em sistemas financeiros, isso é mais difícil do que parece. Não existe “uma arquitetura” — existem dezenas de squads, cada uma com seu histórico técnico, seu apetite a risco e seu calendário de entrega. Os tópicos abaixo mapeiam como o engenheiro pragmático desenha para essa realidade, sem esperar um alinhamento geral que nunca vai vir.

Resiliência de sistema: blindando o usuário do atrito síncrono vs. assíncrono

Em termos simples

🏦 No mundo real do banco

Imagine o cenário: a squad de cartões roda sobre um sistema legado síncrono via HTTP — pesado, engessado e com tempo de resposta imprevisível. Já a squad de investimentos opera em uma arquitetura moderna orientada a eventos, com Kafka e Redis, garantindo baixa latência e alta vazão. Sem uma camada de proteção, qualquer engasgo no legado se propaga em cascata e derruba a experiência do fluxo moderno, mesmo que ele não tenha culpa nenhuma.

A resposta arquitetural é a combinação de dois papéis complementares: o API Gateway (ou BFF) e o Circuit Breaker.

Se o Gateway atua como a Capitania dos Portos — controlando, autenticando e roteando o tráfego de entrada —, o Circuit Breaker é a trava de emergência do atracadouro. Quando o backend síncrono legado ultrapassa o limite de latência ou começa a acumular erros, o Circuit Breaker interrompe as chamadas para aquele serviço específico (abre o circuito).

Em vez de deixar a requisição pendurada até dar timeout, o Gateway responde imediatamente com um estado degradado controlado (um fallback explícito), permitindo que o fluxo de alta performance do resto do banco continue operando de forma intocada e transparente para o cliente.

Os trade-offs que valem a pena pesar

Nenhuma proteção é de graça. Um gateway com circuit breaker é mais um componente rodando 24 horas por dia, mais um ponto que pode falhar, mais um painel que alguém precisa monitorar às 3 da manhã. A pergunta que separa a decisão pragmática da decisão só teórica não é “isso é uma boa prática?” — é “o custo de operar essa camada extra é menor do que o custo de uma falha em cascata acontecer sem ela?”. Em sistemas que movem dinheiro, quase sempre a resposta é sim. Mas vale medir, não assumir: se o legado raramente falha e o impacto de uma falha isolada é baixo, talvez o investimento em resiliência valha mais em outro ponto do sistema.

Existe também um risco de médio prazo: um circuit breaker bem construído é tão bom em esconder problemas que pode virar desculpa para nunca resolver a causa raiz. A squad dona do legado para de sentir a dor da própria lentidão, porque alguém mais construiu uma rede de segurança em volta dela. Isso é ótimo para o usuário no curto prazo e perigoso para a arquitetura no longo prazo, se ninguém tiver a conversa seguinte.

Como comunicar isso

Essa é a conversa que costuma faltar: alinhar com a squad legada, antes de construir a proteção, o que exatamente conta como “degradado aceitável” para o produto — porque essa não é uma decisão só de engenharia, é uma decisão de experiência do cliente que produto e negócio precisam validar junto. E é preciso deixar claro, desde o início, que o gateway não é um substituto permanente para resolver a dívida técnica de origem — é um paliativo com prazo de validade.

ACEITE → que o legado vai continuar instável por um tempo — a prioridade não é consertá-lo agora, é isolar o impacto dele nos demais fluxos.

NÃO ACEITE → que a instabilidade do legado defina, de forma permanente e silenciosa, o teto de performance de tudo que depende dele.

NEGOCIE → com a squad legada um horizonte de tempo — ou pelo menos um critério — para reduzir a dívida técnica de origem, e não apenas mascará-la indefinidamente.

Rompendo silos: contratos de integração (API First) como acordo único

Em termos simples

🏦 No mundo real do banco

Sem padronização, cada squad reinventa a integração à sua maneira — acopladas, redundantes, cada uma com seu próprio jeito de nomear campos e tratar erros. Alinhar como um fluxo de cobrança vai trafegar dados entre 4 ou 5 squads, sem contrato prévio, vira semanas de reunião só para decidir formato de payload.

Os trade-offs que valem a pena pesar

Desenhar um contrato antes de codar tem um custo real e imediato: alguém precisa parar, pensar no formato dos dados, revisar com as squads consumidoras, e só depois começar a implementar. Isso parece mais lento no primeiro dia. O ganho aparece no dia 90, quando cinco squads já evoluíram seus próprios sistemas em paralelo, sem precisar de uma única reunião de sincronização entre elas. O erro comum é tentar fazer o contrato perfeito logo de cara — incluindo todo campo que alguém “pode precisar um dia”. Isso trava a entrega e ainda assim raramente acerta o que o futuro realmente vai pedir. Um contrato bom o suficiente para começar, com espaço claro para evoluir, bate um contrato “completo” que demorou meses para nascer.

Há também uma tensão permanente entre autonomia e coerência: contratos rígidos demais sufocam a squad que precisa se mover rápido; contratos frouxos demais devolvem o caos que o contrato deveria eliminar. Encontrar esse meio-termo é, na prática, uma decisão de governança — não só uma decisão técnica.

Como comunicar isso

Tratar a revisão do contrato como uma negociação de verdade ajuda mais do que buscar consenso unânime entre cinco squads — que raramente existe e, quando existe, geralmente é porque o contrato virou genérico demais para servir a alguém direito. Na prática, isso significa três coisas. Primeiro, existe um dono técnico com a palavra final: alguém — uma pessoa ou uma tribo de plataforma — que decide o formato do contrato quando as squads não chegam a um acordo sozinhas, para que a decisão não fique travada esperando unanimidade. Segundo, esse dono ouve cada squad pelo que ela realmente precisa, não pela lista inteira de “seria bom ter” que toda squad tende a trazer quando é convidada a opinar — o contrato cresce demais e fica lento de aprovar quando tenta agradar todo pedido. Terceiro, fica combinado desde o início que o contrato vai evoluir por versões — campos são adicionados, comportamentos são ajustados — em vez de alguém tentar prever, na v1, tudo que qualquer squad vai precisar nos próximos dois anos.

E existe uma regra que sustenta tudo isso no tempo, e que precisa ser dita em voz alta, sem deixar margem para interpretação: se uma squad decide “integrar por fora” do contrato — por exemplo, combinando informalmente com outra squad um formato de dado que não está documentado, só porque parece mais rápido resolver assim agora — isso não é um atalho inofensivo. É a reintrodução, em miniatura, do exato problema que o contrato existe para resolver: um acordo que só duas pessoas conhecem, não versionado, que pode quebrar sem aviso na próxima mudança de qualquer um dos dois lados. Se essa regra for tratada como sugestão em vez de compromisso, ela vai ser ignorada exatamente nos momentos de mais pressão de prazo — que é justamente quando o contrato mais precisa se sustentar.

ACEITE → que o primeiro contrato não vai satisfazer 100% das necessidades de todo mundo — ele só precisa ser bom o suficiente para todos começarem a trabalhar em paralelo.

NÃO ACEITE → squads integrando “por fora” do contrato porque parece mais rápido no momento — isso devolve o caos que o contrato existe para evitar.

NEGOCIE → um processo leve e com prazo definido para propor mudanças no contrato, com um dono técnico que decide — sem virar nem burocracia travada, nem terra sem lei.

Compartilhar

Falando a língua do negócio: ROI de componentes reutilizáveis vs. prazos rígidos

Em termos simples

🏦 No mundo real do banco

Diretoria vive sob entregas regulatórias e metas trimestrais, e enxerga refatoração grande como perda de tempo. Isolar a regra de negócio central de componentes de infraestrutura reutilizáveis — autenticação, auditoria, resiliência já homologados pelo time de segurança — significa que um produto de crédito novo pluga a lógica de negócio em cima de uma fundação que já passou por todo o ciclo de aprovação.

O argumento certo aqui não é estético, é de reaproveitamento de fundação já auditada: quanto do esforço da squad vai para regra de negócio nova versus quanto vai para reconstruir autenticação, log de auditoria e retry do zero, só para passar pelo mesmo comitê de segurança de novo.

Os trade-offs que valem a pena pesar

Construir uma fundação reutilizável custa tempo antes de gerar qualquer retorno visível — a primeira feature que usa essa fundação sempre parece mais lenta do que teria sido escrevendo tudo do zero, porque o investimento está indo para algo que só paga dividendo na segunda, terceira e décima feature. Esse é exatamente o tipo de trade-off que a liderança de banco, sob pressão trimestral, tende a rejeitar instintivamente — e é papel do engenheiro pragmático traduzir isso em uma conta que faça sentido para quem decide orçamento: quanto tempo essa fundação economiza a partir da segunda vez que for usada.

Existe também um risco na direção oposta: centralizar demais. Um módulo compartilhado de autenticação, auditoria e resiliência que toda squad depende vira, também, um ponto único de gargalo — se ele precisa mudar, todo mundo que depende dele precisa validar, testar e às vezes esperar. Isso reintroduz, em menor escala, o mesmo problema de coordenação que a fundação reutilizável deveria resolver. A linha entre “o que é genuinamente comum a todas as squads” e “o que só parece comum, mas na prática cada squad precisa de uma variação” é uma decisão que vale a pena revisitar, não assumir uma vez e esquecer.

Como comunicar isso

Com a liderança, o discurso técnico de “arquitetura limpa” convence pouco — o que convence é mostrar, em tempo, o custo de repetir autenticação e auditoria em cada produto novo versus o custo de construir uma vez e reaproveitar. Com as squads que vão consumir a fundação, vale alinhar desde o início que “reutilizável” não é sinônimo de “engessado”: precisa existir um canal claro para squads pedirem ajustes, sem que cada pedido vire uma fila de meses.

ACEITE → que construir a fundação reutilizável primeiro atrasa a primeira entrega que depende dela — o retorno aparece a partir da segunda vez que ela é usada, não da primeira.

NÃO ACEITE → pressão para pular a fundação “só dessa vez, por causa do prazo” — isso quase sempre vira prática permanente, não exceção.1

NEGOCIE → o escopo mínimo real da fundação — o que é genuinamente comum a todas as squads — separado do que cada squad deveria manter por conta própria.

Gestão de mudança: evolução arquitetural sem quebrar o legado

Mudar uma API central ou um modelo de dados em produção causa pânico real: sistemas core têm impactos imprevisíveis e caros quando quebram. Desligar o monólito de uma vez, ou trocar o banco de dados da empresa do dia para a noite, nunca é uma opção séria.

O padrão consolidado para isso é o Strangler Fig Pattern: uma camada de roteamento direciona tráfego progressivamente do sistema legado para o novo, funcionalidade por funcionalidade, até o legado “murchar” e poder ser desligado com segurança. Combinado com versionamento estrito de API e feature toggles no backend, squads mais lentas continuam na versão estável enquanto squads ágeis avançam — o risco nunca fica concentrado num único momento.

Os trade-offs que valem a pena pesar

Migração gradual custa mais caro enquanto dura: por um período, a empresa está pagando para operar e monitorar dois sistemas ao mesmo tempo — o legado e o novo — em vez de um só. É um custo real, não hipotético, e vale ser dito em voz alta para quem aprova orçamento, em vez de deixar que a conta apareça como surpresa meses depois. O outro lado da moeda é que o corte único, “big bang”, é mais barato no papel e infinitamente mais arriscado na prática — é exatamente o tipo de risco que sistemas core de banco não podem se dar ao luxo de correr.

Existe um risco menos falado sobre a estratégia gradual: gradualismo sem prazo tende a nunca terminar. Sem um critério objetivo de conclusão, “estamos migrando aos poucos” pode se tornar o estado permanente do sistema — os dois ambientes convivendo indefinidamente, cada um exigindo manutenção, nenhum sendo desligado. Isso não é uma falha do padrão Strangler Fig; é uma falha de quem não definiu, desde o início, quando a migração está oficialmente terminada.

Como comunicar isso

Em bancos, mudanças em sistemas core normalmente não são só uma decisão de engenharia — times de compliance, risco e auditoria costumam ter que aprovar o plano também, e trazê-los para a conversa só no fim, depois que a arquitetura já está desenhada, é um dos jeitos mais eficientes de travar tudo por semanas. 😅

Vale desenhar o plano de migração junto com essas áreas desde o início, não depois. E antes de começar a migrar qualquer coisa, vale deixar por escrito, com quem tem poder de aprovar, quais são os critérios objetivos que marcam o fim da migração — percentual de tráfego estável, tempo sem incidente, o que for — para que “gradual” tenha um destino, não vire um estado permanente.

ACEITE → que a migração vai custar mais caro operacionalmente enquanto os dois sistemas rodam em paralelo — é o preço de evitar um corte único e arriscado.

NÃO ACEITE → uma migração sem data ou critério de conclusão — “gradual” não pode virar sinônimo de “eterno”, com dois sistemas vivendo para sempre em paralelo.

NEGOCIE → os critérios objetivos de quando o legado pode ser desligado — e quem, além de engenharia, precisa validar esse plano antes de começar.

Deixe um comentário

Navegando a assimetria técnica entre squads

Em termos simples

🏦 No mundo real do banco

Enquanto uma squad opera microsserviços escaláveis na nuvem, outra ainda está presa a um mainframe ou a servidores locais que só exportam arquivo plano. Exigir que essa squad reescreva toda a infraestrutura para falar a linguagem de eventos do seu ecossistema é, na prática, uma utopia que trava a entrega indefinidamente.

A saída pragmática é uma camada de tradução — Adapter Pattern ou Anti-Corruption Layer: você recebe o dado exatamente como o outro time consegue enviar (arquivo flat, HTTP síncrono simples), e a própria camada de adaptação o transforma no formato que seu ecossistema espera. A dor do negócio é resolvida sem exigir que a squad vizinha refatore nada.

Os trade-offs que valem a pena pesar

Toda camada de adaptação carrega, embutido, um acordo silencioso: você está aceitando manter uma complexidade que tecnicamente não é sua, para não travar a integração numa dependência que você não controla. Isso é generosidade arquitetural com um custo real — mais um componente para debugar quando algo dá errado, mais uma tradução entre formatos que pode esconder um bug sutil, mais um lugar onde investigar um problema antes de chegar à causa raiz. Vale entrar nessa consciente do preço, não como um favor gratuito.

O risco mais comum com esse tipo de ponte é ela ser tratada como “provisória” no discurso e permanente na prática. Times mudam, gente sai, documentação envelhece — e um Adapter Pattern criado como solução temporária para destravar uma integração pode continuar rodando, sem dono e sem ninguém lembrando por que ele existe, anos depois do problema original ter deixado de fazer sentido.

Como comunicar isso

O combinado mais importante aqui não é técnico, é de propriedade: quem mantém essa camada de tradução daqui a um ano, quando a pessoa que a escreveu já tiver mudado de time? Vale deixar isso explícito por escrito no momento da criação, junto com a condição sob a qual a camada deixa de ser necessária — por exemplo, quando a squad legada eventualmente modernizar sua própria infraestrutura. Sem esse combinado, o adaptador vira órfão, e órfãos técnicos são exatamente o tipo de dívida que ninguém prioriza resolver até que quebrem em produção.

ACEITE → carregar, temporariamente, uma complexidade que não é originalmente sua, para destravar uma integração que de outra forma ficaria travada indefinidamente.

NÃO ACEITE → que essa camada fique sem dono claro — “solução temporária” sem responsável definido é a receita para ela virar permanente e esquecida.

NEGOCIE → por escrito quem mantém o adaptador e sob que condição ele deixa de ser necessário — não deixe isso implícito na cabeça de quem o construiu.

Engenharia de conflitos: vencendo a burocracia dos comitês com PoC

Em termos simples

🏦 No mundo real do banco

Fóruns de arquitetura corporativos tendem ao conservadorismo — apresentações teóricas e diagramas complexos morrem na praia por medo do risco, não por falta de mérito técnico. Debater os benefícios de uma arquitetura assíncrona em abstrato raramente convence arquitetos que carregam a responsabilidade por sistemas core.

A tática pragmática: isolar o cenário, construir uma PoC funcional simplificada e rodar testes de carga locais que provem resiliência sob estresse — com números reais de latência e custo. Métricas concretas pesam mais num comitê do que qualquer argumento conceitual, por melhor que seja construído.

Os trade-offs que valem a pena pesar

Construir uma PoC também tem custo: dias que não estão sendo gastos em compromissos já assumidos no roadmap, e esse tempo precisa ser justificado como investimento, não como desvio de foco. Existe também um risco de sedução com os próprios números: uma PoC roda num cenário controlado, isolado, quase sempre mais simples do que a produção real — e é fácil, apresentar um resultado bom demais para um contexto que não reflete todas as condições que o sistema vai enfrentar de verdade. A PoC reduz incerteza; ela não elimina risco, e tratar os dois como sinônimos é onde comitês bem-intencionados tomam decisões erradas com confiança excessiva.

Vale lembrar também que uma PoC convincente é, por definição, um argumento parcial — ela mostra o caso em que a proposta funciona bem, quase nunca o caso em que ela falha. Apresentar isso com honestidade intelectual, incluindo o que não foi testado, custa um pouco de força ao argumento no curto prazo e compra muito mais credibilidade da próxima vez que você precisar convencer o mesmo comitê.

Como comunicar isso

O erro mais comum é construir a PoC primeiro e só depois perguntar ao comitê o que teria sido suficiente para convencê-lo. Isso convida a um “não foi bem isso que eu queria ver” depois de dias de trabalho já feitos. Definir com quem vai decidir, antes de começar, qual critério objetivo de latência, custo ou taxa de erro conta como evidência suficiente evita esse desgaste — e transforma a apresentação de “convença-me” em “aqui está o que combinamos verificar, e aqui está o resultado”.

ACEITE → que uma PoC reduz incerteza, não elimina risco — ela é evidência para apoiar uma decisão, não uma garantia absoluta de que nada vai dar errado.

NÃO ACEITE → uma exigência de garantia total antes de qualquer teste prático — isso trava qualquer evolução arquitetural indefinidamente, e nenhuma PoC do mundo vai satisfazer esse padrão.

NEGOCIE → o critério de sucesso da PoC antes de construí-la, com quem vai decidir — para que o resultado seja avaliado contra um combinado, não contra uma expectativa que só apareceu depois.

O que muda quando você para de negociar tudo e começa a propor

Repare no que os seis tópicos têm em comum, além do tema. Nenhum deles se resolve com uma reunião geral de alinhamento — porque essa reunião, num ecossistema com dezenas de squads e apetites a risco diferentes, simplesmente não acontece de forma útil. E nenhum deles se resolve só com a decisão técnica certa, sem a conversa certa acontecendo antes, durante ou depois dela. Gateway, contrato, fundação reutilizável, Strangler Fig, Adapter Pattern, PoC — cada um é, ao mesmo tempo, uma escolha de arquitetura e uma proposta de negociação com um público específico: a squad legada, o comitê de segurança, a diretoria, o time vizinho tecnicamente atrás, os arquitetos conservadores.

É por isso que o exercício de aceite / não aceite / negocie vale mais do que os padrões específicos deste artigo. Amanhã você vai enfrentar um problema de arquitetura que não está listado aqui — e a pergunta que realmente ajuda não é “qual é o padrão certo”, é “o que dessa situação eu deveria simplesmente aceitar como restrição, o que eu não deveria aceitar sob hipótese nenhuma, e o que dá pra resolver com uma negociação bem colocada, no lugar certo, com a pessoa certa”. Esse é o hábito de pensamento que sobrevive à tecnologia específica.

Vale também gerenciar a própria expectativa. Nada disso conserta um ambiente corporativo fechado da noite para o dia, e ninguém deveria prometer isso. O que muda, com o tempo, é a sua posição dentro dele: cada contrato que se sustenta, cada migração que termina no prazo combinado, cada PoC que vira decisão real, constrói um crédito de confiança que facilita a próxima proposta. Engenheiros pragmáticos não vencem a burocracia corporativa numa tacada só — eles acumulam pequenas vitórias verificáveis até que propor deixe de ser um combate e vire, simplesmente, o processo padrão.

Você não muda o porto inteiro numa noite. Você padroniza um atracadouro de cada vez — e deixa que o resto do porto perceba, aos poucos, que vale a pena seguir o mesmo padrão.

Fico por aqui nesse artigo! Até o próximo! ❤️

De onde nasceu a ideia de cache (uma breve viagem à CPU)

Em termos simples

O processador do seu computador é absurdamente mais rápido que a memória RAM que alimenta ele de dados. É como ter um leitor que devora uma página por segundo, mas cujo bibliotecário pessoal leva vários segundos para trazer cada página nova.

O cache não nasceu em nenhum banco de dados nem em nenhum framework web — nasceu na arquitetura de hardware, nos anos 60, para resolver exatamente esse gargalo de velocidade entre processador e memória. A solução foi guardar uma cópia dos dados mais usados numa memória menor, mais cara e muito mais rápida, fisicamente mais perto do processador — o que hoje chamamos de L1, L2 e L3 cache, cada nível um pouco maior e um pouco mais lento que o anterior, até chegar na RAM.

O ponto-chave para carregar deste tópico: o problema que resolvemos hoje com Redis na frente de um banco de dados é, estruturalmente, o mesmo problema que engenheiros de hardware resolveram sessenta anos atrás. Muda a escala, muda o vocabulário, mas a ideia central — guardar uma cópia rápida perto de quem precisa, para não pagar o preço de buscar na fonte lenta toda vez — é a mesma.

Cache no mundo real: a mesa do desenvolvedor e a estante de livros

Em termos simples

A analogia é boa justamente porque o problema dela também é real. Se a sua mesa acumula livros demais, você perde espaço e se confunde sobre qual livro tem qual informação — o equivalente a um cache sem política de despejo, crescendo sem limite. E existe um risco mais sutil: você pode estar lendo, na sua mesa, uma edição desatualizada de um livro, enquanto a biblioteca já recebeu a edição nova. É exatamente isso que chamamos de dado obsoleto (stale data) — e é o problema mais difícil de resolver em qualquer sistema de cache, porque a mesa não avisa sozinha quando o livro dela ficou velho.

Por que dado obsoleto é o bug mais traiçoeiro que existe

Vale se demorar aqui, porque stale data tem uma característica que nenhum outro tipo comum de bug tem: ele não gera erro nenhum. Não lança exceção, não aparece em log de falha, não derruba requisição nenhuma. Ele só entrega, com toda a confiança de uma resposta bem-sucedida, um dado que já deixou de ser verdade. Um sistema servindo dado obsoleto parece, de fora, exatamente tão saudável quanto um sistema servindo dado correto — a única forma de perceber a diferença é comparar com a fonte da verdade, coisa que ninguém faz em toda requisição, porque isso anularia o próprio propósito de ter cache.

Pontos de atenção que todo programador precisa carregar

1. A janela entre escrever e invalidar não é instantânea

Existe sempre um intervalo de tempo — que pode ser milissegundos, mas existe — entre o momento em que o banco confirma a escrita e o momento em que a chave correspondente é de fato removida do cache. Qualquer leitura que aconteça exatamente nesse intervalo recebe o dado antigo, mesmo que a escrita já tenha sido concluída com sucesso.

2. Nem todo caminho de escrita passa pelo mesmo lugar

Um job em lote, uma migração manual rodada direto no banco, uma correção feita por outra squad em outro serviço — qualquer escrita que não passe pelo caminho de código “oficial” da aplicação simplesmente não sabe que precisa invalidar cache nenhum. O dado muda na fonte, e o cache nunca fica sabendo.

3. Cache em camadas múltiplas multiplica o problema

CDN, cache do navegador, cache da aplicação, cache de query do próprio banco — é comum ter várias camadas de cache empilhadas, cada uma com sua própria janela de expiração. Invalidar a camada de aplicação não invalida a CDN; o usuário pode continuar vendo dado velho mesmo depois de o seu código ter feito tudo certo.

4. Cache distribuído nem sempre invalida em todo lugar de uma vez

Em arquiteturas com múltiplas instâncias, múltiplas regiões ou réplicas de cache, invalidar uma chave numa instância não garante que ela também sumiu nas outras — dependendo da topologia, pode existir um atraso de propagação, e diferentes usuários, batendo em réplicas diferentes, veem respostas diferentes ao mesmo tempo.

5. Teste normal quase nunca revela o problema

Um teste automatizado típico faz uma escrita, espera, depois lê — sequencialmente, sem concorrência real. Isso nunca exercita a janela de corrida que causa stale data em produção, porque produção tem múltiplas requisições concorrentes que o teste, sozinho, não reproduz. “Passou nos testes” não é evidência de que a invalidação está correta sob carga real.

Nenhum desses pontos significa que stale data é impossível de mitigar — significa que ele nunca é resolvido por uma única linha de código chamando invalidar(). Exige pensar, para cada dado cacheado, em todos os caminhos que podem mudá-lo, em todas as camadas onde uma cópia dele pode estar guardada, e em quanto tempo de inconsistência o negócio realmente tolera.

O que o cache é (e o que ele definitivamente NÃO é)

Cache é uma camada temporária, volátil e de altíssima velocidade para dados de leitura frequente. Essa definição é curta de propósito — porque a parte mais importante deste tópico está no que ele não é, e que engenheiros sob pressão de prazo tendem a esquecer.

✓ O que ele é

• Uma camada temporária e volátil — pode desaparecer, e a aplicação precisa sobreviver a isso.

• Otimizado para leitura de altíssima frequência sobre dado que muda pouco.

• Uma cópia — nunca a fonte da verdade.

✗ O que ele não é

• Não é banco de dados primário — nunca use para persistência crucial que não pode simplesmente sumir.

• Não é solução para query ruim ou índice faltando — cache esconde o sintoma, não cura a causa.

• Não é remédio para código lento — mascarar latência de algoritmo ineficiente com cache é só acumular débito técnico com juros.

Vale grifar o segundo item da coluna o que ele não é, porque é o erro mais comum e mais caro: colocar um cache na frente de uma query lenta resolve o sintoma imediatamente e esconde o problema real por meses — até o dia em que o cache expira no pior momento possível, e a query lenta original volta a bater, sem aviso, direto na cara de todo mundo.

Os 5 grandes benefícios do cache

O lado bom:

1. Redução drástica de latência

Respostas na casa dos milissegundos, às vezes sub-milissegundos — uma diferença de ordem de magnitude frente a uma consulta que precisa tocar disco.

2. Alívio de carga no banco de dados

Libera conexões e CPU do banco principal, deixando mais capacidade disponível justamente para as operações de escrita, que não têm como ser cacheadas da mesma forma.

3. Economia de custo de infraestrutura

Menos processamento repetitivo em instâncias pagas por hora ou por uso — cada leitura evitada no banco é, literalmente, dinheiro que deixou de ser gasto.

4. Maior vazão (throughput)

O sistema suporta muito mais requisições simultâneas, porque a maioria delas nunca chega a competir pelos mesmos recursos escassos do banco.

5. Resiliência parcial

Em alguns cenários, se o banco primário oscilar, o cache ainda consegue servir leituras temporárias — um amortecedor, não uma garantia, mas que já evitou muita indisponibilidade total.

Os 5 perigos mortais do cache (a parte que dói em produção)

O lado ruim:

Esta é a seção que a comunidade sênior mais valoriza — não porque os perigos sejam segredo, mas porque só quem já apanhou de cada um deles em produção sabe o quanto eles doem na prática.

1. Invalidação de cache — “a coisa mais difícil da computação”

Manter o dado do cache sincronizado com a fonte da verdade é, de forma consolidada na indústria, um dos problemas mais difíceis de acertar de verdade. Não é falta de biblioteca ou de padrão — é que “quando exatamente esse dado deixou de ser válido” é uma pergunta genuinamente difícil quando múltiplos caminhos de escrita podem afetar o mesmo dado cacheado.

2. Cache Stampede / Thundering Herd

Quando um item muito acessado expira, e milhares de requisições simultâneas — que estavam todas contando com aquele cache — batem direto no banco de dados ao mesmo tempo, tentando repopular a mesma chave. O banco, que estava tranquilo um segundo antes, recebe um pico brutal e pode simplesmente cair.

3. Inconsistência de dados (stale data)

O usuário atualiza o próprio perfil, mas continua vendo os dados antigos na tela seguinte — porque a chave de cache correspondente não foi invalidada no momento da escrita. É o bug mais confuso de explicar para um usuário, porque para ele parece que o sistema simplesmente “esqueceu” o que ele acabou de fazer.

4. Consumo descontrolado de memória (OOM)

Salvar payloads gigantescos no cache, sem uma política clara de despejo (como LRU — descartar o item menos recentemente usado), transforma uma ferramenta de otimização em uma bomba-relógio de Out Of Memory esperando o momento certo para explodir.

5. Acoplamento e ponto único de falha

Tratar o servidor de cache como infalível é o erro mais silencioso da lista. Quando ele cai — e ele vai cair, cedo ou tarde — a aplicação inteira quebra, porque ninguém escreveu o caminho de código que lida com um cache miss em massa e repentino.

“A invalidação de cache é tão difícil que nós criamos o ‘Time to Live’ (TTL) só para o tempo resolver o problema que a gente não soube resolver na arquitetura.”

Quando arquitetos e devs DEVEM cachear

“Dados que mudam pouco e são lidos muito” é o conselho que todo mundo já ouviu — e é verdadeiro, mas raso demais para decidir de verdade. Na prática, cachear não é uma escolha binária de sim ou não: é uma posição num espectro, definida por dois eixos independentes que precisam ser medidos, não estimados de cabeça.

Deixe um comentário

A matriz que substitui o “achismo” por decisão

Cruze frequência de leitura com frequência de mudança e a decisão fica muito mais clara do que qualquer regra geral:

O eixo horizontal não deveria ser preenchido por intuição — é dado real de APM, de log de query, de métrica de acesso. “Eu acho que esse dado muda pouco” e “esse dado muda, em média, uma vez a cada 40 minutos, medido nos últimos 30 dias” são afirmações completamente diferentes, e só a segunda deveria autorizar uma decisão de cache em produção.

Cenário 1 — dados de alta leitura, baixíssima escrita

Exemplos concretos: a lista de países e estados de um formulário de cadastro, a tabela de tarifas de um banco atualizada uma vez por mês, a configuração de feature flags, as categorias de navegação de um e-commerce. É o cenário mais clássico e mais seguro para cachear — mas “seguro” não significa “sem perguntas”.

Pergunta do arquiteto

“Qual é a razão real entre leituras e escritas desse dado — 10 para 1? 10 mil para 1? Eu medi isso, ou estou assumindo que é alto porque parece óbvio?”

Pergunta do engenheiro

“Quem, além do meu próprio serviço, escreve nesse dado — um job em lote, um script de outro time, uma tela de administração separada? Esse caminho de escrita também invalida o cache, ou só o meu código lembra de fazer isso?”

Cenário 2 — cálculos computacionalmente caros que raramente mudam

Exemplos concretos: um score de crédito calculado a partir de múltiplas fontes de dados, um relatório de fechamento contábil do mês anterior, o resultado de um modelo de recomendação treinado uma vez por dia, um dashboard de métricas agregadas que varre milhões de linhas para gerar um único número.

Pergunta do engenheiro

“Esse cálculo é determinístico — o mesmo input sempre produz o mesmo output — ou depende de algum estado externo que pode mudar entre uma chamada e outra, tornando o resultado cacheado enganoso mesmo dentro do TTL?”

Pergunta do arquiteto

“Existe uma forma de recalcular esse valor de forma incremental, conforme os dados de origem mudam, em vez de recalcular do zero e depender de cache para esconder o custo? Às vezes o cache é usado para mascarar um algoritmo que deveria ser redesenhado, não otimizado com uma camada por cima.”

Cenário 3 — proteção de APIs de terceiros

Exemplos concretos: consulta de CEP e endereço, cotação de moeda de um provedor externo, verificação de score num bureau de crédito como Serasa ou SPC, geolocalização a partir de IP. Aqui o cache deixa de ser só otimização de performance e vira, também, controle de custo e de risco de bloqueio.

Pergunta do arquiteto

“Esse dado muda com a frequência que eu estou assumindo? A cotação do dólar muda a cada segundo no mercado, mas a minha aplicação realmente precisa dessa granularidade, ou um cache de sessenta segundos já é imperceptível para o caso de uso real?”

Pergunta do engenheiro

“Se o provedor externo cair e, ao mesmo tempo, meu cache expirar, existe um plano B — um valor default, uma resposta degradada — ou a minha aplicação simplesmente quebra em cascata porque dependeu de duas coisas saudáveis ao mesmo tempo?”

O estudo da feature: por que entender o negócio antes de cachear

Em termos simples

A pergunta que todo engenheiro deveria fazer antes de configurar um TTL não é “quanto tempo esse dado pode ficar em cache?” — é “qual o impacto se o cliente vir esse dado desatualizado por X segundos?”. Se o saldo de uma conta bancária atrasar dois segundos por causa de cache, isso é inaceitável — dinheiro é o tipo de dado onde inconsistência tem consequência direta e mensurável. Se o estoque de um produto na Black Friday atrasar dois segundos, o prejuízo pode ser igualmente real: venda de item que já esgotou, cliente frustrado, estorno, reputação.

Essa pergunta não tem resposta técnica — tem resposta de produto. É por isso que decidir cachear, e por quanto tempo, exige uma conversa explícita com quem entende o impacto de negócio daquele dado específico, não uma decisão unilateral de engenharia tomada só olhando para o gráfico de latência.

Por que invalidar uma chave simples é fácil, e invalidar uma chave derivada não é

Vale um exemplo concreto do primeiro perigo da lista, porque a diferença entre os dois casos é onde a maioria dos bugs de cache realmente nasce:

invalidação simples — um dado, uma chave

// atualizar o perfil de um usuário
atualizarUsuario(usuario)
cache.invalidar(`usuario:${usuario.id}`)  // direto, óbvio, uma chave

invalidação derivada — um dado, dezenas de chaves possíveis

// atualizar UM produto, que aparece em várias listagens cacheadas
atualizarProduto(produto)
cache.invalidar(`produto:${produto.id}`)          // fácil
cache.invalidar(`categoria:${produto.categoriaId}`)  // esse produto está numa listagem por categoria...
cache.invalidar(`vitrine:destaques`)             // ...que também aparece na vitrine...
cache.invalidar(`busca:*termo-relacionado*`)     // ...e em resultados de busca. Esqueceu um? Bug sile

A primeira invalidação é trivial. A segunda é onde “a coisa mais difícil da computação” ganha o apelido: cada novo lugar onde aquele dado aparece, de forma direta ou agregada, é mais uma chave que alguém precisa lembrar de invalidar — e esquecer uma única delas não gera erro nenhum, só um dado desatualizado silencioso em produção.

Estratégias clássicas de caching

Cache-Aside (Lazy Loading)

O código busca no cache primeiro; se não encontrar, busca no banco e popula o cache para a próxima vez. É a estratégia mais comum, mais simples de implementar, e a que dá mais controle explícito ao próprio código da aplicação.

✓ Prós

• Só entra em cache o dado que é efetivamente pedido — sem gastar memória com o que ninguém lê.

• O cache pode cair inteiro sem quebrar a aplicação: pior caso, tudo vira miss e volta a bater no banco.

✗ Contras — atenção no debug

• A primeira requisição depois de um miss é sempre mais lenta — se acontecer em massa (stampede), o pico atinge o banco de uma vez.

• A responsabilidade de invalidar fica espalhada pelo código da aplicação — fácil esquecer um caminho de escrita, gerando stale data silencioso.

Pergunta antes de adotar

“Quantos lugares no código escrevem esse dado — e cada um deles sabe que precisa invalidar a mesma chave, ou só o caminho ‘principal’ lembra disso?”

Write-Through / Write-Behind

A escrita passa pelo cache antes de ir para o banco (Write-Through, síncrono e mais seguro) ou é enviada ao banco de forma assíncrona depois (Write-Behind, mais rápido para quem escreve, com uma janela de risco se o cache cair antes de persistir).

✓ Prós

• Cache e banco tendem a ficar sincronizados por construção — muito menor chance de stale data comparado ao Cache-Aside.

• Write-Behind reduz a latência percebida pelo cliente, já que a confirmação não espera o banco responder.

✗ Contras — atenção no debug

• Write-Through adiciona latência a toda escrita, porque agora ela depende da saúde de dois sistemas em vez de um.

• Write-Behind cria uma janela real de perda de dado: se o cache cair antes de persistir no banco, a escrita “confirmada” nunca chegou lá.

Pergunta antes de adotar

“Se eu escolher Write-Behind, e o cache cair no meio da janela assíncrona, que dado exatamente eu aceito perder — e alguém do negócio já concordou explicitamente com essa perda?”

Read-Through

A aplicação só conversa com o cache — nunca diretamente com o banco — e é o próprio cache que se encarrega de buscar a fonte quando necessário. Centraliza a lógica de busca, mas cria mais dependência da camada de cache estar sempre saudável.

✓ Prós

• A lógica de “buscar na fonte se não tiver em cache” fica centralizada numa única camada, em vez de duplicada em cada ponto do código que lê esse dado.

• Simplifica bastante o código da aplicação, que passa a conhecer só uma interface — o cache — em vez de duas.

✗ Contras — atenção no debug

• Cria uma dependência mais forte: se o cache cair, a aplicação não sabe mais falar diretamente com o banco, porque nunca foi desenhada para isso.

• Debugar um dado errado é mais opaco — a lógica de busca mora dentro do provedor de cache, fora da visão direta do código da aplicação.

Pergunta antes de adotar

“Se a camada de cache ficar indisponível, minha aplicação tem algum caminho alternativo para falar com o banco — ou o Read-Through virou, sem perceber, um ponto único de falha disfarçado de otimização?”

O trade-off operacional: mais um componente na sua infra

Em termos simples

Adicionar Redis ou Memcached à arquitetura não é uma decisão isolada de código — é adicionar mais uma instância para monitorar, mais um painel de métricas para manter, custo real de transferência de rede, gerenciamento de chaves em escala, e uma preocupação adicional de segurança sobre o que está sendo guardado em memória (e se precisa de criptografia). Nenhum desses custos aparece no código da feature; todos eles aparecem na operação, semanas ou meses depois.

✓ Vale a pena quando

O ganho de latência e a redução de carga no banco são mensuráveis e relevantes para o negócio — e existe capacidade real de operar mais um componente de infraestrutura com o mesmo cuidado que se dá ao banco principal.

✗ Não vale a pena quando

O problema real é uma query sem índice, um algoritmo ineficiente, ou um volume de tráfego que nem justifica a complexidade operacional extra — cachear, nesse caso, só adiciona um componente novo para quebrar sem resolver a causa raiz.

Deixe um comentário

O que dizem os que já pagaram o preço do cache

Tudo o que foi dito até aqui é análise técnica — matriz de decisão, TTL, política de invalidação. Mas existe outra fonte de evidência que vale a pena ouvir: o que engenheiros com décadas de sistemas em produção, e mais de uma cicatriz de cache mal calibrado, escreveram sobre o assunto depois de já terem pago a conta. Três vozes, três ângulos diferentes do mesmo aviso.

“Existem apenas duas coisas difíceis em Ciência da Computação: invalidação de cache e dar nomes às coisas.” - Phil Karlton

A frase já tem mais de trinta anos e virou clichê de tanto ser repetida — o que, paradoxalmente, é a prova de que ela nunca deixou de ser verdadeira. Karlton não estava fazendo piada sobre dificuldade técnica; estava apontando que tanto nomear algo quanto invalidar um cache exigem a mesma coisa difícil: modelar corretamente uma realidade que muda com o tempo. Um nome errado e uma chave de cache não invalidada são o mesmo tipo de erro — a representação parou de corresponder à realidade, e ninguém percebeu no momento em que isso aconteceu.

“Cuidado ao colocar caches em muitos lugares!” - Sam Newman — Building Microservices

Newman escreve isso depois de descrever décadas de sistemas distribuídos que ele próprio ajudou a construir — e o aviso conecta direto com o que já conversamos nesse artigo: cache em camadas múltiplas (CDN, aplicação, banco) não soma proteção, multiplica a chance de alguma camada ficar com dado velho enquanto as outras já atualizaram. Ele também escreve, no mesmo livro, que entender o caminho completo do dado — da fonte até o destino final — é o que realmente revela a complexidade de um cache, não a implementação da chave em si. A lição prática é: antes de adicionar mais uma camada de cache, pergunte quantas já existem no caminho desse dado, porque provavelmente você não é a primeira pessoa a pensar nisso.

“...tão diferente do comportamento das variáveis ​​em um programa normal de thread única.” - Martin Kleppmann — Designing Data-Intensive Applications

Kleppmann usa essa frase para descrever por que consistência eventual é difícil para desenvolvedores. A maioria dos bugs de cache nasce porque o engenheiro, mentalmente, ainda está raciocinando como se o sistema fosse uma única variável numa única thread — muda aqui, lê ali, sempre na ordem esperada. Um sistema com cache nunca é isso: é sempre múltiplas cópias do mesmo dado, em momentos diferentes de atualização, sendo lidas por múltiplos consumidores ao mesmo tempo. O bug não é a implementação; é o modelo mental que não corresponde à arquitetura real.

O fio que conecta os três: nenhum deles trata cache como uma decisão puramente local, resolvida no momento em que a chave é escrita. Os três tratam como uma decisão sistêmica, cujo preço é pago depois — não pelo engenheiro que configurou o TTL numa tarde tranquila, mas por quem estiver de plantão no dia em que a suposição de “isso está sempre atualizado o suficiente” deixar de ser verdade.

O checklist do engenheiro pragmático

Antes de configurar a primeira chave de cache, quatro perguntas honestas valem mais do que qualquer benchmark de performance:

1. O banco de dados já está otimizado — índices no lugar, queries revisadas — antes de adicionar uma camada de cache por cima do problema?

2. A métrica real de acesso (leitura vs. escrita) justifica o uso de cache para esse dado específico, ou é uma suposição não verificada?

3. O time definiu o TTL ideal para cada chave, com base no impacto de negócio de um dado desatualizado — não num número redondo escolhido de forma arbitrária?

4. A aplicação sobrevive se o cache cair agora mesmo — graceful degradation real, testada, não apenas assumida?

Cache não é uma pergunta de “como implementar”. É uma pergunta de “o que meu sistema, meu negócio e minha operação estão dispostos a pagar” — em latência tolerada, em complexidade operacional, e em confiança de que tudo continua de pé no dia em que o cache, inevitavelmente, cair.

• Fundamentos de hierarquia de memória e cache em arquitetura de computadores (L1/L2/L3, décadas de 1960–70)

• Padrões consolidados da indústria: Cache-Aside, Write-Through, Write-Behind, Read-Through

• Cache Stampede / Thundering Herd — padrão de falha documentado em sistemas de alta escala

• Phil Karlton — aforismo “two hard things in computer science” (via Martin Fowler’s bliki)

• Sam Newman — Building Microservices: Designing Fine-Grained Systems

• Martin Kleppmann — Designing Data-Intensive Applications

Há uma cena que se repete em quase toda empresa de tecnologia: alguém recebe uma tarefa, abre o editor e começa a digitar antes de terminar de entender o problema. Duas semanas depois, o time descobre que construiu a coisa errada — com perfeição técnica. Este texto é sobre o profissional que faz o oposto.

Existe um mito silencioso na engenharia de software: o de que o valor de um profissional se mede pela velocidade com que ele produz código. É um mito confortável, porque código é visível, mensurável, versionável. Conversa não aparece no git blame.

Mas observe qualquer engenheiro sênior de verdade em ação — não o que tem mais anos de casa, mas o que as empresas disputam a peso de ouro — e você vai notar um padrão contraintuitivo: ele passa uma fração desproporcional do tempo perguntando, parafraseando, desenhando no quadro, discordando educadamente, até então abrir o editor. E quando abre, escreve rápido, porque já sabe exatamente o que está construindo e por quê.

O código é o efeito, não a causa

O que diferencia esse perfil não é talento de digitação. É que ele enxerga o fluxo de valor de ponta a ponta — do problema de negócio até o resultado que o usuário sente — e trata o código como um meio para chegar lá, não como o objetivo em si. Isso muda a ordem das operações: primeiro alinhar o que é valioso e por quê, depois desenhar o caminho técnico, só então escrever.

Fowler escreveu isso pensando em legibilidade de código, mas a ideia vale um passo antes: escrever para ser entendido também é o que se faz numa conversa de alinhamento. Quem só escreve para a máquina compilar tende a pular a etapa de escrever — falado ou em texto — para as pessoas entenderem.

A pergunta que todo mundo já fez

Se conversar não gera commits, por que isso deveria contar como trabalho de verdade?

Porque comunicação malfeita é o maior gerador de retrabalho que existe — e retrabalho é código também, só que descartado. Frederick Brooks, arquiteto de software do IBM System/360 e autor de The Mythical Man-Month, mostrou que projetos grandes não falham por falta de gente digitando: falham porque o custo de coordenação cresce mais rápido que o número de pessoas. Ele chamou de “conceitual integrity” a ideia de que um sistema bom precisa vir de poucas mentes alinhadas — não porque comitês são burros, mas porque cada nova pessoa multiplica os caminhos de comunicação necessários para todo mundo entender a mesma coisa.

Na visão dele, publicada em 1975 e ainda citada hoje, “conceptual integrity is the most important consideration in system design” — a integridade conceitual é a consideração mais importante no design de um sistema. Conversa é como essa integridade se propaga entre pessoas antes de virar código.

O preço do mal-entendido

Barry Boehm estudou projetos reais na TRW e na IBM e chegou a uma conclusão que hoje parece óbvia mas continua sendo ignorada na prática: um mal-entendido descoberto na fase de requisitos custa uma fração do que custa descobri-lo depois do sistema estar em produção — em análises citadas por engenheiros da NASA, essa diferença chega à ordem de cem vezes. A curva ficou menos exponencial com práticas modernas de entrega contínua, mas a direção da seta nunca mudou: quanto antes você entende errado, mais barato é corrigir.

Kent Beck, criador do Extreme Programming, levou essa ideia a sério de um jeito diferente: em vez de tentar acertar tudo de uma vez no papel, ele propôs achatar a curva com ciclos de feedback curtíssimos — testes antes do código, integração constante, conversas frequentes no lugar de documentos grossos escritos uma única vez. A lição comum aos dois: o problema nunca foi documentar demais ou de menos, foi quando você descobre que entendeu errado.

“...é sempre um problema de pessoas.” - Kent Beck — Extreme Programming Explained

Beck escreveu isso sobre um contexto específico — não importa o que o cliente diga que é o problema técnico, na raiz costuma haver um desalinhamento entre pessoas. É por isso que times que conversam bem corrigem defeitos de entendimento antes que eles virem defeitos de código.

Pergunta seguinte

Então a solução é documentar tudo antes de sair codando?

Não exatamente — é pensar em prosa antes de pensar em sintaxe. A Amazon institucionalizou isso com o processo interno conhecido como Working Backwards: antes de qualquer linha de código, o time escreve um comunicado de imprensa fictício e uma lista de perguntas frequentes descrevendo o produto já pronto, do ponto de vista do cliente. Jeff Bezos resumiu a lógica dizendo que a empresa “start[s] with the customer and work[s] backwards” — começa pelo cliente e trabalha de trás para frente.

O caso mais citado é o da AWS: Bezos e Andy Jassy identificaram a oportunidade em 2004, mas os serviços fundacionais (S3 e EC2) só foram lançados em 2006 — mais de um ano foi gasto escrevendo, revisando e discutindo esses documentos antes de qualquer infraestrutura ser construída. A empresa também substituiu apresentações de slides por memorandos narrativos de até seis páginas nas reuniões de decisão, exatamente porque escrever em prosa força a explicitar relações de causa e efeito que um slide deixa passar batido.

Por que isso não é burocracia

Vale uma ressalva científica aqui. O próprio Brooks fez uma comparação reveladora: a física lida com sistemas tão complexos quanto o software, mas o físico trabalha com fé de que existem princípios unificadores por trás do caos — a complexidade da natureza é, em certo sentido, honesta. A complexidade de um sistema de software, ao contrário, é muitas vezes arbitrária: nasce de decisões humanas, de interfaces que mudam de equipe para equipe, de contexto que não está escrito em lugar nenhum a não ser na cabeça de quem participou da conversa original.

É por isso que engenheiros de alto nível conversam antes: não para seguir processo, mas porque a complexidade arbitrária do software só existe na cabeça das pessoas até alguém a transformar em linguagem compartilhada — falada, escrita ou desenhada. Código é a última tradução dessa cadeia, não a primeira.

Técnicas para não errar a especificação, o entendimento e os testes

Especificação

• Reescreva o pedido com suas próprias palavras antes de abrir o editor, e mande de volta para quem pediu confirmar. Se a paráfrase não bater, o requisito não estava claro — só parecia estar.

• Pergunte pelo que não deve acontecer, não só pelo que deve. Casos de borda e comportamento não-funcional (performance, segurança, limites) raramente aparecem no pedido original.

• Escreva um mini “PR/FAQ” antes de uma POC: qual pergunta este experimento responde e o que provaria que ele falhou. Sem isso, toda POC “funciona” — porque ninguém definiu o que seria fracasso.

Entendimento

• Em sistemas legados, mapeie o comportamento atual antes de mudar (testes de caracterização / golden master). Documente o que o sistema faz hoje, não o que a documentação diz que ele deveria fazer — raramente são a mesma coisa.

• Traga alguém de fora da equipe técnica (produto, suporte, dados) para ouvir sua leitura do problema antes de estimar prazo. Se você não consegue explicar em termos simples, ainda não entendeu o suficiente para estimar.

• Em reuniões de kickoff, seja o último a falar sobre solução. Alinhar o problema antes da solução evita que a primeira ideia técnica vire âncora da conversa inteira.

Testes

• Escreva o teste que evidencia a intenção — dado, quando, então — antes ou junto da implementação, mesmo sem seguir TDD à risca. Um teste escrito depois tende a confirmar o código, não a intenção original.

• Em MVPs, escreva por escrito o que deliberadamente não será testado (non-goals). Isso transforma débito técnico invisível em decisão explícita, revisável mais tarde.

• Revisão de código deve avaliar se o código cumpre o que a conversa combinou, não só se está limpo ou idiomático. Sintaxe correta não é o mesmo que intenção correta.

3 práticas para levar à próxima conversa com seu gestor ou PM

Tudo isso pode soar abstrato se você ainda não tem uma década de bagagem para “simplesmente perceber” quando uma conversa evitaria um problema.

As três práticas abaixo não exigem experiência — só um script pronto e a coragem de usá-lo antes de abrir o editor.

1 · Antes de começar — traduza o pedido em uma frase que se responde com “sim” ou “não”

Você não precisa entender o negócio a fundo para fazer isso. Precisa só devolver o que ouviu, em uma frase curta, e esperar confirmação antes de escrever a primeira linha de código.

“Antes de começar, só confirmando: o objetivo é [o que você entendeu], para que [resultado que a pessoa quer] aconteça. É isso mesmo?”

Se a resposta vier rápida e direta, você entendeu. Se vier uma correção — “não bem, na verdade...” — você acabou de evitar dias de trabalho na direção errada, pelo custo de uma mensagem.

2 · Durante a conversa — pergunte pelo cenário de fracasso, não só pelo de sucesso

PMs e gestores costumam descrever o que a funcionalidade deve fazer. Raramente descrevem o que ela não pode quebrar, porque isso parece óbvio para quem pensa no produto o dia inteiro. Não é óbvio para quem está chegando agora — e perguntar por isso não exige jargão técnico.

"O que aconteceria se essa parte desse errado, ou se ela simplesmente não existisse? Isso me ajuda a saber o que eu não posso quebrar sem perceber."

Essa pergunta funciona em qualquer nível de senioridade porque desloca a conversa do “o que construir” para “o que importa de verdade” — que é exatamente o tipo de informação que normalmente só aparece depois, em produção.

3 · Depois da conversa — feche com um resumo escrito de três linhas

Não precisa ser um documento. Precisa existir, e precisa ser curto o bastante para alguém corrigir em quinze segundos, no mesmo dia — não descobrir o mal-entendido na revisão final.

Entendi: [o problema, em uma frase]
Vou fazer: [o que você vai construir]
Pode dar errado se: [a maior dúvida ou risco que você identificou]

Esse mini-resumo é a versão rascunho do memorando narrativo da Amazon citado antes: força você a organizar o pensamento em texto simples, e dá para quem pediu a tarefa uma chance barata de corrigir o rumo — exatamente o ponto da curva de custo em que a correção ainda é quase de graça.

Vale para código, e vale para o que vem antes dele. Pular a conversa para “ganhar tempo” costuma custar mais tempo depois — só que espalhado, invisível, disfarçado de imprevisto.

O perfil mais disputado do mercado hoje não é o que escreve mais rápido. É o que entende o fluxo de valor de ponta a ponta — do problema de negócio ao resultado sentido pelo usuário — e usa o código como meio, não como fim. Conversar antes de codar não é perder tempo: é onde esse profissional realmente trabalha.

Sua vez

Qual foi a vez em que uma conversa de dez minutos evitou uma semana de retrabalho? Ou o contrário — o que aconteceu quando o time codificou antes de entender? Conte abaixo.

Deixe um comentário

• Frederick P. Brooks Jr. — The Mythical Man-Month: Essays on Software Engineering (1975/1995)

• Colin Bryar & Bill Carr — Working Backwards; processo PR/FAQ da Amazon (workingbackwards.com)

• Barry Boehm — Software Engineering Economics (1981); síntese em relatório da NASA sobre custo de erro

• Kent Beck — Extreme Programming Explained (2000), sobre o achatamento da curva de custo de mudança e mal-entendidos como problema de pessoas

• Martin Fowler — Refactoring: Improving the Design of Existing Code (1999)

• Robert C. Martin — Clean Architecture: A Craftsman’s Guide to Software Structure and Design (2017)

No mundo ideal dos diagramas de arquitetura, o fluxo é lindo:

1. O Core Bancário detecta o atraso.

2. Um evento CreditCardOverdue é publicado no barramento.

3. O microsserviço de Cartões consome a mensagem e muda o status para BLOCKED.

Mas nós somos programadores pragmáticos e sabemos que o mundo real é caótico. E se o consumer de Cartões estiver fora do ar justo nesse milissegundo? E se a mensagem cair numa Dead Letter Quee (DLQ) e for esquecida lá? E se o payload do evento tiver um caractere inválido que quebra o parser (a temida Poison Pill)?

O resultado é o silêncio.

O evento falha, o sistema não tenta de novo, e o contrato entra no que chamamos de State Drift (Desvio de Estado). Para o banco de dados, aquele cliente ainda está ACTIVE. Ele vai ao shopping amanhã e gasta mais R$ 5.000,00. O banco aumentou sua exposição ao risco por uma falha.

Pior ainda: o cenario avança 200 dias. Esse cliente nunca pagou. Pela regulação do Banco Central, esse contrato deveria ser marcado como Prejuízo (Write-off) para fins contábeis e fiscais. Se o seu sistema depende exclusivamente de um evento disparado no dia 200 para fazer isso, e esse evento falha... parabéns, seu banco agora tem um passivo contábil incorreto e está sujeito a multas regulatórias.1

Arquiteturas Orientadas a Eventos são excelentes para escalabilidade e desacoplamento, mas elas não garantem a consistência final dos dados ao longo do tempo.

Para sistemas financeiros críticos, precisamos de mais. Precisamos de uma arquitetura de Self-Healing. Precisamos de sistemas que não apenas “reajam” a eventos, mas que proativamente “busquem e corrijam” estados inconsistentes baseados na passagem do tempo.

Neste artigo, vamos explorar como desenhar uma estratégia robusta de recuperação de estado para ciclos de crédito. Vamos sair do “Happy Path” e desenhar o “Safety Path”: cron jobs inteligentes, máquinas de estado resilientes e estratégias de reconciliação que garantem que, mesmo que o broker pegue fogo, o balanço do banco feche no final do mês.

O que é Self-Healing?

Se você jogou qualquer RPG ou MMO nos últimos 20 anos, o termo “Self-Healing” provavelmente evoca a imagem de um personagem regenerando sua barra de vida automaticamente ou um clérigo lançando um feitiço de cura. No mundo dos jogos, é a mecânica que permite ao jogador continuar na batalha sem precisar parar o tempo todo.

Na engenharia de software, o conceito é surpreendentemente similar, mas a inspiração original não veio dos videogames. Veio da Biologia.

A Biologia como Benchmark

No mundo real, o melhor exemplo de um sistema Self-Healing é o seu próprio corpo. Quando você faz um pequeno corte no dedo, você não precisa abrir um chamado no Jira para o seu cérebro, nem rodar um script manual para iniciar a coagulação. O seu sistema imunológico detecta a “falha” (o corte), isola a área e inicia processos automáticos de reparo para restaurar a integridade da pele.

Se o corpo humano dependesse de intervenção consciente para curar cada micro-lesão, não sobreviveríamos um dia. Sistemas distribuídos complexos chegaram a esse mesmo estágio: eles são grandes demais para serem “curados” manualmente por humanos às 3 da manhã.

O Manifesto da IBM

O termo ganhou força corporativa no início dos anos 2000, quando a IBM lançou seu manifesto sobre Computação Autonômica (Autonomic Computing).

A IBM percebeu que a complexidade dos sistemas de computação estava crescendo mais rápido do que a capacidade humana de gerenciá-los. Eles propuseram que os sistemas deveriam ter quatro propriedades inspiradas no sistema nervoso autônomo:

1. Self-Configuration: Configurar-se sozinho.

2. Self-Optimization: Otimizar recursos sozinho.

3. Self-Protection: Defender-se de ataques.

4. Self-Healing: Detectar, diagnosticar e reparar problemas causados por falhas internas ou externas.

Portanto, Self-Healing não é apenas “tentar de novo”. É a capacidade de um sistema perceber que não está saudável (está inconsistente) e tomar medidas para voltar ao estado normal sem acordar o engenheiro de plantão.

O “Diagnóstico Financeiro”: Meu sistema precisa de Self-Healing?

Implementar Self-Healing (como jobs de reconciliação de GL, retentativas inteligentes ou estornos automáticos) custa caro. Aumenta a complexidade do código e exige manutenção. Não use um canhão para matar uma mosca.

Para saber se o seu microsserviço financeiro precisa dessa arquitetura, faça a si mesmo estas 4 perguntas (O “Teste da Dor Financeira”):

1. A inconsistência gera impacto no P&L ou risco regulatório?

• Contexto: Erros de UI tem um menor impacto; erros de financeiros são fatais.

• Exemplo: Se o avatar do usuário não carregar, o máximo que acontece é uma experiência visual ruim. Ninguém processa o banco por isso. Mas o jogo muda quando entramos na camada regulatória: se o cálculo de IOF falhar silenciosamente e você recolher a menos para a Receita, ou se um contrato inadimplente não sofrer a Baixa Contábil (Write-off) no momento exigido pelas normas vigentes (como a Resolução CMN 4.966), você estará mantendo um ativo 'podre' inflando artificialmente o balanço. Nesse cenário, o erro de software deixa de ser um bug no Jira e vira risco de conformidade, colocando na reta não só a reputação da empresa, mas o CPF dos diretores estatutários.

• Se o erro afeta o balanço contábil ou relatórios para o regulador (BACEN/CVM), a cura precisa ser automática.

2. A operação manual escala com o volume transacional?

• Contexto: O custo do Backoffice vs. Engenharia.

• Exemplo: Se 5 TEDs falham por dia, um analista de N2 pode corrigir na mão acessando o banco de dados. Mas se você processa PIX e tem uma taxa de falha de 0.1% em dia de folha de pagamento (milhares de erros/hora), tentar corrigir isso manualmente vai colapsar seu time de atendimento e gerar milhares de reclamações no Banco Central.

• Se o volume de falhas excede a capacidade humana de digitar UPDATE no banco em tempo real, você precisa de automação.

3. O erro gera Passivo Fantasma?

• Contexto: O perigo do “Sucesso Falso”.

• Exemplo: O sistema de eventos diz que o cartão foi bloqueado, mas o processadora de cartões não recebeu o comando. O cliente continua comprando. Para o seu banco de dados, está tudo certo; para o caixa do banco, há um vazamento de dinheiro invisível ocorrendo agora.

• Se o estado financeiro pode divergir da realidade sem gerar um Exception imediato, você precisa de um “Auditor Robô” (Worker) rodando de tempos em tempos.

4. Existe uma Janela de Clearing ou SLA Regulatório Rígido?

• Contexto: O tempo não perdoa em finanças.

• Exemplo: Você tem até as 16h para enviar a remessa de boletos ou até as 18h30 para fechar o caixa do STR (Sistema de Transferência de Reservas). Se o sistema travar às 15h50, você não tem 20 minutos para esperar um humano investigar logs. O sistema precisa tentar rotas alternativas ou degradar graciosamente para garantir o envio.

• Se perder a janela de tempo significa multa ou travar o dinheiro do banco até o dia seguinte, a recuperação deve ser instantânea.

Se o erro permite que você espere até a daily do dia seguinte para resolver, não gaste engenharia com isso. Mas se o erro faz o banco perder dinheiro, inflacionar o balanço artificialmente ou falhar com o BACEN enquanto você dorme, o Self-Healing é obrigatório.

A Auditoria de Inconsistência (Como encontrar os “Fantasmas” no seu Banco)

Se você passou pelo “Teste da Dor” e desconfia que seu sistema precisa de cura automática, o próximo passo não é abrir o VS Code, mas sim abrir o Jira e o seu banco de dados em produção.

Para justificar o investimento em uma arquitetura de Self-Healing para a diretoria, você precisa de dados. A equipe de engenharia deve conduzir uma investigação em três frentes para mapear a fragilidade atual do sistema.

Chamamos isso de “A Caça aos Fantasmas de Estado”.

1. A Análise de “Toil” (Trabalho Penoso)

O conceito de Toil (do SRE do Google) refere-se ao trabalho manual, repetitivo e tático. Peça para o seu Tech Lead ou coordenador de suporte levantar os chamados dos últimos 6 meses. Procure por padrões nos tickets fechados:

• A “Pasta Mágica” de Scripts: O time tem uma pasta compartilhada com scripts SQL chamados update_status_travado.sql ou destravar_pix.sql? Se existe um script oficial para corrigir dados na mão, isso é um grito de socorro por Self-Healing.

• Tickets de “Sincronia”: Chamados com títulos como “Cliente pagou mas não consta no app” ou “Fatura cancelada ainda aparece como aberta”.

• A Regra dos 20%: Se a sua equipe gasta mais de 20% do sprint executando correções manuais de dados (não de código, mas de dados), a automação não é luxo, é sobrevivência.

2. A “Query Caça-Fantasmas” (Data Integrity Probe)

Não espere o cliente reclamar. A engenharia deve executar queries exploratórias para encontrar estados impossíveis que existem silenciosamente no banco de dados hoje.

Crie queries que busquem violações da sua Máquina de Estados:

• O Limbo do Processamento:

SELECT count(*) FROM transacoes
WHERE status = 'PROCESSING'
AND created_at < NOW() - INTERVAL '24 HOURS';

• Diagnóstico: Em um sistema financeiro, nada deve ficar “processando” por 24 horas. Ou pagou, ou falhou. Se retornou linhas, você tem “fantasmas” que precisam de cura.

• O Zumbi Financeiro:

SELECT count(*) FROM contratos
WHERE dias_atraso > 60
AND status = 'ACTIVE';

• Diagnóstico: O cliente deve há dois meses e o contrato está ativo? O evento de bloqueio falhou e ninguém viu.

3. O Mapeamento de Dependências Cegas

Desenhe a arquitetura e circule em vermelho todos os pontos onde seu sistema espera passivamente por uma resposta externa.

• Webhooks de Pagamento: Se o gateway não chamar o seu webhook de confirmação (ou se o serviço de bloquear), a transação morre?

• Arquivos de Retorno (CNAB): Se o arquivo do banco não chegar até as 10h, o processo para?

O Resultado da Análise

Ao final dessa auditoria, a equipe deve ter uma tabela simples:

Com essa tabela, a decisão deixa de ser técnica (”queremos fazer porque é legal”) e vira financeira (”queremos fazer para recuperar 14 horas de engenharia e destravar R$ 45 mil”).

A Ilusão do "Event-Driven Puro"

Nós, arquitetos e engenheiros de software, fomos seduzidos por uma promessa arquitetural: “Desacople tudo. Use eventos. O sistema será reativo e perfeito.”

Em diagramas de arquitetura, setas ligando o Producer ao Consumer via Kafka ou RabbitMQ representam certeza. Na prática, elas representam esperança. Em sistemas financeiros, especialmente em Cobrança e Crédito, a esperança não é uma estratégia viável.

O Dia 5

Vamos analisar a anatomia de um desastre silencioso. Imagine que seu motor de crédito (Core Banking) dispara o evento PaymentOverdue exatamente no 5º dia de atraso do cliente. A regra de negócio é clara: “Se atrasar 5 dias, bloqueie o cartão imediatamente.”

O evento é publicado. O offset é commitado. O Core Banking “lavou as mãos”, crente de que fez sua parte. Mas do outro lado, no microsserviço de Cartões, o Consumer encontrou um problema:

1. A “Poison Pill”: O payload do evento veio com um caractere invisível no campo contract_id, causando uma Exception de deserialização que trava o processamento daquele lote.

2. Falha de Infra: O pod do Kubernetes estava reiniciando por OOM (Out of Memory) bem naquele segundo.

3. Bug Silencioso: O código consumiu a mensagem, mas falhou ao gravar no banco devido a um Deadlock, e a configuração de retry estava mal implementada.

O Resultado é que o evento se perdeu. Para o sistema, o cliente ainda está “Ativo”. Para o cliente, o cartão continua passando na maquininha.

PDD e Metas Estouradas

Aqui é onde o código afeta o bônus da diretoria e a saúde do banco.

Passam-se 6, 7, 8 dias. O cliente, que já não pagou a fatura anterior, continua comprando (aumentando a exposição do banco ao risco). Chamamos isso de Exposição Sombra. O sistema de Risco acha que a exposição é X, mas ela é X + R$ 5.000,00 que o cliente gastou depois do dia em que deveria ter sido bloqueado.

Quando o time de dados rodar o relatório mensal de PDD (Provisão para Devedores Duvidosos) ou PCL, os números não baterão.

• Impacto no Time: Sua squad para de desenvolver features novas. O Sprint vai para o lixo. Vocês entram em “War Room” para fazer queries manuais no banco, tentando descobrir quais clientes deveriam estar bloqueados e não estão.

• Impacto na Meta: O tempo gasto investigando “fantasmas” (incidências sem logs de erro óbvios) é exponencialmente maior do que corrigir um bug que estoura um alerta 500 no Datadog.

Arquiteturas puramente orientadas a eventos sofrem de um otimismo excessivo. Elas assumem que a mensagem vai chegar.

Para dormir tranquilo, precisamos adotar uma postura pessimista: “O evento vai falhar. E quando ele falhar, quem vai limpar a bagunça?”

Eventos são excelentes para Real-Time (velocidade). Mas Jobs de Varredura são necessários para Consistência (garantia).

Se o evento é o carteiro que entrega a conta, precisamos de alguém que passe depois verificando se a conta foi realmente paga. Precisamos de um “Varredor de Estados”.

O "State Sweeper" – A Rede de Segurança Invisível

O que exatamente é esse “State Sweeper” (Varredor de Estado)?

Em uma definição simples:

O State Sweeper é um componente arquitetural proativo que periodicamente interroga a base de dados em busca de inconsistências temporais ou lógicas que escaparam do fluxo padrão de eventos.

Enquanto a arquitetura orientada a eventos (EDA) é Reativa (o sistema espera algo acontecer para agir), o State Sweeper é Proativo (o sistema vai verificar se algo deveria ter acontecido, mas não aconteceu).

Por que ele é obrigatório em Event-Driven?

Nós amamos arquiteturas orientadas a eventos porque elas desacoplam serviços. O Serviço A grita “Cobrança Criada!” e não se importa com quem vai ouvir.

Mas essa liberdade tem um custo: O Silêncio. Se o evento se perde, ou se o consumidor falha silenciosamente, não há “erro”. Há apenas o vazio. O sistema não quebra; ele simplesmente para de evoluir o estado daquele contrato.

• O cliente não é bloqueado.

• A divida não é transmitida para outros serviços.

• O nome não vai para o Serasa.

O State Sweeper é necessário porque ele não confia na infraestrutura de mensageria. Ele confia apenas na passagem do tempo e no estado persistido. Ele é a garantia final de que a “Consistência Eventual” vai realmente acontecer, mesmo que seja “na marra”.

A Complexidade Oculta: Por que é difícil desenvolver?

Muitos gerentes podem olhar para isso e dizer: “Ah, é só uma rotina que roda a cada diariamente, pede para o estagiário fazer.”

Isso é um grande engano! Desenvolver um Sweeper eficiente e seguro exige um nível de pensamento crítico e análise de negócio que geralmente só encontramos em engenheiros sêniores ou especialistas.

Por que não é simples?

1. Exige Domínio Absoluto das Regras de Negócio Você não pode escrever um Sweeper se não entender profundamente o ciclo de vida da entidade. ⚠️

• Pergunta Difícil: “Se o contrato está atrasado há 200 dias, eu devo mandar para cobrança externa? Mas e se ele tiver uma flag de ‘Renegociação em Andamento’? E se for um dia não-útil? E se o cliente tiver uma liminar judicial?”

• O Sweeper toma decisões. Se a regra estiver errada, ele vai aplicar a regra errada em massa (ex: bloquear 50 mil clientes indevidamente em 1 minuto).

2. O Dilema da Concorrência (Race Conditions) E se o Sweeper rodar exatamente no mesmo milissegundo em que o evento real chegou atrasado?

• Você precisa desenhar mecanismos de travamento (Locks) ou verificações de versão (Optimistic Locking) para garantir que o Sweeper e o Consumer não tentem modificar o mesmo contrato ao mesmo tempo, corrompendo o saldo.

3. O Perigo da “Avalanche” Se o seu sistema ficar fora do ar por 2 horas, você acumulará milhares de pendências.

• Um Sweeper mal desenhado vai tentar corrigir tudo de uma vez assim que o sistema voltar, criando um ataque DDoS contra o seu próprio banco de dados ou contra as APIs de parceiros. É preciso desenhar backoff, paginação e limitação de taxa (throttling).

4. Visibilidade e Rastreabilidade Quando um humano corrige um erro, ele deixa um log. Quando um robô corrige 500 erros, quem fica sabendo?

• Desenvolver um Sweeper exige criar eventos específicos (ex: ContractAutoHealed) para que os analistas saibam a diferença entre “O sistema funcionou normalmente” e “O sistema falhou, mas o robô consertou”.

O State Sweeper não é um “tapa-buraco”. É um componente de Resiliência de Negócio. Ele exige que a equipe de engenharia pare de pensar apenas em código (syntax) e comece a pensar em comportamento sistêmico (semantics) e modos de falha.

System Design com Sweepers em Arquiteturas Distribuídas

Aqui chegamos ao “nó” arquitetural que separa os juniores dos seniores.

No mundo monolítico, o Sweeper seria um script simples que atualizaria todas as tabelas. Mas nós estamos no mundo dos Microsserviços. O Serviço de Cobrança (Collection Service) é a autoridade sobre quem está sendo cobrado, mas ele não é o dono do Contrato de Crédito original (quem manda lá é o Credit Core).

Isso cria um dilema: O Serviço de Cobrança sabe que o cliente está atrasado há 205 dias (violando a regra de negócio de 200 dias), mas ele não pode simplesmente dar um UPDATE na tabela do Core.

Então, como desenhar um Sweeper que impõe a regra sem quebrar o desacoplamento? A resposta está em atuar como um Auditor Ativo.

O Cenário: A Regra dos 200 Dias

A regra é clara: “Contratos com mais de 200 dias de atraso devem ser retirados da carteira interna e enviados para uma Assessoria de Cobrança Externa (Recovery).”

Se o evento do “Dia 200” falhar, o contrato fica esquecido na base de Cobrança com status OVERDUE. O banco perde dinheiro a cada dia.

Passo 1: A Detecção Cirúrgica (NoSQL Strategy)

Primeiro, o Sweeper (um Lambda ou CronJob) precisa encontrar os infratores na sua própria base (Collection Service). Não vamos fazer Scan. Vamos usar a estratégia de Índice de Exceção no DynamoDB.

• Tabela: CollectionCases

• GSI (Índice): GSI_Compliance_Audit

  • PK: CollectionStatus (Ex: OVERDUE)

  • SK: DaysInDelay (Numérico)

A Query do Sweeper: Ele pergunta ao DynamoDB: “Liste apenas os itens onde Status = ‘OVERDUE’ E DaysInDelay >= 200”. Isso é extremamente performático. Se o sistema estiver saudável, retorna zero. Se houver falha no fluxo de eventos, retorna exatamente os contratos problemáticos.

Passo 2: O “Sanity Check” (Consulta de Segurança)

Aqui entra a inteligência distribuída. Antes de tomar uma atitude drástica, o Sweeper precisa garantir que sua visão de mundo não está distorcida. Pode ser que o cliente tenha renegociado a dívida no Core há 10 minutos e o evento de “Renegociação” ainda não chegou na Cobrança.

O Sweeper faz uma chamada síncrona leve (HTTP GET) na API do Core: GET /credit-core/contracts/{id}/status

• Se o Core disser “Renegociado/Pago”: O Sweeper aborta e dispara um alerta de inconsistência de dados (para corrigir sua base local depois).

• Se o Core disser “Atrasado”: O sinal verde está dado. A regra dos 200 dias foi violada e a dívida é válida.

Passo 3: A “Arbitragem Local” e o Disparo do Evento

O Sweeper não ordena que o Core mude. Ele ordena que o Serviço de Cobrança tome a atitude correta para proteger o banco.

1. Atualização da Base Local (Autocura): O Sweeper executa um UpdateItem na tabela CollectionCases:

   • De: OVERDUE

   • Para: SENT_FOR_COLLECTION

   • Metadata: Adiciona um campo UpdatedBy: "SWEEPER_BOT" para rastreabilidade.

2. Comunicação ao Ecossistema (O Grito): Como o contrato mudou de estado, o Serviço de Cobrança precisa avisar o mundo. Ele publica um evento enriquecido no barramento (Kafka/SNS):

   Evento: Collection.CaseSentToExternalRecovery

{
  "contractId": "XYZ-123",
  "daysInDelay": 205,
  "outstandingBalance": 5000.00,
  "reason": "RULE_200_DAYS_LIMIT",
  "trigger": "AUTO_HEALING_WORKER", // Campo crucial para métricas!
  "occurredAt": "2024-01-20T10:00:00Z"
}

O Resultado Arquitetural

Veja a elegância dessa solução:

1. Respeito aos Limites: O Serviço de Cobrança não invadiu o Core. Ele resolveu o problema do seu lado (mudou para SENT_FOR_COLLECTION) e avisou os parceiros.

2. Integração Reativa: Quando a Assessoria de Cobrança escutar esse evento, ela cadastra a dívida lá. Quando o Core escutar esse evento, ele marca o contrato como “Em Prejuízo”.

3. Observabilidade: Graças ao campo trigger: AUTO_HEALING_WORKER, você pode criar um dashboard no Datadog/Grafana. Se o número de eventos disparados pelo Sweeper subir, você sabe que seu fluxo real-time (Kafka) está quebrado, antes mesmo do Diretor reclamar.

O Sweeper aqui não é um “consertador de banco de dados”. Ele é um agente de negócio automatizado que garante que as regras financeiras sejam cumpridas, mesmo quando a infraestrutura falha.

Antes do Código: A Mentalidade Orientada a Perguntas

Agora que você viu uma ponta do Self-Healing em ação, pare um pouco. Antes de abrir a IDE e começar a codar Lambdas ou desenhar índices no DynamoDB, você precisa de algo que nenhuma ferramenta pode te dar: Contexto de Negócio.

Uma arquitetura de autocura não nasce de requisitos técnicos, ela nasce de dores operacionais. Para modelar os dados corretamente e facilitar a introdução dessas rotinas de cura, Tech Leads e Arquitetos precisam adotar uma postura de investigação.

1. A Mina de Ouro: O Time de Suporte (N1/N2)

Se você quer saber onde seu sistema sangra, não olhe para o Datadog agora. Olhe para a fila de chamados. O time que atende o cliente provavelmente já tem uma “Wiki” ou um caderno de anotações com procedimentos manuais para resolver problemas que a engenharia considera “pontuais”, mas que na verdade são crônicos.

Você precisa se perguntar:

• “Por que o atendente precisa verificar manualmente se a fatura do dia 15 fechou?”

• “Quais scripts o time de Operações roda toda sexta-feira para ‘ajustar a base’?”

• “Quantas vezes um cliente ligou reclamando que pagou o acordo, mas continua recebendo SMS de cobrança?”

Cada um desses “procedimentos manuais” é um candidato a automação via Self-Healing. O Sweeper nada mais é do que a codificação do conhecimento tático do time de suporte, rodando 24/7.

2. O Custo da Inconsistência (O Risco Jurídico)

Estados inconsistentes em sistemas financeiros não são apenas “bugs”. São passivos judiciais.

• Cobrança Indevida: Um cliente que renegociou a dívida, mas o evento se perdeu e ele voltou para a régua de cobrança, é um processo ganho no Juizado de Pequenas Causas.

• Bloqueio Indevido: Um cartão bloqueado porque a fatura consta em aberto (quando já foi paga) gera uma experiência terrível e danos morais.

O objetivo do Self-Healing é mitigar esse risco. É garantir que a realidade do cliente (ele pagou) seja igual à realidade do sistema (o status é PAID), independente de falhas na rede. Inconsistência é inaceitável.

3. Access Patterns: Seja Orientado a Perguntas

Aqui entra a virada de chave mental. Para criar um sistema que se cura, você precisa modelar seus dados baseado nas perguntas de auditoria, não apenas nas perguntas de navegação.

Não adianta apenas perguntar: “Como recupero o contrato do cliente X?”. Você deve perguntar: “Como o sistema identifica, em meio a 10 milhões de contratos, quais deveriam ter fechado ontem e não fecharam?”

Se você não tiver essa resposta na ponta da língua (e modelada no seu banco de dados), você não tem observabilidade, você tem cegueira.

• Se o negócio diz: “Faturas acima de R$ 5k não podem ficar abertas por mais de 30 dias”, sua arquitetura deve responder à pergunta: “Onde estão as faturas > 5k com days_delayed > 30?” de forma instantânea.

O sucesso do Self-Healing depende 20% de tecnologia (Lambdas, Streams, Queues) e 80% de entender profundamente as regras de negócio para converter “Dores de Suporte” em “Consultas de Auditoria”.

Compartilhar Chronicles of a Pragmatic Programmer

Conclusão

Há uma verdade desconfortável que todo Tech Lead aprende eventualmente: em sistemas distribuídos, a esperança não é uma estratégia de engenharia.

Nós gastamos horas desenhando diagramas perfeitos no Miro, onde setas conectam microsserviços em uma dança sincronizada. Mas em produção, redes oscilam, brokers engasgam, deploys introduzem bugs e parceiros externos ficam fora do ar. A entropia sempre vence.

A arquitetura de Self-Healing não é sobre construir sistemas que nunca falham; isso é impossível. É sobre construir sistemas que falham com elegância e se recuperam com autonomia.

Ao adotar essa estratégia no seu ciclo de crédito e cobrança, você muda o jogo:

1. Tecnicamente, você para de tratar inconsistências de dados como “incidentes de suporte” e passa a tratá-las como um estado esperado que o próprio software resolve.

2. Culturalmente, você força sua equipe a sair do piloto automático do “Happy Path” e a desenvolver uma obsessão saudável pelos padrões de acesso e pelas regras de negócio.

3. Financeiramente, você protege o ativo mais valioso do banco: a integridade do balanço e a conformidade regulatória.

Implementar Sweepers, garantir idempotência e desenhar para a falha dá trabalho. Exige mais código, mais testes e mais infraestrutura. Mas o retorno desse investimento é a moeda mais valiosa para quem opera sistemas críticos: a tranquilidade.

É a diferença entre ser acordado às 3 da manhã porque “o fechamento não bateu” ou chegar no escritório às 9h, abrir o dashboard e ver que o sistema detectou 50 falhas durante a madrugada — e corrigiu todas elas sozinho, enquanto você dormia.

No fim do dia, programar para o sucesso é fácil. O que separa os sistemas frágeis dos resilientes é o quanto nos preparamos para o inevitável fracasso.

Mas, quando aplicamos essa arquitetura moderna ao crédito — e especificamente à Engenharia de Cobrança — o “Estado da Arte” colide violentamente com o regras e normas!

Na cobrança, a Consistência Eventual não é apenas um detalhe técnico; é um risco jurídico. Um atraso de 500 milissegundos na ingestão de um evento de pagamento pode significar um SMS de ameaça enviado indevidamente a um cliente que acabou de pagar a fatura. O resultado? Dano moral, reclamação no BACEN e prejuízo reputacional.

Como programadores, fomos treinados para lidar com deadlocks, latência e throughput. Mas, na trincheira do sistema financeiro brasileiro, precisamos lidar com variáveis muito mais rígidas: a Resolução CMN 4.966, o arquivo DOC 3040 (SCR), a Lei do Superendividamento e janelas de processamento batch que parecem ter parado nos anos 90.

Não basta que o código compile e os testes passem. O sistema precisa garantir que o “Ledger” (livro razão) sobreviva ao caos de um sistema distribuído, conciliando a velocidade instantânea do Pix com a lentidão burocrática dos arquivos de remessa para o Serasa.

Neste artigo, vamos sair do “Happy Path” da arquitetura e mergulhar nos desafios reais de desenhar sistemas de Cobrança e Crédito.

Bem-vindos ao mundo onde a exatidão vale mais que a performance.

As Regras do Jogo

Vamos ser honestos: a maioria de nós, quando pensa em “requisitos de sistema”, pensa em latência, throughput, escalabilidade e disponibilidade. Se o servidor respondeu em 20ms, o trabalho está feito, certo?

Errado. No mundo financeiro, um sistema performático que ignora a legislação é apenas uma máquina muito eficiente de gerar processos judiciais. Antes de escrevermos a primeira linha de código para cobrar alguém, precisamos entender o campo minado regulatório onde estamos pisando.

O desafio técnico aqui não é apenas “cobrar”. É cobrar de forma cirúrgica, respeitando limites invisíveis que, se cruzados, transformam sua arquitetura em um passivo milionário.

Vamos dissecar os três grandes “chefões” que seu código precisa derrotar antes de mandar aquele SMS.

O Limite do Assédio: Por que você precisa de um Global Rate Limiter

O Artigo 42 do Código de Defesa do Consumidor (CDC) é claro: “Na cobrança de débitos, o consumidor inadimplente não será exposto a ridículo, nem será submetido a qualquer tipo de constrangimento ou ameaça.”

O problema é que, em uma arquitetura de microsserviços, temos múltiplos “atores” independentes tentando recuperar o dinheiro:

1. O microsserviço de SMS quer mandar um lembrete.

2. O sistema de Discador Automático (Dialer) quer ligar.

3. O serviço de Push Notification quer vibrar o celular.

4. O parceiro externo (Assessoria) quer mandar um WhatsApp.

Se cada um desses sistemas trabalhar de forma isolada (o famoso “desacoplamento”), seu cliente receberá 15 contatos em uma manhã. Isso configura assédio.

Além disso, temos a Autorregulação da FEBRABAN (SARB 024), que estabelece normas de conduta, e o “Não Perturbe”.

Como garantir que o Service A saiba que o Service B já ligou para o cliente há 10 minutos?

Aqui morre a ideia de sistemas totalmente independentes. Você precisa implementar um Global Rate Limiter Centrado no Cliente. Não estamos falando de limitar requisições por segundo (RPS) para proteger sua API. Estamos falando de limitar a fricção humana.

Você precisará de uma estrutura de dados compartilhada (provavelmente um Redis ou DynamoDB com TTL) que funcione como o “Guarda de Trânsito” da sua régua de cobrança:

• Chave: interaction:limit:{cpf}:{data}

• Regra: Se count > 3, rejeite qualquer tentativa de contato, não importa o canal.

Seu código precisa ter a inteligência de dizer: “Eu poderia mandar esse SMS agora e ele custaria R$ 0,05. Mas o risco jurídico de mandá-lo após uma ligação telefônica custa R$ 5.000,00 em danos morais. Drop the packet.“

O Relógio Biológico do Cron Job

Você configurou seu Cron Job para rodar às 08:00 da manhã. Lindo. Mas onde está o seu cliente?

Se o seu servidor está em us-east-1 (Virgínia) e são 08:00 UTC, que horas são para o cliente que mora no Acre (-2h de Brasília)? Ou pior: hoje é feriado estadual em São Paulo?

A Lei Estadual 17.334 de São Paulo (e similares em outros estados) proíbe ligações de telemarketing e cobrança em feriados e fora do horário comercial (geralmente 8h às 20h nos dias úteis).

O erro do programador júnior é validar o horário do servidor (DateTime.Now). O acerto do engenheiro sênior é validar o horário do DDD do cliente.

Sua arquitetura de agendamento precisa ser enriquecida com metadados geográficos. Antes de disparar a command para o discador, seu sistema deve consultar uma tabela de feriados nacionais, estaduais e municipais. Se hoje é aniversário da cidade do cliente, seu sistema deve ficar em silêncio. Um Cron burro gera multas inteligentes.

A Lei do Superendividamento (Lei 14.181/2021)

Esta é a legislação mais recente e a que mais impacta a lógica de “Débito Automático” e recuperação de crédito.

A lei introduziu o conceito de “Mínimo Existencial”. Em termos simples: o banco não pode limpar a conta do cliente para cobrir uma dívida se isso deixar a pessoa sem dinheiro para comer.

Antigamente, a lógica do sistema era predadora:

if saldo_conta > 0:
    debitar_divida(saldo_conta) # Pega tudo o que der!

Hoje, esse código é ilegal sob certas condições. A Lei 14.181 exige que as instituições previnam o superendividamento e garantam a dignidade do consumidor.

O Impacto no Código: Seu motor de cobrança não pode mais olhar apenas para o Saldo e para a Dívida. Ele precisa ter acesso (ou estimativa) da Renda e do Comprometimento de Renda desse cliente. A lógica de Business Rule precisa evoluir para: “Se eu debitar essa parcela agora, vou consumir mais de X% da renda mensal declarada desse CPF? Se sim, aborte ou debite um valor parcial.”

Isso exige uma orquestração de dados muito mais complexa. O serviço de Cobrança precisa consultar o serviço de Cadastro/Renda em tempo real (ou ter esses dados cacheados) antes de efetuar o settlement da parcela.

A Matemática da Perda

Se o tópico anterior tratava de como falar com o cliente, este trata de como contabilizar o cliente. E aqui reside uma das maiores armadilhas para times de engenharia que migram de sistemas legados para arquiteturas modernas.

Durante décadas, o sistema financeiro brasileiro operou sob a lógica da Resolução 2.682/99. Para um programador, essa resolução era um sonho. Ela era determinística, baseada em regras rígidas (”Hard Rules”). O algoritmo era basicamente uma escada simples:

// A Lógica Antiga (Resolução 2.682) - O sonho antigo do dev
if (atraso <= 14) return Rating.A;
else if (atraso <= 30) return Rating.B;
// ...
else if (atraso > 360) return Status.Prejuizo; // Write-off

Era confortável. Você esperava o problema acontecer (o atraso) para então reagir contabilmente. Chamávamos isso de Perda Incorrida (Incurred Loss). O banco só admitia que perdeu dinheiro quando o dinheiro já tinha sumido há um ano.

Mas, em 2025 (com a plena vigência da Resolução CMN 4.966/2021), o jogo mudou. O Brasil adotou o padrão internacional IFRS 9. A lógica de “Perda Incorrida” morreu. Bem-vindos à era da Perda Esperada (Expected Loss).

Por que isso MUDA a sua arquitetura?

Porque o provisionamento contábil (quanto dinheiro o banco precisa separar para cobrir calotes) não é mais um reflexo do passado, mas uma projeção do futuro.

Seu sistema não pode mais ser apenas um repositório passivo de transações. Ele precisa ser um motor de cálculo de risco. A resolução divide a vida do contrato em três estágios (Stages), e o seu código precisa saber transitar o cliente entre eles dinamicamente:

• Estágio 1 (O cliente “bom”): O cliente pagou em dia. Tudo certo? Não. Pela norma, você já precisa calcular a probabilidade dele não pagar nos próximos 12 meses e provisionar um percentual disso. O sistema precisa consumir modelos de risco mesmo para quem nunca atrasou.

• Estágio 2 (O sinal amarelo): Aqui a complexidade explode. Se o “Risco de Crédito” aumentou significativamente (ex: o score do cliente caiu no Bureau, ou ele atrasou meros 5 dias), você não provisiona mais 12 meses. Você provisiona a perda esperada para a vida inteira do contrato.

  • Desafio Técnico: Seu sistema precisa detectar “Gatilhos de Risco” (Triggers) externos, não apenas olhar para a sua própria tabela de faturas.

• Estágio 3 (O Ativo Problemático): Esqueça os 360 dias da regra antiga. O novo “game over” é 90 dias.

  • Se o cliente atrasar mais de 90 dias, o contrato é considerado “Ativo Problemático” (Default). A engenharia precisa marcar esse contrato como deteriorado muito antes. Se o seu job de Write-off1 ainda roda procurando por days_overdue > 360, seu banco está carregando “lixo contábil” no balanço por 270 dias a mais do que deveria. Isso distorce o lucro líquido e atrai a fúria dos auditores.

Documento 3040 (SCR)

Toda essa lógica complexa desemboca em um único ponto crítico de falha: o Documento 3040 (o famoso SCR - Sistema de Informações de Crédito do Banco Central).

Para o desenvolvedor desavisado, o 3040 é “apenas um XML chato” que precisa ser gerado e enviado via FTP até o 9º dia útil do mês seguinte. Para o banco e para o cliente, o 3040 é a verdade absoluta.

Aqui está o cenário de pesadelo que acontece quando a consistência eventual falha na geração desse arquivo:

1. O cliente paga a dívida no dia 28.

2. Seu microsserviço de Ingestion recebe o pagamento, mas falha ao atualizar a tabela de “Estado Contábil” (usada para gerar o relatório).

3. O job do 3040 roda no dia 5 do mês seguinte, lê a tabela desatualizada e envia para o BACEN que aquele cliente ainda está em “Prejuízo”.

4. O cliente tenta financiar um apartamento em outro banco e é negado porque “consta prejuízo no SCR”.

5. O cliente processa o seu banco. E ele vai ganhar.

Então o SCR não é um log. O SCR é a reputação financeira do cidadão. A geração desse arquivo não pode ser baseada em um SELECT simples em uma réplica de leitura com lag. Ela exige processos de Reconciliação Prévia.

Antes de gerar o XML para o BACEN, seu sistema deve rodar uma rotina de “Sanidade de Dados”:

• Check: O saldo contábil bate com a soma das parcelas abertas?

• Check: Existem pagamentos processados no Gateway que não foram baixados no Core?

• Check: Há clientes marcados como “Prejuízo” que receberam pagamentos recentes?

Se a resposta for “sim” para qualquer inconsistência, o sistema deve alertar um humano ou auto-corrigir antes de enviar o arquivo. Enviar dados errados para o BACEN não é um bug, é uma infração regulatória sujeita a multas e, em casos extremos, intervenção.

Na engenharia de crédito, a exatidão dos dados é a única feature que realmente importa no final do mês.

Negativação, Bureaus e o Legado que Sobrevive

Se o provisionamento é silencioso e contábil, a Negativação é barulhenta e destrutiva.

Quando você marca um cliente como inadimplente no seu banco de dados, o problema é interno. Mas quando você envia esse nome para os Bureaus de Crédito (Serasa, Boa Vista, SPC), você está acionando a “opção nuclear”. Você está efetivamente impedindo aquela pessoa de alugar um apartamento, financiar um carro ou obter um cartão de crédito em qualquer outro lugar.

Para um Engenheiro de Software, integrar com APIs RESTful modernas é lazer. Mas integrar com o ecossistema de proteção ao crédito é arqueologia.

A Sopa de Letrinhas (PEFIN e REFIN) e os Arquivos Posicionais

Esqueça JSON, gRPC ou GraphQL. A linguagem universal da negativação no Brasil ainda é o Arquivo de Texto Posicional (Flat File).

• O Que São: Estamos falando de arquivos .txt onde a posição exata do caractere define o dado. Do caractere 1 ao 11 é o CPF; do 12 ao 20 é o valor; do 21 ao 28 é a data. Se você inserir um espaço em branco extra na linha 4000, o arquivo inteiro é rejeitado e nenhuma negativação acontece naquele dia.

• Os Protocolos: Esses arquivos geralmente viajam via SFTP ou ferramentas corporativas jurássicas como o ConnectDirect (C:D). Não existe HTTP 200 OK. Existe “O arquivo foi depositado na pasta”. Se ele foi processado com sucesso? Você só vai saber amanhã, lendo o arquivo de Retorno.

• PEFIN vs. REFIN:

  • PEFIN (Pendência Financeira): Usado para dívidas gerais (varejo, telecom, etc.).

  • REFIN (Pendência Bancária): Exclusivo para dívidas com instituições financeiras. Seu sistema precisa saber exatamente qual layout usar, ou a remessa volta.

Você construiu uma arquitetura linda, Event-Driven, rodando no Kubernetes, que cospe eventos o dia todo. Mas se você utiliza o Serasa, ele trabalha em Batch (posso afirmar isso pois trabalho com sistemas que geram esses arquivos posicionais do sistema Sisconvem). Eles não querem um evento a cada cliente que atrasa. Eles querem um arquivo, uma vez por dia (geralmente na madrugada), consolidando tudo. O seu desafio é criar uma janela de agregação robusta: você precisa acumular o estado do dia, gerar esse arquivo monolítico sem corromper os dados e transmiti-lo com segurança.

A Regra de Ouro: Os 5 Dias da “Baixa”

Aqui é onde a tecnologia encontra o tribunal.

Segundo o Código de Defesa do Consumidor e a Súmula do STJ, após o cliente pagar a dívida, a instituição financeira tem um prazo máximo de 5 dias úteis para retirar o nome dele dos órgãos de proteção (dar a “Baixa”).2

Onde mora o perigo para o Engenheiro: Imagine o seguinte cenário de “Tempestade Perfeita”:

1. Sexta-feira, 16:00: O cliente paga a dívida via Pix. Seu microsserviço de Payment processa e emite o evento DebtSettled.

2. Sexta-feira, 23:00: Seu Cron Job que gera o arquivo de “Exclusão de Negativação” para o Serasa falha silenciosamente (talvez um erro de memória ou timeout na conexão SFTP).

3. Sábado e Domingo: Ninguém olha os logs.

4. Segunda-feira: Feriado bancário. O batch não roda.

5. Terça-feira: O time descobre a falha. O arquivo é gerado e enviado à noite.

6. Quarta-feira: O Bureau processa o arquivo.

Você está perigosamente perto de estourar o prazo. Se o processamento do Bureau atrasar mais um dia, o nome do cliente continua sujo ilegalmente.

Se esse cliente tentar um financiamento na quarta-feira e for negado, ele tira um print da tela, processa seu banco por Danos Morais In Re Ipsa (dano presumido, que não precisa de prova do prejuízo) e ganha. A falha do seu Cron Job acabou de custar R$ 10.000,00 ao banco.

Aqui está o desenvolvimento do tópico, conectando a dor financeira (o prejuízo de R$ 10k) à solução arquitetural (FSM), escrito com a profundidade técnica que você pediu.

Por que a Ignorância do Domínio é o seu Maior Bug

Depois de ler sobre leis, arquivos posicionais e regras do Banco Central, você, engenheiro de software, pode estar se perguntando: “Por que eu preciso saber a diferença entre PEFIN e REFIN? Eu fui contratado para escrever Go/Java/C#, configurar Kubernetes e otimizar queries, não para ser advogado.”

A resposta é dura, mas necessária: Em sistemas financeiros, não existe separação entre “Código” e “Regra de Negócio”. O código É a regra.

Se você desenha uma arquitetura sem entender as restrições legais e as limitações dos parceiros legados, você não está criando um sistema moderno; você está criando uma máquina de gerar passivos trabalhistas e cíveis em alta velocidade.

Vou descrever 3 motivos pelos quais o Engenheiro de Software precisam dominar o negócio antes de sair codificando que nem loucos 😂 :

1. Você é o Tradutor da Lei (Domain-Driven Design na Veia)

O documento que o BACEN publica é um PDF escrito por advogados e economistas. O documento que o servidor executa é um binário compilado. Quem faz a tradução de um para o outro? Você.

Se você não entender o que significa “baixa de pagamento em 5 dias”, você vai implementar uma fila de baixa com prioridade baixa. Quando o sistema ficar sobrecarregado, essa fila vai atrasar. O código funcionou (não deu erro 500), a infraestrutura aguentou, mas a lei foi quebrada. O engenheiro precisa praticar o verdadeiro DDD (Domain-Driven Design). As entidades do seu código (OverdueDebt, GracePeriod, ProvisioningBatch) devem refletir exatamente os termos regulatórios. A ignorância do domínio gera “bugs conceituais” que nenhum teste unitário pega, mas que a auditoria do BACEN pega em segundos.

2. A Ilusão da “Caixa Preta” e o Respeito ao Legado

É tentador olhar para arquivos posicionais e mainframes como “dinossauros” que devem ser ignorados ou encapsulados numa caixa preta mágica. Mas a realidade é que o dinheiro do país roda nesses trilhos.

Ignorar como um arquivo CNAB funciona não é “ser moderno”, é ser imprudente.

• Se você não sabe que o arquivo tem um limite físico de tamanho ou horário de corte, você vai desenhar um sistema de streaming que acumula dados infinitamente e estoura a janela de envio na madrugada.

• Entender o legado te dá a humildade necessária para construir sistemas de Resiliência Adaptativa: “Meu sistema voa baixo em Kafka, mas o parceiro anda de bicicleta. Eu preciso construir um freio (Backpressure) eficiente para não atropelar quem recebe meus dados.”

3. Resiliência Financeira > Resiliência Técnica

Em um e-commerce, se o serviço de “Recomendação de Produtos” cair, o usuário compra menos. É ruim, mas aceitável. Em crédito, se o serviço de “Cálculo de Juros” tiver um bug de arredondamento ou cair durante o processamento do lote noturno:

1. Você cobra o valor errado de 500.000 pessoas.

2. Você é obrigado por lei a devolver o dobro do que cobrou indevidamente (Repetição de Indébito).

A resiliência aqui não é apenas sobre o sistema estar “Online” (Uptime). É sobre o sistema estar Correto (Data Integrity). Engenheiros de crédito precisam ser paranoicos. Precisamos de Dead Letter Queues não só para reprocessar, mas para auditar. Precisamos de idempotência não só para evitar erro de banco, mas para evitar cobrar duas vezes. A arquitetura precisa ser desenhada assumindo que errar custa milhões, não apenas latência.

Vamos analisar estrategias que podem nos ajudar a superar esses desafios!

Compartilhar Chronicles of a Pragmatic Programmer

Do “Boolean” à Máquina de Estados (Finite State Machine)

Lembra daquele cenário catastrófico que desenhamos… Aquele em que um simples Cron Job falha, o cliente processa o banco por danos morais e você perde judicialmente?

A raiz desse problema raramente é “o servidor caiu”. A raiz geralmente é uma gestão de estado pobre.

Quando construímos sistemas de cobrança, a tentação de modelar o status de uma fatura como um simples campo no banco de dados (is_paid: boolean ou status: string) é imensa. É rápido, é fácil e funciona nos testes unitários.

Para evitar o prejuízo financeiro e o caos jurídico, precisamos parar de tratar estados como “labels” e começar a tratá-los como um Grafo Direcionado.

A Falácia do “Pago vs. Não Pago”

Engenheiros adoram binários. Zero ou Um. True ou False.

O problema é que a vida financeira de um cliente não é binária. Ela é um espectro de matizes cinzentos regulados por leis e regras de negócio.

Vamos olhar para a realidade. Um contrato de crédito (CreditContract) e uma cobrança (BillingCollection) possuem ciclos de vida distintos, mas entrelaçados. Tentar resolver isso com if (atraso > 5) espalhados pelo código é pedir para ter bugs.

Considere a complexidade real de um Contrato de Crédito:

1. Em Pré-Análise: O cliente pediu, o motor de risco está rodando.

2. Pendente de Assinatura: Aprovado, mas falta o aceite formal (aqui entra a esteira de formalização).

3. Assinado/Ativo: O dinheiro caiu na conta, o contrato está vigente.

Até aqui, é o “Happy Path”. Mas e quando a primeira fatura vence e o pagamento não cai?

O contrato continua Ativo, mas o estado da cobrança muda. E é aqui que a Máquina de Estados (FSM) salva sua vida.

Modelando a Inadimplência com FSM

Precisamos entender que cliente não vira inadimplente no minuto seguinte ao vencimento. Existe uma jornada de estados que seu sistema precisa respeitar rigorosamente para não quebrar a lei (lembra do Tópico 1?):

1. Estado Overdue_Grace (Atraso Técnico): O vencimento foi ontem. O cliente não pagou. O estado muda para Overdue, mas entra numa sub-categoria de Grace Period (ex: 3 dias).

   • Ação Permitida: Enviar “Lembrete amigável” (Push).

   • Ação Bloqueada: Negativar no Serasa ou Bloquear o Cartão. A FSM proíbe a transição para Blocked ou Negative_List enquanto estiver na Grace Window.

2. Estado Overdue_Collection (Cobrança Ativa): Passou o período de graça.

   • Gatilho: DaysPastDue > 5.

   • Transição de Contrato: Aqui, a FSM do contrato escuta o evento da cobrança e transiciona o contrato de Active para Blocked (Bloqueio de novas compras).

   • Transição de Cobrança: O sistema começa a calcular multas e juros diários. O dialer é autorizado a ligar.

3. Estado Legal_Collection (Ajuizado): O atraso superou 60 ou 90 dias (dependendo da política).

   • Ação: O contrato sai da esfera amigável e vai para um Escritório de Cobrança Terceirizado.

   • Guard Clause (Cláusula de Guarda): O sistema não pode aceitar um pagamento parcial simples via app sem antes entender se ocorreu uma renegociação… Se o cliente paga um valor avulso "por fora" via App, ele pode estar quebrando um acordo jurídico que está sendo desenhado pelo escritório parceiro, além de ignorar outros calculos. Nesse estado, a FSM deve bloquear a geração de boletos padrão e forçar o cliente para o fluxo de "Renegociação/Acordo".. A FSM bloqueia pagamentos padrão e exige uma renegociação.

Por que tudo isso pode evitar prejuízo?

A beleza da Máquina de Estados é o Determinismo e a Idempotência.

Imagine o cenário do “Race Condition” do pagamento:

• O sistema recebe o evento PaymentReceived.

• A FSM tenta transicionar o estado de Overdue para Paid.

• Sucesso: O contrato é desbloqueado (Blocked -> Active).

• 1 segundo depois: O mesmo evento chega novamente (duplicidade no Kafka ou retry do Gateway).

• A Mágica: A FSM olha o estado atual. Já é Paid. A transição Paid -> Paid é uma operação nula (ou idempotente). O sistema ignora.

Sem FSM, o código imperativo tradicional (if status == 'Overdue') poderia tentar desbloquear o contrato duas vezes, ou pior, somar o saldo do cliente duas vezes, gerando um crédito indevido que o cliente vai gastar e você vai perder.

Clareza para o Negócio (A Linguagem Ubíqua)

Por fim, abandonar as strings e números mágicos traz sanidade mental para a equipe.

Ninguém sabe o que status = 4 significa. O analista de suporte não sabe, o PM não sabe e o dev novo vai ter medo de mexer.

Mas quando você modela seus estados explicitamente no código (seja usando Enums ricos em Java/C# ou Types em TS), você cria um glossário vivo:

• CONTRACT_STATUS.WAITING_SIGNATURE

• CONTRACT_STATUS.ACTIVE_IN_ARREARS (Ativo, mas devendo)

• CONTRACT_STATUS.WRITTEN_OFF (Prejuízo contabilizado)

Isso permite que analistas de negócio desenhem réguas de cobrança baseadas em estados reais, e não em suposições. Eles podem dizer: “Se o cliente entrar em ACTIVE_IN_ARREARS por mais de 10 dias, dispare o evento para o CRM”.

Não deixe o estado do seu cliente ser definido por um booleano solto no banco de dados. Construa uma Máquina de Estados que reflita a jornada legal e financeira do contrato. É a diferença entre um sistema que “acha” que o cliente deve e um sistema que sabe exatamente em qual etapa da régua de cobrança o cliente está — e o que é legalmente permitido fazer com ele naquele momento.

Agora chegou o momento de falarmos sobre Anti-Corruption Layer

Anti Corruption Layer Pattern

Para entender o Anti Corruption Layer Pattern, imagine que a sua empresa (o Sistema de Cobrança) é uma frota gigantesca de Motoboys.

• Eles são rápidos.

• Eles chegam a todo momento (Real-time).

• Eles trazem pacotes pequenos (Eventos de Pagamento, Atrasos).

• Eles falam gíria, são ágeis e mudam de rota fácil.

Agora, imagine que o Sistema Legado (Serasa, Bacen, Mainframes) é um Navio Cargueiro Transatlântico.

• Ele é lento e pesado.

• Ele só atraca no porto uma vez por dia, às 02:00 da manhã (Janela Batch).

• Ele só aceita contêineres de aço padronizados e soldados (Arquivos Posicionais).

• Ele não muda de rota. O capitão é rígido e segue regras de 1990.

Onde está o Problema? (A Corrupção)

Se você tentar mandar seus motoboys entregarem os pacotes diretamente no navio, o caos acontece:

1. Impedância: O motoboy chega às 10:00 da manhã. O navio não está lá. O motoboy fica esperando? Ele larga o pacote na água? (Perda de Dados).

2. Protocolo: O motoboy tenta jogar o pacote no convés. O capitão grita: “Aqui só entra Contêiner ISO 668!”. O motoboy não sabe o que é isso.

3. Catástrofe: Se 50.000 motoboys tentarem subir na prancha do navio ao mesmo tempo, a prancha quebra (DDoS no parceiro).

Onde está o ACL? (O Pátio de Logística)

O Anti-Corruption Layer é o Armazém/Pátio do Porto que fica entre a rua (seus microsserviços) e o mar (o legado).

1. Recepção (Ingestão): O ACL recebe os motoboys o dia todo. Ele diz: “Obrigado, pode ir embora, eu assumo daqui”. (Desacoplamento).

2. Organização (Agregação): O ACL pega os pacotes pequenos, traduz as etiquetas (De: “Cliente Pagou” Para: “Código 06”) e vai enchendo um contêiner virtual estacionado no pátio.

3. Despacho (Batch): Às 02:00 da manhã, quando o Navio encosta, o ACL pega aquele contêiner perfeitamente arrumado e coloca no navio de uma só vez.