---
name: dolibarr-tva-deductible
description: Prepare the TVA déductible side of the French monthly declaration (CA3 lignes 19 / 20 / 17 / 24) from Arcodange supplier invoices (`/supplierinvoices`). Two workflows — (1) per-period basis × rate aggregation (HT and TVA déductible grouped by year-month and tva_tx) ready to transcribe onto CA3 lignes 20 (standard 20 %), 19 (taux réduits), 17+24 (autoliquidation intra-UE); (2) per-line audit trail with supplier country classification (FR domestic / EU intra-UE / extra-EU import). Mirrors `dolibarr-tva-reconciliation` on the supplier side — TVA collectée vs TVA déductible = TVA nette à reverser. Today on Arcodange the TVA déductible totals ~223 €/all-time across 12 supplier-side 20 % lines plus 1 autoliquidation intra-UE entry (Wise BE) and 1 FR exempt line (timbres La Poste). Use when the user asks "préparer TVA déductible", "achats du mois", "TVA à récupérer", "réconciliation TVA fournisseur", "combien de TVA nette à reverser". Depends on the `dolibarr` skill. SKIP for TVA collectée (handled by `dolibarr-tva-reconciliation`), for the customer-side audit (different skills), and for writes (the declaration goes through impots.gouv.fr).
requires:
  bins: ["curl", "jq", "python3"]
  auth: true
---

# dolibarr-tva-deductible — supplier-side TVA monthly preparation

The mirror of [dolibarr-tva-reconciliation](../dolibarr-tva-reconciliation/SKILL.md) on the supplier side. Together they give you the two numbers a French CA3 needs:

- **TVA collectée** (`dolibarr-tva-reconciliation`) — what Arcodange invoiced and is obligated to remit.
- **TVA déductible** (this skill) — what Arcodange paid to suppliers and can deduct.

The net to remit is the difference. **Read-only**: the declaration itself goes through impots.gouv.fr.

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

## CA3 mapping (supplier side)

| Bucket | Condition | CA3 line(s) |
|---|---|---|
| **20 % standard** | `tva_tx == 20` | ligne 20 |
| **10 % intermediate** | `tva_tx == 10` | ligne 19 |
| **5.5 % reduced** | `tva_tx == 5.5` | ligne 19 |
| **2.1 % special** | `tva_tx == 2.1` | ligne 19 |
| **Intra-UE autoliquidation** | `tva_tx == 0` AND supplier in EU (excl. FR) | ligne 17 (TVA auto-collectée) + ligne 24 (TVA déductible) |
| **FR exempt / HT-only** | `tva_tx == 0` AND supplier country == FR | (e.g. timbres La Poste — no TVA line) |
| **Extra-EU import** | `tva_tx == 0` AND supplier outside EU | ligne 7 (import TVA — usually via customs declaration) |

## API gotchas to know

- **`/supplierinvoices/{id}/lines` returns HTTP 403** for `ai_agent`. We don't need it — lines are also included inline on `/supplierinvoices/{id}`. (Reference: [../dolibarr/examples/acl_403_supplier_lines.json](../dolibarr/examples/acl_403_supplier_lines.json).)
- **`/supplierinvoices` list works fine** — no `voir_tous` gap on supplier invoices the way V1 hit on customer ones.

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

```bash
./scripts/deductible-by-month.sh                      # all-time
./scripts/deductible-by-month.sh --year 2026
./scripts/deductible-by-month.sh --since 2026-01-01 --until 2026-01-31
```

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

```
# TVA déductible by month × rate — window=-inf → +inf

month      tva_tx  count      basis HT     TVA ded  CA3 line
------------------------------------------------------------------------------
2025-10   20.0000      2          6.08        1.22  ligne 20
2026-01    0.0000      2         58.43        0.00  ligne 17 + 24 (autoliquidation) — verify with line-detail
2026-01   20.0000      8        345.02       69.00  ligne 20
2026-02   20.0000      2        765.00      153.00  ligne 20
------------------------------------------------------------------------------
           TOTAL                      1174.53      223.22
```

The 2026-02 ligne 20 number (765 € HT / 153 € TVA) is dominated by Darnis Operations (510 + 255). The 2026-01 row at 0 % is mixed (Wise BE autoliquidation 50 € + La Poste FR exempt 8.43 €) — workflow 2 splits them properly.

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

```bash
./scripts/deductible-line-detail.sh                   # all-time
./scripts/deductible-line-detail.sh --year 2026
./scripts/deductible-line-detail.sh --since 2026-02-01 --until 2026-02-28
```

Live output (captured at [examples/deductible-line-detail.txt](examples/deductible-line-detail.txt)) — supplier name and country annotated:

```
date        ref            supplier                     cnty    tx          HT       TVA  CA3 bucket
------------------------------------------------------------------------------------------------------------------------
2026-01-26  FAF2026001     Wise Europe SA               BE    0.00       50.00      0.00  ligne 17+24 (autoliquidation intra-UE)
2026-02-28  FAF2026009     Darnis Operations            FR   20.00      255.00     51.00  ligne 20/19 (déductible 20.0%)
...
2026-01-12  FAF2026006     La Poste                     FR    0.00        8.43      0.00  FR exempt / HT seulement
...

# Aggregated by CA3 bucket:
  FR exempt / HT seulement                      count=  1  HT=      8.43  TVA=    0.00
  ligne 17+24 (autoliquidation intra-UE)        count=  1  HT=     50.00  TVA=    0.00
  ligne 20/19 (déductible 20.0%)                count= 12  HT=   1116.10  TVA=  223.22
```

## Tying back to the CA3 — combined view

For any given month, the **net TVA à reverser** computation is:

```
net = TVA collectée (from tva-by-month.sh)
    - TVA déductible (from deductible-by-month.sh)
    - autoliquidation neutralized (ligne 17 = ligne 24, cancels)
```

For Arcodange today:
- TVA collectée = 0 € (all KissMetrics, all E2 autoliquidation 259-1°)
- TVA déductible = 223.22 € (mainly 20 % FR suppliers)
- **Net = TVA crédit de 223.22 €** — Arcodange is in TVA credit, can request reimbursement or carry forward.

That's the kind of summary a `dolibarr-tva-summary` (or `arcodange-tva-monthly-report`) skill could produce by composing this skill + `dolibarr-tva-reconciliation`. V5 candidate.

## Wise BE specific gotcha

The Wise Europe SA supplier (BE) currently has **no `tva_intra` field populated** ([dolibarr-thirdparty-completeness](../dolibarr-thirdparty-completeness/SKILL.md) flags this). Article 196 directive TVA requires the EU supplier's VAT number on Arcodange's books to substantiate the autoliquidation entry. **Mandatory remediation** before the next TVA declaration: add Wise's BE VAT number (BE0833 281 858 per their public registration) on the thirdparty record.

## Out of scope

- **Writes.** The declaration goes through impots.gouv.fr.
- **Customs / import TVA on goods.** Service-only Arcodange today; if goods imports happen, customs declarations are out of scope.
- **TVA sur encaissements** (régime spécial — TVA due on the payment date rather than invoice date for services). Not Arcodange's regime today.
- **Composition with collectée** (the net-to-remit summary). V5 candidate — a `dolibarr-tva-summary` skill.