# 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. Sa cotisation va au compte **646**
(cotisations personnelles du dirigeant), pas au compte fournisseur — l'inscrire
en facture fournisseur pollue le grand livre auxiliaire, les balances âgées et
les états de dettes fournisseurs.

**645 contre 646**, la distinction qui décide de tout :

| Compte | Pour qui |
| --- | --- |
| 645 | cotisations **patronales sur salaires** — suppose des salariés |
| **646** | cotisations **personnelles du dirigeant TNS** |

Arcodange n'a aucun salarié et Gabriel est gérant associé unique d'une SARLU,
donc **TNS** : tout va en 646. Le compte 645 doit rester vide.

Dans Dolibarr, cela se pilote par le **type de charge**, jamais par une saisie
manuelle du compte :

- `Securite sociale (URSSAF / MSA)` → régime salarié → 645
- **`Securite sociale des indépendants (URSSAF)`** → TNS → 646 ← **celui-ci**

> [!WARNING]
> Le code comptable de chaque type vit dans **Configuration → Dictionnaires →
> Types de charges sociales**. Vérifier une fois que la ligne « indépendants »
> porte bien 646 : si elle porte autre chose, le bon type enverra quand même
> l'écriture au mauvais compte. Non vérifié à ce jour.

## La commande

```bash
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 :

```bash
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.