Aller au contenu principal

Récupérer les documentations d'un objet

Ce guide explique comment récupérer l'arborescence des documentations associées à un objet spécifique à 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
  • Un ID d'objet valide

Étape 1 : Identifier l'objet​

Vous devez fournir soit le assetId, qui peut être l'uid de l'objet, soit l'identifiant externe de l'objet pour lequel vous souhaitez récupérer la documentation.

Le format de l'uid de l'objet est asset-123 et le format de l'identifiant externe est ERP:BAT001 (une composition du code de type et du code de l'objet séparés par deux-points).

  • S'il n'est pas fourni, l'API renvoie une erreur 400 Bad Request.
remarque

Assurez-vous que l'utilisateur dispose des droits d'accès nécessaires à l'organisation et à l'objet pour pouvoir récupérer la documentation.

Étape 2 : Appeler l'API​

Voir : Spécification de l'API

GET /document-storage/v1/organizations/{organizationCode}/assets/{assetId}/documentations

Paramètres de requête :

Nom Type Requis Description assetId string true Identifiant unique de l'objet ou identifiant externe de l'objet

Important

Au moins un des paramètres assetUid ou externalId doit être fourni.

Exemple de requête utilisant assetUid :

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/assets/asset-123/documentations" \
-H "Authorization: Bearer {token}"

Exemple de requête utilisant externalId :

curl -X GET "https://api.stonal.io/document-storage/v1/organizations/STONAL/assets/ERP:BAT001/documentations" \
-H "Authorization: Bearer {token}"

Réponses possibles​

  • 200 : Entrées de documentation récupérées avec succès
  • 400 : Requête incorrecte (assetUid et externalId sont tous deux absents)
  • 404 : Aucune documentation trouvée pour l'objet indiqué

Remarques​

  • L'API renvoie la structure de documentation jusqu'à un niveau de profondeur par défaut (10 niveaux de profondeur).
  • Si l'objet n'a aucune documentation associée, une erreur 404 Not Found est renvoyée.
  • Assurez-vous de gérer correctement les cas où l'objet ne dispose pas encore de documentation.

Gestion des erreurs​

Scénarios d'erreur courants :

  • assetUid et externalId sont tous deux nuls → 400 Bad Request
  • Référence d'objet invalide ou non autorisée → 404 Not Found
  • Jeton d'accès manquant ou expiré → 401 Unauthorized

Vérifiez toujours le statut de la réponse et gérez les réponses d'erreur de manière appropriée dans votre implémentation.