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

Runbook — enregistrer une charge sociale ou fiscale (URSSAF, CFE, TVA…)

Public : un agent, quel que soit son modèle, ou l'opérateur. Écrit pour être suivi sans redécouvrir le terrain — cette routine a coûté une heure la première fois, elle doit en coûter deux minutes ensuite.

Pourquoi ce n'est pas une facture fournisseur

L'URSSAF n'est pas un fournisseur. L'inscrire en facture fournisseur pollue le grand livre auxiliaire, les balances âgées et les états de dettes fournisseurs : elle se saisit comme charge sociale.

Le compte : 641, et non 646

Important

Ce runbook a d'abord dit 646. C'était faux, et adc-009 l'a tranché. Si tu lis une version qui dit 646, elle est périmée.

Compte	Pour qui	Arcodange
645x	cotisations patronales sur salaires — suppose des salariés	non : aucun salarié, l'opérateur n'est pas employeur
646	cotisations de l'exploitant individuel, sociétés à l'IR	non : Arcodange est une SARL à l'IS
641, sous-compte dédié	la société prend en charge les cotisations personnelles de son gérant majoritaire — c'est un complément de rémunération	oui

Le raisonnement tient en une phrase : dans une société à l'IS, ce que la société verse à l'URSSAF pour son gérant majoritaire n'est pas un prélèvement de l'exploitant, c'est une charge de personnel. D'où 641. Voir adc-009 pour la démonstration complète, y compris la déductibilité intégrale de la CSG/CRDS pour la société — à ne pas confondre avec le sort de la CSG à l'impôt sur le revenu personnel du gérant (art. 62 CGI), qui est une autre question.

Warning

Le type de charge ne pilote PAS le compte sur ce déploiement. Les lignes du dictionnaire Configuration → Dictionnaires → Types de charges sociales sont sans code comptable — vérifié. Choisir « Securite sociale des indépendants (URSSAF) » ne suffit donc pas à envoyer l'écriture en 641 : l'affectation se fait au moment du transfert en comptabilité, ou par le sous-compte porté sur l'écriture. Ne pas croire qu'un bon type suffit.

Le type retenu reste Securite sociale des indépendants (URSSAF) : le gérant associé unique d'une SARLU est TNS, affilié à la Sécurité sociale des indépendants, et non assimilé salarié. C'est exact sur le fond même si ça n'emporte aucune conséquence comptable automatique ici.

La commande

cd test
DOLIBARR_ADDRESS=https://erp-sandbox.arcodange.lab \
  deno run -A recordSocialCharge.ts \
    --label "URSSAF 2026 — 2e échéance" \
    --due 2026-08-05 --amount 1215.00 --period 2026-08-05

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 recordSocialCharge.ts --label "…" --due … --amount … --period …

--dry-run affiche ce qui serait soumis sans rien écrire. --type "CFE" (ou tout autre motif) pour une charge qui n'est pas URSSAF ; le script liste les types disponibles s'il ne trouve pas de correspondance.

La charge est créée impayée. Le règlement s'enregistre séparément, quand il a réellement eu lieu — jamais par anticipation.

Ce que le script garantit

• Idempotent : il cherche d'abord la charge dans la liste (libellé + montant) et ne fait rien si elle existe. Un rejeu ne crée pas de doublon.
• Vérifié par lecture : après soumission il relit la liste, pas l'URL.
• Garde d'hôte : guard.ts refuse toute cible qui n'est pas la sandbox, sauf double opt-in production.

Les quatre pièges, tous rencontrés

1. La date est un piège à double fond. Le champ visible ech est décoratif : le backend ne lit que les champs cachés echday / echmonth / echyear, alimentés par le datepicker jQuery. Remplir le champ texte soumet une date vide — et Dolibarr crée quand même l'enregistrement, avec une période aberrante (20/06/2000 observé). Même chose pour period.
2. Le bouton n'a pas de name. Le cibler par value="Ajouter".
3. L'URL après soumission ne porte pas d'id. Vérifier par l'URL fait conclure à un échec sur une création réussie — c'est ainsi que quatre doublons sont apparus en sandbox pendant que le script affichait « non créée ». Toujours vérifier par la liste.
4. Les milliers s'affichent avec une espace insécable : 1215.00 devient « 1 215,00 ». Une comparaison littérale échoue au-delà de 999 €, et l'idempotence saute silencieusement. Comparer sans les espaces.

Pourquoi pas le pipeline de promotion

Dolibarr n'expose aucune API REST pour les charges sociales : /taxes, /socialcontributions et /chargesociales répondent tous « API not found ». Le module est actif (le droit 91 existe), seule l'API manque. Le pipeline fleet/harness/promote/ parle REST : il ne peut pas porter cette opération.

Ce script en conserve la discipline — répétition sandbox, relecture du résultat, opt-in production explicite — mais pas le juge indépendant ni l'artefact de gate. Acceptable pour une opération à trois champs ; à ne pas généraliser.

Après l'enregistrement

• Rapprocher le prélèvement bancaire quand il apparaît (Qonto pour Arcodange).
• Le calendrier fleet/profile/calendar.yaml porte les échéances URSSAF 2026 : 493,00 (22/05) + 1 215,00 (05/08) + 1 333,00 (05/11) = 3 041,00 €.
• L'échéancier officiel n'est disponible que dans l'espace urssaf.fr : les notifications par mail ne contiennent aucun montant, et le transfert Gmail → Zoho remplace même leur contenu par un texte générique. Récupérer le PDF à la main reste nécessaire.