---
name: iva-quarterly-prep
description: Generate quarterly IVA (VAT) filing summary for the accountant from CloudInvoice data. Run on the 1st of Jan/Apr/Jul/Oct at 07:00 UTC, or on demand for "IVA prep", "quarterly IVA", "resumo trimestral IVA", or "declaração IVA".
user-invocable: true
---

# IVA Quarterly Filing Prep (v1)

Produces a quarterly IVA summary for the accountant from CloudInvoice data (HR + RMR entities). Outputs a markdown artifact and a Telegram digest for João.

## When to run
- **Cron:** 1st of Jan/Apr/Jul/Oct at 07:00 UTC (after the quarter closes)
- **On demand:** When João asks for "IVA prep", "quarterly IVA", "resumo trimestral", "declaração IVA"

## How to run
```bash
# Most recently completed quarter (default)
python3 /opt/data/profiles/finrecon/skills/iva-quarterly-prep/scripts/iva-quarterly-prep.py

# Specific quarter
python3 /opt/data/profiles/finrecon/skills/iva-quarterly-prep/scripts/iva-quarterly-prep.py --quarter Q1 --year 2026

# Dry run (stdout only, no artifact/Telegram)
python3 /opt/data/profiles/finrecon/skills/iva-quarterly-prep/scripts/iva-quarterly-prep.py --dry-run
```

## What the report contains
- Per entity (HR — Quinta da Capelinha, RMR):
  - Total documents, gross revenue, credit notes, net revenue base
  - IVA liquidado at 6% (IVA intermédio — accommodation, Portugal mainland)
  - Breakdown by document type (FRE, FAC, NC)
  - Monthly subtotals within the quarter
  - Breakdown by payment method
- Combined summary (HR + RMR) with total IVA payable
- Note for accountant: cross-check with Modelo 30 periodic declaration

## Outputs
- **Artifact:** `/docker/artifacts/finrecon/iva-YYYY-Qn.md` (auth-gated)
- **Telegram:** Short digest to João via @FinReconBot

## Environment required
| Variable | Source | Purpose |
|---|---|---|
| `CLOUDINVOICE_HR_TOKEN` | CloudInvoice API | HR entity access |
| `CLOUDINVOICE_RMR_TOKEN` | CloudInvoice API | RMR entity access |
| `BOT_TOKEN` | Telegram | @FinReconBot send |
| `ALERT_CHAT_ID` | Telegram | João's chat ID |

## IVA rate note
Portugal mainland accommodation uses IVA intermédio (6%). This is hardcoded. If the rate changes or if services outside accommodation are added, update `IVA_RATE` in the script.

## Failure modes
- CloudInvoice API unreachable → script retries once, then exits non-zero. No partial report.
- Missing env vars → exits with code 2, prints missing var names to stderr.
- Telegram send fails → report is still written to artifacts; warning logged.
- Zero documents for quarter → generates report noting "sem documentos" for that entity.

## Never
- Never fabricate document data if CloudInvoice returns nothing — report the gap.
- Never send the report directly to the accountant — it's a draft for João to review first.
- Never modify CloudInvoice data — this is read-only.