Intégration & API

Le daemon est l'unique point de confiance — vous n'êtes jamais détenteur d'un identifiant.

Guide intégrateur pour bâtir une intégration native contre la plateforme Esovran — sur le même modèle que l'add-in MicroStation de première partie. Surface loopback documentée, en boucle locale, consentie et révocable.

17 ROUTES PUBLIQUESOPENAPI / SWAGGERJETON OPAQUE SCOPÉRFC 7807

La frontière de confiance

Le daemon est le point de confiance unique de la plateforme — cette propriété dicte tout le modèle d'intégration.

Vous ne détenez jamais d'identifiant — l'utilisateur se connecte une seule fois dans le tray du daemon ; aucun mot de passe ne transite par votre intégration.

Appel en boucle locale uniquement — le plugin-host est lié à 127.0.0.1, jamais exposé hors du poste ; pas de CORS sur cette surface.

Accès par jeton consenti, scopé, révocable — l'utilisateur accorde à un plugin nommé un ensemble de dsIds + actions, dans le tray.

Vous êtes un délégué, agissant dans un périmètre choisi par l'utilisateur — jamais un détenteur d'identifiant.

Votre intégration ──loopback HTTP──► Daemon Esovran (127.0.0.1) ──HTTPS──► Filer (par client)
     (jeton opaque scopé)              (point de confiance unique)         (source de vérité)

Le handshake — consentement & jeton

Aucun identifiant n'est jamais échangé — la seule action humaine est l'utilisateur qui clique « Autoriser » dans le tray.

POST /request-token avec pluginId, pluginPath, dsIds → 200 si un consentement existe déjà, sinon 202 avec un handle — le tray affiche le dialogue de consentement.

L'utilisateur clique Autoriser ou Refuser — le tray, jamais votre intégration, enregistre la décision.

GET /request-token/{handle} — sonder jusqu'à 200 (jeton) ou 403 plugin-consent-denied.

# 1) démarrer le handshake
curl -X POST http://127.0.0.1:5180/api/_plugin/v1/request-token \
  -d '{"pluginId":"acme-cad","dsIds":["verallia-poc"]}'
→ 202 { "handle": "b2f9…", "status": "pending" }

# 2) l'utilisateur clique Autoriser dans le tray

# 3) sonder jusqu'à obtention du jeton
curl http://127.0.0.1:5180/api/_plugin/v1/request-token/b2f9…
→ 200 { "accessToken":"<opaque>", "expiresAt":"…", "dsIds":[…], "actions":["read","check_out","check_in","download","upload"] }

Le jeton est opaque (pas un JWT) — ne pas tenter de le décoder. Il est scopé aux dsIds et actions accordées, expire et est révocable à tout moment par l'utilisateur.

Catalogue des endpoints — 17 routes publiques

Toutes les routes sont sous /api/_plugin/v1, cohérentes octet pour octet avec le fichier OpenAPI publié.

Route	Scope	Usage
POST /request-token	—	Démarrer le handshake de consentement.
GET /request-token/{handle}	—	Sonder un handshake en attente.
GET /authorize	probe	Vérifier que le jeton accorde un DS + une action.
POST /documents/browse	read	Parcourir dossiers/documents — servi hors-ligne depuis le miroir local.
POST /search	read	Recherche plein texte — nécessite le Filer joignable.
POST /documents/{id}/fetch	download	Télécharger si référencé, puis matérialiser au chemin natif.
POST /documents/by-path	read	Résoudre un chemin disque en document Esovran.
POST /documents/materialize	read	Matérialiser un document en cache à son chemin natif.
POST /documents	check_in	Créer un document depuis un chemin de sauvegarde.
POST /documents/{id}/check-out	check_out	Verrouillage pessimiste en début d'édition.
POST /documents/{id}/check-in	check_in	Nouvelle version depuis le blob mis en scène.
POST /documents/{id}/release-checkout	check_out	Libérer un verrou tenu à la fermeture.
PUT /blobs/{hash}	upload	Mettre en scène un blob brut adressé par contenu (seule route au corps non-JSON).
POST /references	read	Déclarer une référence entre documents (ex. xref CAO).
POST /references/resolve	read	Résoudre une référence en chemin local / documentId.
POST /projects	read	Lister les projets et leurs dossiers racine (arborescence CAO).
GET /working-dir	read	Résoudre la racine des fichiers éditables du DS.

Les routes de gestion du consentement (consents/*) sont internes au tray — elles ne font pas partie de la surface intégrateur et ne figurent pas dans le spec.

Contrat d'erreur — RFC 7807

Chaque erreur est un corps application/problem+json. Réagissez au slug (dernier segment de type), jamais au seul statut HTTP.

{
  "type": "…/errors/plugin-consent-revoked",
  "title": "plugin-consent-revoked",
  "status": 401,
  "detail": "L'utilisateur a révoqué ce
             consentement dans le tray."
}

Slug	Statut	Réaction
not-signed-in	401	Demander la connexion dans le tray, puis relancer.
plugin-consent-denied	403	Ne pas relancer automatiquement.
plugin-consent-revoked	401	Relancer le handshake une fois, puis réessayer.
plugin-scope-denied	403	Redemander le `dsId`/action manquant.
filer-unavailable	503	Réessayer avec backoff ; les routes hors-ligne fonctionnent.
operation-conflict	409	Rafraîchir l'état ; réessayer ou différer.

Le daemon transmet aussi verbatim les slugs d'erreur du Filer (ex. document-locked-by-workflow) lorsqu'une route relaie une opération — même forme problem+json.

Versioning & stabilité

Seul le sous-ensemble publié dans le spec OpenAPI constitue un engagement de stabilité.

Changements additifs — nouvelle route, champ optionnel, valeur d'enum → version mineure.

Changements cassants — route/champ supprimé ou renommé → version majeure, annoncée.

Le segment v1 fait partie du contrat ; une future génération cassante vivrait sous v2.

Construire contre le spec, pas contre le code source — une route absente du spec ne doit pas être utilisée.

Points d'extension existants

Au-delà de l'API, Esovran offre une extensibilité au niveau configuration — sans code.

Workflows

Phases, rôles, opérations autorisées, effets de transition — configurables en JSON par espace.

Schémas de révision

Comportement d'incrémentation de révision / codification, configurable en JSON.

Codification & métadonnées

Classes de documents, champs, règles de codification et listes de référence configurables.

Le guide intégrateur complet et le spec OpenAPI sont disponibles sur demande.

Demander l'accès développeur