Référence des outils

Le serveur expose trois outils, tous en lecture seule : aucun n'écrit de donnée, aucun n'accède à des données privées, aucun ne demande de compte.

Outil	Rôle	Génération de texte
`general_legal_qa`	Répondre à une question, avec les articles cités	Oui, fondée sur les extraits cités
`search`	Trouver les articles pertinents	Non, extraits réels uniquement
`fetch`	Lire le contenu d'un article à partir de son identifiant	Non, contenu réel uniquement

Portée pays

Le paramètre country_iso vaut BJ par défaut. Seul le Bénin (BJ) dispose aujourd'hui d'un corpus : utilisez BJ. Pour search et fetch, un code de pays hors de la liste acceptée est refusé avec une erreur de validation.

general_legal_qa

Répond à une question juridique en français, avec les articles cités.

Paramètres

Paramètre	Type	Obligatoire	Description
`question`	texte	oui	La question juridique, en français.
`country_iso`	texte	non (`BJ`)	Voir portée pays.

Réponse

Exemple réel (24/09/2026, serveur de développement) pour question: "Quel est le taux de TVA au Bénin ?" :

{
  "answer_markdown": "# Taux de TVA au Bénin\n\nLe taux de la TVA au Bénin est **unique et fixé à 18%**.\n\nLa TVA béninoise est mono-taux, il n'existe pas de taux réduit.\n\n**Référence légale :** Art. 241 CGI",
  "not_found": false,
  "citations": [
    {
      "id": "CGI:Art. 241 CGI@2085ed91",
      "article_code": "Art. 241 CGI",
      "title": "Art. 241 CGI (Code General des Impots BJ 2026)",
      "excerpt": "Art. 241) - Taux de la TVA au Benin: Taux UNIQUE = 18% (la TVA beninoise est mono-taux, pas de taux reduit)...",
      "document_type": "CGI",
      "page": 1,
      "source_url": null
    }
  ],
  "confidence": 0.75,
  "model_used": "eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
  "disclaimer": "⚠️ Information juridique générale fournie à titre informatif, sur la base du corpus légal indexé (...). Elle ne constitue pas un conseil juridique, fiscal ou comptable personnalisé. (...)"
}

Lire le texte officiel d'une citation

L'extrait d'une citation peut provenir du texte officiel ou d'une synthèse attestée par l'équipe PaieNova. Pour lire l'article, ouvrez la citation avec fetch et regardez metadata.source_type (voir fetch).

Champ	Description
`answer_markdown`	La réponse rédigée, en Markdown.
`not_found`	`true` quand le corpus ne couvre pas la question.
`citations[]`	Les articles sur lesquels la réponse s'appuie (voir identifiants stables).
`confidence`	Score de confiance du grounding, entre 0 et 1.
`model_used`	Le modèle qui a rédigé la réponse.
`disclaimer`	Rappel systématique, jamais vide : information, pas conseil personnalisé.

not_found est une réponse valide

Quand la question sort du corpus indexé, la réponse revient avec not_found: true, une liste de citations vide et une confiance à 0. Ce n'est pas une erreur : l'assistant refuse d'inventer. Voir le dépannage pour reformuler.

search

Recherche dans le corpus et renvoie les extraits les plus pertinents, sans aucune génération : chaque résultat est un extrait réel, avec un identifiant directement utilisable par fetch.

Paramètres

Paramètre	Type	Obligatoire	Description
`query`	texte	oui	La recherche, entre 3 et 2000 caractères.
`country_iso`	texte	non (`BJ`)	Voir portée pays.
`k`	entier	non (`5`)	Nombre maximum de résultats, de 1 à 20. Une valeur hors bornes est ramenée dans l'intervalle.

Réponse

Exemple réel (24/09/2026, serveur de développement) pour query: "taux de TVA", k: 3 :

{
  "results": [
    {
      "id": "CGI:Art. 241 CGI@2085ed91",
      "title": "Art. 241 CGI (Code General des Impots BJ 2026)",
      "url": null,
      "text": "Art. 241) - Taux de la TVA au Benin: Taux UNIQUE = 18% (la TVA beninoise est mono-taux, pas de taux reduit)..."
    },
    {
      "id": "DGI_INSTRUCTION:DGI (p.3)@af2dccb7",
      "title": "DGI Benin, E3_exonerations-classiques, page 3",
      "url": null,
      "text": "III - EVALUATION DE LA FISCALITE PERCUE AU CORDON DOUANIER (...) MONTANT DE LA TVA au taux de 18%..."
    },
    {
      "id": "SYSCOHADA:Art. 57 SYSCOHADA@2b5965a6",
      "title": "Art. 57 SYSCOHADA (suite) (OHADA / SYSCOHADA, Guide d'application)",
      "url": null,
      "text": "(...) Le taux de TVA est fixé théoriquement à 18%. (...)"
    }
  ],
  "not_found": false,
  "disclaimer": "⚠️ Information juridique générale fournie à titre informatif (...)"
}

Comme pour les citations, ouvrez un résultat avec fetch pour lire l'article et sa nature (metadata.source_type).

Champ	Description
`results[].id`	Identifiant stable, à passer tel quel à `fetch`.
`results[].title`	Titre de l'article.
`results[].url`	Lien vers la source officielle quand il existe. Souvent `null` aujourd'hui : ne le supposez pas renseigné.
`results[].text`	Un extrait de l'article (aperçu), pas le texte intégral.
`not_found`	`true` et `results` vide quand rien de pertinent n'est trouvé.
`disclaimer`	Rappel systématique, jamais vide.

fetch

Renvoie le contenu d'un article du corpus à partir de son identifiant. Aucune génération.

Paramètres

Paramètre	Type	Obligatoire	Description
`id`	texte	oui	Un identifiant stable renvoyé par `search` (ou par `citations[].id`).
`country_iso`	texte	non (`BJ`)	Voir portée pays.

Réponse

Exemple réel (24/09/2026, serveur de développement) pour id: "CGI:Art. 241 CGI" : c'est le texte officiel de l'article (source_type: "officiel").

{
  "id": "CGI:Art. 241 CGI@73939cf4",
  "title": "Art. 241 CGI (Code General des Impots BJ 2026)",
  "text": "Article 241 : Le taux de la taxe sur la valeur ajoutée est fixé à 18%.",
  "url": null,
  "metadata": {
    "document_type": "CGI",
    "article_code": "Art. 241 CGI",
    "country_iso": "BJ",
    "page": 116,
    "source_type": "officiel",
    "legal_status": "in_force",
    "effective_date": "2026-01-01",
    "superseded_by": null,
    "source_law_ref": null,
    "corpus_version": "73939cf4-c6f3-40aa-9f40-8554c70e457f"
  },
  "disclaimer": "⚠️ Information juridique générale fournie à titre informatif (...)"
}

Champ	Description
`id`	L'identifiant demandé.
`title`	Titre de l'article.
`text`	Le contenu indexé de l'article.
`url`	Lien vers la source officielle quand il existe, souvent `null`.
`metadata`	Informations sur la source, à titre indicatif (voir ci-dessous).
`disclaimer`	Rappel systématique, jamais vide.

metadata : informatif, pas contractuel

Les clés de metadata décrivent la source (type de document, statut juridique, version du corpus, texte de loi d'origine). Elles évoluent avec le travail sur la version en vigueur des textes : ne construisez pas de logique qui dépend de la présence d'une clé précise. source_type distingue le texte officiel d'une synthèse attestée par l'équipe PaieNova.

Identifiants stables

Tous les outils partagent le même format d'identifiant :

<document_type>:<article_code>@<version>

Exemples réels : CGI:Art. 241 CGI@73939cf4 (texte officiel), CGI:Art. 241 CGI@2085ed91 (synthèse attestée).

Le suffixe @<version> distingue les versions indexées d'un même article : le corpus peut contenir le texte officiel et une synthèse attestée.
Le même identifiant apparaît dans citations[].id de general_legal_qa, dans results[].id de search, et s'utilise dans fetch.
Vous pouvez donc ouvrir une citation : passez un citations[].id à fetch pour lire l'article cité.
Passez l'identifiant tel quel, espaces et suffixe compris. Ne le reconstruisez pas à partir d'un numéro d'article. fetch accepte aussi l'identifiant sans suffixe (CGI:Art. 241 CGI) : il renvoie alors la version servie par défaut, aujourd'hui le texte officiel pour cet article.

Parcours type : recherche approfondie

C'est ainsi que les modes de type Deep Research utilisent le serveur :

search avec les mots de la loi, par exemple taux de la TVA.
Sélection des identifiants pertinents dans results.
fetch sur chacun pour lire le contenu.
Rédaction d'une réponse par le client, à partir des contenus lus.

L'étape 4 est faite par votre client IA, pas par PaieNova : seule general_legal_qa rédige une réponse côté PaieNova.

Erreurs

Une erreur est renvoyée comme une erreur d'outil MCP, avec un message de la forme [CODE] message en francais.

Code	Cause	Que faire
`PUBLIC_LEGAL_VALIDATION_FAILED`	Paramètre invalide : `query` trop courte ou trop longue, `id` vide, pays refusé.	Corriger l'appel.
`PUBLIC_LEGAL_RATE_LIMITED`	Limite d'usage atteinte.	Attendre, puis réessayer.
`PUBLIC_LEGAL_UNAVAILABLE`	Service momentanément indisponible.	Réessayer plus tard.
`PUBLIC_LEGAL_TIMEOUT`	Le service n'a pas répondu à temps.	Réessayer.
`PUBLIC_LEGAL_UPSTREAM_ERROR`	Erreur réseau vers le service.	Réessayer plus tard.
`MCP_CONTRACT_MISMATCH`	Réponse du service non conforme.	Signaler au support.

Portée pays​

general_legal_qa​

Paramètres​

Réponse​

search​

Paramètres​

Réponse​

fetch​

Paramètres​

Réponse​

Identifiants stables​

Parcours type : recherche approfondie​

Erreurs​

Portée pays

general_legal_qa

Paramètres

Réponse

search

Paramètres

Réponse

fetch

Paramètres

Réponse

Identifiants stables

Parcours type : recherche approfondie

Erreurs