API REST et serveur MCP

Pilotez votre comptabilité depuis un autre logiciel : une boutique en ligne qui enregistre chaque vente, un agent IA qui saisit les opérations, un outil de reporting qui lit le bilan. Tout ce que fait l'application est accessible, avec les mêmes contrôles comptables.

Démarrer en trois étapes

curl https://votre-site/api/v1/societe \
  -H "Authorization: Bearer clt_VOTRE_CLE"

Clés et droits

Une clé donne accès à une seule société. Elle se transmet à chaque requête dans l'en-tête Authorization: Bearer clt_…. Seul l'administrateur de la société peut en créer (20 au plus) ou en révoquer ; la révocation est immédiate. ComptaLT ne conserve qu'une empreinte de la clé : perdue, elle ne peut pas être retrouvée, il faut en créer une nouvelle.

Portée d'une clé d'écriture

Une clé d'écriture reçoit une portée à sa création (champ portee de POST /api/cles-api, écran Réglages > API et intégrations). Donnez à chaque logiciel la plus étroite qui lui suffit : une clé collée dans une boutique est stockée en clair dans la base de la boutique.

Hors de sa portée, une clé reçoit 403 avec un message qui dit quelle portée demander. Un abonnement webhook créé avec une clé lui est lié (cleApiId, cleApiNom dans GET /webhooks) : quand la clé est révoquée, il est désactivé et ne reçoit plus rien. Quelle que soit sa portée, une clé ne modifie, n'essaie, ne renvoie ni ne supprime que les abonnements qu'elle a créés : ceux créés dans l'application ou par une autre clé lui répondent 403. Un abonnement désactivé ne se réactive par une clé que si c'est elle qui l'a désactivé (desactiveParCle) : désactivé dans l'application, ou à la révocation d'une clé, seule l'application le réactive. Un déclencheur n8n, Zapier ou Make abonné avant ce lien (champ source, sans cleApiId) peut encore être supprimé, désactivé ou réactivé à l'identique par une clé (adresse, événements et description inchangés), jamais modifié ni lié à elle. Le cycle des modules n'utilise que cela : abonnement (POST) et désabonnement (DELETE) de Zapier et Make, création, réactivation et suppression de ses propres abonnements par n8n.

Routes ouvertes à une clé

Une clé n'ouvre que les ressources documentées ici (liste blanche) : /societe, /settings, /comptes, /exercices, /ouverture, /ecritures, /pieces, /rapports, /tva, /exports, /factures, /clients, /devis, /opportunites, /contrats, /stock, /canaux, /commandes, /paiements, /fournisseurs, /banque, /caisse et /webhooks, et ce qui est en dessous. Toute autre adresse répond 403 à une clé, même si l'application l'utilise : par exemple /etat (comptabilité entière), /connexions, /echanges/…, /exports/sauvegarde et /exports/ticket, ainsi que les utilisateurs et les clés. Le refus porte le message « Cette opération n'est pas disponible par clé API : elle reste réservée à l'application (voir /developpeurs). » ; une clé en lecture seule qui tente une modification reçoit « Cette clé API est en lecture seule. » Les règles s'appliquent à l'adresse décodée, comme la lit le serveur : /exports/sauvegard%65 est /exports/sauvegarde et reçoit le même refus.

Conventions

• Corps et réponses en JSON (Content-Type: application/json), texte en UTF-8.
• Dates au format AAAA-MM-JJ. Montants en francs suisses, nombres à deux décimales (108.1).
• Une opération réussie renvoie son résultat, par exemple { "ok": true, "ecriture": { … } }.
• Une erreur renvoie toujours { "erreur": "message lisible", "code": "refus" } : le message en français, prêt à afficher, et un code stable pour vos programmes (le message peut changer, le code jamais).
• Une opération reçue (commande, paiement, remboursement, clôture de caisse, relevé bancaire, facture fournisseur) datée d'une période TVA déjà déclarée n'est pas refusée : elle entre dans le décompte de la période en cours (art. 72 LTVA). Son écriture est passée à la date du jour et la réponse le signale dans avertissements (« Opération du 15.03.2026 passée au 04.10.2026 : la période TVA T1 2026 est déclarée… »).
• Les adresses sont sensibles à la casse : écrivez-les en minuscules, comme ici. /API/v1/societe, /api/V1/societe ou /api/v1/Societe répondent 404. Une barre finale (/api/v1/societe/) est acceptée.

Corps refusé : le détail des champs (400)

Avant tout traitement, le corps des requêtes /api/v1 (et donc des outils MCP) est contrôlé : seuls les types incohérents sont refusés, par exemple un libellé envoyé comme objet, une liste lignes qui n'est pas une liste ou un client qui n'est pas un objet. Les champs inconnus sont ignorés, un nombre en texte ("125.50") et un champ vide restent acceptés ; les contrôles comptables (équilibre, exercice, compte…) répondent toujours 422. Rien n'est enregistré ; la réponse donne le premier motif dans erreur et jusqu'à 20 motifs dans details, chacun avec le chemin du champ (lignes.0.compteNo : premier élément de lignes) :

# Réponse 400 à une écriture dont le libellé est un objet
{
  "erreur": "Requête invalide : libelle : texte attendu.",
  "code": "invalide",
  "details": [
    { "champ": "libelle", "message": "texte attendu" }
  ]
}

Codes d'erreur

Chaque réponse en erreur porte un champ code, stable d'une version à l'autre : testez le code, pas le message. Un refus de la comptabilité répond toujours 422 sur /api/v1 (et 200 avec { "res": { "ok": false, "message", "code" } } sur /api/compta), même quand son code est introuvable ou invalide : le statut HTTP des intégrations existantes ne change pas, le code précise la raison. Les autres erreurs ont le statut de leur code.

Renvoyer une requête sans risque de doublon

Ajoutez l'en-tête Idempotency-Key à toute modification (POST, PUT, DELETE), sur /api/v1/… comme sur /api/compta/…, avec une valeur propre à l'opération : le numéro de commande de votre boutique, un identifiant tiré au hasard. Si la même requête arrive à nouveau dans les 24 heures (coupure réseau, nouvel essai automatique), ComptaLT ne l'exécute pas une deuxième fois : il renvoie la réponse d'origine avec l'en-tête Idempotent-Replayed: true. Deux envois simultanés n'enregistrent qu'une opération : le second attend la fin du premier.

• La clé est enregistrée avec l'opération elle-même : elle reste valable après un redémarrage du serveur.
• Elle vaut pour une clé API (ou un utilisateur), une méthode et une adresse : la même valeur envoyée à une autre adresse est une autre opération. Ne réutilisez jamais une valeur pour une opération différente sur la même adresse : elle serait prise pour un renvoi. 500 caractères au plus.
• Une requête refusée avant tout traitement (400, 403, 409) n'est pas retenue : corrigée, elle peut être renvoyée avec la même clé.
• Si la réponse d'origine était très volumineuse (plus de 16 Ko), le renvoi répond seulement { "ok": true } : relisez la ressource si vous en avez besoin.

Ne pas écraser une modification faite entre-temps

Chaque réponse porte la révision de la comptabilité dans l'en-tête ComptaLT-Revision (un nombre qui augmente à chaque enregistrement). Elle est aussi dans l'ETag (fort, ETag: "12") : d'une lecture, la révision lue ; d'une modification, la révision qu'elle a enregistrée (une modification refusée ou qui n'enregistre rien n'a pas d'ETag). Pour une modification qui dépend de ce que vous avez lu, envoyez cette révision dans l'en-tête facultatif If-Match (If-Match: "12" ou If-Match: 12) : si la comptabilité a changé depuis (autre utilisateur, autre intégration), la requête est refusée en 409 sans rien modifier ; relisez, puis refaites la modification. Sans If-Match (ou avec If-Match: *), rien ne change : la modification s'applique à la comptabilité du moment.

curl -X POST https://votre-site/api/v1/ecritures \
  -H "Authorization: Bearer clt_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-1042" \
  -H "If-Match: 12" \
  -d '{ … }'

Réponses allégées : Prefer: return=minimal

Les réponses de /api/v1 ne contiennent que le résultat de l'opération ({ "ok": true, "ecriture": { … } }). L'API de l'application, /api/compta/…, renvoie en plus, par défaut, toute la comptabilité de la société après chaque modification ({ "res": { … }, "base": { … } }), ce qui pèse lourd pour une grosse société. Avec l'en-tête Prefer: return=minimal (RFC 7240), une modification renvoie seulement son résultat et la nouvelle révision, { "res": { … }, "revision": 42 }, avec l'en-tête Preference-Applied: return=minimal. Une modification qui renverrait la comptabilité ou les réglages seuls (PUT /settings, sur /api/v1 aussi) répond { "revision": 42 }. Les lectures et les réponses sans l'en-tête ne changent pas ; un renvoi idempotent sans l'en-tête renvoie la réponse complète.

Requêtes simultanées

Vous pouvez envoyer plusieurs modifications en parallèle : pour une même société, ComptaLT les traite l'une après l'autre, sans en perdre aucune. Les lectures ne sont jamais bloquées.

Société et réglages

Plan comptable

Exercices

Écritures

Toute opération est une écriture en partie double : la somme des débits égale la somme des crédits, et chaque ligne porte soit un débit, soit un crédit. La date doit tomber dans l'exercice, qui doit être ouvert.

POST /api/v1/ecritures
{
  "annee": 2026,
  "date": "2026-09-17",
  "libelle": "Loyer de septembre",
  "lignes": [
    { "compteNo": "6000", "debit": 1650, "credit": 0 },
    { "compteNo": "1020", "debit": 0,    "credit": 1650 }
  ]
}

decompteTva: true est réservé au paiement, au remboursement ou à la provision de la TVA (écriture exclue du décompte) : une écriture qui le porte ne touche que les comptes de TVA et l'argent. Posé sur une autre écriture (une vente, par exemple, qui sortirait ainsi du décompte), il est refusé (422). Le paiement de la TVA d'une période terminée (decompteTva: true, libellé qui nomme la période, par exemple « Décompte TVA T1 2026 ») la rend déclarée.

Paiement déjà encaissé par le relevé bancaire (422)

Une nouvelle écriture qui encaisse un débiteur (un compte d'argent au débit, les débiteurs au crédit du même montant) est refusée quand le relevé bancaire importé a déjà encaissé ce paiement : transaction du même compte et du même montant, à 31 jours près, rapprochée d'une facture, d'une commande ou d'une écriture de débiteurs, sans autre transaction de ce montant à traiter. L'enregistrer compterait l'argent deux fois. La réponse est 422 :

{ "erreur": "Ce paiement de 1081.00 CHF semble déjà enregistré : le relevé bancaire du 10.03.2026 l'a encaissé la facture 2026-0001 (Client SA). …",
  "code": "doublon_probable",
  "doublonProbable": { "transactionId": "…", "date": "2026-03-10", "montant": 1081, "compteNo": "1020" } }

S'il s'agit bien d'un autre paiement, renvoyez la même écriture avec "doublonConfirme": true ("true" et 1 sont acceptés) ; sinon, ne la renvoyez pas : le paiement est déjà en comptabilité. Pour encaisser une facture, préférez POST /factures/{id}/encaisser ou /paiements, qui tiennent compte du relevé.

Écritures verrouillées

Une écriture d'un exercice clôturé, ou qui entre dans le décompte d'une période TVA déclarée, ne se modifie plus (date, montants, comptes, drapeau decompteTva) et ne se supprime plus : POST /ecritures avec son id et DELETE /ecritures/{id} répondent 422 (« L'écriture n° 12 du 15.03.2026 ne se modifie plus : la période TVA T1 2026 est déclarée. Corrigez-la par une extourne datée du jour, puis une nouvelle écriture »). Seul son libellé se corrige. Corrigez-la par POST /ecritures/{id}/corriger. Une nouvelle écriture datée d'une période déclarée est refusée de même (422) : passez-la à une date de la période en cours.

Les montants debit et credit reçus par l'API sont arrondis au centime (un calcul de TVA par expression, par exemple 11.3894, devient 11.39). Si l'écriture reçue était équilibrée, l'écart d'arrondi (un centime par ligne au plus) est repris sur la ligne que l'arrondi a le plus déplacée (à égalité, sur un compte hors TVA) ; une écriture reçue déséquilibrée reste refusée (422). Un montant est un nombre JSON ou un texte décimal simple ("125.50") ; tout autre valeur (true, "0x10", "1e3", "12,50") est refusée (422). Envoyez de préférence des montants déjà arrondis.

Pièces jointes

Rapports, TVA et exports

Les rapports PDF, le grand livre Excel et les fichiers d'échange sont produits en arrière-plan, quelques-uns à la fois pour toute la plateforme. Quand trop d'exports sont déjà en cours, ou si un export dépasse le délai maximal (deux minutes par défaut), la réponse est 503 avec l'en-tête Retry-After (en secondes, par exemple Retry-After: 60) et { "erreur": "Trop d'exports sont en cours sur la plateforme : réessayez dans une minute." } : attendez ce délai avant de redemander le fichier, sans boucle de nouvelles tentatives immédiates. Les PDF d'une facture ou d'un devis ne sont pas concernés.

Clients

Factures

Cycle : brouillon (sans numéro) → émise (numéro définitif, écriture débiteurs / produits) → payée en partie (partielle) → payée (écriture argent / débiteurs), ou annulée. Une facture émise se corrige par un avoir.

• Numéro attribué à l'émission : un brouillon a "numero": "" ; POST /factures/{id}/emettre lui donne le numéro suivant de l'année (2026-0007), sans trou même si des brouillons sont supprimés. Lisez le numéro dans la réponse de l'émission, pas dans celle de la création. Un brouillon créé avant le 04.10.2026 garde le numéro qu'il avait déjà.
• Règlements : paiements liste chaque règlement { "id", "date", "montant", "nature", "ecritureId"?, "compteNo"?, "avoirId"?, "factureId"?, "montantRecu"? }, nature valant paiement, escompte, perte (perte sur débiteur) ou avoir (avoir imputé) ; absent sur une facture payée avant le 04.10.2026 (encaissementId et datePaiement comme avant). Par une clé API, chaque facture porte aussi solde : le solde ouvert (total moins les règlements ; 0 pour un brouillon ou une facture annulée). Une facture partielle attend encore son solde : traitez-la comme une facture à encaisser.
• Avoir : une facture au total négatif, avoirDe (identifiant de la facture d'origine) et motif, numérotée dans la même suite, émise aussitôt et imputée sur le solde ouvert de la facture d'origine ; le reste se rembourse au client. Ses lignes ont des quantités négatives. Une facture de total négatif sans avoirDe reste refusée (422).
• Relances : relances liste { "niveau", "date", "soldeOuvert", "interets"? } ; les intérêts moratoires ({ "taux", "depuis", "jusquau", "jours", "montant" }, art. 104 CO) ne sont pas comptabilisés.

Devis et opportunités

Contrats récurrents

Stock

Canaux de vente

Un canal regroupe les réglages comptables d'une source de ventes : une boutique, une caisse, un prestataire de paiement. Son code (minuscules, chiffres, ., _, -) est choisi par le logiciel qui l'alimente. Un canal inconnu est créé avec les valeurs par défaut à la première commande.

PUT /api/v1/canaux/prestashop-1
{
  "nom": "Boutique PrestaShop",
  "type": "prestashop",
  "mode": "ecritures",
  "stock": "mouvements",
  "comptes": {
    "ventesNormal": "3200", "ventesReduit": "3201", "ventesHebergement": "3401", "ventesExonere": "3200",
    "fraisPort": "",
    "encaissement": { "*": "1020", "carte": "1030", "paypal": "1036", "twint": "1037" },
    "frais": "6900", "debiteurs": "1100", "banque": "1020"
  }
}

Commandes

La façon la plus simple de relier une boutique : envoyez la commande telle quelle, ComptaLT calcule la TVA par taux, passe l'écriture (ou la facture), l'encaissement, la commission et la sortie de stock. Une commande renvoyée n'est jamais comptée deux fois : canal + reference l'identifient durablement.

curl -X POST https://votre-site/api/v1/commandes \
  -H "Authorization: Bearer clt_VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{
    "canal": "prestashop-1", "reference": "1042", "numero": "XKBKNABJK", "date": "2026-09-17",
    "prixTTC": true,
    "client": { "nom": "Marie Dupont", "email": "marie@exemple.ch", "npaLocalite": "1800 Vevey", "pays": "CH" },
    "lignes": [
      { "reference": "BOUG-01", "description": "Bougie parfumée", "quantite": 2, "prixUnitaire": 25.00, "tauxTva": 8.1 },
      { "reference": "LIV-12", "description": "Livre de recettes", "quantite": 1, "prixUnitaire": 30.00, "tauxTva": 2.6 },
      { "type": "port", "description": "Poste CH", "montant": 7.00, "tauxTva": 8.1 },
      { "type": "rabais", "description": "Code BIENVENUE", "montant": 5.00, "tauxTva": 8.1 }
    ],
    "total": 82.00,
    "paiement": { "moyen": "carte", "frais": 1.50, "reference": "pi_3Nabc" }
  }'
# → { "ok": true, "dejaEnregistree": false, "commande": { "statut": "payee", "totalTtc": 82, "totalTva": 4.66,
#      "ventilation": [{ "taux": 8.1, "compte": "3200", "ht": 48.1, "tva": 3.9, "ttc": 52 }, …], "avertissements": [] } }

Les avertissements ne bloquent pas (article inconnu du stock, stock insuffisant, exercice ouvert automatiquement, taux de TVA étranger, écart d'arrondi) : affichez-les dans le journal de votre connecteur. Une date dans l'année qui suit le dernier exercice ouvre cet exercice automatiquement ; un exercice clôturé refuse la commande.

POST /api/v1/commandes/prestashop-1/1042/remboursements
{
  "reference": "avoir-17",
  "date": "2026-09-25",
  "montantTtc": 32.00,
  "retours": [{ "reference": "BOUG-01", "quantite": 1 }],
  "motif": "Article abîmé"
}

• reference du remboursement obligatoire, unique par commande : renvoyé, il répond "dejaEnregistre": true.
• Montant, par priorité : lignes (détail, TVA de chaque ligne) ; montantTtc (argent rendu, TVA comprise) ; montant (dans la base de la commande) ; sinon tout le solde.
• Sans lignes, la TVA suit les articles de retours quand ils couvrent le montant (le surplus, par exemple les frais de port, est réparti sur le reste de la commande) ; sinon le montant est réparti au prorata des taux de la commande. Pour un avoir sans retour en stock sur une commande à plusieurs taux, envoyez les lignes.
• retours remet des articles en stock (canal en mode mouvements) ; retourStock: false n'en remet aucun.

Paiements isolés et versements

Pour un prestataire de paiement sans détail d'articles (lien de paiement, terminal, facture payée en ligne).

POST /api/v1/paiements
{ "canal": "stripe", "reference": "pi_3Nabc", "date": "2026-09-17", "montant": 108.10, "frais": 3.35,
  "moyen": "twint", "description": "Atelier du 20 septembre", "tauxTva": 8.1, "compte": "3400",
  "factureNumero": "2026-0012" }

• Si factureNumero désigne une facture ComptaLT émise, la facture est encaissée (et la commission passée) ; sinon le paiement devient une vente TTC d'une ligne.
• Il est rangé avec les commandes (origine paiement ou facture) : remboursements par /commandes/{canal}/{reference}/remboursements.

POST /api/v1/paiements/versements
{ "canal": "stripe", "reference": "po_1Nxyz", "date": "2026-09-19", "montant": 1045.30, "frais": 0 }
# Écriture : banque du canal au débit, compte d'encaissement (en transit) du canal au crédit.

Catalogue par référence

Fournisseurs et factures fournisseurs

POST /api/v1/fournisseurs/factures
{
  "fournisseur": { "nom": "Swisscom SA", "iban": "CH93 0076 2011 6238 5295 7" },
  "numero": "F-88123", "date": "2026-09-10", "echeance": "2026-10-10",
  "lignes": [{ "description": "Abonnement internet", "montant": 64.90, "tauxTva": 8.1, "compteCharge": "6570" }],
  "referencePaiement": "210000000003139471430009017"
}

lignes[].montant est TVA comprise : l'impôt préalable est extrait selon tauxTva (sauf méthode forfaitaire). Une ligne avec articleId et quantite fait entrer la marchandise en stock (au coût HT). Le paiement par le rapprochement bancaire solde la facture automatiquement quand la référence correspond.

Relevés bancaires et rapprochement

Formats reconnus : camt.053, camt.052 et camt.054 (ISO 20022, normes SIX), MT940 et CSV (PostFinance, UBS, Raiffeisen, exports génériques ; correspondance des colonnes détectée ou fournie). Les fichiers s'envoient en texte (contenu) ou en base64 (contenuBase64, UTF-8 ou Windows-1252). Un mouvement déjà importé est ignoré, y compris un paiement QR reçu d'abord par un avis camt.054 puis par le relevé camt.053 (même compte, date, montant et référence).

Caisse

Boutiques en ligne : modules prêts à installer

Les modules suivent exactement l'API ci-dessus : PUT /canaux/{code} à l'enregistrement de la configuration, POST /commandes au paiement, /remboursements pour les avoirs, /annuler, PUT /stock/articles/reference/{sku} pour le catalogue. Les erreurs 5xx, 429 et réseau sont réessayées ; 4xx et 422 attendent une correction puis un renvoi manuel.

Paiements en ligne et Shopify : connexions directes

Dans « API et intégrations », une connexion reçoit une adresse secrète https://votre-site/api/connecteurs/cx_… que vous indiquez à la plateforme. ComptaLT vérifie la signature, comptabilise, et tient un journal ; un événement refusé par la comptabilité (exercice manquant…) répond 200 à la plateforme et reste à rejouer après correction.

n8n, Zapier et Make

Tous se connectent avec l'adresse de ComptaLT et une clé API ; les déclencheurs créent et suppriment eux-mêmes leur webhook.

Webhooks : abonnements

Chaque livraison est un POST JSON ; une réponse 2xx en moins de 10 secondes la valide, sinon ComptaLT réessaie après 1 min, 5 min, 30 min, 2 h, 6 h et 24 h. L'adresse doit être en https et publique (les adresses internes sont refusées).

{
  "id": "evt_Yd0…", "type": "facture.payee", "creeLe": "2026-09-17T08:00:00.000Z", "societe": "Boutique Léman",
  "donnees": { … la facture … }
}

Événements

Les événements naissent de toute modification : application, API, agent IA, connexion directe ou tâche planifiée.

Vérifier la signature

L'en-tête ComptaLT-Signature: t=1726567200,v1=5f3c… contient l'horodatage et HMAC-SHA256(secret, "{t}.{corps brut}") en hexadécimal. Calculez-le sur le corps brut, comparez en temps constant et refusez un horodatage de plus de 5 minutes. ComptaLT-Livraison identifie la livraison (utile pour ignorer un doublon).

import { createHmac, timingSafeEqual } from 'node:crypto'

export function signatureValide(corpsBrut, entete, secret) {
  const parties = Object.fromEntries(entete.split(',').map((p) => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parties.t)) > 300) return false
  const attendue = createHmac('sha256', secret).update(`${parties.t}.${corpsBrut}`).digest('hex')
  return attendue.length === parties.v1.length && timingSafeEqual(Buffer.from(attendue), Buffer.from(parties.v1))
}

$corps = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_COMPTALT_SIGNATURE'] ?? ''), $parties);
$attendue = hash_hmac('sha256', $parties['t'] . '.' . $corps, $secret);
$valide = abs(time() - (int) $parties['t']) <= 300 && hash_equals($attendue, $parties['v1'] ?? '');

import hmac, hashlib, time

def signature_valide(corps_brut: bytes, entete: str, secret: str) -> bool:
    parties = dict(p.split("=", 1) for p in entete.split(","))
    if abs(time.time() - int(parties["t"])) > 300:
        return False
    attendue = hmac.new(secret.encode(), f"{parties['t']}.".encode() + corps_brut, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendue, parties.get("v1", ""))

Guide : facturer par l'API

# 1. Brouillon
POST /api/v1/factures
{
  "date": "2026-09-17", "annee": 2026,
  "client": { "nom": "Atelier Rossier Sàrl", "adresse": "Rue du Lac 4",
              "npaLocalite": "1800 Vevey", "pays": "CH", "email": "compta@rossier.ch" },
  "objet": "Refonte du site",
  "lignes": [
    { "description": "Conception", "quantite": 12, "prixUnitaire": 120,
      "tauxTva": 8.1, "compteProduit": "3400" }
  ]
}
# → { "ok": true, "facture": { "id": "…", "numero": "", "statut": "brouillon", … } }
# Le brouillon n'a pas encore de numéro.
# Sans "prixTTC" : selon facturation.prixTtcApiParDefaut (hors TVA pour une nouvelle société, 8.1 % en sus).
# Précisez-le : "prixTTC": false, 120 hors TVA ; "prixTTC": true, 120 TVA comprise (« dont TVA »).

# 2. Émission (le numéro est attribué ici), envoi, puis encaissement
POST /api/v1/factures/{id}/emettre
# → { "ok": true, "facture": { "numero": "2026-0012", "statut": "emise", … } }
POST /api/v1/factures/{id}/envoyer
POST /api/v1/factures/{id}/encaisser   { "compteArgentNo": "1020", "datePaiement": "2026-10-10" }

# Paiement partiel : la facture passe « partielle », solde = ce qui reste à payer
POST /api/v1/factures/{id}/paiements   { "compteArgentNo": "1020", "datePaiement": "2026-10-10", "montant": 500 }

# Correction d'une facture émise : avoir (toute la facture, ou des lignes), puis remboursement du reste
POST /api/v1/factures/{id}/avoir       { "date": "2026-10-20", "motif": "Prestation non réalisée" }
POST /api/v1/factures/{avoirId}/rembourser   { "compteArgentNo": "1020", "date": "2026-10-25" }

# PDF avec QR-facture du solde ouvert
GET  /api/v1/exports/facture?id={id}

Connecter un agent IA (MCP)

Le Model Context Protocol permet à un assistant IA d'utiliser directement votre comptabilité : « enregistre les frais de ce ticket », « quel est mon résultat à fin août ? », « facture 12 heures à l'Atelier Rossier ». Le serveur MCP de ComptaLT utilise le transport Streamable HTTP et la même clé API que l'API REST : une clé en lecture seule ne montre à l'agent que les outils de consultation, une clé d'écriture que les outils de sa portée (tous avec une clé complete).

claude mcp add --transport http comptalt https://votre-site/mcp \
  --header "Authorization: Bearer clt_VOTRE_CLE"

{
  "mcpServers": {
    "comptalt": {
      "type": "http",
      "url": "https://votre-site/mcp",
      "headers": { "Authorization": "Bearer clt_VOTRE_CLE" }
    }
  }
}

// TypeScript, @modelcontextprotocol/sdk
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL('https://votre-site/mcp'), {
  requestInit: { headers: { Authorization: 'Bearer ' + process.env.COMPTALT_CLE } }
})
const client = new Client({ name: 'mon-agent', version: '1.0.0' })
await client.connect(transport)
const { tools } = await client.listTools()
const resultat = await client.callTool({ name: 'rapport', arguments: { type: 'balance', annee: 2026 } })

Outils disponibles

Chargement de la liste…

Protocole brut

Serveur sans session : chaque message JSON-RPC 2.0 est un POST /mcp qui reçoit sa réponse en JSON (les lots de messages sont traités dans l'ordre). Versions de protocole acceptées : 2025-06-18, 2025-03-26, 2024-11-05.

curl -X POST https://votre-site/mcp \
  -H "Authorization: Bearer clt_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": { "name": "lister_ecritures",
                    "arguments": { "annee": 2026, "limite": 5 } } }'

Un outil refusé par la comptabilité répond normalement, avec "isError": true et le message d'erreur en texte : l'agent peut corriger et réessayer.

Bonnes pratiques de sécurité

• Une clé par logiciel : vous saurez qui fait quoi (date de dernière utilisation) et pourrez en couper un seul.
• Le minimum de droits : un tableau de bord ou un agent d'analyse n'a besoin que de la lecture seule.
• Gardez la clé côté serveur (variable d'environnement, coffre-fort de secrets), jamais dans une page web, une application mobile ou un dépôt de code.
• Une clé exposée par erreur se révoque immédiatement dans API et intégrations, puis se remplace.
• Un agent IA avec droits d'écriture agit en votre nom : relisez ce qu'il propose avant les opérations importantes (suppression, clôture).
• Webhooks : vérifiez toujours la signature et répondez vite (traitez en arrière-plan) ; un secret se régénère à tout moment.
• Connexions directes : l'adresse /api/connecteurs/cx_… est secrète ; supprimez la connexion si elle a fuité. Les secrets et clés des prestataires restent sur le serveur, chiffrés avec la comptabilité, et ne sont jamais renvoyés par l'API ni à l'application.