Récupérer les modèles de documentation

Ce guide explique comment récupérer les modèles de documentation et leur structure détaillée à l'aide de l'API publique.

Prérequis

• Un jeu valide d'identifiants d'API
• Un jeton d'accès valide
• Un code d'organisation valide
• La permission de portée stonal.document.template.read

Vue d'ensemble

L'API des modèles de documentation fournit deux points de terminaison principaux :

1. Lister les modèles - Obtenir tous les modèles de documentation disponibles pour une organisation
2. Obtenir les détails d'un modèle - Récupérer l'arborescence complète des dossiers d'un modèle spécifique

---

Lister les modèles de documentation

Étape 1 : Appeler l'API

Voir : Spécification de l'API

GET /document-storage/v1/organizations/{organizationCode}/templates

Paramètres

Nom	Type	Requis	Description
organizationCode	string	true	Code d'organisation (paramètre de chemin)
language	string	false	Langue préférée (paramètre de requête, ex. « fr-FR »)

Exemple de requête

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/templates?language=fr-FR" \
-H "Authorization: Bearer {token}"

Réponse

{
  "templates": [
    {
      "id": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d",
      "name": "DOE Template",
      "organizationCode": "STONAL",
      "attachmentType": "BUILDING_GROUP"
    }
  ]
}

Réponses possibles

• 200 : Liste des modèles récupérée avec succès
• 403 : Interdit (permissions insuffisantes)

---

Obtenir les détails d'un modèle de documentation

Étape 1 : Identifier le modèle

Vous devez fournir le templateId, qui est l'identifiant unique du modèle dont vous souhaitez récupérer les détails.

Le format de l'ID de modèle est généralement un UUID : f90ee77d-b6cc-41fa-8d1f-bea649e6d93d

remarque

Assurez-vous que l'utilisateur dispose des droits d'accès nécessaires à l'organisation et au modèle pour pouvoir récupérer les détails du modèle.

Étape 2 : Appeler l'API

Voir : Spécification de l'API

GET /document-storage/v1/organizations/{organizationCode}/templates/{templateId}

Paramètres

Nom	Type	Requis	Description
organizationCode	string	true	Code d'organisation (paramètre de chemin)
templateId	string	true	Identifiant unique du modèle (paramètre de chemin)
language	string	false	Langue préférée (paramètre de requête, ex. « fr-FR »)

Exemple de requête

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/templates/f90ee77d-b6cc-41fa-8d1f-bea649e6d93d?language=fr-FR" \
-H "Authorization: Bearer {token}"

Réponse

{
  "template": {
    "id": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d",
    "name": {
      "fr-FR": "Modèle DOE"
    },
    "organizationCode": "STONAL",
    "attachmentType": "BUILDING_GROUP",
    "folders": [
      {
        "id": "folder-123",
        "name": {
          "fr-FR": "Documentation technique"
        },
        "parentId": null,
        "documentClass": {
          "identifier": "documentClassIdentifier",
          "code": "DPE"
        }
      }
    ]
  }
}

Réponses possibles

• 200 : Détails du modèle récupérés avec succès
• 404 : Modèle introuvable
• 403 : Interdit (permissions insuffisantes)

Remarques

• Paramètre de langue : Lorsqu'il est fourni, l'API renvoie les noms localisés dans la langue spécifiée. S'il n'est pas fourni ou s'il est invalide, la langue par défaut du système est utilisée.
• Hiérarchie des dossiers : Le tableau folders contient tous les dossiers avec leurs relations parent-enfant définies par le champ parentId.
• Dossiers racine : Les dossiers ayant parentId: null sont des dossiers de premier niveau.
• Classes de documents : Certains dossiers peuvent avoir des classes de documents associées qui définissent le type de documents pouvant y être stockés.

Gestion des erreurs

Scénarios d'erreur courants :

• Jeton d'accès manquant ou expiré → 401 Unauthorized
• Permissions de portée insuffisantes → 403 Forbidden
• Code d'organisation invalide → 403 Forbidden
• Modèle introuvable ou accès refusé → 404 Not Found

Bonnes pratiques :

• Vérifiez toujours le code de statut de la réponse avant de la traiter
• Gérez les réponses d'erreur de manière appropriée dans votre implémentation
• Mettez en cache les listes de modèles lorsque cela est pertinent afin de réduire les appels à l'API
• Utilisez le paramètre de langue pour offrir des expériences utilisateur localisées

Performance

Le point de terminaison des détails de modèle est optimisé pour éviter les schémas de construction-puis-aplatissement, afin d'offrir de meilleures performances lors de la récupération de structures de dossiers volumineuses.

Sécurité

Les deux points de terminaison nécessitent :

• Un jeton d'authentification valide
• La permission de portée stonal.document.template.read
• Des droits d'accès appropriés à l'organisation et aux modèles

L'API filtre automatiquement les résultats en fonction des permissions de l'utilisateur, garantissant que les utilisateurs ne voient que les modèles auxquels ils ont accès.