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

---
name: invoice
description: Gestão de facturação Desk CRM. Criar facturas, converter estimates, facturar timesheets, registar pagamentos e listar facturas vencidas.
disable-model-invocation: 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:**

```markdown
## 💰 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 <client>

```
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 <id>

```
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 <project>

```
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 <id>

```
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 <id>

```
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:**

```markdown
## ⚠️ 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®*

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"}
```

*Adicionar nova linha após cada erro corrigido.*