Centre d'aideIntégrations

Pour: Administrateurs

Téléversez et joignez des fichiers à l'aide d'une clé de hub.

Obtenez une adresse de téléchargement, téléchargez un fichier, joignez-le à une publication, une note, une tâche, un formulaire ou une signature électronique, et téléchargez les fichiers d'un dossier.

Dans cet article10 sections

Avant de commencer

Cette page explique comment télécharger des fichiers dans un dossier spécifique, les ajouter à ce dossier, et les récupérer à nouveau, en utilisant une clé de hub. Les chemins de répertoires se trouvent sous https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Comment ça marche

Un fichier nécessite trois étapes : demander une adresse pour le téléchargement du fichier, télécharger le fichier à cette adresse, puis l’attacher au produit concerné.

ArticleAdresse de téléchargementAttacherRetirer
Un postGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
Une noteGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
Une tâche à accomplirGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Une tâche pour enfantGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
Un document sous forme électronique, signé ou noté.GET /<forms, signs or notes>/<id>/drive Avec media_group=schemasPUT /<forms, signs or notes>/<id>/schema/media—
  • Une clé ne peut associer des fichiers qu’aux messages créés par l’assistant virtuel. Elle peut en revanche associer des fichiers à toutes sortes de notes, tâches ou sous-tâches.
  • Pour joindre un fichier à un commentaire, demandez l’adresse correspondante, indiquée dans le champ /drive de ce commentaire ou de cette tâche. Ensuite, utilisez le champ PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media pour y insérer le fichier. Un clé ne peut être associé qu’à ses propres commentaires.
  • Une forme ou un signe électronique contient un seul document, et aucun autre fichier. Une fois que le document est enregistré, il ne prend pas en compte d’autres fichiers, à moins que le premier fichier ne réussisse pas à être converti.

1. Obtenez une adresse de téléchargement

ParamètreCe que cela faitRequisDéfaut
media_groupLe type de fichier : docs, images, audios, videos ou files. Pour les documents liés à des formulaires, des signes électroniques ou des notes, le type de fichier peut également être schemas.Oui.—
media_extensionL’extension du fichier, par exemple pdf. Il doit s’agir d’une extension valable ; files peut être utilisée pour n’importe quel type d’extension.Oui.—
tag_idLe nom sous lequel le fichier est enregistré est composé de lettres, de chiffres et de tirets, par exemple repair-estimate.Oui.—
GentilExtensions
docs et schemasCSV, DOC, DOCX, ODT, PDF, PPT, PPTX, RTF, TXT, XLS, XLSX
imagesBMP, GIF, JPEG, JPG, PNG, SVG, TIFF, WebP
audiosaac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma… Et des formats audio moins courants.
videos3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV… ainsi que d’autres formats de vidéo moins courants.
filesTout
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cela répond à la question. url, L’adresse à utiliser pour l’enregistrement. fields, Les champs de formulaires à envoyer avec le fichier. fields.key C’est là que le fichier sera sauvegardé. L’adresse indiquée est valable pendant une heure.

2. Téléchargez le fichier

Envoyer un message. multipart/form-data Envoyer par e-mail. url, Pour chaque entrée… fields Comme indiqué, alors le fichier est le dernier en ordre de précession. file. fields Il contient un espace vide. Content-Type: Remplissez ce champ avec le type de fichier, par exemple : application/pdf, Au lieu d’envoyer une deuxième demande, cette requête est envoyée vers le stockage des fichiers, et non vers l’API. Par conséquent, elle ne nécessite pas de clé pour être traitée.

curl -X POST "<url>" \
  --form-string "key=<fields.key>" \
  --form-string "Content-Type=application/pdf" \
  --form-string "<every other entry of fields, as given>" \
  -F "file=@repair-estimate.pdf"

Envoyez les entrées de fields avec --form-string, et non avec -F. Certaines entrées commencent par <. -F est considéré comme un fichier.

Cela répond à la question 201. Le fichier le plus volumineux est le limiteur pour ce type de fichiers, soit 5 000 Mo par défaut. Un administrateur peut le diminuer via les paramètres Configurations › Rôles. Tout fichier dépassant cette taille sera rejeté par le serveur de stockage de fichiers. Un fichier téléchargé qui n’est jamais attaché au système sera supprimé après trois jours.

3. Attachez-le

curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media": [{"media_key": "<fields.key>"}]}'
{
  "data": {
    "items": [{"media_key": "hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf", "media_id": "20261002154512_5f4e3d2c1b0a99"}],
    "currentItemCount": 1
  }
}
  • media prend plusieurs fichiers en même temps. Chacun de ces fichiers doit avoir été téléchargé depuis le même endroit.
  • L’opération d’attachement consiste à ajouter des fichiers ; elle ne les remplace jamais.
  • Il s’agit d’une publication, avec l’envoi de vos webhooks. add_post_media Pour chaque fichier, l’e-mail concernant la publication compte également le nombre de fichiers associés à ce fichier.

Après avoir attaché

Les fichiers sont traités après leur téléchargement : les images sont réduites en taille, les fichiers audio et vidéo sont préparés pour être joués, et les documents sont convertis en format PDF, avec des images de chaque page. Les fichiers du type files restent inchangés.

L’élément lu par rapport à chaque élément, comme GET /posts/<post_id>, liste ses fichiers sous media.<kind>.items.<media_id>.

ChampCe qu'il contient
execution_statusRUNNING Pendant que le processus est en cours de traitement… SUCCEEDED Ou FAILED
originalLe fichier a été téléchargé.
pdfUn document converti en format PDF, une fois prêt.
flatUne copie numérique verrouillée, une fois que tout le monde a signé.
tag_id, content_type, media_sizeSon nom, son type et sa taille en octets.

Pendant que tout fichier est encore en cours de traitement, l’élément correspondant est indiqué dans la liste encoding. Un formulaire ou un signe électronique ne peut être publié qu’après que le document soit prêt.

Téléchargement d'un fichier

Téléchargez un fichier depuis https://privcdn.caseactive.com/, en indiquant ses original, pdf ou flat. Utilisez également votre clé dans le même en-tête que pour chaque appel.

curl "https://privcdn.caseactive.com/hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" -o repair-estimate.pdf

Les vérifications liées à la clé s’appliquent également à chaque appel. Le champ d’IP concerné est également pris en compte. La fonctionnalité permet de télécharger des informations provenant de n’importe quelle zone géographique, afin que l’assistant virtuel puisse interagir avec ces données.

Suppression d'un fichier

DELETE /<item>/media accepte un corps JSON contenant les informations sur le fichier media_id et media_group. Il renvoie en retour la valeur 200. Sur une publication, vos webhooks reçoivent les données delete_post_media. Les documents générés par un formulaire, une signature électronique ou une note ne peuvent pas être supprimés ; il est donc nécessaire de supprimer l’élément concerné.

Exemple : un PDF dans un nouvel article

  1. POST /posts Avec le poste en question… message. Le message est publié immédiatement, avec une notification par portail. L’e-mail arrive environ 30 secondes plus tard. À ce moment-là, le système compte les fichiers joints. Il est donc conseillé de joindre ces fichiers dans ce délai.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Téléchargez le fichier dans url, avec les informations indiquées en fields.
  4. Avec PUT /posts/<post_id>/media et fields.key.
  5. Lisez le contenu de GET /posts/<post_id> jusqu’à ce que le nombre dans execution_status soit égal à SUCCEEDED ou FAILED.

Si un appel est refusé

StatutmessagePourquoi
400SchemaFieldsExceptionUn paramètre manque ou est inválide. Par exemple, une extension que le type ne peut pas prendre. tag_id Avec des espaces entre les mots. errors Il l’appelle ainsi. media.<n>.media_key, L’upload n’a pas été trouvé. Il s’agissait probablement d’un autre fichier. /schema/media, Il n’a pas été téléchargé. schemas; C’est également la réponse lorsque l’élément que vous souhaitez associer à quelque chose ne existe pas. Aucun élément n’est attaché dans la demande.
403ItemUpdateFailedExceptionLe fichier est déjà attaché, ou le formulaire, la signature électronique ou l’note contient déjà le document correspondant.
403ItemAuthorOnlyExceptionLa personne qui a tenté de soumettre ce fichier à un post ou à un commentaire écrit par quelqu’un d’autre, a essayé de le faire en utilisant une clé de chiffrement.
403CaseClosedExceptionL’affaire est close.
404ItemNotFoundExceptionL’élément en question n’existe pas lorsque vous demandez son adresse d’enregistrement. De plus, le fichier que vous souhaitez supprimer ne existe pas non plus.

L’upload lui-même se fait dans le format propre au stockage des fichiers : EntityTooLarge pour les fichiers qui dépassent la limite autorisée, et AccessDenied lorsque l’adresse a expiré. Pour en savoir plus sur le corps d’erreur de l’API et les autres codes, veuillez consulter Manipulation des erreurs et codes de statut de l’API.

Articles connexes

Comprendre les possibilités de l'APIDécouvrez ce que permettent chacune une clé de gestion et une clé de hub, pourquoi chaque clé agit comme un assistant virtuel et où trouver la liste technique complète.IntégrationsAjouter des publications et des commentaires avec une clé de hubAjoutez des publications au flux d'un dossier, répondez par des commentaires et lisez, modifiez ou supprimez-les depuis votre propre logiciel, en tant qu'assistant virtuel.IntégrationsEnvoyez des signatures électroniques et lisez les signatures avec une clé de hubCréez un formulaire de signature électronique pour un dossier à partir d'un modèle, choisissez qui signe chaque champ, publiez-le pour signature et téléchargez la copie verrouillée une fois que tout le monde a signé.IntégrationsGérer les erreurs et les codes d'état de l'APILisez le corps de l'erreur, ce que signifient les codes 400, 401, 403, 404, 500 et 503, et pourquoi un élément que votre clé ne peut pas voir renvoie la réponse 404.Intégrations