Возможности

Функционал файлов позволяет пользователям amoCRM загружать файлы, а также получать доступ к полученным файлам из разных источников.
Например, файлы из мессенджеров, из форм, файлы загружаемые в бота или примечания – все эти файлы доступны в едином месте – в разделе Файлы.

Загруженные файлы можно использовать в качестве значений для полей, шаблонов ответов на сообщения, в полях типа файл и примечаниях.

Мы предоставляем API файлов для всех интеграций. Для получений доступа к API файлов – необходимо в вашей интеграции указать scope – доступ к файлам и, если необходимо, удаление файлов.

Важно отметить, что при использовании Файлов, расходуется дисковое пространство аккаунта, которое можно докупить в разделе Настройки -> Счет и оплата.

Пользователь может гибко управлять своим файловым пространством с помощью:

  • Триггер удаления файлов
  • Правила автоматического удаления файла
  • Ограничить автоматическое скачивание больших файлов из мессенджеров

Подробнее о функционале управления файлами – читайте на лендинге и в пользовательской документации.

На данный момент загруженные файлы можно использовать в следующих местах:

  • прикреплять к сущности
  • примечание с файлом
  • значение поля типа файл
  • шаблоны сообщений мессенджеров
  • Salesbot при отправке сообщений и установки значения дополнительного поля типа файл

У каждого файла есть набор основных свойств:

  • uuid – уникальный идентификатор файла
  • version_uuid – уникальный идентификатор версии
  • name – название файла
  • size – размер файла
  • created_at/updated_at/deleted_at – временные метки
  • created_by/updated_by/deleted_by – информация об авторе действия
  • is_trashed – флаг, говорящий о том, удален файл или нет
  • extension – расширение файла
  • type – тип файла – изображение, видео, документ и файл
  • mime_type – mime тип файла

Важной особенностью файлов является поддержка версий файла для файлов, которые используются в дополнительных полях. Подробнее об этом читайте ниже в возможностях API файлов.

Ниже рассмотрим основные возможности, а также дополнительные, которые могут сделать вашу интеграцию более полезной для пользователя.

Основные возможности API файлов

В данной статье рассмотрим описанные выше возможности с точки зрения пользователя, с технической точки зрения – в следующих статьях.

Загрузка файла в amoCRM

Жизненный цикл файла начинается при его загрузке в систему.
Каждый файл загружается частями, максимальный размер загружаемой в одном запросе части файла, возвращается при открытии сессии.

Если ваш файл превышает максимальный размер части, полученный при открытии сессии, то его необходимо разбить на части, не превышающие максимальный размер, самостоятельно.

Для начала загрузки файла – интеграция должна открыть сессию для загрузки файла, сообщив какого размера и типа будет загружаемый файл.
Это необходимо для того, чтобы в случае сетевых проблем, можно было продолжить загрузку не всего файла, а той части, которая еще не загружена.
Сессия на загрузку файла живет до окончания загрузки файла, но не более 24 часов после создания.

При открытии сессии – интеграция получает информацию, о максимальном размере загружаемых частей файла и ссылку на загрузку первой части файла.

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

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

При управлении файлом через API, его можно использовать и переиспользовать в разных местах, например в примечании и в поле файл.

Получение списка файлов

API файлов предоставляет метод получения списка файлов, как удаленных, так и активных.
Кроме получения списка файлов, вы сможете фильтровать по части параметров, например, по расширению или размеру.

Данный метод будет полезен для интеграций, которые хотят следить за состоянием файлового хранилища.
Также для интеграций, которые хотят переиспользовать файлы по максимуму.

Удаление файлов

При получении дополнительного scope "Удаление файлов", интеграция может пользоваться методом пакетного удаления файлов.
Кроме методов удаления, доступен и метод восстановления файлов, если удаление произошло случайно.

Данные методы вынесены в отдельный scope, чтобы пользователю было понятно, что интеграция, потенциально, может удалить файлы,
и ответственность за удаление файлов – лежит на интеграции.

Данные методы могут быть полезны интеграциям для более гибких и уникальных решений по контролю за файлами.

После удаления файла – он попадает в корзину и окончательно удаляется через 30 дней. При этом место освобождается уже после перемещения в корзину.

Удаленные файлы нельзя использовать в примечаниях, полях и других частях системы.

Использование файла в примечании

Загруженный файл можно использовать в качестве вложения к примечанию. Для этого необходимо добавить примечание типа attachment
через API методы примечаний.

Для того, что добавить примечание с файлом – достаточно передать uuid файла и название файла для отображения в примечании.

Важно отметить, что если вы хотите, чтобы у файла отображался комментарий – необходимо добавить 2 примечания с одинаковой датой создания (created_at).

Использование файла в дополнительном поле

Загруженный файл можно использовать в качестве значения дополнительного поля типа файл. Файлы в полях поддерживают версионность.

Например, интеграция генерирует договор для конкретной сделки, загружает его в файлы, а затем указывает в качестве значения поля.
Также для файлов в полях есть поддержка версий файлов, например, были внесены корректировки в договор, интеграция генерирует новый договор,
но не загружает новый файл, а создает версию для уже загруженного. В таком кейсе, клиент сможет видеть все версии файла, скачать каждую из них.

Использование файла в шаблонах ответов для мессенджеров

Загруженный файл можно использовать в качестве файла для шаблона ответа в мессенджеры.

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

Прикрепление файла к сущности amoCRM

Каждый загруженный файл можно прикрепить к одной или нескольким основным сущностям: сделки, контакты, компании, покупатели.

Файл будет отображаться во вкладке файлы в карточке сущности.

Во вкладке файлы отображаются файлы, которые были получены от клиента или загружены в примечание, а также добавленные в карточку через API. Файлы, загруженные в поля не отображаются во вкладке файлы.

Кроме прикрепления, API позволяет отвязать файл и получить список всех прикрепленных файлов.