v1.4.7

Démarrer avec l'API (agents)

Tout ce qu'un agent IA doit savoir pour piloter Comptasse : authentification, conventions, scénarios et documentation lisible par machine.

Documentation lisible par machine

Toute cette documentation est également servie en Markdown brut (suffixe .md), pensé pour être consommé par un agent LLM. Le point d'entrée unique est le sommaire :

/documentation/sommaire.md

✓Chaque page HTML a une équivalente .md (ex : /documentation/guide/référence-api.md)
✓Chaque compte du PCG a sa page : /documentation/comptabilité/ressources/comptes/512.md
✓Chaque scénario comptable a sa page avec paramètres et exemples d'écritures
✓Le glossaire couvre les termes comptables français

Découvrir l'API

Un catalogue JSON de toutes les routes est exposé publiquement (sans authentification) :

GET /routes

{
  "routes": [
    {
      "method": "POST",
      "path": "/organizations/:idOrganization/years/:idYear/scenarios/:scenario",
      "name": "execute-scenario",
      "body": [
        { "name": "idYear", "type": "string", "required": true },
        { "name": "idJournal", "type": "string", "required": true },
        { "name": "params", "type": "record", "required": false },
        { "name": "isIdempotent", "type": "boolean", "required": false, "default": true }
      ],
      "return": [ ... ]
    }
  ]
}

Authentification

L'API utilise un cookie de session signé. Connectez-vous une fois, puis réutilisez le cookie :

# 1. Sign-in (conserve le cookie de session)
curl -c cookies.txt -X POST https://api.example.com/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email": "demo@comptasse.com", "password": "..."}'

# 2. Appels authentifiés
curl -b cookies.txt https://api.example.com/organizations

✓L'organisation est résolue depuis l'URL (recommandé), l'en-tête X-Organization-Id, ou le cookie comptasse_id_organization
✓Toute route non authentifiée renvoie 401 avec un JSON { message }

Conventions

Sujet	Convention
Corps de requête	JSON ; les routes GET lisent leurs paramètres dans la query string
Identifiants	Chaînes (idOrganization, idYear, idEntry…) passés dans l'URL
Dates	ISO 8601 (ex : 2025-01-31T00:00:00.000Z)
Montants	Chaînes numériques à 2 décimales (ex : "100.00") — jamais de nombres flottants
Erreurs	JSON { message, cause? } avec le code HTTP approprié (400, 401, 404…)
Pagination	Paramètres limit / offset sur les routes de liste

Scénarios comptables

Les scénarios génèrent des écritures métier prêtes à l'emploi (achats, ventes, paie, TVA, amortissements…). Chaque scénario est documenté avec ses paramètres et des exemples d'écritures équilibrées :

# Lister les scénarios disponibles
GET /organizations/:idOrganization/years/:idYear/scenarios

# Consulter les paramètres et un exemple d'écriture
GET /organizations/:idOrganization/years/:idYear/scenarios/achat-marchandises-fournisseur

# Exécuter un scénario (les comptes sont référencés par numéro PCG)
POST /organizations/:idOrganization/years/:idYear/scenarios/achat-marchandises-fournisseur
{ "idYear": "<idYear>", "idJournal": "<idJournal>",
  "params": { "amountHT": "1000", "vatRate": 20, "paymentMode": "credit" } }

Information

Les scénarios d'ouverture et de clôture (ouverture-exercice, cloture-exercice) lisent les soldes des comptes directement dans la base : aucune donnée à transmettre hormis l'exercice et le journal. Ils sont idempotents par défaut. Voir la page Exercices pour le workflow complet de fin d'exercice.

Contrôle qualité des écritures

✓POST .../entries/audit/missing-attachments : écritures sans pièce justificative
✓POST .../entries/audit/non-balanced : écritures déséquilibrées avec totaux et écart

Ces deux endpoints renvoient la liste des écritures à corriger — utile en fin de mois ou avant clôture.

CLI

Le CLI comptasse encapsule l'API pour les agents en ligne de commande :comptasse scenarios run, comptasse entries non-balanced, comptasse years close… Voir la Référence CLI.