/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.
Développeurs · Agents IA
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
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
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
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
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/health | GET | Santé du service, télémétrie d'exécution et version canonique. |
/api/v1/validate/xml | POST | Validation structurelle locale d'un document : schéma, somme de contrôle, arithmétique. |
/api/v1/math/calculate-breakdown | POST | Ventilation HT, taxe et retenue à la source, en unités mineures exactes. |
/api/v1/sandbox/clear | POST | Simulation locale d'un corridor. Aucun envoi, aucune administration sollicitée. |
/api/v1/audit/seal | POST | Ajout d'une entrée à la chaîne SHA-256 et preuve d'inclusion Merkle. |
/api/v1/audit/verify-chain | GET | Vérification de la chaîne et retour de la preuve d'inclusion. |
/api/v1/corridors/treaty-dossier | POST | Constitution du dossier conventionnel d'un corridor bilatéral. |
/api/v1/erp/verify-connection | POST | Contrôle du raccordement d'un connecteur ERP. |
/api/v1/pricing | GET | Quotas 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.
Serveur MCP
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. |
{
"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": ""
}
}
}
}
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
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.
Surfaces lisibles par machine
Pas de page à parser : deux documents stables, publiés à des URL fixes, que l'agent fetch avant de répondre.
/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.
/api/v1/openapi.json
Le contrat de l'API : routes, méthodes, schémas, codes d'erreur et mécanismes d'authentification, en JSON.
Idempotency-Key
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
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.
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.
Créez un compte Nano en deux minutes, ou montrez-nous deux cas concrets lors d'une démonstration de vingt minutes.