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

name, description, requires

name	description	requires
dolibarr-tva-deductible	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).	bins auth curl jq python3 true

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

The mirror of dolibarr-tva-reconciliation 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 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.)
• /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)

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

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

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