Engenheiros recebem um guia de campo para sistemas fintech

O Fintech Engineering Handbook apresenta um conjunto prático de padrões para engenheiros que constroem software em torno de dinheiro, desde o design de ledger e idempotência até webhooks, reconciliação, controles de acesso e testes em produção.

O handbook atende engenheiros que entram em fintech vindos de outras áreas de software. Um app social pode se recuperar de uma notificação duplicada. Um sistema financeiro não pode ignorar um saque duplicado, uma tarifa arredondada para baixo ou um registro de liquidação ausente. O guia enquadra esse trabalho em torno de três regras: não invente dados, não perca dados e não confie em sistemas externos ou internos sem validações.

A primeira lição começa com a representação. Dinheiro precisa de um valor e uma moeda, armazenados com precisão suficiente para a tarefa. O handbook alerta contra tipos de ponto flutuante para valores financeiros porque parsers e runtimes comuns podem introduzir erros de arredondamento na borda de um sistema que, de outra forma, seria cuidadoso. Ele orienta as equipes para unidades mínimas fixas, decimais de precisão arbitrária, números racionais ou uma mistura dessas abordagens, dependendo de o sistema armazenar saldos, calcular taxas ou lidar com criptoativos.

Essa distinção importa. Um saldo fiduciário de $12.34 pode caber como 1.234 centavos sob os metadados da moeda em ISO 4217. Um token cripto pode usar 18 casas decimais e estourar um inteiro de 64 bits. Um número JSON simples pode desfazer um design interno cuidadoso se um cliente o interpretar como um double IEEE 754. O handbook incentiva os engenheiros a enviar dinheiro como strings ou inteiros da menor unidade em vez disso.

O guia trata o arredondamento como uma decisão de negócio, não como uma preocupação de formatação. Cálculos de tarifas, conversões de moeda, juros e aplicações de taxas podem criar frações que o sistema precisa alocar. As equipes precisam escolher quem recebe ou perde o restante, registrar o resíduo e evitar arredondar até uma fronteira como persistência ou exibição. Se uma plataforma divide um pagamento em várias partes, as partes arredondadas podem não somar de volta ao valor original. O handbook orienta as equipes a rastrear essa diferença em vez de escondê-la.

A seção de ledger dá ao handbook seu centro de gravidade. O guia explica a contabilidade de partida dobrada como um padrão de engenharia: cada movimento credita uma conta e debita outra, então o dinheiro tem uma origem e um destino. Provedores externos também recebem contas. Saldos de usuários vêm de lançamentos, e não de campos de saldo mutáveis. Correções acontecem por meio de novos lançamentos vinculados, não de edições em registros já lançados.

Essa abordagem oferece aos auditores um rastro. Um sistema financeiro precisa explicar o que aconteceu, quem acionou, quando o sistema registrou, por que aconteceu e quais dados de origem sustentaram a decisão. O handbook separa tempo de valor, tempo de lançamento contábil e tempo de liquidação porque essas datas respondem a perguntas diferentes. Uma transação de cartão pode ocorrer na segunda-feira, entrar no sistema da empresa na terça-feira e liquidar no banco na sexta-feira. Colapsar essas datas em um único campo created_at apaga fatos que a equipe não consegue reconstruir depois.

O handbook também trata event sourcing com cuidado. O event sourcing pode dar às equipes um rastro de auditoria forte porque o log de eventos se torna a fonte para o estado derivado. O guia não o vende como uma resposta universal. Engenheiros ainda precisam de projeções, snapshots, evolução de schema e ferramentas para eventos antigos que precisam sobreviver por anos. Para muitos domínios ao redor, o handbook diz que um modelo convencional com um log de mudanças confiável pode atender à necessidade com menor custo operacional.

Padrões de execução ocupam outra grande parte do guia. Idempotência recebe atenção especial porque sistemas de fintech reexecutam chamadas por design. Uma solicitação de saque pode expirar depois que o provedor a recebe. O cliente pode tentar novamente. O servidor precisa consolidar essas entregas em um único efeito. O handbook favorece chaves explícitas de idempotência delimitadas por cliente e operação, além de barreiras atômicas que lidam com duas solicitações duplicadas chegando ao mesmo tempo.

A reserva de fundos lida com outra condição de corrida. Antes de uma plataforma enviar dinheiro ou chamar um provedor de compliance, ela reserva o valor necessário contra o saldo disponível do usuário. O usuário ainda é dono dos fundos, mas o sistema impede que outra transação gaste a mesma quantia. O guia deixa claro um requisito rígido: verificar o saldo e registrar a reserva precisam de forte consistência. Uma leitura desatualizada pode permitir que dois saques passem sobre os mesmos fundos.

O handbook não finge que reservas eliminam saldo negativo. Sistemas externos podem forçar saldos negativos por liquidação maior que a esperada, reversões, chargebacks ou tarifas atrasadas. O guia adverte os engenheiros contra codificar saldos não negativos como um tipo sem sinal ou uma restrição de banco de dados que rejeita a realidade. Um sistema que não consegue representar saldo negativo pode quebrar, truncar o valor para zero ou criar dinheiro por meio de um caminho de correção ruim. O handbook orienta as equipes a registrar o saldo negativo, investigá-lo e recuperá-lo por meio de depósitos futuros, reembolso ou uma conta de perda.

Integrações externas recebem a mesma desconfiança. Processadores de pagamento, bancos, custodians, fornecedores de KYC, fornecedores de AML, nós de blockchain e serviços internos podem retornar payloads malformados, registros desatualizados, mensagens duplicadas ou silêncio. O handbook aconselha as equipes a validar os campos de que dependem, armazenar requests e responses em formato consultável e fazer contas rápidas contra as cotas do provedor antes que o tráfego exponha um limite.

Webhooks recebem um tratamento direto. Um webhook deve disparar uma verificação, não liquidar um fato. O guia recomenda verificar assinaturas sobre bytes brutos, salvar o payload bruto, responder rapidamente e processar o trabalho fora do caminho da request. As equipes devem consultar a API do provedor para o estado atual e criar jobs de reconciliação para os webhooks que nunca chegam. O mesmo evento pode chegar duas vezes ou fora de ordem, então os handlers de webhook precisam de idempotência e verificações de estado.

O handbook conecta esse padrão à publicação confiável. Um sistema que atualiza seu banco de dados e envia um evento Kafka ou um webhook de saída em uma etapa separada pode falhar entre as duas. O guia descreve o padrão outbox, change data capture e event sourcing como respostas práticas. Ferramentas como Debezium, AWS Database Migration Service, Temporal, Camunda, e AWS Step Functions cobrem partes desse espaço, embora cada uma traga seu próprio modelo e custo operacional.

A reconciliação atua como a rede de segurança. O handbook incentiva as equipes a comparar seu ledger com processadores, bancos, custodians, blockchains e outras fontes independentes. Uma divergência pode significar dados ausentes, valores diferentes, liquidação desatualizada ou transferências em lote de um para muitos. O guia adverte contra sobrescrever um lado para deixar um relatório verde. Engenheiros precisam de correções de primeira classe, caminhos de reprocessamento e lógica de correspondência que respeite o tempo de liquidação.

A seção de controles amplia a ideia de desconfiança para funcionários e sistemas dentro da empresa. Operações sensíveis com dinheiro, mudanças de tarifas, deploys em produção e mudanças de infraestrutura podem exigir segregação de funções ou aprovação maker-checker. A própria aprovação precisa de um registro: solicitante, aprovador, motivo, timestamp e prova de que a mesma pessoa não desempenhou ambos os papéis. O controle de acesso recebe o mesmo tratamento por meio de privilégio mínimo, acesso baseado em papéis, trilhas de mudanças e revisões periódicas.

Os testes encerram o handbook com técnicas que se ajustam melhor ao estado financeiro do que verificações apenas baseadas em exemplos. Testes baseados em propriedades podem gerar sequências de operações e afirmar que os livros fecham após cada etapa. Injeção de falhas pode matar um fluxo de longa duração entre cada par de etapas e provar que um worker consegue retomá-lo. Testes golden podem fixar quebras de tarifas ou extratos em saídas revisadas. Testes de compatibilidade retroativa podem manter payloads de eventos antigos legíveis após mudanças de schema.

Os exemplos end-to-end do handbook tornam os padrões concretos. Um saque de cripto combina envio idempotente, reserva de fundos, checagens de compliance, broadcast on-chain, profundidade de confirmação, lançamentos em ledger, liquidação de tarifas e reconciliação da cadeia. Um depósito com cartão mostra por que uma plataforma deve tratar um webhook de capture como um sinal, creditar por meio de uma conta de clearing, aguardar a liquidação e lidar com chargebacks por meio de reversões vinculadas. Uma conversão in-app com cashback mostra por que spread, arredondamento, taxas de referência e dinheiro promocional precisam todos de lançamentos no ledger.

O projeto não anuncia financiamento, investidores ou um lançamento comercial. Sua posição de mercado vem de uma lacuna diferente: muitos engenheiros entram em fintech com fortes habilidades em sistemas distribuídos, mas pouca exposição à contabilidade, liquidação, custódia, verificações de sanções, chargebacks e evidência de auditoria. O handbook empacota essas preocupações como padrões de software, e não como folclore financeiro.

Isso torna o guia útil além das startups de fintech. Qualquer equipe que armazene saldos, mova ativos, credite fundos promocionais, emita relatórios financeiros ou integre com provedores de pagamento enfrenta a mesma pressão. Software de dinheiro falha nas frestas entre serviços, timestamps, retries e overrides humanos. O handbook oferece aos engenheiros um vocabulário para essas frestas e um conjunto de controles que eles podem transformar em código.