APIs externes – Documentation consolidée

Auteur : Équipe 4NK

Ce document consolide la documentation des APIs externes utilisées par LeCoffre.io. Référence détaillée (Ancrage Bitcoin Signet, Annuaire, configuration, déploiement) : projects/lecoffreio/docs/API.md dans le dépôt ia_dev. Référence unique des checks de déploiement : voir Deployment.md (cartographie des checks).

API agent IA notaire (ai_working_help)

Vue d'ensemble

Le backend appelle l’API ai_working_help pour les opérations ask (legacy), enqueue et getResponse. L’URL de base est configurée via NOTARY_AI_AGENT_URL. Le projet et l’env sont identifiés par le token Bearer ; l’API résout le projet via projects/<id>/.secrets/<env>/ia_token. Filtrage IP 192.168.1.* côté API.

Authentification

Tous les appels doivent envoyer :

Authorization: Bearer <token>

Le token est de la forme base + env (ex. nicolecoffreiotest, nicolecoffreiopprod). En base : NOTARY_AI_AGENT_TOKEN. Côté ai_working_help : variable AI_WORKING_HELP_API_TOKEN ; si définie, toute requête sans header ou avec token invalide reçoit 401 Unauthorized. Routes /health et /v1/:slug/health peuvent rester sans authentification.

POST {NOTARY_AI_AGENT_URL}/ask — question synchrone (legacy)
POST {NOTARY_AI_AGENT_URL}/enqueue — mise en file (spooler)
GET {NOTARY_AI_AGENT_URL}/response/:request_uid — récupération de la réponse (poll)

Implémentation : lecoffre-back-main/src/services/notary/NotaryFolderAIService/NotaryFolderAIService.ts. Le header n’est ajouté que si NOTARY_AI_AGENT_TOKEN est renseigné.

Chat IA dossier notaire (endpoints applicatifs)

POST /api/v1/notary/folders/:uid/ai-question
- Auth : même chaîne que les autres routes dossier notaire.
- Body : { question: string }
- 202 : { request_uid: string } (requête en file ; réponse produite par l’agent).
- 503 : Agent non configuré ou enqueue en échec.
GET /api/v1/notary/folders/:uid/ai-response/:requestUid
- Auth : idem ; vérifie que la requête appartient à l’utilisateur/dossier.
- 200 : { status: "pending" } ou corps { answer, nextActionsTable, membersInfoSheet, synthesisRecommendation }.
- 404 : requête inconnue ou expirée. 503 : agent indisponible.

Flux : front → backend → ai_working_help (enqueue) ; agent (boucle Cursor) produit la réponse ; front poll GET response jusqu’à status !== "pending". Logs backend : [NotaryFolderAIService], [FolderNotaryAIController]. Front : [FolderNotaryAiChat].

Sécurité et restrictions

L’agent ne doit jamais renvoyer RIB, coordonnées bancaires ou de paiement. Contexte envoyé : métadonnées dossier, type d’acte, types de documents, résumé membres (rôle, nom, email), résumé documents (type, déposant, statut). Pas de contenu de fichier ni donnée de paiement.

API Annuaire V2 – Recherche offices et membres (IdNot PP)

Recherche offices : route GET .../api/v2/directory/lookup avec paramètre nomOffice uniquement (recherche sur l’office ; pas de mélange notaire). Retour : offices sans liste de collaborateurs.
Membres à la sélection : à la sélection d’un office, le front appelle GET /api/v1/notary/search/offices/:officeIdNot/members?officeName=... ; le backend appelle IdNot GET /api/pp/v2/entites/:officeIdNot/personnes et retourne les membres avec roleLabel (typeLien IdNot : Notaire, Collaborateur, etc.).
Front : getOfficeMembers(officeIdNot, officeName) ; hook useOfficeMembers(selectedOffice) ; affichage « Chargement des membres… » puis liste « Prénom Nom (roleLabel) » (ShareFolderModal, SearchConfrereSection).
Référence : API Annuaire V2 doc § VII.iii.a (nom, nomOffice, nomNotaire) ; IdNot PP entites/:id/personnes. Conformité : docs/compliance-annuaire-idnot-specs.md.

Autres APIs (référence détaillée)

API d’ancrage Bitcoin Signet : vue d’ensemble, endpoints /api/anchor/document, /api/anchor/verify, flux synchrone, configuration et déploiement — voir projects/lecoffreio/docs/API.md.
Intégration Genapi / iNot : POST /api/v1/notary/documents/:uid/push-inot, OAuth, création eDocument, code métier GENAPI_API_UNAVAILABLE.
Erreurs d’intégrations externes : mappings *_API_UNAVAILABLE (GENAPI, ANNUAIRE, ANCHORAGE, IDNOT, OPENID, IPFS, MAILCHIMP, STRIPE) ; conventions integration.operation pour la traçabilité.

Sources des messages backend (exposés à l’utilisateur)

PermissionDeniedMessageBuilder.ts : messages 403 en français (office, dossier, document) ; utilisé par FolderThirdPartiesAccessHelper, DocumentsNotaryAccessHelper.
errorMessages.ts : constantes techniques (réponses API, logique métier).
errorHandlers.ts : construction des réponses d’erreur, handlePermissionDeniedError (message du builder 403).
FolderSharingValidationHelper.ts : messages 400 partage dossier — invitation « même cabinet » unifiée : « Vous ne pouvez pas inviter un notaire de votre propre cabinet en tant que notaire invité. Veuillez choisir un notaire d'un autre cabinet. » (chemin même office UID et chemin même cabinet par email) ; logs [SHARE FOLDER] Tentative d'invitation vers le même cabinet avec email invité.

Règle : tout message destiné à l’utilisateur (ex. corps 403/400) en français et fonctionnel ; constantes et libellés centralisés dans ces modules (ou un module dédié documenté ici).

5.5 KiB Raw Blame History Unescape Escape