Reconciliação de transações em lote para equipes da Vila Guarani: guia prático

Na Vila Guarani, uma equipe de 12 técnicos de manutenção predial atende em média 45 chamados por dia. Cada atendimento gera um pagamento — Pix na hora, boleto para o dia seguinte, cartão parcelado para contratos anuais. Até o mês passado, a conferência desses recebíveis consumia três horas diárias de uma analista financeira que baixava extratos do banco, exportava relatórios do sistema de gestão e cruzava linha a linha no Excel. Uma única divergência de 247,50 reais em um Pix mal identificado levou dois dias para ser resolvida. O cenário mudou quando a empresa adotou a conciliação em lote via API da ViperPay.

O volume de transações diárias de equipes de campo não para de crescer. Segundo dados internos de clientes ViperPay, prestadores de serviço na zona sul de São Paulo processam entre 800 e 2.500 pagamentos por mês por equipe. Sem automação, a conciliação vira gargalo: atrasa o fechamento do caixa, dificulta a previsão de fluxo de caixa e expõe a operação a riscos de fraude e inadimplência não detectada. A solução está em tratar o lote como unidade atômica de processamento, não como soma de transações individuais.

Por que conciliação em lote resolve a dor das equipes de campo

Equipes que atuam na Vila Guarani e bairros vizinhos — como Vila Mariana, Saúde e Jabaquara — operam com alta mobilidade e baixa previsibilidade de meios de pagamento. O cliente paga com o que tem na mão: Pix, cartão por aproximação, boleto gerado na hora. Cada meio tem liquidação, taxa e prazo diferentes. A conciliação em lote da ViperPay normaliza essa diversidade: recebe o arquivo de retorno bancário (CNAB 240 ou 400), parseia cada registro, enriquece com metadados da transação (ID do chamado, técnico responsável, tipo de serviço) e cruza com o que foi efetivamente liquidado no banco.

O ganho não é apenas tempo. A conciliação em lote cria rastreabilidade ponta a ponta. Cada transação recebe um status imutável: “conciliado”, “divergente”, “pendente” ou “estornado”. Divergências são classificadas automaticamente — valor diferente, data diferente, pagador não identificado, duplicidade — e roteadas para o responsável via dashboard ou webhook. A analista financeira da equipe da Vila Guarani hoje gasta 15 minutos por dia revisando exceções, contra 180 minutos do processo manual.

Arquitetura da conciliação em lote na ViperPay

O fluxo técnico segue quatro estágios orquestrados por workers assíncronos:

1. Ingestão: a plataforma puxa arquivos de retorno do banco via SFTP, API bancária (Open Finance) ou upload manual. Suporta CNAB 240, CNAB 400, OFX e CSV padronizado.
2. Normalização: cada registro é transformado em objeto canônico com campos obrigatórios — transaction_id, amount, settlement_date, payer_document, payment_method, fee, net_amount.
3. Casamento (matching): motor de regras compara o objeto canônico com transações pendentes no ViperPay. Usa chaves compostas: external_reference + amount + settlement_date ± 1 dia. Regras de fuzzy matching cobrem variações de nome do pagador.
4. Resultado e notificação: transações conciliadas recebem status final; divergências geram objetos reconciliation_exception com código de erro, descrição e sugestão de ação. Webhooks disparam para o ERP e para o dashboard.

{
  "reconciliation_batch_id": "rec_7f3a9k2m",
  "status": "completed",
  "processed_at": "2024-11-15T14:23:12Z",
  "summary": {
    "total_records": 342,
    "matched": 331,
    "exceptions": 11,
    "unmatched_bank_records": 0
  },
  "exceptions": [
    {
      "code": "AMOUNT_MISMATCH",
      "bank_record_id": "bnk_8x9p",
      "viperpay_transaction_id": "txn_4m7q",
      "bank_amount": 189.90,
      "system_amount": 189.00,
      "suggested_action": "verify_discount_or_fee"
    }
  ]
}

Essa estrutura permite que o ERP da empresa consuma o resultado e atualize contas a receber, comissão de técnicos e relatórios gerenciais sem intervenção humana no caminho feliz.

Regras de matching que funcionam na prática

O segredo da conciliação em lote eficaz está nas regras de matching. A ViperPay permite configurar múltiplas estratégias em cascata:

A regra 1 resolve 92% dos casos em clientes ViperPay. As regras 2 e 3 capturam Pix sem referência externa (chave aleatória) e boletos pagos em lotéricas com data de liquidação diferente. A regra 4 serve como auditoria de integridade do arquivo bancário.

Para a equipe da Vila Guarani, a configuração vencedora foi: prioridade 1 para transações originadas no app da ViperPay (que já carregam external_reference), prioridade 2 para Pix recebidos via chave estática do CNPJ da empresa, prioridade 3 para boletos. Resultado: 98,7% de conciliação automática na primeira passada.

Tratamento de exceções: do alerta à resolução

Exceções não são falhas — são sinais de processo. A ViperPay classifica cada exceção com código padronizado e sugere ação. A equipe financeira da Vila Guarani adotou este fluxo:

1. AMOUNT_MISMATCH: conferir se houve desconto comercial, taxa de antecipação ou juros de mora não previstos. Resolução: ajustar lançamento no ERP ou registrar diferença como despesa financeira.
2. DATE_DRIFT: pagamento liquidou em data diferente da prevista. Comum em boletos pagos sexta-feira (liquida terça). Resolução: aceitar com ajuste de competência.
3. PAYER_NOT_IDENTIFIED: Pix via chave aleatória sem external_reference. Resolução: cruzar com agenda de atendimentos do dia por valor e horário aproximado.
4. DUPLICATE_BANK_RECORD: mesmo registro aparece duas vezes no arquivo do banco. Resolução: marcar como duplicata e ignorar na segunda ocorrência.
5. ORPHAN_BANK_RECORD: transação no banco sem correspondente no ViperPay. Resolução: verificar se foi pagamento direto na conta (transferência espontânea) ou nova venda não registrada.

Cada exceção tem SLA de resolução: 4 horas para AMOUNT_MISMATCH e PAYER_NOT_IDENTIFIED (impactam caixa imediato), 24 horas para as demais. O dashboard mostra contador de exceções por tipo, idade e responsável.

Integração com ERP e rotinas agendadas

A conciliação em lote só entrega valor pleno quando integrada ao sistema de gestão. A ViperPay fornece SDKs e documentação para como integrar a API ViperPay com seu e-commerce de forma segura e rápida, mas o mesmo padrão se aplica a ERPs legados. O padrão recomendado:

1. Agendar job (cron) que roda a cada 4 horas: POST /api/v1/reconciliation/batches/process com bank_account_id e date_range.
2. Job aguarda webhook reconciliation.batch.completed com batch_id.
3. Consome GET /api/v1/reconciliation/batches/{batch_id}/result para obter resumo e exceções.
4. Atualiza ERP: transações conciliadas → baixa de contas a receber; exceções → cria tarefa no módulo financeiro com link para dashboard ViperPay.
5. Loga batch_id, timestamp, resumo e hash do arquivo bancário para auditoria.

Para equipes que preferem processamento noturno único, a ViperPay suporta agendamento nativo na plataforma — dispensa cron externo. Basta configurar horário, contas bancárias e regras de matching no painel. O relatório diário consolidado chega por e-mail às 6h com PDF anexo.

Métricas que a gestão deve acompanhar

Conciliação em lote gera dados para gestão ativa. Os KPIs essenciais:

• Taxa de conciliação automática (matched / total): meta > 95%
• Tempo médio de resolução de exceção (MTTR): meta < 2 horas para críticas
• Volume de exceções por tipo/semana: identifica problemas recorrentes (ex: boletos com data errada)
• Diferença bruta vs. líquida conciliada: garante que taxas e antecipações estão contabilizadas
• Atraso médio de liquidação por meio de pagamento: subsidia negociação de taxas com adquirentes

O gerenciamento eficaz da conciliação financeira com o dashboard ViperPay centraliza esses indicadores em tempo real. A equipe da Vila Guarani usa o relatório semanal para alinhar com a contabilidade e ajustar previsão de fluxo de caixa.

Segurança e conformidade no processamento em lote

Processar arquivos bancários em lote exige controles rigorosos. A ViperPay aplica:

• Criptografia em trânsito (TLS 1.3) e em repouso (AES-256) para arquivos CNAB e resultados.
• Assinatura digital HMAC-SHA256 em webhooks para garantir integridade e autenticidade.
• Controle de acesso baseado em papéis (RBAC): apenas “financeiro_conciliacao” pode disparar reprocessamento ou marcar exceção como resolvida.
• Trilha de auditoria imutável (append-only log) com batch_id, user_id, action, timestamp, before_state, after_state.
• Conformidade LGPD: dados do pagador (CPF/CNPJ) são pseudonimizados em logs e dashboards; acesso ao dado claro requer justificativa e aprovação.

Esses controles permitiram que um cliente ViperPay do setor de saúde passasse em auditoria SOC 2 Tipo II sem achados na esteira de conciliação.

Caso real: da planilha ao painel em 3 semanas

A empresa de manutenção da Vila Guarani seguiu este cronograma:

1. Semana 1: mapeamento de meios de pagamento, contas bancárias, layout CNAB do banco (Itaú CNAB 240), regras de split por técnico.
2. Semana 2: homologação em sandbox — processamento de 3 arquivos históricos, validação de matching, ajuste de regras fuzzy, integração com ERP (Omie) via webhook.
3. Semana 3: produção assistida — conciliação paralela (manual + automática) por 5 dias, comparação de resultados, treinamento da analista no dashboard de exceções. Corte total do processo manual no dia 22.

Resultado após 60 dias: 98,7% conciliação automática, tempo da analista caiu de 15h/semana para 1,25h/semana, zero divergências não resolvidas no fechamento mensal. A equipe financeira redirecionou o tempo ganho para análise de inadimplência e negociação de taxas com adquirentes.

detalhes aqui

Próximos passos para sua equipe

Comece pelo mapeamento: liste todos os meios de pagamento, contas bancárias, layouts de arquivo e regras de negócio (split, comissão, centro de custo). Em seguida, abra conta de teste na ViperPay e processe um arquivo histórico no sandbox. Valide as regras de matching com dados reais antes de automatizar. O investimento inicial é técnico — configuração de regras e integração — mas o retorno vem na primeira semana de produção: fechamento de caixa no mesmo dia, visibilidade total de recebíveis e equipe financeira focada em análise, não em digitação.

A conciliação em lote não é projeto de TI; é habilitador de gestão financeira ágil para equipes que não param. Na Vila Guarani e em qualquer bairro onde o volume de transações supera a capacidade manual, a automação deixa de ser opção e vira condição de crescimento sustentável.

Checklist prático

Perguntas frequentes