fatura-cartao

Imported from barikamal086-jpg/salon.erp (salon-erp/.claude/skills/fatura-cartao/SKILL.md). Install upstream with npx skills add barikamal086-jpg/salon.erp --skill fatura-cartao. Copyright stays with the author.

Fatura de cartão — leitura, validação e conciliação

Uma fatura de cartão mistura três coisas que o ERP precisa separar: compras à vista do período, parcelas de compras antigas e ajustes (crédito, estorno, encargos). O erro clássico é tratar cada compra parcelada como um único lançamento com o valor de uma parcela — o ERP passa a "casar" aquele lançamento com a parcela de qualquer mês e esconde que as outras parcelas nunca foram registradas. Esta skill existe para impedir isso.

Siga as etapas na ordem. Não pule a etapa 4 (validação): ela é o que garante que a leitura está certa antes de qualquer coisa tocar no banco de dados.

Etapa 0 — Confirme o banco de destino antes de gravar

Antes de qualquer INSERT/UPDATE (mesmo os de teste), rode algo que passe por database.js (ex: node -e "require('./database')") e leia o banner 🔌 Conectando em: <host>:<porta>/<banco> que ele imprime. Compare com o banco que você espera (produção = Railway, nunca Supabase depois de uma migração). Isso já existia como bug real desta skill em 2026-09-24: o .env local ficou apontando pro Supabase depois da migração pro Railway, e uma sessão inteira de conciliação foi gravada no banco errado sem ninguém notar até comparar com produção. Se o banco no banner não for o esperado, pare e avise o usuário antes de continuar.

Etapa 1 — Identificar o documento

Anote, a partir do conteúdo do documento (nunca do nome do arquivo, que costuma estar errado):

• Banco e tipo: fatura completa (tem resumo) ou extrato (só lista + total).
• Vencimento: o campo "vencimento" do documento. É a data em que o dinheiro sai.
• Fechamento, se houver.
• Situação: só processe faturas fechadas. Fatura em aberto ainda muda.
• Cartões: uma fatura pode ter vários cartões (finais diferentes), cada um com subtotal.

Depois leia o arquivo do banco em references/bancos/<banco>.md. Se o banco não tiver arquivo, copie references/bancos/_modelo.md, preencha com o que observar nesta fatura e mostre ao usuário antes de seguir.

Etapa 2 — Extrair para JSON

Transcreva todas as linhas, inclusive valores negativos e centavos, para um JSON no formato abaixo. Não resuma, não agrupe, não pule linha "irrelevante".

{
  "banco": "itau",
  "tipo": "fatura_completa",
  "vencimento": "2026-09-28",
  "fechamento": "2026-09-16",
  "situacao": "fechada",
  "resumo": {"anterior": -142.31, "pagamentos": 0, "lancamentos_atuais": 14353.17, "encargos": 0, "total": 14210.86},
  "total_documento": null,
  "cartoes": [
    {"final": "9678", "titular": "YOUNES", "subtotal": 2524.41,
     "itens": [{"data": "18/05", "descricao": "MAK FRIGO REFRIGER04/10", "valor": 530.00}]}
  ],
  "proximas": {"proxima_fatura": 3797.62, "demais_faturas": 7165.05}
}

• resumo = null quando o documento não tem resumo (extrato).
• total_documento = o "Total" do extrato quando não há resumo.
• proximas = null quando o banco não mostra parcelas futuras.
• Mantenha a descrição exatamente como impressa — o sufixo da parcela está nela.

Etapa 3 — Entender as regras universais

Estas regras valem para qualquer banco:

1. A data na fatura é a data da compra, não do pagamento. Uma parcela 4/6 aparece com a data da compra original, meses atrás.
2. O sufixo n/N no fim da descrição é a parcela (atual/total), com n ≤ N. O formato muda por banco (GR04/06, 008/012, 02/06). Cuidado: ANUIDADE 04/12 parece data, mas é parcela 4 de 12.
3. Sem ano na data: a compra é sempre anterior ao fechamento. Se o mês da compra for maior que o mês do fechamento, a compra é do ano anterior.
4. Uma compra parcelada gera N lançamentos ao longo do tempo, um por parcela, cada um só quando a fatura daquele mês é processada — nunca um lançamento só por compra, e nunca as parcelas futuras adiantadas (ver Etapa 8). Regra definitiva de data: despesa de cartão vale no mês do vencimento da fatura, não no mês da compra — vale tanto na Visão Geral quanto no Fluxo de Caixa (as duas telas usam COALESCE(data_vencimento, data)). Uma parcela de compra feita em maio, cobrada na fatura de setembro, é despesa de setembro nas duas telas.
5. Negativos são estorno ou crédito — lançam negativo, não somem.
6. Encargos (juros, IOF, multa, anuidade) são despesa financeira. Nunca CMV.
7. Duas parcelas com o mesmo valor na mesma fatura são compras diferentes. Uma compra não cobra duas parcelas no mesmo mês.
8. Coluna em moeda estrangeira: use sempre o valor em R$ cobrado.

Etapa 4 — Validar (obrigatório)

Rode:

python scripts/validar_fatura.py fatura.json --cronograma cronograma.json

O script confere:

Se qualquer validação falhar, pare. Não lance, não altere e não "ajuste" valores para fechar a conta. Mostre ao usuário a diferença e as linhas suspeitas — quase sempre é linha pulada ou valor transcrito errado.

O script também gera cronograma.json: cada compra parcelada com as parcelas anteriores (já cobradas em faturas passadas, com vencimento estimado), a parcela atual e as futuras (com vencimento previsto). Quando o banco não mostra parcelas futuras (V3/V4 não rodam), esse cronograma é o controle: na fatura do mês seguinte, cada parcela n+1 tem que aparecer.

Etapa 5 — Classificar

Use references/fornecedores.md, que vale para todos os bancos (o mesmo fornecedor tem a mesma categoria em qualquer cartão).

• Status "confirmado" → aplique.
• Status "sugerido" → aplique, mas liste no relatório.
• Status "perguntar" ou fornecedor ausente da tabela → não classifique. Liste para o usuário decidir. Isso inclui possíveis gastos pessoais do sócio (streaming, farmácia, transporte por app, bebidas) e compras na própria empresa.
• Não use a categoria que o banco imprime (Itaú "ALIMENTAÇÃO", "MORADIA"…): ela reflete o ramo cadastrado do estabelecimento, não o que foi comprado.

Etapa 6 — Conciliar com o ERP

Identifique cada parcela pela chave: fornecedor + data_compra + valor + parcela_atual/parcela_total + cartão.

Relate em quatro grupos:

• Faltando: na fatura e não no ERP.
• Sobrando: no ERP ligado ao cartão e não na fatura.
• Duplicado: mesma chave duas vezes.
• Data errada: lançado, mas sem o vencimento real desta fatura.

Use a lista anteriores do cronograma para conferir se as parcelas já cobradas em faturas passadas existem no ERP — é aí que costuma faltar dinheiro. Antes de concluir que parcelas antigas faltam, verifique se faturas anteriores foram lançadas como valor global ("Cartão de Crédito" com o total) e qual é o lançamento mais antigo do ERP — a parcela pode estar dentro de um valor global ou ser anterior ao início do sistema.

Antes de criar qualquer lançamento novo: checar despesas lançadas por outro canal

O ERP tem outros jeitos de lançar despesa (ex: Lançamento Mobile) que não passam pela fatura e não têm origem_cartao, fornecedor nem parcela — sem essa checagem, a mesma despesa que o dono já lançou pelo celular quando pagou vira uma duplicata quando a fatura do cartão é processada depois.

Para cada item que a fatura pediria pra criar, antes de criar:

1. Busque despesas com origem_cartao IS NULL, mesmo valor, e data da compra ±2 dias.
2. Um candidato só → vincule nele (preencha data_vencimento, origem_cartao, fornecedor, parcela_atual/parcela_total nesse lançamento existente) — não crie um lançamento novo, e não mude a categoria que já estava lá.
3. Vários candidatos, ou dúvida → não decida sozinho; liste pro usuário escolher qual (ou nenhum) vincular.
4. Valor bate com parcela × total de parcelas (ex: parcela é R$470 e o candidato tem R$2.820 = 470×6) → não vincule automaticamente; marque como "revisar" — é sinal de que a compra inteira foi lançada de uma vez em vez de parcelada, e vincular perderia essa informação.

Nota fiscal da mesma compra (paga no cartão, subida como XML depois)

Incidente real (2026-09-24): a mesma compra (Mega G Alimentos, R$2.490,52) tinha uma NF processada separadamente da fatura do cartão — duas linhas em faturamento pro mesmo pagamento, contando a despesa em dobro. Regra:

• A compra paga no cartão vale o lançamento da fatura — a NF é só vinculada a ele (notas_fiscais.faturamento_id), nunca cria um lançamento próprio quando já existe o do cartão.
• Se a NF for processada antes da fatura chegar: quando a fatura do cartão for importada depois, a checagem "antes de criar qualquer lançamento novo" (acima) já cobre isso — o lançamento que a NF gerou tem origem_cartao IS NULL, então cai como candidato pra vincular (passo 2 da checagem) em vez de criar um novo. Só depois de vincular, também atualize notas_fiscais.faturamento_id pra apontar pro mesmo id.
• Ao concluir uma conciliação de fatura, rode uma varredura final: todo lançamento com origem_cartao preenchido contra toda notas_fiscais, por valor (±R$0,01) e data_emissao ±3 dias da data do lançamento. Par achado com faturamento_id diferente do lançamento do cartão (ou vazio, mas com um outro lançamento parecido) = duplicata a resolver.

Etapa 7 — Relatório e aprovação

Mostre o relatório e espere aprovação explícita antes de criar, alterar ou excluir qualquer lançamento. O relatório tem:

1. Resultado das validações V1–V4.
2. Os quatro grupos da etapa 6, com totais.
3. Itens a classificar (status "perguntar" ou desconhecido).
4. Cronograma de parcelas futuras e o total de compromissos do cartão.

Etapa 8 — Lançar (só depois de aprovado)

Regra definitiva (2026-09-24): só lance as parcelas DESTA fatura. Parcela futura nunca é lançada adiantada — ela entra no ERP só quando a fatura do mês dela for processada, do mesmo jeito. (Antes desta regra, o Fase 1 desta skill criava lançamentos previsto pras parcelas futuras inteiras do cronograma — isso gerou 49 lançamentos fantasmas que tiveram que ser removidos. Não repita.)

Modelo de dados esperado (adapte os nomes ao schema do ERP; se os campos não existirem, proponha a migração e peça aprovação — não crie colunas sozinho):

O cronograma.json (etapa 4) continua sendo gerado — mas fica só como arquivo de controle, pra conferir a fatura do mês seguinte quando ela chegar (etapa 9). Nunca vira lançamento no ERP antes da hora.

Regime: já definido — despesa de cartão vale no mês do vencimento em toda parte do ERP (Visão Geral e Fluxo de Caixa), nunca no mês da compra. Não é mais uma pergunta em aberto.

Etapa 9 — Conferir compromissos futuros (sem lançar nada)

O ERP não guarda parcela futura — "quanto ainda vou pagar" vem só do cronograma.json da fatura mais recente de cada cartão (campos proxima_fatura e demais_faturas, calculados pelo script). Quando a fatura do mês seguinte chegar, rode a etapa 4 nela e confira: cada parcela n+1 do cronograma anterior tem que aparecer como parcela n (ou já paga) na fatura nova. Se não aparecer, é parcela faltando — trate como a Etapa 6 trata "faltando".

Referências

• references/bancos/itau.md — layout da fatura Itaú Empresas
• references/bancos/bradesco.md — layout do extrato Bradesco Net Empresa
• references/bancos/_modelo.md — modelo para cadastrar um banco novo
• references/fornecedores.md — tabela fornecedor → categoria (todos os bancos)
• scripts/validar_fatura.py — validações V1–V4 e cronograma de parcelas
• examples/ — faturas reais já extraídas em JSON, para teste do script