Центр поддержкиИнтеграции

Для: Администраторы

Загружайте и прикрепляйте файлы с помощью ключа хаба.

Получите адрес для загрузки, загрузите файл, прикрепите его к сообщению, заметке, заданию, форме или электронной подписи, а также скачайте файлы дела.

В этой статье10 разделов

Прежде чем начать

На этой странице рассказывается о загрузке файлов в соответствующий раздел системы, их прикреплении к документу, а также о возможности скачивания файлов с помощью специального ключа. Пути к файлам указаны под https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Как это работает

Файл выполняет три операции: сначала запрашивается адрес для загрузки файла, затем файл загружается на этот адрес, после чего файл прикрепляется к соответствующему элементу информации.

ЭлементЗагрузить адресПрикреплятьУдалять
Пост/ОтчетGET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
ПримечаниеGET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
ЗадачаGET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
Детская задачаGET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
Документ в формате электронной подписи или простая записка.GET /<forms, signs or notes>/<id>/drive с media_group=schemasPUT /<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 и 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 – это некоторые из распространенных форматов аудио.
videos3GP, 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_statusRUNNING Пока процесс обработки продолжается… 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-файл в новой публикации

  1. POST /posts С этим сообщением… message. Он сразу же отправляется в путь, с сообщением о процессе отправки. Электронная почта приходит примерно через 30 секунд после отправки, и в этот момент уже можно считать приложенные файлы. Поэтому необходимо прикрепить файлы в течение этого времени.
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate.
  3. Загрузите файл в url с использованием значений fields.
  4. С PUT /posts/<post_id>/media и fields.key.
  5. Читать GET /posts/<post_id> до тех пор, пока файл не будет обработан execution_status есть SUCCEEDED или FAILED.

Если звонок отклонен

СтатусmessageПочему
400SchemaFieldsExceptionПараметр отсутствует или является некорректным. Например, может быть некорректное значение для определенного параметра, или может быть использован элемент типа tag_id с пробелами внутри его значения. Элемент с именем errors также может отсутствовать. На месте media.<n>.media_key загрузка не состоялась; возможно, загрузка была сделана для другого элемента. На месте /schema/media данный элемент не был загружен в виде schemas. Это также может происходить, когда элемент, который вы пытаетесь загрузить, вообще не существует. В запросе ничего не было загружено.
403ItemUpdateFailedExceptionФайл уже приложен, или форма, электронная подпись или записка уже содержат необходимый документ.
403ItemAuthorOnlyExceptionКлючник пытался прикрепить файл к посту или комментарию, написанному кем-то другим.
403CaseClosedExceptionДело закрыто.
404ItemNotFoundExceptionЭтот элемент не существует, когда вы пытаетесь получить адрес для загрузки этого элемента. Также файл, который нужно удалить, также отсутствует.

Сам процесс загрузки данных представлен в формате, используемом самой системой хранения файлов: EntityTooLarge для файлов, объем которых превышает допустимый лимит; AccessDenied – для файлов, адрес которых уже истек. Что касается тела ошибки, возникающей при использовании API, а также других кодов, см. раздел Управление ошибками и статусными кодами API.

Статьи по теме

Разберитесь, что может делать API.Узнайте, к чему могут иметь доступ ключ управления и ключ концентратора, почему каждый ключ действует как виртуальный помощник и где находится полный технический паспорт.ИнтеграцииДобавляйте публикации и комментарии с помощью ключа хаба.Добавляйте сообщения в ленту обращения, отвечайте комментариями, читайте, редактируйте или удаляйте их с помощью собственного программного обеспечения, выступая в роли виртуального помощника.ИнтеграцииОтправляйте электронные подписи и считывайте подписи с помощью центрального ключа.Создайте электронную подпись для дела на основе шаблона, выберите, кто подпишет каждое поле, опубликуйте документ для подписания и загрузите заблокированную копию после того, как все подпишут.ИнтеграцииОбработка ошибок и кодов состояния API.Прочитайте текст ошибки, что означают коды 400, 401, 403, 404, 500 и 503, и почему элемент, который ваш ключ не видит, выдает ошибку 404.Интеграции