erp/.claude/skills/dolibarr-sandbox-write/RUNBOOK_quel_instrument.md

Runbook — quel instrument pour quelle dette

Public : un agent, quel que soit son modèle, ou l'opérateur.

Lire ceci AVANT d'enregistrer quoi que ce soit. Le choix de l'instrument décide de tout ce qui suit : le compte comptable, les rapports où l'écriture apparaîtra, et jusqu'à la voie technique disponible. Une opération parfaitement exécutée avec le mauvais instrument reste une erreur, et elle est plus coûteuse à défaire qu'à éviter.

La question qui tranche

À qui la société doit-elle cet argent ?

Le créancier est…	Instrument	Écran Dolibarr
un fournisseur réel (prestataire, éditeur, greffe, La Poste…)	facture fournisseur	Facturation → Factures fournisseur
un organisme social ou fiscal (URSSAF, CFE, TVA…)	charge sociale ou fiscale	Comptabilité → Charges sociales/fiscales
l'associé lui-même, ou personne (régularisation interne)	paiement divers	Banques → Paiements divers

Le piège, et il a été payé deux fois

Ni l'URSSAF ni le gérant ne sont des fournisseurs. Leur ouvrir une fiche fournisseur les fait apparaître au grand livre auxiliaire, dans les balances âgées et dans les états de dettes fournisseurs — des états censés ne montrer que le poste fournisseurs. L'erreur est invisible à la saisie et se découvre à la clôture.

Le contrôle qui la révèle est gratuit : regarder l'existant. Les dettes déjà portées au compte courant d'associé sont toutes des factures de fournisseurs réels payées personnellement par le gérant — le tiers y est le fournisseur, jamais le gérant. Un modèle qui contredit celui déjà en place est presque toujours le mauvais.

Le compte courant d'associé : deux usages à ne pas confondre

Le compte bancaire CCA1 (id 3) porte le numéro comptable 45511 et son propre journal comptable. Il sert dans deux cas différents :

1. Le gérant a avancé une dépense — un fournisseur réel a facturé, le gérant a payé de sa poche. → facture fournisseur au nom du fournisseur, puis règlement sur le compte 3. C'est adc-005.

2. La société doit quelque chose au gérant lui-même — indemnité d'occupation, remboursement forfaitaire. → paiement divers sur le compte 3, sans aucun tiers.

cd test
DOLIBARR_ADDRESS=https://erp-sandbox.arcodange.lab \
  deno run -A recordVariousPayment.ts \
    --label "Indemnité d'occupation — mars 2026" \
    --amount 220.00 --date 2026-03-31

Production — double opt-in explicite, comme toute écriture de production :

DOLIBARR_ADDRESS=https://erp.arcodange.lab \
ARCO_ALLOW_PRODUCTION=erp.arcodange.lab \
ARCO_PROD_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD \
  deno run -A recordVariousPayment.ts --label "…" --amount … --date …

Défauts : --account 3 (compte courant), --code 613 (Locations), --sens 0 (débit). --dry-run affiche sans écrire.

L'écriture produite :

débit  613000  Locations                     (la charge)
crédit 45511   G. RADUREAU, compte courant   (la dette envers l'associé)

Le plan comptable est chargé — nuance à connaître

358 comptes sont disponibles dans le sélecteur des paiements divers, dont un 455110 déjà dédié au compte courant du gérant. Ne pas confondre trois choses :

• le plan comptable est chargé et utilisable depuis ce formulaire ;
• l'API REST comptable n'est pas exposée (/accountancy/* → 404) ;
• le dictionnaire des types de charges sociales ne porte aucun code comptable (colonne vide pour tous les types, TAXSSI compris).

Conclusion pratique : sur un paiement divers, le compte se choisit et est enregistré. Sur une charge sociale, le type n'est qu'un libellé et l'imputation vit dans le grand livre de l'expert-comptable.

Ce que le pipeline gated ne peut pas porter

fleet/harness/promote/ parle REST. Or ni les charges sociales ni les paiements divers n'ont d'API : /taxes, /socialcontributions, /chargesociales, /variouspayments répondent tous « API not found ».

Le choix de l'instrument décide donc de la voie disponible. Facture fournisseur → pipeline gated complet, avec juge et artefact de gate. Charge sociale ou paiement divers → script UI, qui garde la discipline (répétition sandbox, relecture par la liste, opt-in production) sans juge indépendant ni gate. Ne pas choisir l'instrument pour la commodité de la voie : c'est la nature de la dette qui décide, et la voie s'ajuste.

Les pièges, tous rencontrés

1. Les dates sont un piège à double fond. Le champ visible est décoratif : le backend ne lit que les champs cachés {nom}day / {nom}month / {nom}year. Remplir le champ texte seul soumet une date vide. Vaut pour datep, datev, ech, period.
2. Vérifier par la LISTE, jamais par l'URL. Dolibarr renvoie des pages sans identifiant : conclure d'après l'URL fait déclarer un échec sur une création réussie — c'est ainsi que quatre doublons sont apparus en sandbox.
3. Comparer le libellé ENTIER, jamais un préfixe. Une version comparait les 24 premiers caractères ; « Indemnité d'occupation — » en fait exactement 24, si bien que mars reconnaissait février et se déclarait déjà enregistré — six mois silencieusement sautés. Un préfixe ne distingue que ce qui diffère avant lui. (recordSocialCharge.ts porte encore ce défaut, latent : ses libellés diffèrent avant le 24ᵉ caractère, aujourd'hui seulement.)
4. Les milliers s'affichent avec une espace insécable : 1215.00 devient « 1 215,00 ». Comparer sans les espaces, sinon l'idempotence saute au-delà de 999 €.
5. En zsh, set -- $var ne découpe pas les mots (contrairement à bash) : une boucle de saisie a produit des dates 2026--. Écrire les appels explicitement, ou utiliser un tableau.

Après l'enregistrement

• Rapprocher le mouvement bancaire réel quand il a lieu — un paiement divers sur le compte courant ne déplace aucune trésorerie, il constate une dette.
• Attacher le justificatif à l'objet concerné : voir RUNBOOK_ged.md.