erp/.claude/skills/dolibarr-tva-reconciliation/SKILL.md

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

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 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)

./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):

# 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)

./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) 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.