Методы API

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

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

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

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

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

Требования к работе с API файлов
Создание сессии загрузки файла
Загрузка части файла
Получение файлов
Получение файла по UUID
Редактирование файла
Удаление файлов
Восстановление файлов
Получение версий файла
Получение файлов связанных с сущностью
Привязка файлов к сущности
Отвязка файлов от сущности
Получение сущностей связанных с файлом

Требования к работе с 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
    }
  ]
}

Продукт

Продукт

Коммуникации

Интеграция с MAX

AI-агенты и боты

Материалы

Материалы

Наши ресурсы

Для разработчиков

Методы API

Оглавление

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

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

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

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

Метод

Описание

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

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

HTTP коды ответа

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

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

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

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

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

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

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

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

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

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Метод

Описание

Ограничения