75 lines
6.4 KiB
Markdown
75 lines
6.4 KiB
Markdown
# 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/kogus/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 ; côté dépôt **ia_dev**, l’API résout le projet via les fichiers secrets du projet (chemin typé **`projects/<id>/.secrets/...`** selon la convention du projet). Côté monorepo LeCoffre, les secrets nominaux sont sous **`.secrets/<site>/<env>/`** — voir **`docs/features/multi-site-architecture.md`**. Filtrage IP 192.168.1.* côté API.
|
||
|
||
### Authentification
|
||
|
||
Tous les appels doivent envoyer :
|
||
|
||
```http
|
||
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 : `back-common/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]`.
|
||
|
||
Fiche détaillée (comportement métier, workflow, table des fichiers **front / back / ia_dev**) : **`docs/features/notary-folder-ai-workflow.md`**.
|
||
|
||
### 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** d’abord, puis **nom** si aucun office (recherche sur l’office ; pas de mélange notaire côté premier passage). Le backend pagine l’annuaire jusqu’à épuisement des pages (plafond de sécurité ~500 pages / pass), regroupe les offices distincts, **les trie par nom d’étude** (`localeCompare` `fr`, sensibilité de base), puis applique `offset` / `limit` (défaut 15) pour la réponse JSON. `hasMore` : il reste des études après la fenêtre courante.
|
||
- **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/kogus/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). Les **400** émis via `handleBadRequestError` / `handleBadRequestErrorJson` ont un corps JSON `{ "message", "http_status" }` (forme unique pour toutes les routes qui passent par ces helpers).
|
||
- **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).
|