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	(Paramètre de requête, voir Paramètres de requête) Filtre les documents mis à jour pendant ou après cette date. Accepte une date ISO-8601 (YYYY-MM-DD) ou une date-heure ISO-8601 complète avec fuseau horaire ou décalage (ex. 2026-07-01T00:00:00Z). Une valeur invalide ou mal formée renvoie 400 Bad Request.
createdAfter	String	(Paramètre de requête, voir Paramètres de requête) Filtre les documents créés pendant ou après cette date. Mêmes formats acceptés que updatedAfter. Une valeur invalide ou mal formée renvoie 400 Bad Request.

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.
hasPendingSuggestion	Boolean	Filtrer les documents ayant une suggestion de classification par l'IA en attente de validation humaine (true) ou aucune (false), c'est-à-dire un dossier et une classe de document prédits par l'IA mais pas encore validés manuellement.

---

2. Appel à l'API de recherche de documents

Les filtres se placent dans le corps JSON de la requête. La pagination, le tri et les filtres de date (updatedAfter/createdAfter) se passent en paramètres de requête dans l'URL, pas dans le corps.

Paramètres de requête

Paramètre	Type	Description
pageNumber	Integer	Numéro de page pour la pagination par décalage (commence à 1 ; 0 est accepté pour la rétrocompatibilité). Par défaut 1.
pageSize	Integer	Taille de page pour la pagination par décalage. Par défaut 20.
sortOrder	String	Ordre de tri pour la pagination par décalage : ASC ou DESC.
columnToSort	String	Colonne de tri pour la pagination par décalage (ex. creationDate). Mettez updateDate avec afterId pour activer la pagination par curseur sur la date de mise à jour, voir Pagination par curseur ci-dessous.
updatedAfter	String	Filtre les documents mis à jour pendant ou après cette date. Accepte une date ISO-8601 (YYYY-MM-DD) ou une date-heure ISO-8601 complète avec fuseau horaire ou décalage (ex. 2026-07-01T00:00:00Z). Une valeur invalide ou mal formée renvoie 400 Bad Request.
createdAfter	String	Filtre les documents créés pendant ou après cette date. Mêmes formats acceptés que updatedAfter.
afterId	String	Curseur pour la pagination par clé, voir Pagination par curseur ci-dessous.
afterValue	String	Valeur de curseur utilisée avec afterId et columnToSort=updateDate, voir Pagination par curseur ci-dessous.

Exemple de requête

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

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

2.1 Pagination par curseur (recommandée pour le polling)

Pour parcourir de façon fiable les documents triés par date de modification, par exemple pour interroger périodiquement les documents modifiés depuis la dernière exécution, utilisez la pagination par curseur plutôt que pageNumber/columnToSort/sortOrder. Contrairement au suivi de max(updatedAfter) + 1 seconde côté client, elle ne peut pas sauter silencieusement des documents mis à jour dans la même seconde.

• afterId : position du curseur, ordonnée par id croissant. Passez afterId=0 pour démarrer un nouveau parcours ; passez le nextCursor de la réponse précédente pour récupérer la page suivante.
• afterValue : valeur de curseur utilisée avec afterId et columnToSort=updateDate pour parcourir les documents par date de mise à jour plutôt que par id. Omettez-la pour démarrer un nouveau parcours depuis le début.
• columnToSort=updateDate : bascule le parcours par curseur sur l'ordre de date de mise à jour. Toute autre valeur (ou son absence) revient à la pagination par curseur ordonnée par id.

Lorsque afterId est présent, pageNumber, sortOrder et columnToSort (hors updateDate) sont ignorés.

Démarrer à une date précise plutôt qu'au début : passez votre propre afterValue avec afterId=0 (elle ne correspond au tout début que lorsqu'elle est omise). afterValue doit être une date-heure ISO-8601 simple sans fuseau horaire ni décalage, par exemple 2026-01-01T00:00:00 et non 2026-01-01T00:00:00Z (contrairement à updatedAfter/createdAfter, qui acceptent un Z ou un décalage). Une afterValue mal formée n'est pas rejetée par une erreur : elle est ignorée silencieusement et le parcours repart du tout début, vérifiez donc bien le format avant de vous y fier.

Premier appel : démarrer un parcours ordonné par date de mise à jour depuis le début :

curl -X POST "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/documents/search?afterId=0&columnToSort=updateDate" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{}'

La réponse contient nextCursor et nextCursorValue (voir Format de la réponse). Les appels suivants renvoient ces valeurs en afterId/afterValue :

curl -X POST "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/documents/search?afterId=12345&afterValue=2026-07-17T14%3A32%3A10.123456&columnToSort=updateDate" \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{}'

Continuez à interroger avec les derniers nextCursor/nextCursorValue jusqu'à ce que la réponse ne renvoie plus de nextCursor (il n'y a plus de page).

---

3. Format de la réponse

200 OK avec du JSON :

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

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

nextCursor et nextCursorValue ne sont renseignés que lors d'une pagination avec afterId (voir Pagination par curseur) :

• nextCursor : curseur opaque à passer en afterId à l'appel suivant. null lorsqu'il n'y a plus de page, ou si afterId n'a pas été utilisé pour cette requête.
• nextCursorValue : valeur de curseur à passer en afterValue à l'appel suivant, avec columnToSort=updateDate. null lorsqu'il n'y a plus de page, ou si ce mode n'a pas été utilisé.

---

4. Gestion des erreurs

• 400 Bad Request : Filtres manquants ou invalides. Pour une valeur invalide de updatedAfter/createdAfter, le corps de la réponse est un message d'erreur en texte brut (pas du JSON), par exemple Invalid updatedAfter: 2026-07-00. Expected an ISO-8601 date (e.g. 2026-07-01) or date-time (e.g. 2026-07-01T00:00:00Z).
• 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.
• Préférez la pagination par curseur (afterId/afterValue/columnToSort=updateDate) au polling sur updatedAfter pour suivre de façon fiable les modifications de documents dans le temps, voir Pagination par curseur.

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