Fintech & Agronegócio
Motor de apuração de cashback para programa de fidelidade no agronegócio
Contexto
Uma multinacional do agronegócio mantém um programa de fidelidade que dá cashback a agricultores pela compra de insumos via distribuidores e cooperativas. O motor que calcula quanto cada agricultor tem direito a receber era operado por uma consultoria externa. O objetivo era internalizar esse motor e tirar a empresa da dependência operacional de um fornecedor para uma função financeira crítica. O escopo foi deliberadamente recortado numa primeira versão paliativa: entregar rápido o essencial — cálculo em reais convertido direto em cashback via um único parceiro de pagamento — cortando features caras (moeda virtual própria, expiração de saldo, conversão em pontos, integração completa com o app do programa) que ficam para a versão definitiva.
Desafio
Assumir um cálculo financeiro que já estava em produção, com histórico de pagamentos herdado do fornecedor anterior, sem duplicar nem perder um centavo na virada. Cada rodada precisa reconciliar o novo cálculo contra o que já foi pago (incluindo a herança), aplicar automaticamente limites regulatórios e antifraude, e despachar o pagamento para um parceiro externo que não deduplica requisições — exigindo um protocolo de idempotência desenhado a partir de conversa direta com o fornecedor.
Abordagem
- Pipeline orientado a eventos: nota fiscal (sell-out) importada em batch diário via data warehouse e Glue Jobs → engine de elegibilidade (grupo agrupador de comprador, ativação de voucher, vigência de campanha, allowlist de produto, mix mínimo) → engine de cálculo (combos, aceleradores entre campanhas, dose por hectare equivalente, melhor combinação para o comprador) → guardrails → carteira → dispatch.
- Guardrails financeiros embutidos no cálculo (não um módulo à parte): bloqueio automático de benefício acima de um teto percentual da nota, por item e agregado, detecção de duplicidade, retenção por saldo devedor e blocklist por campanha.
- Carteira de cashback por agricultor em ledger (crédito, reserva, confirmação e estorno de conversão), com uma segunda carteira que carrega a dívida/crédito herdado do fornecedor anterior e um processo noturno que amortiza essa herança contra o delta de cada rodada antes de creditar a carteira real.
- Dispatch síncrono ao parceiro de pagamento com protocolo de idempotência: sempre reenviar com a mesma chave em timeout, nunca gerar chave nova para o mesmo dinheiro.
- Backend 100% serverless em AWS (Node.js/TypeScript): Lambda orquestrado por CDK v2, Step Functions para os fluxos longos, EventBridge para desacoplamento assíncrono, DynamoDB transacional e S3 como data lake/auditoria, API Gateway REST versionada e contract-first via OpenAPI.
- Decomposição em 30+ stacks CDK isoladas por domínio (campanha, voucher, elegibilidade, cálculo, carteira, fulfillment, processamento manual, import de sell-out, import histórico, console de aprovações, guardrails), para permitir trocar peças — parceiro de pagamento, moeda virtual — sem reescrever o motor.
- Operação com trava de segurança: motor roda em modo pausado por padrão em produção, toda rodada pode ser simulada em dry-run antes de liberar pagamento real, fila única de pendências acionáveis para operação e trilha de auditoria imutável de qualquer mutação administrativa com retenção de 10 anos.
- Desenvolvimento orientado a spec (requisitos → design → tarefas → changelog por módulo) e 286 arquivos de teste no backend, incluindo testes baseados em propriedade (fast-check) para as mecânicas de cálculo, onde teste por exemplo isolado dificilmente pegaria os casos de borda.
- Painel administrativo interno em Next.js 16 (App Router), React 19, HeroUI e Tailwind, autenticado via Azure AD corporativo e publicado por AWS Amplify.
Resultado
Motor de apuração de cashback construído e em fase de validação, rodando o cálculo novo contra a base histórica do fornecedor anterior antes da virada em produção. Base de 14 milhões de notas fiscais no histórico (média de ~85 mil/dia, pico de 3,5 milhões num único dia), cerca de 30 campanhas simultâneas e 35 mil documentos de clientes na safra atual, com média de 480 conversões de pagamento por dia. Dois bugs reais de unidade monetária (reais × centavos cruzando as fronteiras campanha → cálculo → carteira) documentados e corrigidos, incluindo um fator 100 que se cancelava com um erro espelhado na ferramenta de comparação.