---
name: dolibarr-tva-summary
description: One-shot CA3-ready monthly French TVA summary for Arcodange — composes `dolibarr-tva-reconciliation` (TVA collectée customer-side) and `dolibarr-tva-deductible` (TVA déductible supplier-side) into a single per-month report with bucket-by-bucket breakdown and a net verdict (TVA à reverser, crédit de TVA, or équilibre). Each month shows both sides with their CA3 bucket assignments (A1 / A4 / E2 for collectée; 19 / 20 / 17+24 for déductible) plus the net = collectée − déductible. Today Arcodange is in cumulative TVA credit of 223.22 € (0 € collectée under KissMetrics autoliquidation 259-1° CGI vs 223.22 € déductible on supplier invoices). Use when the user asks "résumé TVA du mois", "combien à reverser ce mois", "préparer la CA3", "crédit ou dette TVA", "synthèse TVA mensuelle". Depends on `dolibarr`, internally consumes the same endpoints as the two TVA sibling skills. SKIP for per-line audit (use the sibling skills directly), for writes (the declaration itself goes through impots.gouv.fr), and for non-Arcodange TVA regimes.
requires:
  bins: ["curl", "jq", "python3"]
  auth: true
---

# dolibarr-tva-summary — CA3-ready monthly TVA report

The single workflow that combines [dolibarr-tva-reconciliation](../dolibarr-tva-reconciliation/SKILL.md) (TVA collectée — customer side) and [dolibarr-tva-deductible](../dolibarr-tva-deductible/SKILL.md) (TVA déductible — supplier side) into one table per month with a net verdict.

**CLI shortcut:** `bin/arcodange tva summary [--year YYYY] [--since … --until …]`

Depends on the [dolibarr](../dolibarr/SKILL.md) base skill.

## What it computes

For each month in the window:

```
net = TVA collectée − TVA déductible
```

Then categorizes:
- `net > 0` → **TVA À REVERSER** (Arcodange doit cet écart à l'État sur la CA3 du mois)
- `net < 0` → **CRÉDIT DE TVA** (l'État doit cet écart à Arcodange — report ou remboursement)
- `net = 0` → équilibre

For each side, the output breaks down by CA3 bucket so you can transcribe directly:
- **Collectée**: A1 (domestic with TVA), A4 (autoliquidation intra-UE), E2 (export hors UE)
- **Déductible**: ligne 19/20 (20 % standard / taux réduits), ligne 17+24 (autoliquidation intra-UE), ligne 7 (import hors UE), FR exempt

## Workflow

```bash
bin/arcodange tva summary                       # all-time
bin/arcodange tva summary --year 2026
bin/arcodange tva summary --since 2026-01-01 --until 2026-01-31
```

Live output for the all-time window (captured at [examples/tva-summary.txt](examples/tva-summary.txt)):

```
=== 2026-01 ===
  Customer side (TVA collectée)   basis HT=    510.00   TVA=    0.00
      E2 (export hors UE)                         HT=    510.00  TVA=    0.00
  Supplier side (TVA déductible)  basis HT=    403.45   TVA=   69.00
      FR exempt / HT seulement                    HT=      8.43  TVA=    0.00
      ligne 17+24 (autoliquidation intra-UE)      HT=     50.00  TVA=    0.00
      ligne 19/20 (20.0% déductible)              HT=    345.02  TVA=   69.00
  --- Net du mois : collectée − déductible = 0.00 − 69.00 =   -69.00   → CRÉDIT DE TVA : 69.00 €

=== 2026-02 ===
  Customer side (TVA collectée)   basis HT=   7650.00   TVA=    0.00
      E2 (export hors UE)                         HT=   7650.00  TVA=    0.00
  Supplier side (TVA déductible)  basis HT=    765.00   TVA=  153.00
      ligne 19/20 (20.0% déductible)              HT=    765.00  TVA=  153.00
  --- Net du mois : collectée − déductible = 0.00 − 153.00 =  -153.00   → CRÉDIT DE TVA : 153.00 €

=== CUMUL window=-inf → +inf ===
  TVA collectée totale  :       0.00
  TVA déductible totale :     223.22
  Net cumulé            :    -223.22   → CRÉDIT DE TVA cumulé : 223.22 €
```

## Reading the result for the CA3 declaration

For each month:
1. **Lignes E2 / A4 / A1** on the CA3 form ← from the customer-side breakdown (HT amounts).
2. **Lignes 19 / 20 / 17 / 24** ← from the supplier-side breakdown (TVA amounts).
3. **TVA nette** = collectée line totals − déductible line totals.
4. If credit, request reimbursement or carry forward to the next month.

Today Arcodange is in **continuous credit** because of the 259-1° CGI export posture (collectée = 0 systematically against KissMetrics) while normal operating expenses generate déductible. As long as Arcodange has only extra-EU export customers, this stays the steady state.

## When this skill stops being the right answer

- **A French B2B client is invoiced** (with TVA collectée > 0). Then the A1 bucket starts populating and the net can flip positive. Still the right skill, just different numbers.
- **A goods import** lands a customs ligne 7 entry. The deductible-line-detail breakdown will surface it but verifying matches against customs paperwork is out of scope.
- **TVA sur encaissements** (régime spécial). The current skill uses invoice date as the period anchor; encaissements would need to swap that for payment date. Not Arcodange's regime today.

## Out of scope

- **Writing the declaration on impots.gouv.fr.** Manual step always.
- **Préfinancement TVA / régime simplifié CA12.** Different aggregation cadence; could be a sibling skill if Arcodange's regime changes.
- **Other periodic taxes** (CFE, CVAE, IS). Different data sources.