ComposioHQ/invoice-organizer

Organizador de Faturas

Esta habilidade transforma pastas caóticas de faturas, recibos e documentos financeiros em um sistema de arquivamento limpo e pronto para impostos, sem esforço manual.

Quando Usar Esta Habilidade

• Preparando-se para a temporada de impostos e precisando de registros organizados
• Gerenciando despesas de negócios com vários fornecedores
• Organizando recibos de uma pasta bagunçada ou downloads de e-mail
• Configurando arquivamento automatizado de faturas para contabilidade contínua
• Arquivando registros financeiros por ano ou categoria
• Conciliando despesas para reembolso
• Preparando documentação para contadores

O Que Esta Habilidade Faz

1. Lê o Conteúdo da Fatura: Extrai informações de PDFs, imagens e documentos:

   • Nome do vendedor/empresa
   • Número da fatura
   • Data
   • Valor
   • Descrição do produto ou serviço
   • Método de pagamento

2. Renomeia Arquivos de Forma Consistente: Cria nomes de arquivo padronizados:

   • Formato: AAAA-MM-DD Vendedor - Fatura - ProdutoOuServico.pdf
   • Exemplos: 2024-03-15 Adobe - Fatura - Creative Cloud.pdf

3. Organiza por Categoria: Classifica em pastas lógicas:

   • Por vendedor
   • Por categoria de despesa (software, escritório, viagem, etc.)
   • Por período (ano, trimestre, mês)
   • Por categoria fiscal (dedutível, pessoal, etc.)

4. Lida com Múltiplos Formatos: Funciona com:

   • Faturas em PDF
   • Recibos digitalizados (JPG, PNG)
   • Anexos de e-mail
   • Capturas de tela
   • Extratos bancários

5. Mantém os Originais: Preserva os arquivos originais enquanto organiza cópias

Como Usar

Uso Básico

Navegue até sua pasta de faturas bagunçada:

cd ~/Desktop/recebimentos-para-organizar

Depois peça ao Claude Code:

Organize estas faturas para impostos

Ou mais especificamente:

Leia todas as faturas nesta pasta, renomeie-as para o formato 
"AAAA-MM-DD Vendedor - Fatura - Produto.pdf" 
e organize por vendedor

Organização Avançada

Organize estas faturas:
1. Extraia data, vendedor e descrição de cada arquivo
2. Renomeie para o formato padrão
3. Classifique em pastas por categoria de despesa (Software, Escritório, Viagem, etc.)
4. Crie uma planilha CSV com todos os detalhes das faturas para meu contador

Instruções

Quando um usuário solicitar organização de faturas:

1. Examine a Pasta

   Identifique todos os arquivos de fatura:

   # Encontre todos os arquivos relacionados a faturas
   find . -type f \( -name "*.pdf" -o -name "*.jpg" -o -name "*.png" \) -print
   

   Relate os resultados:

   • Número total de arquivos
   • Tipos de arquivo
   • Intervalo de datas (se discernível pelos nomes)
   • Organização atual (ou falta dela)

2. Extraia Informação de Cada Arquivo

   Para cada fatura, extraia:

   De faturas em PDF:

   • Use extração de texto para ler o conteúdo da fatura
   • Procure por padrões comuns:
     • "Data da Fatura:", "Data:", "Emitido em:"
     • "Fatura #:", "Número da Fatura:"
     • Nome da empresa (geralmente no topo)
     • "Valor Devido:", "Total:", "Valor:"
     • "Descrição:", "Serviço:", "Produto:"

   De recibos em imagem:

   • Leia o texto visível das imagens
   • Identifique o nome do vendedor (geralmente no topo)
   • Procure a data (formatos comuns)
   • Encontre o valor total

   Fallback para arquivos não claros:

   • Use pistas do nome do arquivo
   • Verifique a data de criação/modificação do arquivo
   • Sinalize para revisão manual se informações críticas estiverem faltando

3. Determine a Estratégia de Organização

   Pergunte a preferência do usuário se não especificada:

   Encontrei [X] faturas do período [intervalo de datas].
   
   Como você gostaria de organizá-las?
   
   1. **Por Vendedor** (Adobe/, Amazon/, Stripe/, etc.)
   2. **Por Categoria** (Software/, Material de Escritório/, Viagem/, etc.)
   3. **Por Data** (2024/T1/, 2024/T2/, etc.)
   4. **Por Categoria Fiscal** (Dedutível/, Pessoal/, etc.)
   5. **Personalizado** (descreva sua estrutura)
   
   Ou posso usar uma estrutura padrão: Ano/Categoria/Vendedor
   

4. Crie Nome de Arquivo Padronizado

   Para cada fatura, crie um nome de arquivo seguindo este padrão:

   AAAA-MM-DD Vendedor - Fatura - Descricao.ext
   

   Exemplos:

   • 2024-03-15 Adobe - Fatura - Creative Cloud.pdf
   • 2024-01-10 Amazon - Recibo - Material de Escritorio.pdf
   • 2023-12-01 Stripe - Fatura - Processamento de Pagamento Mensal.pdf

   Melhores Práticas de Nomeação:

   • Remova caracteres especiais, exceto hífens
   • Capitalize nomes de vendedores corretamente
   • Mantenha descrições concisas, mas significativas
   • Use formato de data consistente (AAAA-MM-DD) para classificação
   • Preserve a extensão original do arquivo

5. Execute a Organização

   Antes de mover arquivos, mostre o plano:

   # Plano de Organização
   
   ## Estrutura Proposta
   

   Faturas/ ├── 2023/ │ ├── Software/ │ │ ├── Adobe/ │ │ └── Microsoft/ │ ├── Servicos/ │ └── Escritorio/ └── 2024/ ├── Software/ ├── Servicos/ └── Escritorio/

   
   ## Exemplos de Mudanças
   
   Antes: `fatura_adobe_marco.pdf`
   Depois: `2024-03-15 Adobe - Fatura - Creative Cloud.pdf`
   Localização: `Faturas/2024/Software/Adobe/`
   
   Antes: `IMG_2847.jpg`
   Depois: `2024-02-10 Staples - Recibo - Material de Escritorio.jpg`
   Localização: `Faturas/2024/Escritorio/Staples/`
   
   Processar [X] arquivos? (sim/não)
   

   Após aprovação:

   # Crie a estrutura de pastas
   mkdir -p "Faturas/2024/Software/Adobe"
   
   # Copie (não mova) para preservar os originais
   cp "original.pdf" "Faturas/2024/Software/Adobe/2024-03-15 Adobe - Fatura - Creative Cloud.pdf"
   
   # Ou mova se o usuário preferir
   mv "original.pdf" "novo/caminho/nome-padronizado.pdf"
   

6. Gere Relatório Resumido

   Crie um arquivo CSV com todos os detalhes das faturas:

   Data,Vendedor,Número da Fatura,Descrição,Valor,Categoria,Caminho do Arquivo
   2024-03-15,Adobe,INV-12345,Creative Cloud,52.99,Software,Faturas/2024/Software/Adobe/2024-03-15 Adobe - Fatura - Creative Cloud.pdf
   2024-03-10,Amazon,123-4567890-1234567,Material de Escritório,127.45,Escritório,Faturas/2024/Escritório/Amazon/2024-03-10 Amazon - Recibo - Material de Escritório.pdf
   ...
   

   Este CSV é útil para:

   • Importação em softwares de contabilidade
   • Compartilhamento com contadores
   • Acompanhamento e relatórios de despesas
   • Preparação de impostos

7. Forneça Resumo de Conclusão

   # Organização Completa! 📊
   
   ## Resumo
   - **Processados**: [X] faturas
   - **Período**: [mais antiga] a [mais recente]
   - **Valor total**: R$[soma] (se valores extraídos)
   - **Vendedores**: [Y] vendedores únicos
   
   ## Nova Estrutura
   

   Faturas/ ├── 2024/ (45 arquivos) │ ├── Software/ (23 arquivos) │ ├── Servicos/ (12 arquivos) │ └── Escritorio/ (10 arquivos) └── 2023/ (12 arquivos)

   
   ## Arquivos Criados
   - `/Faturas/` - Faturas organizadas
   - `/Faturas/resumo-faturas.csv` - Planilha para contabilidade
   - `/Faturas/originais/` - Arquivos originais (se copiados)
   
   ## Arquivos que Precisam de Revisão
   [Liste quaisquer arquivos onde a informação não pôde ser extraída completamente]
   
   ## Próximos Passos
   1. Revise o arquivo `resumo-faturas.csv`
   2. Verifique os arquivos na pasta "Precisa de Revisão"
   3. Importe o CSV para seu software de contabilidade
   4. Configure a organização automática para faturas futuras
   
   Pronto para a temporada de impostos! 🎉
   

Exemplos

Exemplo 1: Preparação para Impostos (De Martin Merschroth)

Usuário: "Tenho uma pasta bagunçada de faturas para impostos. Classifique-as e renomeie-as corretamente."

Processo:

1. Examina a pasta: encontra 147 PDFs e imagens
2. Lê cada fatura para extrair:
   • Data
   • Nome do vendedor
   • Número da fatura
   • Descrição do produto/serviço
3. Renomeia todos os arquivos: AAAA-MM-DD Vendedor - Fatura - Produto.pdf
4. Organiza em: 2024/Software/, 2024/Viagem/, etc.
5. Cria resumo-faturas.csv para o contador
6. Resultado: Faturas organizadas prontas para impostos em minutos

Exemplo 2: Conciliação Mensal de Despesas

Usuário: "Organize meus recibos de negócios do mês passado por categoria."

Saída:

# Recibos de Março de 2024 Organizados

## Por Categoria
- Software e Ferramentas: R$ 847,32 (12 faturas)
- Material de Escritório: R$ 234,18 (8 recibos)
- Viagem e Refeições: R$ 1.456,90 (15 recibos)
- Serviços Profissionais: R$ 2.500,00 (3 faturas)

Total: R$ 5.038,40

Todos os recibos renomeados e arquivados em:
`Recibos-Negocios/2024/03-Marco/[Categoria]/`

Exportação CSV: `despesas-marco-2024.csv`

Exemplo 3: Arquivo de Múltiplos Anos

Usuário: "Tenho 3 anos de faturas aleatórias. Organize-as por ano e depois por vendedor."

Saída: Cria estrutura:

Faturas/
├── 2022/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
├── 2023/
│   ├── Adobe/
│   ├── Amazon/
│   └── ...
└── 2024/
    ├── Adobe/
    ├── Amazon/
    └── ...

Cada arquivo renomeado corretamente com data e descrição.

Exemplo 4: Limpeza de Downloads de E-mail

Usuário: "Baixo faturas do Gmail. Todas se chamam 'fatura.pdf', 'fatura(1).pdf', etc. Arrume essa bagunça."

Saída:

Encontrados 89 arquivos todos nomeados "fatura*.pdf"

Lendo cada arquivo para extrair informações reais...

Exemplos renomeados:
- fatura.pdf → 2024-03-15 Shopify - Fatura - Assinatura Mensal.pdf
- fatura(1).pdf → 2024-03-14 Google - Fatura - Workspace.pdf
- fatura(2).pdf → 2024-03-10 Netlify - Fatura - Plano Pro.pdf

Todos os arquivos renomeados e organizados por vendedor.

Padrões Comuns de Organização

Por Vendedor (Simples)

Faturas/
├── Adobe/
├── Amazon/
├── Google/
└── Microsoft/

Por Ano e Categoria (Amigável para Impostos)

Faturas/
├── 2023/
│   ├── Software/
│   ├── Hardware/
│   ├── Servicos/
│   └── Viagem/
└── 2024/
    └── ...

Por Trimestre (Acompanhamento Detalhado)

Faturas/
├── 2024/
│   ├── T1/
│   │   ├── Software/
│   │   ├── Escritorio/
│   │   └── Viagem/
│   └── T2/
│       └── ...

Por Categoria Fiscal (Pronto para o Contador)

Faturas/
├── Dedutivel/
│   ├── Software/
│   ├── Escritorio/
│   └── Servicos-Profissionais/
├── Parcialmente-Dedutivel/
│   └── Refeicoes-Viagem/
└── Pessoal/

Configuração de Automação

Para organização contínua:

Crie um script que monitore minha pasta ~/Downloads/faturas 
e organize automaticamente quaisquer novos arquivos de fatura 
usando nossa estrutura de nomenclatura e pastas padrão.

Isto cria uma solução persistente que organiza faturas à medida que chegam.

Dicas Profissionais

1. Digitalize e-mails para PDF: Use Preview ou similar para salvar faturas de e-mail como PDF primeiro
2. Downloads consistentes: Salve todas as faturas em uma pasta para processamento em lote
3. Rotina mensal: Organize faturas mensalmente, não anualmente
4. Backup dos originais: Mantenha os arquivos originais antes de reorganizar
5. Inclua valores no CSV: Útil para acompanhamento de orçamento
6. Marque por dedutibilidade: Observe quais despesas são dedutíveis de impostos
7. Guarde recibos por 7 anos: Período padrão de auditoria

Casos Especiais

Informações Faltando

Se data/vendedor não puderem ser extraídos:

• Sinalize o arquivo para revisão manual
• Use a data de modificação do arquivo como fallback
• Crie uma pasta "Precisa-de-Revisao/"

Faturas Duplicadas

Se a mesma fatura aparecer várias vezes:

• Compare hashes dos arquivos
• Mantenha a versão de maior qualidade
• Anote duplicatas no resumo

Faturas de Múltiplas Páginas

Para faturas divididas em vários arquivos:

• Mescle PDFs se necessário
• Use nomenclatura consistente para partes
• Anote no CSV se a fatura está dividida

Formatos Não Padrão

Para formatos de recibo incomuns:

• Extraia o que for possível
• Padronize o que puder
• Sinalize para revisão se informações críticas estiverem faltando

Casos de Uso Relacionados

• Criar relatórios de despesas para reembolso
• Organizar extratos bancários
• Gerenciar contratos de vendedores
• Arquivar registros financeiros antigos
• Preparar para auditorias
• Acompanhar custos de assinaturas ao longo do tempo