Gabriel Radureau
e7abfd5e22
V2 in the dolibarr-* family. Three workflows:
- km-payment-state.sh: per-invoice reconciliation (TTC vs sum of
payments) with OK / PARTIAL / UNPAID / OVERPAID classification.
More honest than the `paye` boolean for deferred-cycle agreements.
- km-payment-timeline.sh: all KM payments sorted by date with
cumulative balance — the foundation for cohort-review deferred
9-month-cycle tracking (actual cash receipts vs contractual schedule).
- payments-by-month.sh: monthly aggregation, KM-scoped by default
or --all-clients for accounting basis.
Also updates dolibarr/SKILL.md endpoint catalogue with
/invoices/{id}/payments (note the date-as-string vs unix-epoch quirk)
and /bankaccounts, plus captures the corresponding examples.
V1 baseline of live data: KM is fully reconciled across 5 invoices
(1 avoir + 4 regular), 8160 € total cash receipts spread Feb/Mar/Apr 2026,
all on WISE EURO (BE).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
dolibarr — one-time setup
Skill body: SKILL.md. This README is the human-facing setup checklist.
1. Create .env (mode 600, never committed)
cat > .claude/skills/dolibarr/.env <<'EOF'
DOLIBARR_URL=https://erp.arcodange.lab
DOLIBARR_API_KEY=<get from Dolibarr UI: Users → ai_agent → API key>
DOLIBARR_USER=ai_agent
DOLIBARR_PASSWORD=<the ai_agent password, only needed for occasional UI login>
EOF
chmod 600 .claude/skills/dolibarr/.env
Verify it's gitignored:
git check-ignore .claude/skills/dolibarr/.env # should print the path
2. Grant ai_agent the four voir_tous permission flags
ai_agent is read-only by design. But Dolibarr's per-record ACL silently filters out invoices and thirdparties unless the voir_tous (see-all) flags are ticked. Without them, /invoices returns [] and /thirdparties returns 404 — looks like an empty database.
In the Dolibarr UI (https://erp.arcodange.lab/ → Setup → Users & Groups → ai_agent → Permissions), tick:
- Tiers → Lire les tiers
- Tiers → Voir tous les tiers (et pas seulement ceux liés à l'utilisateur courant)
- Factures → Lire les factures
- Factures → Voir toutes les factures (et pas seulement celles liées à l'utilisateur courant)
Save. Future modules used by dolibarr-* sibling skills (Paiements, Produits, …) need the same treatment.
3. Quick-start test
./.claude/skills/dolibarr/scripts/dol-curl.sh /users/info | jq -r .login
# → ai_agent
./.claude/skills/dolibarr/scripts/dol-curl.sh /status
# → {"success":{"code":200,"dolibarr_version":"22.0.4",...}}
./.claude/skills/dolibarr/scripts/dol-curl.sh /thirdparties/1 | jq '{ref, country_code, town}'
# → {"ref":"KissMetrics","country_code":"US","town":"St. Petersburg"}
If the third one returns HTTP 403 Access not allowed for login ai_agent on this thirdparty, the voir_tous flags from step 2 are missing.
4. Rotating the API key
If the key leaks: Dolibarr UI → Users → ai_agent → API key → Generate new → copy the new value into .env. No other change needed; every dolibarr-* skill picks it up via dol-curl.sh.
Pointers
- Full skill body, endpoint catalogue, gotchas: SKILL.md.
- First workflow skill that depends on this one: ../dolibarr-invoice-audit/SKILL.md.