Списки

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

Списки – это хранилище данных, элементы которого вы можете прикрепить к карточке.

Возможные параметры списка

Параметр Тип Описание
id int Уникальный идентификатор списка
name string Имя списка
created_by int Кем создан список
created_at timestamp Когда был создан список
updated_by int Кем обновлен список
updated_at timestamp Когда был обновлен список
sort int Порядок среди других возможных списков
type string Типа списка: regular (список), invoices (счета), products (продукты)
can_add_elements bool Добавление счета из интерфейса
can_show_in_cards bool Возможность добавить вкладку со списком в карточку сделки/покупателя
can_link_multiple bool Возможность привязывать один элемент данного списка к нескольким сделкам/покупателям
can_be_deleted bool Возможно ли удаление списка
sdk_widget_code string Код виджета, связанного со списком (доступно только для счетов)
account_id int Уникальный идентификатор аккаунта
request_id int Уникальный идентификатор записи в клиентской программе, необязательный параметр (информация о request_id нигде не сохраняется)

Перечень списков

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

URL метода

GET /api/v4/catalogs – для получения перечня списков

GET /api/v4/catalogs/{id} – для получения списка по идентификатору

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


GET https://example.amocrm.ru/api/v4/catalogs

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 4769,
                "name": "Счета",
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1579712638,
                "updated_at": 1589284968,
                "sort": 40,
                "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": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/4769"
                    }
                }
            },
            {
                "id": 1209,
                "name": "Товары",
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1575291059,
                "updated_at": 1589284968,
                "sort": 60,
                "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": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209"
                    }
                }
            }
        ]
    }
}

ДОБАВЛЕНИЕ И ОБНОВЛЕНИЕ СПИСКОВ

Эти методы доступны только пользователям, у которых есть права на доступ к спискам. Методы позволяют добавлять списки по одному или пакетно, а также обновлять данные по уже существующим спискам.

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

URL метода

POST /api/v4/catalogs

Параметры доступные при создании списка:

– name
– can_add_elements
– can_link_multiple
– request_id
– type (invoices или regular)

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


POST https://example.amocrm.ru/api/v4/catalogs
Content-Type: application/json

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

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


{
    "_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"
                    }
                }
            }
        ]
    }
}

Обновление списков

URL метода

PATCH /api/v4/catalogs/{id:\d+} – для обновления по идентификатору

PATCH /api/v4/catalogs – для массового обновления

Параметры доступные для обновления у списка:

– name
– can_add_elements
– can_link_multiple
– request_id

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


PATCH https://example.amocrm.ru/api/v4/catalogs/5787
Content-Type: application/json

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

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


{
    "id": 5787,
    "name": "Test 3",
    "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"
        }
    }
}

Пример запроса на массовое обновление


PATCH https://example.amocrm.ru/api/v4/catalogs
Content-Type: application/json

[
    {
        "id": 5787,
        "name": "New name"
    },
    {
        "id": 5793,
        "name": "New name 2"
    }
]

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


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs"
        }
    },
    "_embedded": {
        "catalogs": [
            {
                "id": 5787,
                "name": "New name",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589399557,
                "updated_at": 1589400002,
                "sort": 40,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "account_id": 123123,
                "request_id": "5787",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/5787"
                    }
                }
            },
            {
                "id": 5793,
                "name": "New name 2",
                "created_by": 3944275,
                "updated_by": 3944275,
                "created_at": 1589399983,
                "updated_at": 1589400002,
                "sort": 10,
                "type": "regular",
                "can_add_elements": true,
                "can_show_in_cards": false,
                "can_link_multiple": true,
                "can_be_deleted": true,
                "account_id": 123123,
                "request_id": "5793",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/5793"
                    }
                }
            }
        ]
    }
}

ЭЛЕМЕНТЫ СПИСКОВ

Элементы списков – это сущности, состоящие из набора полей, системных и кастомных. Далее мы рассмотрим методы, которые позволяют нам работать со списками в amoCRM

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

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

URL метода

GET /api/v4/catalogs/{catalog_id:\d+}/elements – для получения всех элементов

GET /api/v4/catalogs/{catalog_id:\d+}/elements/{id:\d+} – для получения элемента по id

Возможные параметры элемента списка

Параметр Тип Описание
id int Идентификатор элемента
name string Имя элемента
created_by int Кем создан элемент
created_at timestamp Когда был создан элемент
updated_by int Кем обновлен элемент
updated_at timestamp Когда был обновлен элемент
is_deleted bool Удален ли элемент
custom_fields_values array Дополнительные поля элемента
catalog_id int Идентификатор списка к которому относится элемент
account_id int Идентификатор аккаунта

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


GET https://example.amocrm.ru/api/v4/catalogs/1209/elements/914901

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


{
    "id": 914901,
    "name": "Товар для теста",
    "created_by": 281868,
    "updated_by": 281868,
    "created_at": 1584893625,
    "updated_at": 1585736169,
    "is_deleted": false,
    "custom_fields_values": [
        {
            "field_id": 14687,
            "field_name": "Цена",
            "field_code": "PRICE",
            "field_type": "numeric",
            "values": [
                {
                    "value": "100"
                }
            ]
        },
        {
            "field_id": 14693,
            "field_name": "External ID",
            "field_code": "EXTERNAL_ID",
            "field_type": "text",
            "values": [
                {
                    "value": "18c75678-6c58-11ea-2e89-fa163eb5a41c"
                }
            ]
        }
    ],
    "catalog_id": 1209,
    "account_id": 123123,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/914901"
        }
    }
}

Пример получения всех элементов списка


GET https://example.amocrm.ru/api/v4/catalogs/1209/elements

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


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements?page=1&limit=50&offset=0"
        }
    },
    "_embedded": {
        "elements": {
            {
                "id": 886309,
                "name": "Товар 1”,
                "created_by": 281868,
                "updated_by": 281868,
                "created_at": 1583149007,
                "updated_at": 1585736170,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 14683,
                        "field_name": "Артикул",
                        "field_code": "SKU",
                        "field_type": "text",
                        "values": [
                            {
                                "value": "1255455"
                            }
                        ]
                    }
                ],
                "catalog_id": 1209,
                "account_id": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/886309"
                    }
                }
            },
            {
                "id": 758017,
                "name": "Товар 2”,
                "created_by": 3987910,
                "updated_by": 3987910,
                "created_at": 1579085390,
                "updated_at": 1585741978,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 234583,
                        "field_name": "Кол-во",
                        "field_code": null,
                        "field_type": "numeric",
                        "values": [
                            {
                                "value": "1"
                            }
                        ]
                    }
                ],
                "catalog_id": 1209,
                "account_id": 123123,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/758017"
                    }
                }
            }
        ]
    }
}

Создания элемента списка

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

URL метода

POST /api/v4/catalogs/{catalog_id:\d+}/elements

Для создания элемента/элементов списка необходимо передать массив из JSON, который содержит обязательный параметр name (имя элемента) и дополнительные параметры:
– custom_fields_values
– created_by
– updated_by

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


POST https://example.amocrm.ru/api/v4/catalogs/1209/elements
Content-Type: application/json

[
    {
        "name": "Новый элемент списка",
        "custom_fields_values": [
            {
                "field_id": 14687,
                "field_name": "Цена",
                "values": [
                    {
                        "value": "1000"
                    }
                ]
            }
        ]
    }
]

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


{
    "_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": 1589294541,
                "is_deleted": false,
                "custom_fields_values": [
                    {
                        "field_id": 14687,
                        "field_name": "Цена",
                        "field_code": "PRICE",
                        "field_type": "numeric",
                        "values": [
                            {
                                "value": "1000"
                            }
                        ]
                    }
                ],
                "catalog_id": 1209,
                "account_id": 123123,
                "request_id": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/986757"
                    }
                }
            }
        ]
    }
}

Изменение элементов списка

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

URL метода

PATCH /api/v4/catalogs/{catalog_id:\d+}/elements/{id:\d+}

PATCH /api/v4/catalogs/{catalog_id:\d+}/elements

Параметры доступные для изменения у элементов списка:
– name
– custom_fields_values

Пример изменения элемента списка по id


PATCH https://example.amocrm.ru/api/v4/catalogs/1209/elements/986757
Content-Type: application/json

{
    "name": "Новый элемент каталога",
    "custom_fields_values": [
        {
            "field_id": 14687,
            "field_name": "Цена",
            "values": [
                {
                    "value": "10030"
                }
            ]
        }
    ]
}

Пример массового изменения элементов списка


PATCH https://example.amocrm.ru/api/v4/catalogs/1209/elements
Content-Type: application/json

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

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


{
    "_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,
                "_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,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1209/elements/986753"
                    }
                }
            }
        ]
    }
}

Смотрите также

КОДЫ ОШИБОК API