---
name: dolibarr-tva-reconciliation
description: Prepare monthly French TVA declarations (CA3 / CA12) from Arcodange Dolibarr invoices. Two workflows — (1) per-period basis × rate aggregation (HT and TVA collectée grouped by year-month and tva_tx) ready to transcribe onto CA3 lines A1 / A4 / E2; (2) per-line audit trail with thirdparty country classification (FR domestic A1, EU intra-UE autoliquidation A4, non-EU export hors UE E2), so the operator can see WHY each line lands in its bucket. Handles credit notes (AVOIRs net out at the basis level). Currently in production for Arcodange: all KissMetrics invoices are autoliquidation 259-1° (extra-UE → E2, basis only, TVA collectée = 0). Use when the user asks "préparer la TVA du mois", "déclaration TVA mensuelle", "base CA3 ligne E2 / A4", "réconciliation TVA", "combien de TVA à reverser". Depends on the `dolibarr` skill for connection. SKIP for the legal-mention audit (different skill), for the deferred-cycle / cash receipts (handled by `dolibarr-payments-state` — TVA on encaissements is a separate concern), for writes (the declaration itself goes through impots.gouv.fr, not Dolibarr).
requires:
  bins: ["curl", "jq", "python3"]
  auth: true
---

# dolibarr-tva-reconciliation — monthly TVA basis preparation

**CLI shortcuts:** `bin/arcodange tva collect` · `bin/arcodange tva collect-detail` (or the combined `bin/arcodange tva summary`)

Builds the numbers the CA3 (régime réel normal) or CA12 (réel simplifié) declaration needs, straight from Dolibarr invoice lines. **Read-only**: this skill prepares the basis; the actual declaration goes through impots.gouv.fr.

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

## French TVA mental model (the buckets this skill outputs)

Dolibarr stores `tva_tx` per invoice line. Combined with the thirdparty's country code, each line belongs to one **CA3 bucket**:

| Bucket | Condition | What goes there |
|---|---|---|
| **A1** | `tva_tx > 0` (any country) | Domestic operations with collected TVA. Basis on line A1, TVA on line 08 (20 %) / 09 (10 % / 5.5 % / 2.1 %). |
| **A4** | `tva_tx == 0` AND thirdparty country in EU (excl. FR) | Intra-UE B2B services / goods on autoliquidation. Basis on A4, no TVA collectée. |
| **E2** | `tva_tx == 0` AND thirdparty country outside EU | Export of services hors UE (article 259-1° CGI for services / 262 for goods). Basis on E2, no TVA collectée. |
| **A1 (domestic 0%)** | `tva_tx == 0` AND country == FR | Atypical — domestic 0 %. Worth a manual check. |

Today **Arcodange is in a single bucket**: KissMetrics is the only client, US-based → **E2 export hors UE** with the 259-1° CGI mention. As soon as a French B2B is invoiced, A1 will start populating.

Credit notes (AVOIRs) are first-class: negative HT correctly nets the basis. A canceled-and-reissued cycle (like FAC001-CL00001 / AVC001 / FAC001-CL0001001 from V1) sums to the right net basis.

## Workflow 1 — Aggregate per month × rate (the CA3 basis)

```bash
./scripts/tva-by-month.sh                      # all-time
./scripts/tva-by-month.sh --year 2026          # full year
./scripts/tva-by-month.sh --since 2026-04-01 --until 2026-04-30   # one month
```

Live output (captured at [examples/tva-by-month.txt](examples/tva-by-month.txt)):

```
# TVA basis by month × rate — window=-inf → +inf

month     tva_tx  count      basis HT         TVA  CA3 line
----------------------------------------------------------------------
2026-01    0.0000      4        510.00        0.00  (see tva-line-detail for cnty)
2026-02    0.0000     11       7650.00        0.00  (see tva-line-detail for cnty)
----------------------------------------------------------------------
           TOTAL                  8160.00        0.00
```

All zero TVA collectée — consistent with the autoliquidation posture. The basis number is what you'd transcribe onto E2 (after the country breakdown from workflow 2 confirms it's all extra-UE).

## Workflow 2 — Per-line audit trail (the CA3 bucket assignment)

```bash
./scripts/tva-line-detail.sh                   # all-time
./scripts/tva-line-detail.sh --year 2026
./scripts/tva-line-detail.sh --since 2026-04-01 --until 2026-04-30
```

Live output (captured at [examples/tva-line-detail.txt](examples/tva-line-detail.txt)) shows each line with its country, rate, HT, TVA, and CA3 bucket. Plus a summary per bucket at the bottom — that's the line-by-line evidence that confirms the workflow-1 aggregate.

**Use this when** : you want the *why* behind a line in the monthly basis. If workflow 1 shows a 0 % bucket but workflow 2 says one line is FR domestic 0 %, that's worth flagging — it shouldn't be there.

## Tying back to impots.gouv.fr

The CA3 form is filed monthly (régime réel normal) by the 19th of the month following the operation. Transcription map for Arcodange's current single-bucket case:

| Form line | From this skill |
|---|---|
| E2 (Exportations) | sum of HT in the "E2 export hors UE" bucket |
| Total | sum across all buckets |
| TVA collectée | 0 (autoliquidation) |
| TVA déductible | from the suppliers side — out of scope here (no `/fournisseurfactures` workflow yet) |

For now the **TVA déductible** part (deductible TVA on Arcodange's expenses) is NOT covered — there's no supplier-invoice workflow in this skill family yet. Once Arcodange starts logging supplier invoices in Dolibarr, a sibling `dolibarr-tva-deductible` skill would complete the loop.

## Out of scope

- **TVA déductible / supplier invoices.** Different endpoint family (`/supplierinvoices`). V4 candidate.
- **TVA sur encaissements** (régime spécial for services where TVA is due on cash receipts, not invoice date). Not Arcodange's regime today; if it ever becomes one, this skill needs to swap `invoice.date` for `payment.date` as the period anchor.
- **CA12 quarterly form / TVA forfaitaire.** Different aggregation cadence — would need a `--quarter` option.
- **Writes to impots.gouv.fr.** Always a manual step in the official portal.