Gabriel Radureau
585b7beb03
V4 bundle — two more sibling skills, both read-only, both depending on the dolibarr base skill. dolibarr-thirdparty-completeness: - audit-thirdparty.sh <socid>: country-aware completeness audit for any thirdparty (FR: SIREN + SIRET + tva_intra; EU non-FR: tva_intra; extra-EU: national tax id). Generalizes the V1 KM-hardcoded script. - audit-all-thirdparties.sh: loops over /thirdparties and surfaces a compact table of gaps. --clients-only / --suppliers-only flags. - Live baseline finds 5/10 thirdparties with mandatory gaps: KissMetrics (US tax id), Wise Europe SA (BE tva_intra), Medialex (FR SIRET + tva_intra), Qonto (SIRET), Infogreffe (SIRET). dolibarr-tva-deductible: - deductible-by-month.sh: TVA déductible aggregated per period × rate. - deductible-line-detail.sh: per supplier-invoice line with country- based CA3 bucket assignment (ligne 20 for 20 % FR, ligne 19 for reduced rates, ligne 17+24 for intra-UE autoliquidation). - Live baseline: 223.22 € total TVA déductible across 13 lines. Wise Europe SA correctly identified as intra-UE autoliquidation; La Poste correctly identified as FR exempt (timbres). - Mirrors dolibarr-tva-reconciliation on the supplier side. Together they give the two numbers a CA3 monthly declaration needs. Also extends dolibarr/SKILL.md endpoint catalogue with /supplierinvoices (noting the 403 on the /lines sub-endpoint — inline lines on the detail endpoint make this a non-issue). dolibarr/README.md gains two new permission checkboxes for Factures fournisseurs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
114 lines
7.0 KiB
Markdown
114 lines
7.0 KiB
Markdown
---
|
||
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.
|