Téléverser un fichier

Ce guide couvre les stratégies prises en charge pour téléverser des documents vers la plateforme Stonal. Il détaille les principales combinaisons que vous pouvez utiliser pour indiquer au système où et comment placer votre document lors du téléversement.

Prérequis

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

1. Stratégies de téléversement et champs requis

Chaque stratégie correspond à une combinaison de champs du manifeste. Utilisez le tableau ci-dessous pour identifier la charge utile adaptée à votre scénario.

Stratégie	Champs requis du manifeste	Description
1. UID d'objet + Modèle de documentation ⭐	`asset.uid`, `documentation.template`	Recommandé : laissez la plateforme déterminer la documentation correcte pour l'objet.
2. Code externe d'objet + Modèle de documentation ⭐	`asset.externalIds.{source}`, `documentation.template`	Recommandé lorsque votre intégration n'utilise pas les UID d'objets Stonal.
3. Objet + Modèle de documentation + Modèle de dossier ⭐	Stratégie 1 ou 2 + `folder.template`	Recommandé lorsque vous souhaitez cibler un type de dossier spécifique au sein de la documentation.
4. UID de documentation	`documentation.uid`	Utilisez cette stratégie lorsque vous connaissez déjà la documentation existante dans laquelle vous souhaitez téléverser.

linkedAssets, tags.documentation et documentClass sont des enrichissements facultatifs qui peuvent venir s'ajouter à ces stratégies.

2. Exemples de charges utiles de manifeste

N'incluez que les champs nécessaires à la stratégie que vous avez choisie.

2.1 Par UID d'objet + Modèle de documentation ⭐

{
  "asset": {
    "uid": "822d8c50-0deb-4dae-8def-c9f9eab7f5be"
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  }
}

2.2 Par code externe d'objet + Modèle de documentation ⭐

{
  "asset": {
    "externalIds": {
      "code": "BUILDING_001"
    }
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  }
}

2.3 Par Objet + Modèle de documentation + Modèle de dossier ⭐

{
  "asset": {
    "externalIds": {
      "code": "BUILDING_001"
    }
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  },
  "folder": {
    "template": "e8df7c2a-b5bb-41fa-8d1f-bea649e6d93d"
  }
}

2.4 Par UID de documentation

Utilisez cette stratégie lorsque l'UID de documentation est déjà connu, par exemple parce que vous l'avez précédemment récupéré depuis le point de terminaison des documentations de l'objet.

{
  "documentation": {
    "uid": "62c42614-31a8-43bb-a76f-8499c1b868e0"
  }
}

2.5 Ajouter des objets liés

linkedAssets peut être combiné avec les stratégies recommandées fondées sur les modèles.

{
  "asset": {
    "externalIds": {
      "code": "BUILDING_001"
    }
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  },
  "linkedAssets": [
    { "code": "RU-001" },
    { "uid": "fac98b98-c8ba-47e7-b5a6-2bc5222ae402" }
  ]
}

Remarques importantes :

Les linkedAssets indiqués par code sont résolus relativement à l'asset parent.
Si vous envoyez des linkedAssets sans asset, les objets liés peuvent être ignorés.
Utilisez le format de liste indiqué ci-dessus pour les nouvelles intégrations.

2.6 Ajouter des étiquettes de documentation et une classe de document

Les étiquettes de documentation ne sont associées que si elles existent déjà sur la documentation cible. L'API de téléversement ne crée pas d'étiquettes à la volée.

{
  "asset": {
    "uid": "822d8c50-0deb-4dae-8def-c9f9eab7f5be"
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  },
  "documentClass": "123e4567-e89b-12d3-a456-426614174007",
  "tags": {
    "documentation": ["LEASE 2026", "SIGNED"]
  }
}

3. Découverte des modèles (workflow recommandé)

Avant d'utiliser les stratégies fondées sur les modèles, découvrez les modèles disponibles :

3.1 Lister les modèles disponibles

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

Réponse :

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

3.2 Obtenir les détails d'un modèle avec ses dossiers

curl -H "Authorization: Bearer {accessToken}" \
  "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/templates/{templateId}?language=fr-FR"

Réponse :

{
  "template": {
    "id": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d",
    "name": {
      "fr-FR": "DOE"
    },
    "organizationCode": "STONAL",
    "attachmentType": "BUILDING_GROUP",
    "folders": [
      {
        "id": "e8df7c2a-b5bb-41fa-8d1f-bea649e6d93d",
        "name": {
          "fr-FR": "Documents généraux"
        },
        "parentId": null,
        "documentClass": {
          "identifier": "documentClassIdentifier",
          "code": "DPE"
        }
      }
    ]
  }
}

Vous pouvez ensuite utiliser :

template.id comme documentation.template
template.folders[].id comme folder.template

3.3 Récupérer les documentations existantes d'un objet

Si vous souhaitez téléverser dans une documentation existante, récupérez d'abord les documentations rattachées à l'objet :

curl -H "Authorization: Bearer {accessToken}" \
  "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/assets/{assetId}/documentations"

Utilisez l'identifier renvoyé comme documentation.uid.

Pour le workflow complet de récupération, voir Récupérer les documentations d'un objet.

4. Appel à l'API en une seule requête

Envoyez à la fois votre manifeste et votre fichier dans un seul POST multipart/form-data :

curl -X POST \
  "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/files/upload" \
  -H "Authorization: Bearer {accessToken}" \
  -F 'manifest=@manifest.json;type=application/json' \
  -F 'file=@/path/to/your/file.pdf;type=application/pdf'

Remplacez les espaces réservés par vos valeurs réelles.

5. Format de la réponse

200 OK avec du JSON :

{
  "documentId": "123e4567-e89b-12d3-a456-426614174000",
  "duplicateDocumentIds": []
}

L'API peut également renvoyer des avertissements non bloquants dans l'en-tête de réponse X-DOCUMENT-STORAGE-WARNING.

Exemples :

LINKED_ASSETS_NOT_FOUND
LINKED_ASSETS_NOT_FOUND:RU-001,PARK-002
LINKED_ASSETS_SKIPPED_NO_PARENT

Quand le traitement par l'IA est-il déclenché ?

Dans les flux de téléversement publics, une requête d'IA est envoyée lorsque le fichier téléversé est rattaché à un contexte de documentation.

Le traitement demandé dépend alors du contexte de téléversement :

si le fichier est téléversé uniquement dans une documentation, une classification par l'IA est demandée
si une classe de document est fournie, une extraction de métadonnées est demandée
l'OCR est toujours demandé dans le cadre de la requête d'IA

En pratique, les téléversements fondés sur les modèles restent le principal moyen public de placer le document dans la bonne documentation avant le démarrage du traitement par l'IA.

6. Gestion des erreurs

Statut	Cas
400 Bad Request	Champs du manifeste manquants ou invalides, requête multipart invalide, ou fichier refusé (voir 6.1)
404 Not Found	Objet, documentation, dossier de modèle référencé, ou documentation correspondant à l'objet et au modèle de documentation fournis introuvable
409 Conflict	L'objet et la documentation spécifiés ne sont pas liés
413 Payload Too Large	Le fichier dépasse la taille autorisée pour son type
415 Unsupported Media Type	Le type de fichier n'est pas pris en charge
422 Unprocessable Entity	Aucun modèle de documentation ne correspond à l'objet

Gérez ces réponses de manière appropriée dans votre intégration.

6.1 Fichiers refusés

Quand c'est le fichier lui-même qui est refusé, le corps de la réponse suit l'enveloppe d'erreur Stonal (RFC 9457) :

{
  "type": "tag:UnsupportedFileType",
  "title": "Unsupported file type",
  "status": 415,
  "detail": "Unsupported file type: malware.exe"
}

`type`	Statut	Signification
`tag:EmptyFile`	400	Le fichier est vide
`tag:InvalidFileName`	400	Le nom du fichier est absent ou contient un chemin
`tag:InvalidContentType`	400	Le `Content-Type` déclaré ne correspond pas à l'extension du fichier
`tag:InvalidFileSignature`	400	Le contenu du fichier ne correspond pas à son extension, par exemple une photo JPEG renommée en `.pdf`
`tag:FileTooLarge`	413	Le fichier dépasse une limite de taille de téléversement. Quand c'est la limite propre au type de fichier qui est dépassée, le corps contient aussi `fileName`, `documentType`, `fileSizeBytes` et `maxFileSizeBytes` ; ces champs sont absents quand le serveur refuse le corps multipart avant la validation.
`tag:UnsupportedFileType`	415	L'extension du fichier n'est pas prise en charge

Basez votre traitement sur type, jamais sur le libellé de detail, qui peut changer. Les erreurs de manifeste restent renvoyées en texte brut.

Le corps contient aussi les champs error et message, conservés pour les intégrations existantes. Ils sont dépréciés et seront supprimés : utilisez type et detail à la place.

7. Bonnes pratiques

Privilégiez les modèles : il s'agit du principal chemin d'intégration public et du plus pérenne.
Découvrez d'abord les modèles : utilisez l'API /templates pour explorer les options disponibles.
Préférez les UID d'objets lorsque c'est possible : ils restent les identifiants les plus clairs.
N'utilisez l'UID de documentation que lorsqu'il est déjà connu : récupérez-le d'abord depuis le point de terminaison des documentations de l'objet.
N'utilisez les objets liés qu'avec un objet parent : les objets liés fondés sur un code sont résolus relativement à ce parent.
N'oubliez pas que les étiquettes de documentation ne sont pas créées automatiquement : seules les étiquettes de documentation existantes sont associées.

Pour plus de détails, consultez notre spécification de l'API.

8. Exemple complet

8.1 Approche recommandée

Pour cet exemple de manifeste :

manifest.json
{
  "asset": {
    "externalIds": {
      "code": "BUILDING_001"
    }
  },
  "documentation": {
    "template": "f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"
  },
  "folder": {
    "template": "e8df7c2a-b5bb-41fa-8d1f-bea649e6d93d"
  },
  "linkedAssets": [
    { "code": "RU-001" }
  ],
  "tags": {
    "documentation": ["DPE 2026"]
  },
  "documentClass": "123e4567-e89b-12d3-a456-426614174007"
}

Nous utiliserons la commande suivante pour téléverser le fichier :

curl \
  -X POST "https://api.stonal.io/document-storage/v1/organizations/{organizationCode}/files/upload" \
  -H "Authorization: Bearer {accessToken}" \
  -F 'manifest=@manifest.json;type=application/json' \
  -F 'file=@sample.pdf;type=application/pdf'

8.2 Documentation existante déjà connue

Pour cet exemple de manifeste :

manifest.json
{
  "documentation": {
    "uid": "62c42614-31a8-43bb-a76f-8499c1b868e0"
  }
}

Nous utiliserons la même commande de téléversement avec ce manifeste.

Prérequis​

1. Stratégies de téléversement et champs requis​

2. Exemples de charges utiles de manifeste​

2.1 Par UID d'objet + Modèle de documentation ⭐​

2.2 Par code externe d'objet + Modèle de documentation ⭐​

2.3 Par Objet + Modèle de documentation + Modèle de dossier ⭐​

2.4 Par UID de documentation​

2.5 Ajouter des objets liés​

2.6 Ajouter des étiquettes de documentation et une classe de document​

3. Découverte des modèles (workflow recommandé)​

3.1 Lister les modèles disponibles​

3.2 Obtenir les détails d'un modèle avec ses dossiers​

3.3 Récupérer les documentations existantes d'un objet​

4. Appel à l'API en une seule requête​

5. Format de la réponse​

Quand le traitement par l'IA est-il déclenché ?​

6. Gestion des erreurs​

6.1 Fichiers refusés​

7. Bonnes pratiques​

8. Exemple complet​

8.1 Approche recommandée​

8.2 Documentation existante déjà connue​