Списки

В данном разделе описываются доступные методы для работы с сущностью списков

Оглавление

Общая информация

  • В аккаунте может быть создано не более 10 списков
  • Существует 3 вида списков – обычный (regular), счета (invoices), товары (products)
  • В одном аккаунте может быть не более 1 списка счетов и 1 списка товаров
  • Элементы списка могут быть добавлены к сущностям: сделки, покупатели, транзакции

Доступные списки

Метод

GET /api/v4/catalogs

Описание

Метод позволяет получить доступные списки в аккаунте.

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован

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

Метод возвращает коллекцию моделей списков, рассмотрим ниже свойства списка.

Параметр Тип данных Описание
id int ID списка
name string Название списка
created_by int ID пользователя, создавший список
updated_by int ID пользователя, изменивший список последним
created_at int Дата создания списка, передается в Unix Timestamp
updated_at int Дата изменения списка, передается в Unix Timestamp
sort int Сортировка списка
type string Тип списка
can_add_elements bool Можно ли добавлять элементы списка из интерфейса (Применяется только для списка счетов)
can_show_in_cards bool Должна ли добавляться вкладка со списком в карточку сделки/покупателя (Применяется только для списка счетов)
can_link_multiple bool Если ли возможность привязывать один элемент данного списка к нескольким сделкам/покупателям
can_be_deleted bool Может ли список быть удален через интерфейс
sdk_widget_code int Код виджета, который управляет списком и может отобразить своё собственное окно редактирования элемента (Применяется только для списка счетов)
account_id int ID аккаунта, в котором находится список

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs?page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/catalogs?page=2&limit=50"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 4589,
                "name": "Просто список",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1590742040,
                "updated_at": 1590742040,
                "sort": 10,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/4589"
                    }
                }
            },
            {
                "id": 4521,
                "name": "Товары",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589390310,
                "updated_at": 1590742040,
                "sort": 20,
                "type": "products",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": false,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/4521"
                    }
                }
            },
            {
                "id": 4517,
                "name": "Счета",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589379462,
                "updated_at": 1590742040,
                "sort": 30,
                "type": "invoices",
                "can_add_elements": false,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "sdk_widget_code": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/4517"
                    }
                }
            }
        ]
    }
}

Получение списка по ID

Метод

GET /api/v4/catalogs/{id}

Описание

Метод позволяет получить данные конкретного списка по ID.

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован

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

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

Параметр Тип данных Описание
id int ID списка
name string Название списка
created_by int ID пользователя, создавший список
updated_by int ID пользователя, изменивший список последним
created_at int Дата создания списка, передается в Unix Timestamp
updated_at int Дата изменения списка, передается в Unix Timestamp
sort int Сортировка списка
type string Тип списка
can_add_elements bool Можно ли добавлять элементы списка из интерфейса (Применяется только для списка счетов)
can_show_in_cards bool Должна ли добавляться вкладка со списком в карточку сделки/покупателя (Применяется только для списка счетов)
can_link_multiple bool Если ли возможность привязывать один элемент данного списка к нескольким сделкам/покупателям
can_be_deleted bool Может ли список быть удален через интерфейс
sdk_widget_code int Код виджета, который управляет списком и может отобразить своё собственное окно редактирования элемента (Применяется только для списка счетов)
account_id int ID аккаунта, в котором находится список

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

{
    "id": 4589,
    "name": "Просто список",
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1590742040,
    "updated_at": 1590742040,
    "sort": 10,
    "type": "regular",
    "can_add_elements": true,
    "can_show_in_cards": false,
    "can_link_multiple": true,
    "can_be_deleted": true,
    "sdk_widget_code": null,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/4589"
        }
    }
}

Добавление списков

Метод

POST /api/v4/catalogs

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Параметр Тип данных Описание
name string Название списка. Обязательный параметр
type string Тип списка. Параметр не является обязательным, по умолчанию – regular
sort int Сортировка списка. Параметр не является обязательным
can_add_elements bool Можно ли добавлять элементы списка из интерфейса. Параметр не является обязательным
can_link_multiple bool Можно ли привязывать один элемент данного списка к нескольким сделкам/покупателям. Параметр не является обязательным
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

[
    {
        "name": "Тестовый список",
        "can_add_elements": true,
        "can_link_multiple": false,
        "request_id": "123"
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию списков, которые были созданы. Параметры аналогичны тем, что возвращаются при запросе списка.

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 5785,
                "name": "Тестовый список",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589397957,
                "updated_at": 1589397957,
                "sort": 10,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": false,
                "can_be_deleted": true,
                "account_id": 123123,
                "request_id": "123",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/5785"
                    }
                }
            }
        ]
    }
}

Редактирование списков

Метод

PATCH /api/v4/catalogs

Описание

Метод позволяет редактировать списки пакетно.
Также вы можете добавить ID списка в метод для редактирования конкретного списка (/api/v4/catalogs/{id}).
При редактировании пакетно передается массив из объектов-списков, при редактировании одного списка, передается просто модель списка.

Ограничения

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

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

Content-Type: application/json

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

Параметр Тип данных Описание
name string Название списка. Обязательный параметр
can_add_elements bool Можно ли добавлять элементы списка из интерфейса. Параметр не является обязательным
can_link_multiple bool Можно ли привязывать один элемент данного списка к нескольким сделкам/покупателям. Параметр не является обязательным
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

В данном примере мы обновим 1 список запросом на /api/v4/catalogs/5787.

{
    "name": "Новое имя списка",
    "can_add_elements": true,
    "can_link_multiple": false
}

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Списки были успешно изменены
401 Пользователь не авторизован
400 Переданы некорректные данные. Подробности доступны в теле ответа

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

Метод возвращает коллекцию или модель списка, которые были изменены. Параметры аналогичны тем, что доступны при получении списка.

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

{
    "id": 5787,
    "name": "Новое имя списка",
    "created_by": 3944275,
    "updated_by": 3944275,
    "created_at": 1589399557,
    "updated_at": 1589399886,
    "sort": 30,
    "type": "regular",
    "can_add_elements": true,
    "can_show_in_cards": false,
    "can_link_multiple": false,
    "can_be_deleted": true,
    "account_id": 123123,
    "request_id": "5787",
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/5787"
        }
    }
}

Доступные элементы списка

Метод

GET /api/v4/catalogs/{catalog_id}/elements

Описание

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

Ограничения

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

GET параметры

Параметр Тип данных Описание
page int Страница выборки
limit int Количество возвращаемых сущностей за один запрос (Максимум – 250)
query string
int		 Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
filter object Фильтр
filter[id] int
array		 Фильтр по ID элемента. Можно передать как один ID, так и массив из нескольких ID
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован

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

Метод возвращает коллекцию моделей элементов списка, рассмотрим ниже её свойства.

Параметр Тип данных Описание
id int ID элемента списка
catalog_id int ID списка
name string Название элемента
created_by int ID пользователя, создавший элемент
updated_by int ID пользователя, изменивший элемент последним
created_at int Дата создания элемента, передается в Unix Timestamp
updated_at int Дата изменения элемента, передается в Unix Timestamp
is_deleted bool Удален ли элемент
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного элемента
account_id int ID аккаунта, в котором находится элемент списка
_embedded[warning][message] string
null		 Предупреждение о наличии перерасчета в счете. Вернется null, если перерасчета не произошло. Данный ключ возвращается только при получении элементов списка счетов

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/4521/elements?page=1&limit=50"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/4521/elements?page=2&limit=50"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 525439,
                "name": "Элемент",
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1589390333,
                "updated_at": 1590683336,
                "is_deleted": null,
                "custom_fields_values": [
                    {
                        "field_id": 271207,
                        "field_name": "Артикул",
                        "field_code": "SKU",
                        "field_type": "text",
                        "values": [
                            {
                                "value": "dsg"
                            }
                        ]
                    },
                    {
                        "field_id": 271209,
                        "field_name": "Описание",
                        "field_code": "DESCRIPTION",
                        "field_type": "textarea",
                        "values": [
                            {
                                "value": "Описание"
                            }
                        ]
                    },
                    {
                        "field_id": 271211,
                        "field_name": "Цена",
                        "field_code": "PRICE",
                        "field_type": "numeric",
                        "values": [
                            {
                                "value": "12"
                            }
                        ]
                    },
                    {
                        "field_id": 271213,
                        "field_name": "Группа",
                        "field_code": "GROUP",
                        "field_type": "category",
                        "values": [
                            {
                                "value": "Телефоны",
                                "enum_id": 10663
                            }
                        ]
                    }
                ],
                "catalog_id": 4521,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/4521/elements/525439"
                    }
                }
            }
        ]
    }
}

Параметры для GET-параметра with

Параметр Описание
invoice_link При передаче данного параметра, вернется дополнительное свойство invoice_link, содержащие ссылку на печатную форму счета. Если передать этот параметр с отличным от списка Счетов списком, то вернется null.

Получение элемента списка по ID

Метод

GET /api/v4/catalogs/{catalog_id}/elements/{id}

Описание

Метод позволяет получить элемент списка по его ID.

Ограничения

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

GET параметры

Параметр Тип данных Описание
with string Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры.

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа Условие
200 Запрос выполнен успешно
401 Пользователь не авторизован

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

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

Параметр Тип данных Описание
id int ID элемента списка
catalog_id int ID списка
name string Название элемента
created_by int ID пользователя, создавший элемент
updated_by int ID пользователя, изменивший элемент последним
created_at int Дата создания элемента, передается в Unix Timestamp
updated_at int Дата изменения элемента, передается в Unix Timestamp
is_deleted bool Удален ли элемент
custom_fields_values array
null		 Массив, содержащий информацию по значениям дополнительных полей, заданных для данного элемента
account_id int ID аккаунта, в котором находится элемент списка
_embedded[warning][message] string
null		 Предупреждение о наличии перерасчета в счете. Вернется null, если перерасчета не произошло. Данный ключ возвращается только при получении элемента списка счетов

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

{
    "id": 525439,
    "name": "Элемент",
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1589390333,
    "updated_at": 1590683336,
    "is_deleted": null,
    "custom_fields_values": [
        {
            "field_id": 271207,
            "field_name": "Артикул",
            "field_code": "SKU",
            "field_type": "text",
            "values": [
                {
                    "value": "dsg"
                }
            ]
        },
        {
            "field_id": 271209,
            "field_name": "Описание",
            "field_code": "DESCRIPTION",
            "field_type": "textarea",
            "values": [
                {
                    "value": "Супер телефон"
                }
            ]
        },
        {
            "field_id": 271211,
            "field_name": "Цена",
            "field_code": "PRICE",
            "field_type": "numeric",
            "values": [
                {
                    "value": "12"
                }
            ]
        },
        {
            "field_id": 271213,
            "field_name": "Группа",
            "field_code": "GROUP",
            "field_type": "category",
            "values": [
                {
                    "value": "Телефоны",
                    "enum_id": 10663
                }
            ]
        }
    ],
    "catalog_id": 4521,
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/4521/elements/525439"
        }
    }
}

Параметры для GET-параметра with

Параметр Описание
invoice_link При передаче данного параметра, вернется дополнительное свойство invoice_link, содержащие ссылку на печатную форму счета. Если передать этот параметр с отличным от списка Счетов списком, то вернется null.

Добавление элементов списков

Метод

POST /api/v4/catalogs/{catalog_id}/elements

Описание

Метод позволяет добавлять элементы списков в аккаунт пакетно.

Ограничения

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

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

Content-Type: application/json

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

Параметр Тип данных Описание
name string Название элемента списка. Обязательный параметр
custom_fields_values array Массив, содержащий информацию по значениям дополнительных полей, заданных для данного элемента. Примеры заполнения полей
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

[
    {
        "name": "Покупка #11111",
        "custom_fields_values": [
            {
                "field_id": 1107159,
                "values": [
                    {
                        "value": {
                            "name": "Новый покупатель #1",
                            "address": "Москва, Вымышленная набережная, дом 1"
                        }
                    }
                ]
            },
            {
                "field_id": 1107155,
                "values": [
                    {
                        "enum_id": 1302891
                    }
                ]
            },
            {
                "field_id": 1107157,
                "values": [
                    {
                        "value": {
                            "entity_id": 1163189
                        }
                    }
                ]
            },
            {
                "field_id": 1107165,
                "values": [
                    {
                        "value": {
                            "sku": "34N4124",
                            "description": "Товар #1",
                            "unit_price": 10,
                            "quantity": 5,
                            "unit_type": "шт.",
                            "discount": {
                                "type": "amount",
                                "value": 25
                            },
                            "vat_rate_id": 18
                        }
                    }
                ]
            }
        ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию элементов, которые были созданы. Параметры аналогичны тем, что возвращаются при запросе списка элементов.

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 1163197,
                "name": "Покупка #11111",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294541,
                "updated_at": 1589294541,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 1107159,
                        "field_name": "Плательщик",
                        "field_code": "PAYER",
                        "field_type": "payer",
                        "values": [
                            {
                                "value": {
                                    "name": "Новый покупатель #1",
                                    "address": "Москва, Вымышленная набережная, дом 1"
                                }
                            }
                        ]
                    },
                    {
                        "field_id": 1107155,
                        "field_name": "Статус",
                        "field_code": "BILL_STATUS",
                        "field_type": "select",
                        "values": [
                            {
                                "value": "Создан",
                                "enum_id": 1302891,
                                "enum_code": "created"
                            }
                        ]
                    },
                    {
                        "field_id": 1107157,
                        "field_name": "Поставщик",
                        "field_code": "SUPPLIER",
                        "field_type": "supplier",
                        "values": [
                            {
                                "value": {
                                    "entity_id": 1163189
                                }
                            }
                        ]
                    },
                    {
                        "field_id": 1107165,
                        "field_name": "Позиции счета",
                        "field_code": "ITEMS",
                        "field_type": "items",
                        "values": [
                            {
                                "value": {
                                    "sku": "34N4124",
                                    "product_id": null,
                                    "description": "Товар #1",
                                    "unit_price": 10.0,
                                    "unit_type": "шт.",
                                    "quantity": 5.0,
                                    "discount": {
                                        "type": "amount",
                                        "value": 25.0
                                    },
                                    "vat_rate_id": 18,
                                    "vat_rate_value": 0,
                                    "bonus_points_per_purchase": 0.0,
                                    "external_uid": "",
                                    "metadata": [],
                                    "is_discount_recalculated": false,
                                    "is_total_sum_recalculated": false,
                                    "total_sum": 25.0
                                }
                            }
                        ]
                    }
                ],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 0,
                "invoice_link": "https://pay.amocrm.ru/rqPf8Z8igH",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/1163197"
                    }
                }
            }
        ]
    }
}

Редактирование элементов списков

Метод

PATCH /api/v4/catalogs/{catalog_id}/elements

Описание

Метод позволяет редактировать элементы списков пакетно.
Также вы можете добавить ID элемента в метод для редактирования конкретного элемента (/api/v4/catalogs/{catalog_id}/elements/{id}).
При редактировании пакетно передается массив из объектов-элементов, при редактировании одного элемента, передается просто модель элемента.

Ограничения

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

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

Content-Type: application/json

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

Параметр Тип данных Описание
name string Название элемента списка. Обязательный параметр
custom_fields_values array Массив, содержащий информацию по значениям дополнительных полей, заданных для данного элемента. Примеры заполнения полей
request_id string Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

[
    {
        "id": 986757,
        "name": "Новое имя элемента"
    },
    {
        "id": 986753,
        "name": "Новое имя элемента 2"
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает коллекцию или модель элемента, которые были изменены. Параметры аналогичны тем, что доступны при получении списка элементов.

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements"
        }
    },
    "_embedded": {
        "elements": [
            {
                "id": 986757,
                "name": "Новое имя элемента",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294541,
                "updated_at": 1589295769,
                "is_deleted": false,
                "custom_fields_values": [ ],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 986757,
                "invoice_link": null,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/986757"
                    }
                }
            },
            {
                "id": 986753,
                "name": "Новое имя элемента 2",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589294429,
                "updated_at": 1589295769,
                "is_deleted": false,
                "custom_fields_values": [],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 986753,
                "invoice_link": null,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/986753"
                    }
                }
            }
        ]
    }
}