# 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 :

```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 : `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).

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