Методы API

В данном разделе описываются доступные методы для работы с API файлов в amoCRM.

Через методы API файлов интеграция может загружать файлы, удалять их, создавать версии файлов, связывать файлы с сущностями.

Интеграция идентифицируется посредством проверки переданного Access Token в заголовке Authorization: Bearer ACCESS_TOKEN.

Большинство методов API файлов доступны только через отдельный домен сервиса файлов.

Важно учесть, что при добавлении файла по общему адресу, некоторые функции, например поиск этого файла, могут быть доступны с задержкой.
Для получения адреса сервиса, который обслуживает текущий аккаунт, можно запросить свойства аккаунта с флагом with=drive_url.

Оглавление

Требования к работе с API файлов

Для работы с API файлов у интеграции должен быть установлен scope – Доступ к файлам. Для удаления файлов у интеграции дополнительно должен быть установлен scope – Удаление файлов.

Создание сессии загрузки файла

Метод

POST /v1.0/sessions

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля – file_name и file_size

Параметр Тип данных Описание
file_name string Имя загружаемого файла
file_size int Размер загружаемого файла
file_uuid string UUID файла, для которого загружается новая версия файла. Если UUID не задан, то будет создан новый файл.
content_type string MIME-тип файла
with_preview bool При установке данного флага для файла будет сгенерировано превью

Пример запроса

{
  "file_name": "aaa",
  "file_size": 3435,
  "content_type": "image/jpeg",
  "file_uuid": "367b9f38-5f01-4cea-947e-dfab47aea522"
}

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Сессия загрузки успешно создана
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные

Параметры ответа

Метод возвращает модель сессии, рассмотрим ниже её свойства.

Параметр Тип данных Описание
session_id int ID сессии
upload_url string URL по которому должна быть закачена первая часть файла
max_file_size int Максимальный размер файла
max_part_size int Максимальные размер загружаемой части файла

Пример ответа

{
  "max_file_size": 314572800,
  "max_part_size": 524288,
  "session_id": 26136001,
  "upload_url": "https://drive-b.amocrm.ru/v1.0/sessions/upload/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjc0MTg3MzYwMCwiaWF0Ijo3NDE4NzM2MDAsIm5iZiI6NzQxODczNjAwLCJhY2NvdW50X2lkIjo3Nzc3Nzc3Nywic2Vzc2lvbl9pZCI6Nzc3Nzc3NzcsInVzZXJfaWQiOjc3Nzc3NzcsInVzZXJfdHlwZSI6ImludGVybmFsIiwicGFydF9udW0iOjF9.8sdJVTZJ_MjuHhMGDkU7_eSi2q1u1EG-au_TZhmmXK8"
}

Загрузка части файла

Метод

POST /v1.0/sessions/upload/{session_token}

Описание

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

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
404 Сессия загрузки не найдена

Параметры ответа

Метод возвращает ссылку для загрузки следующей части файла.

Параметр Тип данных Описание
session_id int ID сессии
next_url string URL для загрузки следующей части файла

Пример ответа

{
  "next_url": "https://drive-b.amocrm.ru/v1.0/sessions/upload/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjc0MTg3MzYwMCwiaWF0Ijo3NDE4NzM2MDAsIm5iZiI6NzQxODczNjAwLCJhY2NvdW50X2lkIjo3Nzc3Nzc3Nywic2Vzc2lvbl9pZCI6Nzc3Nzc3NzcsInVzZXJfaWQiOjc3Nzc3NzcsInVzZXJfdHlwZSI6ImludGVybmFsIiwicGFydF9udW0iOjF9.8sdJVTZJ_MjuHhMGDkU7_eSi2q1u1EG-au_TZhmmXK8",
  "session_id": 26434413
}

Параметры ответа при загрузке последней части файла

Метод возвращает модель загруженного файла.

Параметр Тип данных Описание
uuid string UUID файла
type string Тип файла. Возможные параметры – image, video, audio, document, file
is_trashed bool Удален ли файл
name string Имя файла
sanitized_name string Имя файла в ASCII кодировке
size int Размер файла в байтах
source_id int|null Идентификатор источника из которого пришел файл
version_uuid string Идентификатор версии файла
has_multiple_versions bool Имеет ли файл множество версий
created_at int Время создания файла Unix Timestamp
created_by object Пользователь создавший файл
created_by[id] int ID пользователя создавшего файла
created_by[type] string Тип пользователя создавшего файла
updated_at int Время последнего обновления файла Unix Timestamp
updated_by object Пользователь обновивший файл
deleted_at int|null Время удаления файла Unix Timestamp
deleted_by object|null Пользователь удаливший файл
metadata object|null Метаданные файла
metadata[extension] string Расширение файла
metadata[mime_type] string MIME-тип файла
previews array|null Массив превью для файла
previews[0] object Превью файла
previews[0][download_link] string URL для загрузки превью
previews[0][width] int Ширина превью
previews[0][height] int Высота превью

Пример ответа при загрузке последней части файла

{
  "_links": {
    "download": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/picture.png"
    },
    "download_version": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/43de3be7-307b-4766-a23e-5e88211b9a8d/picture.png"
    },
    "self": {
      "href": "https://drive-b.amocrm.ru/v1.0/files/367b9f38-5f01-4cea-947e-dfab47aea522"
    }
  },
  "created_at": 1671687247,
  "created_by": { "type": "internal", "id": 7758337 },
  "deleted_at": null,
  "deleted_by": null,
  "has_multiple_versions": false,
  "is_trashed": false,
  "metadata": { "extension": "png", "mime_type": "image/png" },
  "name": "product",
  "previews": null,
  "sanitized_name": "product",
  "session_id": 26136001,
  "size": 7526,
  "source_id": null,
  "type": "file",
  "updated_at": 1671687247,
  "updated_by": { "type": "internal", "id": 7758337 },
  "uuid": "367b9f38-5f01-4cea-947e-dfab47aea522",
  "version_uuid": "43de3be7-307b-4766-a23e-5e88211b9a8d"
}

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

Метод

GET /v1.0/files

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

GET параметры

Параметр Тип данных Описание
filter[uuid] string Массив UUID’ов файлов, перечисленных через запятую
filter[name] string Имя файла
filter[extensions][] string Расширение файла
filter[term] string Подстрока содержащаяся в имение файла или имени какой-то из связанных сущностей
filter[source_id] int Идентификатор источника из которого был получен файл
filter[deleted] null Если параметр передан, то будут выведены удалённые файлы
filter[size][unit] int Количество байт в единице размера файла (по умолчанию 1 байт)
filter[size][from] int Минимальный размер файла
filter[size][to] int Максимальный размер файла
filter[date][type] string Тип события по которому производится фильтрация. Возможные значения – created_at, updated_at
filter[date][date_preset] string Пресет для задания временного диапазона. Возможные значения – day, tomorrow, yesterday, week, previous_week, next_week, month, next_month, previous_month, quarter, previous_quarter, next_quarter, last_3_days, next_3_days, last_6_month, year
filter[date][from] int Время после которого произошло событие Unix Timestamp
filter[date][to] int Время до которого произошло событие Unix Timestamp
filter[created_by][] int Создатель файла. Возможные значения: -1 – клиент, 0 – робот, {id} – внутренний пользователь
filter[updated_by][] int Пользователь последний обновивший файл. Возможные значения: -1 – клиент, 0 – робот, {id} – внутренний пользователь

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 Файлов не найдено
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные

Параметры ответа

Метод возвращает массив моделей файлов.

Пример ответа

{
  "_count": 25,
  "_embedded": {
    "files": [
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/26ec7266-d953-433b-8bc5-737eb70da87a/8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX.jpg"
          },
          "download_version": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/26ec7266-d953-433b-8bc5-737eb70da87a/0244c437-1637-4cdf-887a-e574f55eb114/8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX.jpg"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/26ec7266-d953-433b-8bc5-737eb70da87a"
          }
        },
        "created_at": 1671871033,
        "created_by": { "type": "internal", "id": 7758337 },
        "deleted_at": null,
        "deleted_by": null,
        "has_multiple_versions": false,
        "is_trashed": false,
        "metadata": { "extension": "jpg", "mime_type": "image/jpeg" },
        "name": "8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX",
        "previews": null,
        "sanitized_name": "8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX",
        "size": 38635,
        "source_id": null,
        "type": "image",
        "updated_at": 1671871033,
        "updated_by": { "type": "internal", "id": 7758337 },
        "uuid": "26ec7266-d953-433b-8bc5-737eb70da87a",
        "version_uuid": "0244c437-1637-4cdf-887a-e574f55eb114"
      },
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/9403badc-5690-4c7d-a999-be09f8c57566/-96.png"
          },
          "download_version": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/9403badc-5690-4c7d-a999-be09f8c57566/2a93e2a2-7c09-4f0d-b8ee-f0228e890307/-96.png"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/9403badc-5690-4c7d-a999-be09f8c57566"
          }
        },
        "created_at": 1671814907,
        "created_by": { "type": "internal", "id": 2647957 },
        "deleted_at": null,
        "deleted_by": null,
        "has_multiple_versions": false,
        "is_trashed": false,
        "metadata": { "extension": "png", "mime_type": "image/png" },
        "name": "_96",
        "previews": null,
        "sanitized_name": "-96",
        "size": 5230,
        "source_id": null,
        "type": "image",
        "updated_at": 1671814907,
        "updated_by": { "type": "internal", "id": 2647957 },
        "uuid": "9403badc-5690-4c7d-a999-be09f8c57566",
        "version_uuid": "2a93e2a2-7c09-4f0d-b8ee-f0228e890307"
      },
      ...
    ]
  },
  "_links": {
    "next": {
      "href": "https://drive-b.amocrm.ru/v1.0/files?filter%5Bextensions%5D%5B%5D=bmp&filter%5Bextensions%5D%5B%5D=jpeg&filter%5Bextensions%5D%5B%5D=jpg&filter%5Bextensions%5D%5B%5D=png&filter%5Bis_filter%5D=true&filter%5Bsize%5D%5Bunit%5D=1000000&limit=25&page=2"
    },
    "self": {
      "href": "https://drive-b.amocrm.ru/v1.0/files?filter%5Bextensions%5D%5B%5D=bmp&filter%5Bextensions%5D%5B%5D=jpeg&filter%5Bextensions%5D%5B%5D=jpg&filter%5Bextensions%5D%5B%5D=png&filter%5Bis_filter%5D=true&filter%5Bsize%5D%5Bunit%5D=1000000&limit=25&page=1"
    }
  }
}

Получение файла по UUID

Метод

GET /v1.0/files/{file_uuid}

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос выолнен успешно
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
404 Файл не найден

Параметры ответа

Метод возвращает модель файла.

Пример ответа

{
  "_links": {
    "download": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/picture.png"
    },
    "download_version": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/43de3be7-307b-4766-a23e-5e88211b9a8d/picture.png"
    },
    "self": {
      "href": "https://drive-b.amocrm.ru/v1.0/files/367b9f38-5f01-4cea-947e-dfab47aea522"
    }
  },
  "created_at": 1671687247,
  "created_by": { "type": "internal", "id": 7758337 },
  "deleted_at": null,
  "deleted_by": null,
  "has_multiple_versions": false,
  "is_trashed": false,
  "metadata": { "extension": "png", "mime_type": "image/png" },
  "name": "product",
  "previews": null,
  "sanitized_name": "product",
  "session_id": 26136001,
  "size": 7526,
  "source_id": null,
  "type": "file",
  "updated_at": 1671687247,
  "updated_by": { "type": "internal", "id": 7758337 },
  "uuid": "367b9f38-5f01-4cea-947e-dfab47aea522",
  "version_uuid": "43de3be7-307b-4766-a23e-5e88211b9a8d"
}

Редактирование файла

Метод

PATCH /v1.0/files/{file_uuid}

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательных полей нет. Поля name и version_uuid не могут быть заданны одновременно.

Параметр Тип данных Описание
name string Новое имя файла
version_uuid string UUID версии файла, которая должна быть установлена как активная версия файла

Пример запроса

{
  "name": "Новое имя файла"
}

{
  "version_uuid": "367b9f38-5f01-4cea-947e-dfab47aea522"
}

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Файл был успешно изменен
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа
404 Файл не найден

Параметры ответа

Метод возвращает модель файла.

Пример ответа

{
  "_links": {
    "download": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/picture.png"
    },
    "download_version": {
      "href": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/43de3be7-307b-4766-a23e-5e88211b9a8d/picture.png"
    },
    "self": {
      "href": "https://drive-b.amocrm.ru/v1.0/files/367b9f38-5f01-4cea-947e-dfab47aea522"
    }
  },
  "created_at": 1671687247,
  "created_by": { "type": "internal", "id": 7758337 },
  "deleted_at": null,
  "deleted_by": null,
  "has_multiple_versions": false,
  "is_trashed": false,
  "metadata": { "extension": "png", "mime_type": "image/png" },
  "name": "product",
  "previews": null,
  "sanitized_name": "product",
  "session_id": 26136001,
  "size": 7526,
  "source_id": null,
  "type": "file",
  "updated_at": 1671687247,
  "updated_by": { "type": "internal", "id": 7758337 },
  "uuid": "367b9f38-5f01-4cea-947e-dfab47aea522",
  "version_uuid": "43de3be7-307b-4766-a23e-5e88211b9a8d"
}

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

Метод

DELETE /v1.0/files

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Удаление файлов.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Тело запроса должно содержать массив объектов с полем uuid.

Параметр Тип данных Описание
uuid string UUID файла

Пример запроса

[
  {
    "uuid": "367b9f38-5f01-4cea-947e-dfab47aea522"
  },
  {
    "uuid": "bf1097fb-58fe-42c1-b385-ac443228ddd0"
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
204 Файлы успешно удалены
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод не возвращает тело ответа при успешном запросе.

Восстановление файлов

Метод

POST /v1.0/files/restore

Описание

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

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Тело запроса должно содержать массив объектов с полем uuid.

Параметр Тип данных Описание
uuid string UUID файла

Пример запроса

[
  {
    "uuid": "367b9f38-5f01-4cea-947e-dfab47aea522"
  },
  {
    "uuid": "bf1097fb-58fe-42c1-b385-ac443228ddd0"
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Файлы были успешно восстановлен
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает коллекцию восстановленых файлов.

Пример ответа

{
  "_count": 2,
  "_embedded": {
    "files": [
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/26ec7266-d953-433b-8bc5-737eb70da87a/8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX.jpg"
          },
          "download_version": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/26ec7266-d953-433b-8bc5-737eb70da87a/0244c437-1637-4cdf-887a-e574f55eb114/8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX.jpg"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/26ec7266-d953-433b-8bc5-737eb70da87a"
          }
        },
        "created_at": 1671871033,
        "created_by": { "type": "internal", "id": 7758337 },
        "deleted_at": null,
        "deleted_by": null,
        "has_multiple_versions": false,
        "is_trashed": false,
        "metadata": { "extension": "jpg", "mime_type": "image/jpeg" },
        "name": "8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX",
        "previews": null,
        "sanitized_name": "8Z5PQ3D7wbS6Doz-svQ0zYdWXeTq8HqfSQzjM-aDY2cI5uM3wcRZ0dD8nLV8TUcX",
        "size": 38635,
        "source_id": null,
        "type": "image",
        "updated_at": 1671871033,
        "updated_by": { "type": "internal", "id": 7758337 },
        "uuid": "26ec7266-d953-433b-8bc5-737eb70da87a",
        "version_uuid": "0244c437-1637-4cdf-887a-e574f55eb114"
      },
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/9403badc-5690-4c7d-a999-be09f8c57566/-96.png"
          },
          "download_version": {
            "href": "https://drive-b.amocrm.ru/download/367b9f38-5f01-4cea-947e-dfab47aea522/9403badc-5690-4c7d-a999-be09f8c57566/2a93e2a2-7c09-4f0d-b8ee-f0228e890307/-96.png"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/9403badc-5690-4c7d-a999-be09f8c57566"
          }
        },
        "created_at": 1671814907,
        "created_by": { "type": "internal", "id": 2647957 },
        "deleted_at": null,
        "deleted_by": null,
        "has_multiple_versions": false,
        "is_trashed": false,
        "metadata": { "extension": "png", "mime_type": "image/png" },
        "name": "_96",
        "previews": null,
        "sanitized_name": "-96",
        "size": 5230,
        "source_id": null,
        "type": "image",
        "updated_at": 1671814907,
        "updated_by": { "type": "internal", "id": 2647957 },
        "uuid": "9403badc-5690-4c7d-a999-be09f8c57566",
        "version_uuid": "2a93e2a2-7c09-4f0d-b8ee-f0228e890307"
      }
    ]
  }
}

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

Метод

GET /v1.0/files/{file_uuid}/versions

Описание

Метод позволяющий получать версии файлов. Запрос должен отправляться на хост сервиса файлов.

Ограничения

Метод доступен интеграциям у которых установлен scope – Доступ к файлам.

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
404 Файл не найден
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные

Параметры ответа

Метод возвращает коллекцию версий файла.

Параметр Тип данных Описание
uuid string UUID версии файла
file_uuid string UUID файла
type string Тип версии файла. Возможные параметры – image, video, audio, document, file
name string Имя версии файла
sanitized_name string Имя версии файла в ASCII кодировке
size int Размер версии файла в байтах
is_main bool Является ли данная версия активной версией файла
source_id int|null Идентификатор источника из которого пришла версия файла
created_at int Время создания версии файла Unix Timestamp
created_by object Пользователь создавший версию файла
created_by[id] int ID пользователя создавшего версию файла
created_by[type] string Тип пользователя создавшего версию файла
updated_at int Время последнего обновления версии файла Unix Timestamp
updated_by object Пользователь обновивший версию файла
metadata object|null Метаданные файла
metadata[extension] string Расширение файла
metadata[mime_type] string MIME-тип файла
previews array|null Массив превью для файла
previews[0] object Превью файла
previews[0][download_link] string URL для загрузки превью
previews[0][width] int Ширина превью
previews[0][height] int Высота превью

Пример ответа

{
  "_count": 2,
  "_embedded": {
    "versions": [
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/21c0e773-0b10-57ac-96d1-c0b97ba6a3f7/89a61e7b-ba30-476f-b2f6-705a964e85c6/fd8401e1-c1db-4033-851c-1df68d40f579/source.jpeg"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/89a61e7b-ba30-476f-b2f6-705a964e85c6/versions/fd8401e1-c1db-4033-851c-1df68d40f579"
          }
        },
        "created_at": 1671995440,
        "created_by": { "type": "internal", "id": 7758337 },
        "file_uuid": "89a61e7b-ba30-476f-b2f6-705a964e85c6",
        "is_main": true,
        "metadata": { "extension": "jpeg", "mime_type": "image/jpeg" },
        "name": "source",
        "previews": null,
        "sanitized_name": "source",
        "size": 93425,
        "source_id": null,
        "type": "image",
        "updated_at": 1671995440,
        "updated_by": { "type": "internal", "id": 7758337 },
        "uuid": "fd8401e1-c1db-4033-851c-1df68d40f579"
      },
      {
        "_links": {
          "download": {
            "href": "https://drive-b.amocrm.ru/download/21c0e773-0b10-57ac-96d1-c0b97ba6a3f7/89a61e7b-ba30-476f-b2f6-705a964e85c6/17006a5b-aa43-4b2f-a380-e851786b9a57/consoleText.txt"
          },
          "self": {
            "href": "https://drive-b.amocrm.ru/v1.0/files/89a61e7b-ba30-476f-b2f6-705a964e85c6/versions/17006a5b-aa43-4b2f-a380-e851786b9a57"
          }
        },
        "created_at": 1663233556,
        "created_by": { "type": "internal", "id": 7758337 },
        "file_uuid": "89a61e7b-ba30-476f-b2f6-705a964e85c6",
        "is_main": false,
        "metadata": { "extension": "txt", "mime_type": "" },
        "name": "consoleText",
        "previews": null,
        "sanitized_name": "consoleText",
        "size": 7347,
        "source_id": null,
        "type": "file",
        "updated_at": 1670599185,
        "updated_by": { "type": "internal", "id": 7758337 },
        "uuid": "17006a5b-aa43-4b2f-a380-e851786b9a57"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://drive-b.amocrm.ru/v1.0/files/89a61e7b-ba30-476f-b2f6-705a964e85c6/versions"
    }
  }
}

Получение файлов связанных с сущностью

Метод

GET /api/v4/leads/{entity_id}/files

GET /api/v4/contacts/{entity_id}/files

GET /api/v4/companies/{entity_id}/files

GET /api/v4/customers/{entity_id}/files

Описание

Метод позволяет получить файлы связанные с сущностью.

Ограничения

Метод доступен в соответствии с правами пользователя.

GET параметры

Обязательных полей нет

Параметр Тип данных Описание
limit int Количество возвращаемых связей за один запрос
before_id int Вернутся связи с ID меньше заданного

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
204 У сущности нет связанных файлов
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа
404 Сущность не найдена

Параметры ответа

Метод возвращает массив объектов, содержащих идентификатор файлов.

Параметр Тип данных Описание
file_uuid string UUID файла
id int ID связи сущность-файл

Пример ответа

{
  "_links": {
    "self": {
      "href": "https://wombat.amocrm.ru/ajax/v4/leads/18437733/files?limit=50"
    }
  },
  "_embedded": {
    "files": [
      { "file_uuid": "50ca4b6b-0b88-4ece-9f89-d48961579ae0", "id": 2140857 },
      { "file_uuid": "5ef222cd-bce4-4df8-8466-3dee7d16e70d", "id": 2128681 }
    ]
  }
}

Привязка файлов к сущности

Метод

PUT /api/v4/leads/{entity_id}/files

PUT /api/v4/contacts/{entity_id}/files

PUT /api/v4/companies/{entity_id}/files

PUT /api/v4/customers/{entity_id}/files

Описание

Метод позволяет привязывать файл к сущности.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Тело запроса содержит массив объектов с указанием UUID’ов привязываемых файлов.

Параметр Тип данных Описание
file_uuid string UUID привязываемого файла

Пример запроса

[
  {
    "file_uuid": "50ca4b6b-0b88-4ece-9f89-d48961579ae0"
  },
  {
    "file_uuid": "367b9f38-5f01-4cea-947e-dfab47aea522"
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
202 Файлы успешно привязаны
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа
404 Сущность не найдена

Параметры ответа

Метод не возвращает тело ответа при успешном запросе.

Отвязка файлов от сущности

Метод

DELETE /api/v4/leads/{entity_id}/files

DELETE /api/v4/contacts/{entity_id}/files

DELETE /api/v4/companies/{entity_id}/files

DELETE /api/v4/customers/{entity_id}/files

Описание

Метод позволяет отвязать файл от сущности.

Ограничения

Метод доступен в соответствии с правами пользователя.

Параметры запроса

Тело запроса содержит массив объектов с указанием UUID’ов отвязываемых файлов.

Параметр Тип данных Описание
file_uuid string UUID отвязываемого файла

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
202 Запрос выполнен успешно
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа
404 Сущность не найдена

Параметры ответа

Метод не возвращает тело ответа при успешном запросе.

Получение сущностей связанных с файлом

Метод

GET /api/v4/files/{file_uuid}/links

Описание

Метод позволяет получить сущности связанные с файлом.

Ограничения

Метод доступен в соответствии с правами пользователя.

Заголовок типа данных при успешном результате

Content-Type: application/hal+json

Заголовок типа данных при ошибке

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
403 Не хватает прав для вызова данного метода
401 Неудачная аутентификация
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Метод возвращает объект, содержащий UUID файла и массив связанных с ним сущностей.

Параметр Тип данных Описание
file_uuid string UUID файла
entities array Массив связанных с файлом сущностей
entities[0] object Связанная с файлом сущность

Пример ответа

{
  "file_uuid": "5ef222cd-bce4-4df8-8466-3dee7d16e70d",
  "entities": [
    {
      "id": 22859207,
      "name": "Сделка #22859207",
      "created_by": 0,
      "main_user_id": 7758337,
      "date_create": 1669372247,
      "price": 20,
      "pipeline_id": 3858604,
      "date_update": 1672060100,
      "updated_by": 7758337,
      "entity_type": "leads",
      "status_id": 37066879,
      "closest_task_at": null
    },
    {
      "id": 19229439,
      "name": "Сделка #19229439",
      "created_by": 0,
      "main_user_id": 7758337,
      "date_create": 1651773549,
      "price": 20,
      "pipeline_id": 3858604,
      "date_update": 1662404148,
      "updated_by": null,
      "entity_type": "leads",
      "status_id": 37066876,
      "closest_task_at": null
    }
  ]
}