Gabriel Radureau
1c0ba8ea75
Two changes that go together: now operators can run every read-only
workflow without going through Claude. The skills (SKILL.md files)
remain the source of behaviour documentation and Claude triggers;
bin/arcodange is the human-facing entry point.
bin/arcodange:
- Bash dispatcher at the project root. Subcommands per domain:
tva {collect, collect-detail, deductible, deductible-detail, summary},
invoice {list, audit}, thirdparty {audit, audit-all},
payments {state, timeline, by-month},
templates {list, inspect},
snapshot, whoami, ping, curl, help.
- Locates the project root via `git rev-parse` so it works from any
CWD (including from a worktree).
- Per-subcommand `help` text. Unknown commands exit 2 with a hint.
- Reuses the existing per-skill scripts under .claude/skills/<name>/
scripts/ via `exec` (zero behaviour drift, full credit to the
existing tested code).
dolibarr-tva-summary:
- Composes dolibarr-tva-reconciliation (TVA collectée customer-side)
and dolibarr-tva-deductible (TVA déductible supplier-side) into a
single CA3-ready monthly summary with per-month net verdict
(TVA à reverser / crédit de TVA / équilibre) and a cumulative line.
- Live baseline: Arcodange en crédit de TVA de 223.22 € cumulé
(0 € collectée 259-1° CGI vs 223.22 € déductible).
- Exposed as `arcodange tva summary [--year|--since|--until]`.
Each existing skill's SKILL.md gets a one-line "CLI shortcut" near
the top so the human path is discoverable from any skill page.
The project root README.md gets a CLI section as the primary
operator entry point.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
116 lines
7.1 KiB
Markdown
116 lines
7.1 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
|
||
|
||
**CLI shortcuts:** `bin/arcodange tva deductible` · `bin/arcodange tva deductible-detail` (or the combined `bin/arcodange tva summary`)
|
||
|
||
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.
|