Rechercher des documents

Ce guide couvre tous les filtres pris en charge pour interroger les documents dans la plateforme Stonal. Il détaille chaque filtre que vous pouvez utiliser pour affiner vos requêtes de recherche.

---

Prérequis

• Un jeton d'accès OAuth valide (voir Authentification)
• Votre code d'organisation (utilisé dans le chemin du point de terminaison)

---

1. Groupes de filtres et champs

Chaque groupe représente un ensemble de filtres ciblant différents aspects de vos documents.

1.1 Filtres d'emplacement de classement

Filtre	Type	Description
assetIdentifiers	Set[String]	Ne renvoyer que les documents rattachés à ces UID d'objets.
documentationIdentifiers	Set[String]	Ne renvoyer que les documents liés à ces UID de documentation.
folderIdentifiers	Set[String]	Ne renvoyer que les documents stockés dans ces UID de dossiers.

1.2 Filtres de contexte métier

Filtre	Type	Description
linkedAssetIdentifiers	Set[String]	Documents liés à des objets liés spécifiques (ex. bâtiment, appartements).
tenantIdentifiers	Set[String]	Documents appartenant à des locataires spécifiques ou créés par eux.
linkedAsset	String	Correspondance partielle ou totale du nom de l'objet lié — utile lorsque vous n'avez pas les UID sous la main.
hasLinkedAssets	Boolean	Filtrer les documents qui ont au moins un objet lié (true) ou aucun (false).

1.3 Filtres de document de base

Filtre	Type	Description
identifier	Set[String]	UID exacts des documents à récupérer.
name	String	Correspondance partielle ou totale du nom (insensible à la casse).
documentStatus	String	L'une des valeurs CLASSIFICATION, METADATA_EXTRACTION, COMPLETED.
hashSha256	String	Somme de contrôle SHA-256 du contenu du document.
updatedAfter	String	Horodatage ISO-8601 pour filtrer les documents mis à jour pendant ou après cette date.

1.4 Filtres de métadonnées

Filtre	Type	Description
tags	Set[String]	Documents étiquetés avec une ou plusieurs étiquettes spécifiées.
properties	Map[String,String]	Documents avec des paires clé-valeur de métadonnées correspondantes.
propertyKey	String	Documents contenant une clé de métadonnée spécifique (quelle que soit la valeur).
hasMetadata	Boolean	Filtrer les documents disposant de métadonnées exploitables (true) ou aucune (false).

1.5 Filtres de dossier et de classification

Filtre	Type	Description
parentFolderName	String	Correspondance partielle sur le nom du dossier parent.
predictedFolderName	String	Nom de dossier prédit par l'IA après classification.
folder	{ name, locale }	Faire correspondre le dossier par nom et locale exacts.
documentClass	{ name, locale }	Faire correspondre la classe de classification par nom et locale.

---

2. Appel à l'API de recherche de documents

Envoyez votre requête dans une seule charge utile JSON :

curl -X POST "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/documents/search" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "tags": ["important","finance"],
    "folderIdentifiers": ["folder-123"],
    "assetIdentifiers": ["asset-456"],
    "linkedAsset": "Unit A",
    "pageNumber": 1,
    "pageSize": 100,
    "sortOrder": "DESC",
    "columnToSort": "creationDate",
  }'

La pagination commence à 1 : utilisez pageNumber: 1 pour la première page.

---

3. Format de la réponse

200 OK avec du JSON :

{
  "result": [],
  "total": 42,
  "pageable": {
    "pageNumber": 1,
    "pageSize": 100,
    "sort": {}
  }
}

pageable.pageNumber commence également à 1 dans les réponses.

---

4. Gestion des erreurs

• 400 Bad Request : Filtres manquants ou invalides
• 401 Unauthorized : Jeton d'accès invalide ou manquant
• 403 Forbidden : Portée stonal.document.read manquante
• 404 Not Found : organizationCode non reconnu

---

5. Bonnes pratiques

• Utilisez les UID dès que possible (identifier, assetIdentifiers) pour des requêtes précises et performantes.
• Combinez plusieurs filtres pour restreindre les résultats (ex. statut + métadonnées + dossier).
• Tirez parti de linkedAsset pour des recherches conviviales lorsque vous n'avez pas les UID exacts.
• Les filtres d'étiquettes et de propriétés sont idéaux pour un regroupement contextuel entre documents.

Pour la référence complète de l'API, consultez la spécification de l'API Stonal.