claude-plugins/crm-ops/skills/invoice/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
invoice	Gestão de facturação Desk CRM. Criar facturas, converter estimates, facturar timesheets, registar pagamentos e listar facturas vencidas.	true

/invoice v1.0 - Gestão de Facturação

Facturação completa via Desk CRM: criar, enviar, pagamentos.

---

Comandos

Comando	Função
/invoice	Resumo: pendentes, vencidas
/invoice create <client>	Criar factura directa
/invoice from-estimate <id>	Converter estimate aceite
/invoice from-timesheets <project>	Facturar horas
/invoice send <id>	Enviar ao cliente
/invoice payment <id>	Registar pagamento
/invoice overdue	Listar vencidas

---

Protocolo

/invoice (Resumo)

1. mcp__desk-crm-v3__get_invoices({ status: [1,4] }) // Unpaid + Overdue
2. Calcular totais
3. Mostrar resumo

Output:

## 💰 Facturação

### Pendentes (3)
| # | Cliente | Valor | Vencimento |
|---|---------|-------|------------|
| INV-2026-045 | TechCorp | €2.500 | 10/02 |
| INV-2026-044 | StartupX | €1.800 | 15/02 |

### Vencidas (1)
| # | Cliente | Valor | Dias |
|---|---------|-------|------|
| INV-2026-040 | OldClient | €950 | 15 dias |

### Totais
- Pendente: €4.300
- Vencido: €950
- **A receber:** €5.250

---

/invoice create

1. mcp__desk-crm-v3__search_customers({ query: client })
2. Se não encontrar: "Cliente não encontrado"
3. Perguntar itens:
   - Descrição
   - Quantidade
   - Valor unitário
4. Calcular subtotal + IVA (23%)
5. mcp__desk-crm-v3__create_invoice({
     client_id: client_id,
     items: [...],
     tax_id: 1,  // IVA 23%
     status: 1
   })
6. "Factura #X criada (€Y). Enviar ao cliente? [Sim/Não]"

---

/invoice from-estimate

1. mcp__desk-crm-v3__get_estimate({ estimate_id: id })
2. Verificar status = 4 (Aceite)
   - Se não aceite: "Estimate não aceite. Não é possível converter."
3. Mostrar detalhes do estimate
4. "Converter estimate #X para factura? [Sim/Não]"
5. mcp__desk-crm-v3__convert_estimate_to_invoice({ estimate_id: id })
6. "Factura #Y criada. Enviar? [Sim/Não]"

---

/invoice from-timesheets

1. mcp__desk-crm-v3__get_project({ project_id })
2. mcp__desk-crm-v3__get_timesheets_advanced({
     project_id: project_id,
     billed: false
   })
3. Calcular total horas × rate do projecto
4. Mostrar resumo:
   - Horas: Xh
   - Rate: €Y/h
   - Total: €Z
5. "Criar factura de €Z? [Sim/Não]"
6. mcp__desk-crm-v3__create_invoice({
     client_id: project.client_id,
     items: [{ description: "Horas - Projecto X", qty: hours, rate: rate }]
   })
7. mcp__desk-crm-v3__bulk_mark_billed({ timesheet_ids: [...] })
8. "Factura #Y criada. Timesheets marcados como facturados."

---

/invoice send

1. mcp__desk-crm-v3__get_invoice({ invoice_id: id })
2. Verificar dados do cliente (email)
3. "Enviar factura #X para [email]? [Sim/Não]"
4. Marcar como enviada (status: 2)
5. Confirmar envio

---

/invoice payment

1. mcp__desk-crm-v3__get_invoice({ invoice_id: id })
2. Mostrar: Total €X, Pago €Y, Falta €Z
3. Perguntar:
   - Valor pago
   - Data pagamento
   - Método (Transferência, MB, PayPal, etc.)
4. mcp__desk-crm-v3__process_payment({
     invoice_id: id,
     amount: valor,
     payment_date: data,
     payment_mode: metodo
   })
5. Confirmar: "Pagamento de €V registado. Saldo: €S"

---

/invoice overdue

1. mcp__desk-crm-v3__overdue_invoices_report()
2. Ordenar por dias de atraso
3. Mostrar lista com opções

Output:

## ⚠️ Facturas Vencidas (3)

| # | Cliente | Valor | Dias | Contacto |
|---|---------|-------|------|----------|
| INV-040 | OldClient | €950 | 15 | joao@old.pt |
| INV-038 | SlowPay | €2.100 | 22 | maria@slow.pt |
| INV-035 | LateInc | €750 | 30 | admin@late.pt |

**Total vencido:** €3.800

Acções:
- [Enviar lembrete a todos]
- [Ver detalhes de #X]

---

Status Invoices

ID	Status
1	Unpaid (não paga)
2	Paid (paga)
3	Partially Paid (parcial)
4	Overdue (vencida)
5	Cancelled (cancelada)

---

Workflow Completo: Estimate → Invoice → Payment

1. Estimate aceite pelo cliente (status: 4)
2. /invoice from-estimate <estimate_id>
3. /invoice send <invoice_id>
4. Cliente paga
5. /invoice payment <invoice_id>
6. Factura fechada (status: 2)

---

Workflow: Facturar Timesheets Mensais

1. Final do mês
2. /invoice from-timesheets <project_id>
3. Revê horas e valores
4. Confirma criação
5. Timesheets marcados como facturados
6. /invoice send <id>

---

IVA (Portugal)

Taxa	Uso
23%	Serviços gerais (default)
13%	Alimentação
6%	Bens essenciais

---

Anti-Patterns

• NUNCA converter estimate não-aceite
• NUNCA criar factura sem confirmar valores
• NUNCA enviar factura sem verificar dados cliente
• NUNCA registar pagamento sem confirmar valor

---

Integração

• /crm 360: Mostra facturas pendentes do cliente
• /today: Alerta de facturas vencidas
• /report weekly: Inclui facturação emitida/recebida

---

Changelog

v1.0.0 (2026-02-05)

• Versão inicial
• Criar, enviar, pagamentos
• Facturar timesheets
• Relatório de vencidas

---

Skill v1.0.0 | 2026-02-05 | Descomplicar®