Для: Администраторы
Загружайте и прикрепляйте файлы с помощью ключа хаба.
Получите адрес для загрузки, загрузите файл, прикрепите его к сообщению, заметке, заданию, форме или электронной подписи, а также скачайте файлы дела.
В этой статье10 разделов
Прежде чем начать
На этой странице рассказывается о загрузке файлов в соответствующий раздел системы, их прикреплении к документу, а также о возможности скачивания файлов с помощью специального ключа. Пути к файлам указаны под https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Как это работает
Файл выполняет три операции: сначала запрашивается адрес для загрузки файла, затем файл загружается на этот адрес, после чего файл прикрепляется к соответствующему элементу информации.
| Элемент | Загрузить адрес | Прикреплять | Удалять |
|---|---|---|---|
| Пост/Отчет | GET /posts/<post_id>/drive | PUT /posts/<post_id>/media | DELETE /posts/<post_id>/media |
| Примечание | GET /notes/<note_id>/drive | PUT /notes/<note_id>/media | DELETE /notes/<note_id>/media |
| Задача | GET /tasks/<task_id>/drive | PUT /tasks/<task_id>/media | DELETE /tasks/<task_id>/media |
| Детская задача | GET /subtasks/<subtask_id>/drive | PUT /subtasks/<subtask_id>/media | DELETE /subtasks/<subtask_id>/media |
| Документ в формате электронной подписи или простая записка. | GET /<forms, signs or notes>/<id>/drive с media_group=schemas | PUT /<forms, signs or notes>/<id>/schema/media | — |
- Ключ может прикреплять файлы только к постам, созданным Виртуальным помощником. Он может прикреплять файлы к любым заметкам, задачам или подзадачам.
- Чтобы прикрепить файл к комментарию, необходимо запросить адрес соответствующего поста или задачи, используя те самые символы
/drive. Затем можно использовать символыPUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/mediaдля прикрепления файла к данному комментарию. Ключ может быть прикреплен только к своим собственным комментариям. - Форма или электронный документ содержит только один документ, а не другие файлы. Как только форма получает свой документ, она принимает ещё один документ лишь в том случае, если первый не был правильно конвертирован.
1. Получите адрес для загрузки.
| Параметр | Что это делает | Необходимый | По умолчанию |
|---|---|---|---|
media_group | Тип файла: docs, images, audios, videos или files; для документов форм, электронных подписок или записок – schemas. | Да. | — |
media_extension | Расширение файла – например, pdf. Это должен быть один из допустимых расширений; расширение files может использоваться для любого файла. | Да. | — |
tag_id | Название файла записывается в виде сочетания букв, чисел и тире. Например: repair-estimate | Да. | — |
| Добрый | Расширения |
|---|---|
docs и schemas | CSV, DOC, DOCX, ODT, PDF, PPT, PPTX, RTF, TXT, XLS, XLSX |
images | bmp, gif, jpeg, jpg, png, svg, tiff, webp |
audios | aac, aiff, amr, flac, m4a, mp3, oga, opus, wav, wma – это некоторые из распространенных форматов аудио. |
videos | 3GP, AVI, FLV, M4V, MKV, MOV, MP4, MPEG, MPG, OGG, WebM, WMV – а также другие менее распространенные форматы видео. |
files | Любое |
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"
Это ответ. url, Адрес, к которому необходимо загрузить данные. fields, Поля формы, которые необходимо указать вместе с файлом. fields.key Здесь и будет сохраняться файл. Это адрес, который будет действителен в течение часа.
2. Загрузите файл.
Отправьте сообщение. multipart/form-data Отправить сообщение на POST. url, С каждым записанным элементом. fields Согласно данным, файл находится в конце списка. file. fields Заставляет эту полость пустой. Content-Type: Заполните это поле соответствующим типом файла. Например: application/pdf, Вместо того чтобы отправить второй запрос, этот запрос передается в файловый хранилище, а не через API. Следовательно, для его обработки не требуется использовать какой-либо ключ.
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"
Посылайте записи с fields и --form-string, а не с -F. Некоторые из этих записей начинаются с <. Значение -F рассматривается как имя файла.
Это соответствует значению 201. Максимальный размер файла для роли Виртуального помощника составляет 5,000 МБ по умолчанию. Администратор может изменить этот размер в разделе Настройки › Роли. Файл, имеющий размер более указанного значения, не будет сохранен в хранилище файлов. Файлы, загружаемые без какого-либо приложения, удаляются через три дня.
3. Прикрепите его.
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принимает несколько файлов одновременно. Каждый из этих файлов должен быть загружен с адреса, относящегося к этому же элементу.- Приложение позволяет добавлять файлы; однако оно никогда не заменяет самих файлов.
- На посте можно прикрепить свои вебхокы.
add_post_mediaДля каждого файла существует отдельная электронная почта, которая содержит информацию о количестве файлов, связанных с этим файлом.
После прикрепления
Файлы обрабатываются после их загрузки: изображения изменяют свои размеры, а аудио- и видеоматериалы готовятся к воспроизведению. Документы преобразуются в формат PDF с сохранением изображений на страницах документов. Файлы типа files сохраняются в исходном виде.
Каждый элемент списка, например GET /posts/<post_id>, содержит информацию о своих файлах, указанных под media.<kind>.items.<media_id>.
| Поле | Что в нём содержится |
|---|---|
execution_status | RUNNING Пока процесс обработки продолжается… SUCCEEDED или FAILED |
original | Файл был загружен. |
pdf | Документ, преобразованный в формат PDF, готов. |
flat | Электронная копия документа, находящаяся в защищенном состоянии, после того, как все подписали ее. |
tag_id, content_type, media_size | Его название, тип и размер в байтах |
Пока какой-либо файл еще обрабатывается, информация о нем отображается в элементе encoding. Форма или электронный документ не могут быть опубликованы до тех пор, пока их документ не будет готов.
Загрузка файла
Скачайте файл из сайта https://privcdn.caseactive.com/, а затем указывайте его номер original, pdf или flat. Ваш ключ для доступа к файлу должен быть указан в той же заголовочной информации, что и при каждом запросе на получение данного файла.
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
Проверки ключей проводятся так же, как и при любом вызове. Указывается диапазон IP-адресов, на которые может обращаться виртуальный помощник. Также возможно загрузить информацию из любого места, где может находиться виртуальный помощник.
Удаление файла
DELETE /<item>/media принимает JSON-объект, содержащий данные о файле media_id и media_group. В ответе используется значение 200. При отправке сообщений вебхоук получают значение delete_post_media. Документы, связанные с формами, электронными документами или записями, не могут быть удалены; в таких случаях необходимо удалить сам объект.
Пример: PDF-файл в новой публикации
POST /postsС этим сообщением…message. Он сразу же отправляется в путь, с сообщением о процессе отправки. Электронная почта приходит примерно через 30 секунд после отправки, и в этот момент уже можно считать приложенные файлы. Поэтому необходимо прикрепить файлы в течение этого времени.GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.- Загрузите файл в
urlс использованием значенийfields. - С
PUT /posts/<post_id>/mediaиfields.key. - Читать
GET /posts/<post_id>до тех пор, пока файл не будет обработанexecution_statusестьSUCCEEDEDилиFAILED.
Если звонок отклонен
| Статус | message | Почему |
|---|---|---|
| 400 | SchemaFieldsException | Параметр отсутствует или является некорректным. Например, может быть некорректное значение для определенного параметра, или может быть использован элемент типа tag_id с пробелами внутри его значения. Элемент с именем errors также может отсутствовать. На месте media.<n>.media_key загрузка не состоялась; возможно, загрузка была сделана для другого элемента. На месте /schema/media данный элемент не был загружен в виде schemas. Это также может происходить, когда элемент, который вы пытаетесь загрузить, вообще не существует. В запросе ничего не было загружено. |
| 403 | ItemUpdateFailedException | Файл уже приложен, или форма, электронная подпись или записка уже содержат необходимый документ. |
| 403 | ItemAuthorOnlyException | Ключник пытался прикрепить файл к посту или комментарию, написанному кем-то другим. |
| 403 | CaseClosedException | Дело закрыто. |
| 404 | ItemNotFoundException | Этот элемент не существует, когда вы пытаетесь получить адрес для загрузки этого элемента. Также файл, который нужно удалить, также отсутствует. |
Сам процесс загрузки данных представлен в формате, используемом самой системой хранения файлов: EntityTooLarge для файлов, объем которых превышает допустимый лимит; AccessDenied – для файлов, адрес которых уже истек. Что касается тела ошибки, возникающей при использовании API, а также других кодов, см. раздел Управление ошибками и статусными кодами API.