Engenharia de dados aplicada ao Split Payment do Bem

Do arquivo de origem à conciliação financeira com Python, Databricks e inteligência artificial

No artigo “Split Payment do bem e Split Payment do mal”, discuti a divisão comercial dos pagamentos e a segregação tributária. Agora quero acompanhar o dinheiro por dentro dos sistemas. De qual fonte veio o valor? Qual contrato determinou o repasse? O crédito chegou à conta correta?

Para responder, proponho uma arquitetura com um exemplo numérico verificável. O estudo usa mil pagamentos fictícios de R$ 100, quatro parcelas por pagamento e quatro parceiros PJ. O objetivo é mostrar o caminho completo até um painel que permita investigar uma diferença, e não apenas exibir um total.

O “Bem”, neste recorte, está na clareza dos repasses e na capacidade de conferir a parte de cada parceiro. Split comercial não altera sozinho a base tributável. Aqui, a existência de receitas próprias por PJ é uma premissa do exemplo, sujeita à validação contratual e fiscal.

A simulação dos cálculos e da deduplicação foi executada localmente. A infraestrutura Azure, os jobs Databricks, as conexões bancárias e o Power BI são uma proposta de implementação; não foram implantados neste estudo.

As fontes precisam contar a mesma história

Eu começaria pelo inventário das fontes e pelos responsáveis por cada informação. O ERP informa o que foi vendido. O provedor de pagamento informa captura, liquidação e tarifas. O extrato confirma o crédito. A nota fiscal documenta a prestação, mas não comprova, sozinha, que houve pagamento.

Não existe um formato universal de nota fiscal ou extrato. Cada conector precisa conhecer o leiaute efetivamente contratado. Para um banco sem identificador de transação, uso o lote de liquidação e uma tabela de composição; não invento uma correspondência apenas porque dois valores são iguais.

O database controla as regras operacionais

Nesta proposta, o PostgreSQL é o cadastro transacional de contratos e beneficiários. Uma alteração de percentual gera nova versão, com início e fim de vigência, usuário aprovador e trilha de auditoria. O lakehouse recebe esse histórico por CDC ou snapshots versionados. Não consulta o cadastro atual para recalcular indiscriminadamente o passado.

O vínculo entre pedido, nota e pagamento pode ser muitos para muitos. Uma venda pode ter várias notas, e um pagamento pode liquidar mais de uma cobrança. A tabela de associação guarda o valor vinculado e impede que um JOIN multiplique o faturamento no relatório.

Bronze preserva o que realmente chegou

A camada Bronze mantém o conteúdo recebido e os metadados necessários para rastrear sua origem. A Silver valida e harmoniza esses registros; a Gold os organiza para consumo. Essa é a divisão de responsabilidades do padrão medalhão [1]. O desenho das tabelas abaixo é uma proposta específica para este caso.

Do conector ao arquivo original

O coletor Python lê a API com paginação, timeout e retentativas limitadas para falhas transitórias. Registra o cursor confirmado somente depois de persistir o lote. Uma janela de sobreposição recupera atualizações atrasadas; a deduplicação posterior evita contagem dupla. Credenciais ficam em um gerenciador de segredos, nunca no notebook ou no log.

No ADLS, organizo os originais por origem e data de ingestão, com nomes únicos: /landing/psp/ingest_date=2026-10-01/batch_001.json. O arquivo fica preservado segundo a política de retenção. Um hash ajuda a reconhecer reenvios idênticos, mas não substitui a chave do evento de negócio.

Em todas elas, acrescento source_system, source_file, source_record_id, ingested_at, batch_id, payload_hash e schema_version. O identificador original permanece junto do payload. Arquivos ilegíveis entram no registro de falhas com localização e motivo; não desaparecem do controle de recebimento.

Mudança de esquema não pode virar silêncio

O Auto Loader pode controlar a leitura incremental dos arquivos. Cada fluxo recebe seu checkpoint e seu local de esquema. Campos inesperados ou incompatíveis devem ser preservados para inspeção, usando recursos como rescued data [2]. A promoção à Silver depende da aprovação do esquema; um campo monetário inválido não vira zero.

No exemplo local, chegam 4.001 eventos de liquidação: quatro parcelas para cada um dos mil pagamentos, mais um reenvio. A Bronze conserva as duas ocorrências do evento repetido. O valor financeiro só será somado depois da identificação dos eventos únicos.

Silver transforma registros em eventos conciliáveis

Na Silver, cada tabela tem uma granularidade explícita. Valores usam DECIMAL, moeda é obrigatória, datas de evento e ingestão ficam separadas e o CNPJ é tratado como identificador textual. Uma captura e sua liquidação não são dois recebimentos: são eventos distintos do ciclo do pagamento.

Duplicidade e correção são situações diferentes

No caso simulado, a chave identifica provedor, pagamento, parcela, tipo de evento e versão. Um reenvio idêntico é ignorado na visão canônica. Se a mesma chave vier com outro conteúdo, o registro exige investigação. Se a origem enviar uma correção com versão superior, a projeção é atualizada sem apagar a evidência anterior.

Antes de executar MERGE, reduzo o lote a uma decisão por chave. Múltiplas linhas da origem tentando atualizar o mesmo destino podem causar ambiguidade; MERGE, isoladamente, não resolve a duplicidade de entrada [3]. Na simulação local, a deduplicação é feita em memória e representa esse controle, sem executar Spark.

O contrato precisa valer na data do evento

Cada parcela recebe contract_version_id e a regra que determina a data de referência: contratação, venda ou outra data prevista. As quotas devem somar 100%. Contrato ausente, vigência sobreposta, moeda incompatível e valor ilegível vão para quarentena com motivo e responsável. Em produção, centavos residuais seguem uma política determinística de rateio.

O fechamento desta etapa produz 4.000 eventos únicos e 16.000 alocações: mil pagamentos × quatro parcelas × quatro PJs. O reenvio do mesmo lote não cria novo recebimento. Estornos e chargebacks têm eventos próprios, sinal, vínculo e regra de reversão; não apago a venda para fazer o total “bater”.

Os pipelines precisam respeitar suas dependências

Eu usaria Lakeflow Jobs como orquestrador neste desenho. A captura das fontes pode rodar em paralelo. Depois, as tarefas dependem dos resultados anteriores e dos controles de qualidade. Dependências e condições de execução são recursos documentados do produto [4]; as regras de publicação são decisões deste projeto.

Uma tarefa não fica bem-sucedida só porque o processo terminou. O controle do lote registra quantidade recebida, aceita, duplicada e rejeitada; somatórios monetários; horário da fonte; duração e versão do código. A identidade de fechamento é: recebidos = aceitos + duplicados + rejeitados, com categorias exclusivas definidas para cada fluxo.

Se o extrato ainda não chegou, a Gold pode publicar o valor esperado com status parcial. O crédito confirmado permanece indisponível, nunca convertido em zero por conveniência. O fechamento exige as fontes previstas e a reconciliação do lote. O painel mostra a última atualização de cada origem e a cobertura dos dados.

Como ponto de partida, proponho captura do PSP a cada 15 minutos e extratos na frequência oferecida pelo banco. Isso é configuração do projeto, não SLA garantido. Reprocessamentos usam o lote original, as versões das regras e escrita idempotente. Um backfill é executado em recorte controlado antes de substituir resultados publicados.

Uma divergência bancária válida continua visível no painel. Um dado inválido não entra na métrica. Essa separação evita que o controle de qualidade esconda justamente a diferença que o financeiro precisa investigar.

O cálculo separa repasse de provisão tributária

O contrato fictício atribui 40% à PJ A e 20% a cada uma das PJs B, C e D. A tarifa total simulada é 2%, rateada proporcionalmente, sem antecipação ou custo adicional de split. A provisão hipotética é 6% da receita própria de cada PJ. Esses percentuais não representam enquadramento tributário real.

Os valores por parceiro e o efeito no caixa

Valores em reais. O crédito esperado em conta é de R$ 98 mil. Os R$ 92 mil representam o disponível depois de provisionar tributos. Neste caso, não existe retenção tributária automática. Se ela existir em outra operação, registro o evento efetivo separadamente e evito descontar o mesmo tributo duas vezes.

Nas quatro parcelas, o bruto agregado é R$ 25 mil por parcela; a tarifa é R$ 500; o crédito esperado, R$ 24.500. A recebe R$ 9.800 por parcela e cada outro parceiro, R$ 4.900. A provisão proporcional de R$ 1.500 por parcela é uma convenção didática: a apuração real deve seguir competência, regime e regras aplicáveis.

Para ampliar o volume, o pipeline processa mais eventos. Não assumo que um faturamento dez vezes maior manterá a mesma alíquota, tarifa ou custo computacional. O contrato e o sistema fiscal fornecem as regras válidas de cada período.

A Gold entrega um painel que pode ser explicado

Na Gold, separo fatos de repasse, tarifas, posição tributária e conciliação. O primeiro guarda pagamento, parcela e PJ; o segundo guarda cobranças; o terceiro preserva a competência fiscal; o quarto compara esperado e confirmado na granularidade disponível. Dimensões de parceiro, data, provedor e contrato ajudam a navegar sem misturar essas bases.

O painel numérico e a investigação da diferença

Figura 6 • Painel proposto com dados da simulação local. A divergência é exibida como pendência de conciliação, não como perda comprovada.

O filtro do painel precisa dizer qual data está usando: venda, vencimento, liquidação ou competência. Para a diretoria, mostro caixa e diferenças. Para o financeiro, parcelas, prazos e lançamentos. Para cada parceiro, apenas suas linhas e os descontos que lhe pertencem. O controle de acesso fica no modelo e na plataforma, além do filtro visual.

Neste exemplo, a diferença está na PJ D, parcela 4, lote B04: R$ 4.900 esperados e R$ 4.700 confirmados. A tela de detalhe deve abrir a composição do lote, os eventos do PSP, o extrato original e a regra aplicada. Sem essa evidência, a causa permanece “a investigar”.

Também exponho métricas de operação: atraso por fonte, registros em quarentena, duplicados, ausência de contrato e cobertura da conciliação. Um dashboard financeiramente bonito, mas baseado em extrato incompleto, não pode parecer um fechamento definitivo.

Um cálculo pequeno e verificável

O trecho abaixo calcula uma parcela agregada de R$ 25 mil. É a mesma regra usada na simulação local, com Decimal para evitar aritmética monetária em ponto flutuante. Aqui os valores dividem exatamente; uma implementação geral também precisa distribuir resíduos de centavos.

def moeda(valor):
    return valor.quantize(D("0.01"), rounding=ROUND_HALF_UP)

parcela = D("25000.00")
quotas = {"A": D(".40"), "B": D(".20"),
          "C": D(".20"), "D": D(".20")}
assert sum(quotas.values()) == D("1")
credito_total = D("0")
for pj, quota in quotas.items():
    bruto = moeda(parcela * quota)
    tarifa = moeda(bruto * D(".02"))
    provisao = moeda(bruto * D(".06"))
    credito = bruto - tarifa
    disponivel = credito - provisao
    credito_total += credito
    print(pj, credito, disponivel)
assert credito_total == D("24500.00")        

Saída por parcela: A → crédito 9.800,00 e disponível 9.200,00; B, C e D → crédito 4.900,00 e disponível 4.600,00 cada. Provisão não é uma ordem de recolhimento, e o lakehouse não movimenta dinheiro.

O que foi conferido nesta execução

A execução sintética confirmou R$ 100 mil de bruto, R$ 2 mil de tarifas, R$ 98 mil esperados, R$ 97,8 mil confirmados e R$ 6 mil provisionados. Foram preservados 4.001 eventos de entrada e considerados 4.000 eventos únicos. O mesmo lote reenviado manteve a quantidade canônica em 4.000; a soma das 16.000 alocações conservou o bruto.

O que ainda exigiria homologação

A integração real precisa validar autenticação, limites das APIs, parser fiscal, atualização fora de ordem, cancelamentos, mudanças de contrato, centavos residuais, indisponibilidade de fonte e recuperação de checkpoint. O ensaio local comprova as contas deste exemplo; não comprova desempenho, segurança ou operação ponta a ponta em Databricks.

A IA ajuda a investigar com acesso às evidências

O uso mais útil de IA aqui começa depois que o dado ganha contexto. Uma descrição de tarifa pouco clara pode receber uma classificação sugerida. Um contrato novo pode ter cláusulas extraídas para revisão. Uma divergência pode ser resumida com referência aos eventos e documentos que a sustentam. A aprovação das regras continua com os responsáveis pela operação.

No caso dos R$ 200, a resposta esperada seria: “A diferença está no lote B04 da PJ D. O valor esperado foi calculado com o contrato vigente; o extrato confirma R$ 4.700. Consulte o detalhamento do provedor para verificar o valor restante.” Não seria correto afirmar que houve fraude, tarifa extra ou atraso sem a evidência correspondente.

Para implementar, disponibilizo consultas de leitura sobre views aprovadas e documentos permitidos. O assistente recebe o contexto do usuário, aplica o mesmo isolamento por empresa e devolve os identificadores consultados. Não recebe credenciais bancárias, não altera contratos e não executa repasses. PDFs e mensagens são tratados como dados, nunca como instruções para o agente.

Registro a versão do modelo, as fontes usadas e a decisão humana. Avalio respostas contra casos conhecidos: a IA apontou a parcela correta? Citou registros existentes? Reconheceu quando faltava informação? O ganho pode ser medido pelo tempo de triagem e pela taxa de encaminhamentos corretos, sem inventar um percentual de melhoria antes do piloto.

O valor está em conseguir explicar o pagamento

É essa continuidade que quero dar ao Split Payment do Bem. A divisão comercial fica mais compreensível quando conseguimos seguir o valor desde o pedido e a nota até o contrato, a parcela e o crédito em conta. A arquitetura permite discutir o dinheiro com evidência e corrigir o processo na origem.

Se aparecer uma diferença de R$ 200 no fechamento da sua operação, hoje você consegue chegar ao evento que a explica? Ou a investigação ainda começa com uma nova planilha?

Referências técnicas e limites do estudo

[1] Databricks — What is the medallion lakehouse architecture? https://docs.databricks.com/aws/en/lakehouse/medallion

[2] Databricks — Configure schema inference and evolution in Auto Loader. https://docs.databricks.com/aws/en/ingestion/cloud-object-storage/auto-loader/schema

[3] Databricks — Upsert into a Delta Lake table using merge. https://docs.databricks.com/aws/en/delta/merge

[4] Databricks — Configure task dependencies. https://docs.databricks.com/aws/en/jobs/run-if

Fontes consultadas em 8 de outubro de 2026. Arquitetura autoral proposta; números sintéticos. Regras fiscais, prazos, formatos e permissões precisam ser definidos com as áreas responsáveis antes de uma implantação.