Développeurs · Agents IA

Une API, un serveur MCP, et une chaîne de preuves que vous vérifiez vous-même.

VATMesh expose une API REST versionnée sous /api/v1, une spécification OpenAPI 3.1 complète et un serveur MCP JSON-RPC 2.0. Vos agents et vos ERP appellent le même moteur déterministe : arithmétique en unités mineures, validation structurelle locale, journal d'audit chaîné par SHA-256.

API REST

Une API versionnée, deux modes d'authentification.

La base des routes est /api/v1. Les erreurs reviennent dans une enveloppe JSON commune (ok, code, error). Chaque requête est scopée à un tenant : un accès croisé renvoie 403 FORBIDDEN_CROSS_TENANT_ACCESS.

/api/v1

Une base, une version

La spécification OpenAPI 3.1 est publiée à /api/v1/openapi.json. Elle décrit chaque route, chaque schéma d'entrée et de sortie, et chaque code d'erreur.

Bearer

Session ou clé d'API

Une session (e-mail et mot de passe) délivre un jeton de session ; une clé de tenant s'envoie en Bearer dans l'en-tête Authorization. Le mode clé d'API est celui des intégrations ERP et des agents.

Idempotency-Key

Les reprises sont sûres

Une clé d'idempotence rejoue la réponse identique pendant 24 h (empreinte SHA-256 du tenant, de la méthode, du chemin et du corps). Un doublon concurrent renvoie 409 ; un corps modifié renvoie 422.

Route Méthode Rôle
/api/v1/healthGETSanté du service, télémétrie d'exécution et version canonique.
/api/v1/validate/xmlPOSTValidation structurelle locale d'un document : schéma, somme de contrôle, arithmétique.
/api/v1/math/calculate-breakdownPOSTVentilation HT, taxe et retenue à la source, en unités mineures exactes.
/api/v1/sandbox/clearPOSTSimulation locale d'un corridor. Aucun envoi, aucune administration sollicitée.
/api/v1/audit/sealPOSTAjout d'une entrée à la chaîne SHA-256 et preuve d'inclusion Merkle.
/api/v1/audit/verify-chainGETVérification de la chaîne et retour de la preuve d'inclusion.
/api/v1/corridors/treaty-dossierPOSTConstitution du dossier conventionnel d'un corridor bilatéral.
/api/v1/erp/verify-connectionPOSTContrôle du raccordement d'un connecteur ERP.
/api/v1/pricingGETQuotas et tarifs de dépassement publiés, par devise.

La liste complète des routes, les schémas et les codes d'erreur sont dans la spécification OpenAPI 3.1. Le détail des mécanismes est dans llms.txt, écrit pour les agents.

Ouvrir la spécification

Serveur MCP

Un serveur MCP, douze outils documentés.

Le serveur MCP parle JSON-RPC 2.0 sur /api/v1/mcp. Il exige une clé active et un tenant authentifié, transmis dans l'en-tête Authorization (Bearer) ou x-api-key. Les douze outils appellent les moteurs déterministes de la plateforme — jamais un modèle de langue.

calculate_vat_tn

Calcule la TVA tunisienne (7 %, 13 %, 19 %), le FODEC facultatif (1 %) et le timbre fiscal (1,000 DT) sur un montant hors taxes.

Entréessubtotal (montant HT en dinars, obligatoire), vat_rate (7, 13 ou 19 ; 19 par défaut), apply_fodec (false par défaut), stamp_tax (1,000 DT par défaut).

RésultatMontant de la TVA, FODEC, timbre fiscal et total TTC, arrondis au millime pour le dinar.

Référentiel tunisien uniquement : art. 18 du Code de la TVA et LF 2026. L'outil calcule ; il ne déclare rien.

calculate_payroll_cnss

Calcule les cotisations CNSS salarié (9,18 %) et employeur (17,07 %), l'IRPP par tranches, la CSS de 1 % et le salaire net.

Entréesgross_salary (salaire brut mensuel en dinars, obligatoire), dependent_children (0 par défaut), is_married (false par défaut).

RésultatCotisations CNSS salarié et employeur, IRPP par tranche, CSS de 1 %, salaire net à payer.

Échelle tunisienne. L'outil calcule la paie : il n'émet ni bulletin, ni déclaration CNSS, ni attestation.

calculate_corporate_tax_is

Calcule l'impôt sur les sociétés tunisien (IS 15 % standard, 10 % réduit, 35 % élevé) et le minimum d'imposition, selon le chiffre d'affaires local et d'export.

Entréestaxable_profit (bénéfice fiscal imposable en dinars, obligatoire), turnover (chiffre d'affaires annuel), regime (standard, reduced ou high ; standard par défaut), is_export (false par défaut).

RésultatImpôt sur les sociétés dû, minimum d'imposition et taux effectif.

Référentiel tunisien uniquement. Un taux réduit ou élevé doit correspondre à un régime réel : l'outil calcule, il ne qualifie pas.

validate_vat_mentions_tn

Contrôle les neuf mentions obligatoires d'une facture tunisienne (art. 18 du Code de la TVA et LF 2026).

Entréesdate, number, seller_name, seller_tax_id, buyer_name, buyer_tax_id, items (lignes de facture), total_vat, total_ttc, total_in_words. Obligatoires : date, number, seller_name, seller_tax_id, buyer_name, items, total_ttc.

RésultatListe des mentions manquantes ou non conformes, et verdict global.

Contrôle des mentions, pas du schéma : la validation XSD et Schematron du document est l'outil MCP validate_schematron, et la route REST POST /api/v1/validate/xml — les deux appellent le même moteur.

zatca_generate_qr

Génère le QR code TLV à 9 balises de la phase 2 ZATCA FATOORA, avec signature ECDSA et chaînage SHA-256 du PIH.

Entréesseller_name, vat_number (numéro d'enregistrement TVA saoudien à 15 chiffres), timestamp, invoice_total, vat_total. Obligatoires : seller_name, vat_number, invoice_total, vat_total. Vous pouvez fournir votre propre ecdsa_signature et public_key.

RésultatLes 9 balises TLV, le contenu encodé, la signature ECDSA, le hachage PIH et le verdict de conformité phase 2.

L'outil prépare le bloc de signature : il ne signe pas avec votre CSID et ne transmet rien à ZATCA. Vous signez et vous déposez depuis votre propre portail.

tej_calculate_withholding

Calcule la retenue à la source tunisienne (RS 1,5 %, 10 %, 15 %, 25 %) et produit la structure du certificat TEJ.

Entréesdebiteur et beneficiaire (objets avec matricule_fiscal), factures (liste de lignes : numero, montant_ht, taux_tva, taux_rs).

RésultatRetenue calculée par facture, total retenu et charge utile du certificat TEJ.

L'outil produit la structure du certificat ; le dépôt de la déclaration TEJ reste entre vos mains.

autofattura_generate

Génère la charge utile XML d'une autofattura italienne (TD17, TD18, TD19) pour les services et biens transfrontaliers (art. 17 du DPR 633/72).

Entréesitalian_buyer (acheteur italien : Partita IVA, Codice Fiscale), foreign_supplier (prestataire étranger), tipo_documento (TD17, TD18 ou TD19), lines (lignes de facture).

RésultatLe XML prêt à signer, à transmettre par votre propre compte SdI.

Génération locale : vous signez avec votre certificat qualifié et vous transmettez depuis votre propre espace SdI.

swarm_list_agents

Liste les agents de conformité et de vérification fiscale disponibles dans le registre de domaine OmniTax.

EntréesAucune entrée.

RésultatLa liste des agents, avec leur périmètre et leurs fonctions appelables.

Le registre évolue avec la plateforme : appelez l'outil pour l'état du jour plutôt que de coder une liste figée.

swarm_call_agent

Exécute une fonction d'un agent spécialisé de conformité ou de fiscalité (par exemple algeria_tax_agent, pem_eur1_customs_agent).

Entréesagent_name (obligatoire), function_name (obligatoire), parameters (objet transmis à la fonction).

RésultatLe résultat JSON de l'agent.

L'agent exécute la fonction demandée sur les paramètres que vous transmettez. Le registre est public : appelez swarm_list_agents pour connaître le périmètre exact de chaque agent.

clear_corridor

Calcule le déblocage transfrontalier déterministe d'un corridor : il valide l'identifiant statutaire de chaque partie, applique l'article du traité et les taux de retenue, convertit le net à régler dans la devise de règlement et renvoie le reçu avec son sceau SHA-256.

EntréesAucune entrée obligatoire. corridor (code du corridor : TN_IT, IT_TN, TN_FR, TN_EU, TN_KSA, TN_MA, IT_EU, MA_FR, AE_EU ; TN_IT par défaut), invoice_number (par défaut : un identifiant INV horodaté, généré par le serveur), origin_tax_id (alias seller_matricule), dest_tax_id (alias buyer_tax_id), currency, settlement_currency, gross_amount (alias total_ttc ; 1000 par défaut), description, issue_date (aujourd'hui par défaut), seller_has_pe (à laisser vide quand le fait est inconnu : la détermination signale alors le fait manquant), evidence (tax_residency_certificate_present, pe_non_existence_declaration, dtt_form_submitted).

RésultatLe reçu de déblocage : corridor et ses rails, les parties et leurs identifiants validés, la ventilation du règlement (brut, retenue, économies, net, taux de change appliqué), la détermination réglementaire et ses faits manquants, l'archivage et le sceau SHA-256.

Même moteur, mêmes paramètres et mêmes valeurs par défaut que la route REST POST /api/v1/clearinghouse/clear. Le reçu est un calcul, pas une décision d'une administration fiscale : il porte son propre statut is_conclusive et signale les faits qui manquent. VATMesh ne dépose rien auprès d'une administration.

validate_schematron

Valide un document XML de facture contre un schéma public publié (TEIF v1.8.8, FatturaPA v1.2.2, Factur-X / EN 16931, ZATCA FATOORA) et renvoie les règles en échec avec leur chemin et leur ligne, l'audit arithmétique des totaux et le schéma détecté.

Entréesxml (payload XML du document fiscal, obligatoire ; alias acceptés : xmlString, xml_content, documentContent, content), schemaType (auto par défaut : le profil est détecté depuis la racine du document, sinon TEIF, FatturaPA, ZATCA ou FacturX ; alias : schema, standard), country (indice de juridiction : TN, IT, SA, EU, FR ; auto par défaut).

RésultatLe verdict de validation : schéma détecté, règles en échec, avertissements et audit arithmétique des totaux du document.

Même moteur, mêmes champs acceptés et mêmes valeurs par défaut que la route REST POST /api/v1/validate/xml. Le contrôle porte sur la structure du document et sur les règles des schémas : il ne détermine pas le traitement fiscal ou juridique de la transaction, il n'envoie rien à une administration fiscale et il ne certifie rien.

verify_merkle_seal

Vérifie la chaîne de hachage SHA-256 en ajout seul du journal d'audit du tenant appelant : chaque empreinte d'entrée et la racine Merkle sont recalculées du bloc genesis à la tête, et le résultat porte le rapport de chaîne ainsi que, lorsqu'un document est nommé, sa preuve d'inclusion Merkle.

EntréesAucune entrée obligatoire. document_id (document dont la preuve d'inclusion est renvoyée), seal (enregistrement ajouté à la chaîne avant la vérification : documentId obligatoire, eventType — DOCUMENT_CLEARED par défaut —, payload, jurisdiction — GLOBAL par défaut).

RésultatLe rapport de chaîne (intact, count, latest_hash, merkle_root), le tenant concerné et la preuve d'inclusion du document ; le reçu du scellement quand un seal est fourni.

Mêmes fonctions et même portée de tenant que les routes REST GET /api/v1/audit/verify-chain et POST /api/v1/audit/seal. Le journal est en ajout seul et inviolable à la détection, et son horodatage est un horodatage serveur, interne à la plateforme : ce n'est pas un service d'horodatage qualifié, et la preuve est un résultat d'intégrité technique, pas une garantie juridique ou fiscale.

Trois capacités disponibles des deux côtés : en MCP et en REST.

Les douze outils ci-dessus couvrent le calcul, le contrôle des mentions, la génération de documents, le déblocage d'un corridor, la validation XSD et Schematron d'un document et la vérification du journal d'audit. Les trois dernières capacités sont aussi exposées en REST : les deux surfaces appellent le même moteur, avec les mêmes paramètres et les mêmes valeurs par défaut, et renvoient les mêmes valeurs.

Capacité Outil MCP Route REST Ce qu'elle renvoie
Déblocage d'un corridor clear_corridor POST /api/v1/clearinghouse/clear Détermination conventionnelle : article du traité, retenue à la source, taux de change appliqué et sceau SHA-256.
Validation XSD et Schematron validate_schematron POST /api/v1/validate/xml Règles en échec, position de l'erreur et verdict global sur un document.
Sceau et chaîne d'audit verify_merkle_seal POST /api/v1/audit/seal · GET /api/v1/audit/verify-chain Ajout d'une entrée à la chaîne SHA-256, preuve d'inclusion Merkle et vérification de la chaîne.

Ouvrir la spécification OpenAPI 3.1

claude_desktop_config.json
{
  "mcpServers": {
    "vatmesh-fiscal-engine": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vatmesh.com/api/v1/mcp",
        "--header",
        "Authorization:${VATMESH_API_KEY}"
      ],
      "env": {
        "VATMESH_API_KEY": ""
      }
    }
  }
}
Outils exposés : calculate_vat_tn calculate_payroll_cnss calculate_corporate_tax_is validate_vat_mentions_tn zatca_generate_qr tej_calculate_withholding autofattura_generate swarm_list_agents swarm_call_agent clear_corridor validate_schematron verify_merkle_seal

Le pont utilisé ci-dessus est mcp-remote, un paquet npm public : il relaie le JSON-RPC 2.0 de /api/v1/mcp vers votre client MCP local. Remplacez la valeur d'environnement par votre clé d'API ; le serveur MCP exige une clé active et un tenant authentifié, et répond 401 sans elle.

Connecteurs ERP

Parlez à votre ERP.

Le principe est toujours le même : votre ERP émet un document, VATMesh le valide et le prépare, vous signez avec votre propre certificat et vous déposez depuis votre propre portail.

ERP Connexion Détail
SAP S/4HANA / Business One OData / IDoc Le connecteur SAP projette le document validé sur les champs IDoc : en-tête, code de taxe, identifiant fiscal du fournisseur.
QuickBooks Online QBO REST API v3 Le connecteur QuickBooks projette le document validé sur les champs d'une facture fournisseur : type, lignes, montant total.
Odoo REST / JSON-RPC Le connecteur Odoo projette le document validé sur les champs d'une facture fournisseur : type, base HT, taxe, montant TTC.
Sage 50 / 100 CSV / XML (lot) Le connecteur Sage projette le document validé sur les champs du lot : référence de compte, code de TVA, montants.
Tout autre ERP (Oracle ERP et autres) Point d'entrée REST universel Aucun connecteur spécifique n'est nécessaire : le document est envoyé au même point d'entrée. GET /api/v1/erp/supported liste les connecteurs publiés.

L'API est synchrone : le verdict de validation et le statut de scellement reviennent dans la réponse de la route appelée. Un en-tête Idempotency-Key rend les reprises sûres, et GET /api/v1/audit/verify-chain relit la chaîne à la demande.

Lire le guide d'intégration ERP

Surfaces lisibles par machine

Deux index que votre agent peut lire directement.

Pas de page à parser : deux documents stables, publiés à des URL fixes, que l'agent fetch avant de répondre.

/llms.txt

llms.txt

Un index en texte : ce que fait la plateforme, les formats couverts, les routes utiles et le périmètre du produit — écrit pour être lu par un modèle.

Ouvrir llms.txt

/api/v1/openapi.json

OpenAPI 3.1

Le contrat de l'API : routes, méthodes, schémas, codes d'erreur et mécanismes d'authentification, en JSON.

Ouvrir la spécification

Idempotency-Key

Reprises sûres

Toute route d'écriture accepte un en-tête d'idempotence : un retry renvoie la même réponse, un doublon concurrent renvoie 409, un corps modifié renvoie 422.

Périmètre

Ce que VATMesh ne fait pas.

Le périmètre est étroit, et il est écrit noir sur blanc : c'est ce qui permet à un intégrateur de construire la bonne intégration.

  • VATMesh n'envoie aucun document à une administration fiscale, à un portail officiel ou à un réseau de facturation électronique. Vous signez avec votre propre certificat qualifié et vous déposez depuis votre propre portail.
  • VATMesh n'est ni certifié, ni reconnu, ni mandaté par un État, une autorité fiscale ou un organisme de normalisation : il ne détient aucun statut officiel et aucun pouvoir de contrôle.
  • VATMesh ne fournit aucun conseil fiscal, juridique ou comptable : il calcule et il contrôle des structures, il ne recommande rien.
  • VATMesh n'est pas une autorité d'horodatage et n'émet aucun certificat d'horodatage tiers : l'horodatage du journal est un horodatage serveur, interne à la plateforme.
  • L'isolation des données est technique, pas réglementaire : un fichier SQLite par tenant, un tenant_id vérifié sur chaque requête, et 403 sur tout accès croisé.
Ce que vous pouvez vérifier vous-même

La chaîne SHA-256, les preuves d'inclusion Merkle et les reprises idempotentes sont exposés par l'API. Le registre du périmètre réglementaire détaille, juridiction par juridiction, ce que VATMesh applique et ce qui reste au client.

Lire le statut réglementaire

Industrialisez votre conformité, document par document.

Créez un compte Nano en deux minutes, ou montrez-nous deux cas concrets lors d'une démonstration de vingt minutes.