Поля и группы полей

В данном разделе описывается работа с дополнительными полями и группами полей через API

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

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

Пользовательские поля могут быть созданы для сделок, контактов, компаний, списков, сегментов и покупателей
Адреса методов зависят от сущности

Список полей сущности

Метод

GET /api/v4/leads/custom_fields

GET /api/v4/contacts/custom_fields

GET /api/v4/companies/custom_fields

GET /api/v4/customers/custom_fields

GET /api/v4/customers/segments/custom_fields

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

Описание

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

Ограничения

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

GET параметры

Параметр	Тип данных	Описание
page	int	Страница выборки
limit	int	Количество возвращаемых сущностей за один запрос (Максимум – 250)
filter[type][0]	string	Тип поля. Список доступных полей
order	object	Сортировка результатов списка. Доступные поля для сортировки: sort, id. Доступные значения для сортировки: asc, desc. Пример: /api/v4/leads/custom_fields?order[sort]=asc

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID поля
name	string	Название поля
code	string	Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля
sort	int	Сортировка поля
type	string	Тип поля. Список доступных полей
entity_type	string	Тип сущности (leads, contacts, companies, segments, customers, catalogs)
is_computed	bool	Параметр отвечает за определение типа поля как "вычисляемое" (computed) поле. Данный ключ возвращается только при получении списка полей сделки
is_predefined	bool	Является ли поле предустановленным. Данный ключ возвращается только при получении списка полей контактов и компаний
is_deletable	bool	Доступно ли поле для удаления. Данный ключ возвращается только при получении списка полей контактов и компаний
is_visible	bool	Отображается ли поле в интерфейсе списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_deletable	bool	Можно ли удалить поле из интерфейса. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_required	bool	Обязательно ли поле для заполнения при создании элемента списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
settings	array null	Настройки поля. Данный ключ возвращается только при получении списка полей списков (каталогов)
remind	string null	Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц). Значение данного поля доступно только для поля типа birthday. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
currency	string(3) null	Код валюты поля. Применимо только для типа поля – monetary. Для других типов полей – null.
enums	array null	Доступные значения для поля. Значение данного поля доступно только для полей с поддержкой enum
enums[0]	object	Доступное значение для поля
enums[0][id]	int	ID значения
enums[0][value]	string	Значение
enums[0][sort]	int	Сортировка значения
enums[0][code]	string null	Символьный код значения
nested	array null	Вложенные значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0]	object	Модель вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][id]	int	ID вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][parent_id]	int	ID родительского вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][value]	string	Значение вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][sort]	int	Сортировка вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
is_api_only	bool	Доступно ли поле для редактирования только через API. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
group_id	string null	ID группы полей, в которой состоит данное поле. Данный ключ возвращается только при получении списка полей контактов, сделок, покупателей и компаний
required_statuses	array null	Обязательные поля для смены этапов. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0]	object	Модель обязательного поля для смены этапов. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0][status_id]	int	ID статуса, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
required_statuses[0][pipeline_id]	int	ID воронки, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении списка полей контактов, сделок и компаний
hidden_statuses	array	Настройка скрытия полей. Поля скрываются в интерфейсе в зависимости от статуса. Данный ключ возвращается только при получении списка полей сделок.
hidden_statuses[0]	object	Модель настройки скрытия полей.
hidden_statuses[0][status_id]	int	ID статуса, в котором поле скрыто
hidden_statuses[0][pipeline_id]	int	ID воронки, в котором поле скрыто
chained_lists	array null	Настройка поля типа chained_list. Данный ключ возвращается только при получении списка полей сделок и покупателей.
chained_lists[0]	object	Модель настройки связанного списка.
chained_lists[0][title]	string null	Название связанного списка, которое отображается в карточке
chained_lists[0][catalog_id]	int	ID каталога
chained_lists[0][parent_catalog_id]	int	ID родительского каталога
tracking_callback	string	Сallback js-функция, которая будет выполнена на странице с CRM Plugin и формой amoCRM при отправке данных. Данное значение возвращается для полей типа tracking_data
search_in	string null	ID списка или символьный код (contacts, companies, contacts_and_companies) для поля типа Связь с другим элементов (linked_entity).

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

{
    "_total_items": 2,
    "_page": 1,
    "_page_count": 10,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=2"
        },
        "last": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields?limit=2&page=10"
        }
    },
    "_embedded": {
        "custom_fields": [
            {
                "id": 4439091,
                "name": "Пример текстового поля",
                "sort": 504,
                "type": "text",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": [
                    {
                        "status_id": 41221,
                        "pipeline_id": 3142
                    }
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/custom_fields/4439091/"
                    }
                }
            },
            {
                "id": 4440043,
                "name": "Пример поля с типом 'data'",
                "sort": 505,
                "type": "date",
                "is_predefined": false,
                "settings": null,
                "remind": null,
                "is_api_only": false,
                "group_id": null,
                "enums": null,
                "required_statuses": null,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/custom_fields/4440043/"
                    }
                }
            }
        ]
    }
}

Получение поля сущности по его ID

Метод

GET /api/v4/leads/custom_fields/{id}

GET /api/v4/contacts/custom_fields/{id}

GET /api/v4/companies/custom_fields/{id}

GET /api/v4/customers/custom_fields/{id}

GET /api/v4/customers/segments/custom_fields/{id}

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

Описание

Метод позволяет получить поле сущности по его ID.

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

Метод возвращает модель поля, рассмотрим ниже свойства поля. Состав полей модели может отличаться в зависимости от сущности.

Параметр	Тип данных	Описание
id	int	ID поля
name	string	Название поля
code	string	Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля
sort	int	Сортировка поля
type	string	Тип поля. Список доступных полей
entity_type	string	Тип сущности (leads, contacts, companies, segments, customers, catalogs)
is_predefined	bool	Является ли поле предустановленным. Данный ключ возвращается только при получении поля контакта и компании
is_deletable	bool	Доступно ли поле для удаления. Данный ключ возвращается только при получении поля контакта и компании
is_visible	bool	Отображается ли поле в интерфейсе списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_deletable	bool	Можно ли удалить поле из интерфейса. Данный ключ возвращается только при получении списка полей списков (каталогов)
is_required	bool	Обязательно ли поле для заполнения при создании элемента списка. Данный ключ возвращается только при получении списка полей списков (каталогов)
settings	array null	Настройки поля. Данный ключ возвращается только при получении поля списка (каталога)
remind	string int	Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц). Значение данного поля доступно только для поля типа birthday. Данный ключ возвращается только при получении поля контакта, сделки и компании
enums	array null	Доступные значения для поля. Значение данного поля доступно только для полей с поддержкой enum
enums[0]	object	Доступное значение для поля
enums[0][id]	int	ID значения
enums[0][code]	string\|null	Символьный код значения
enums[0][value]	string	Значение
enums[0][sort]	int	Сортировка значения
is_api_only	bool	Доступно ли поле для редактирования только через API. Данный ключ возвращается только при получении поля контакта, сделки и компании
group_id	string null	ID группы полей, в которой состоит данное поле. Данный ключ возвращается только при получении поля контакта, покупателя, сделки и компании
required_statuses	array null	Обязательные поля для смены этапов. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0]	object	Модель обязательного поля для смены этапов. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0][status_id]	int	ID статуса, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении поля контакта, сделки и компании
required_statuses[0][pipeline_id]	int	ID воронки, для перехода в который данное поле обязательно к заполнению. Данный ключ возвращается только при получении поля контакта, сделки и компании
nested	array null	Вложенные значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0]	object	Модель вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][id]	int	ID вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][parent_id]	int	ID родительского вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][value]	string	Значение вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
nested[0][sort]	int	Сортировка вложенного значения. Данные ключ возвращается только при получении списка полей каталогов и значение доступно только для поля category
hidden_statuses	array	Настройка скрытия полей. Поля скрываются в интерфейсе в зависимости от статуса. Данный ключ возвращается только при получении списка полей сделок.
hidden_statuses[0]	object	Модель настройки скрытия полей.
hidden_statuses[0][status_id]	int	ID статуса, в котором поле скрыто
hidden_statuses[0][pipeline_id]	int	ID воронки, в котором поле скрыто
chained_lists	array null	Настройка поля типа chained_list. Данный ключ возвращается только при получении списка полей сделок и покупателей.
chained_lists[0]	object	Модель настройки связанного списка.
chained_lists[0][title]	string null	Название связанного списка, которое отображается в карточке
chained_lists[0][catalog_id]	int	ID каталога
chained_lists[0][parent_catalog_id]	int	ID родительского каталога
tracking_callback	string	Сallback js-функция, которая будет выполнена на странице с CRM Plugin и формой amoCRM при отправке данных. Данное значение возвращается для полей типа tracking_data
search_in	string null	ID списка или символьный код (contacts, companies, contacts_and_companies) для поля типа Связь с другим элементов (linked_entity).
currency	string(3) null	Код валюты поля. Применимо только для типа поля – monetary. Для других типов полей – null.

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

{
    "id": 3,
    "name": "Телефон",
    "type": "multitext",
    "account_id": 28805383,
    "code": "PHONE",
    "sort": 4,
    "is_api_only": false,
    "enums": [
        {
            "id": 1,
            "value": "WORK",
            "sort": 2
        },
        {
            "id": 3,
            "value": "WORKDD",
            "sort": 4
        },
        {
            "id": 5,
            "value": "MOB",
            "sort": 6
        },
        {
            "id": 7,
            "value": "FAX",
            "sort": 8
        },
        {
            "id": 9,
            "value": "HOME",
            "sort": 10
        },
        {
            "id": 11,
            "value": "OTHER",
            "sort": 12
        }
    ],
    "group_id": null,
    "required_statuses": [],
    "is_deletable": false,
    "is_predefined": true,
    "entity_type": "contacts",
    "remind": null,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/custom_fields/3"
        }
    }
}

Создание дополнительных полей сущности

Метод

POST /api/v4/leads/custom_fields

POST /api/v4/contacts/custom_fields

POST /api/v4/companies/custom_fields

POST /api/v4/customers/custom_fields

POST /api/v4/customers/segments/custom_fields

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для создания поля необходимо передать модель поля.

Параметр	Тип данных	Описание	Обязательное	Поддерживаемы типы полей
type	string	Тип поля. Доступные типы полей	✅	Доступно для всех полей
name	string	Название поля	✅	Доступно для всех полей
code	string	Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля	❌	Доступно для всех полей
sort	int	Сортировка поля в группе полей	❌	Доступно для всех полей
group_id	string	ID группы полей	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
is_api_only	bool	Доступно ли поле для редактирования только через API	❌	Доступно для всех полей контактов, компаний и сделок
required_statuses	array null	Обязательные поля для смены этапа сделки	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0]	object	Модель обязательного поля для смены этапа сделки	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][status_id]	int	ID статуса, для перехода в который данное поле обязательно к заполнению	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][pipeline_id]	int	ID воронки, для перехода в который данное поле обязательно к заполнению	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
settings	object	Настройки поля	❌	Доступно для всех полей списков (каталогов)
is_visible	bool	Отображается ли поле в интерфейсе списка	❌	Доступно для всех полей списков (каталогов)
is_required	bool	Обязательно ли поле для заполнения при создании элемента списка	❌	Доступно для всех полей списков (каталогов)
remind	string null	Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц)	❌	Доступно для типа поля birthday
enums	array	Доступные значения поля	✅	Доступно для полей: multiselect radiobutton select
enums[0]	object	Модель доступного значения поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][value]	string	Значение одного из доступных значения поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][sort]	int	Сортировка среди других доступных значений поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][code]	string	Символьный код значения	❌	Доступно для полей: multiselect radiobutton select
nested	array	Вложенные значения	❌	Доступно для полей: category
nested[0]	object	Модель вложенного значения	❌	Доступно для полей: category
nested[0][id]	int	ID вложенного значения	❌	Доступно для полей: category
nested[0][parent_id]	int	ID родительского вложенного значения	❌	Доступно для полей: category
nested[0][value]	string	Значение вложенного значения	❌	Доступно для полей: category
nested[0][sort]	int	Сортировка вложенного значения	❌	Доступно для полей: category
nested[0][request_id]	string	Временный идентификатор вложенного значения, должен быть уникальным в пределах запроса, нигде не сохраняется, используется для создания больше одного уровня вложенности за запрос	❌	Доступно для полей: category
nested[0][parent_request_id]	string	Временный идентификатор родителя вложенного значения, используется только на момент запроса, нигде не сохраняется, определяет на какой уровень вложенности добавлять элемент, если родительский элемент еще не был создан	❌	Доступно для полей: category
tracking_callback	string	Сallback js-функция, которая будет выполнена на странице с CRM Plugin и формой amoCRM при отправке данных	❌	Доступно для полей: tracking_data
hidden_statuses	array	Настройка скрытия полей. Поля скрываются в интерфейсе в зависимости от статуса. Данный ключ возвращается только при получении списка полей сделок.	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0]	object	Модель настройки скрытия полей.	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0][status_id]	int	ID статуса, в котором поле скрыто	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0][pipeline_id]	int	ID воронки, в котором поле скрыто	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
chained_lists	array null	Настройка поля типа chained_list. Данный ключ возвращается только при получении списка полей сделок и покупателей.	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0]	object	Модель настройки связанного списка.	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][title]	string null	Название связанного списка, которое отображается в карточке	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][catalog_id]	int	ID каталога	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][parent_catalog_id]	int	ID родительского каталога	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
search_in	string null	ID списка или символьный код (contacts, companies, contacts_and_companies) для поля типа Связь с другим элементов (linked_entity).	✅	Доступно для полей: linked_entity
currency	string null	Код валюты поля.	✅	Доступно для полей: monetary , но только, если в аккаунте подключена функция Супер-поля

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

[
    {
        "name": "multi select",
        "type": "multiselect",
        "sort": 510,
        "required_statuses": [
            {
                "pipeline_id": 16056,
                "status_id": 20540473
            }
        ],
        "enums": [
            {
                "value": "Значение 1",
                "sort": 1
            },
            {
                "value": "Значение 2",
                "sort": 2
            }
        ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа	Условие
201	Запрос выполнен успешно
422	Запрос не может быть обработан, подробности в теле ответа
401	Пользователь не авторизован
400	Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

{
    "_total_items": 1,
    "_embedded": {
        "custom_fields": [
            {
                "name": "multi select",
                "type": "multiselect",
                "sort": 510,
                "settings": null,
                "is_predefined": false,
                "id": 4457223,
                "remind": null,
                "is_api_only": false,
                "enums": [
                    {
                        "value": "Значение 1",
                        "sort": 1,
                        "id": 3778801
                    },
                    {
                        "value": "Значение 2",
                        "sort": 2,
                        "id": 3778803
                    }
                ],
                "group_id": null,
                "required_statuses": [
                    {
                        "status_id": 20540473,
                        "pipeline_id": 16056
                    },
                ],
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/custom_fields/4457223/"
                    }
                }
            }
        ]
    }
}

Редактирование дополнительных полей сущности

Метод

PATCH /api/v4/leads/custom_fields

PATCH /api/v4/contacts/custom_fields

PATCH /api/v4/companies/custom_fields

PATCH /api/v4/customers/custom_fields

PATCH /api/v4/customers/segments/custom_fields

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

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для редактирования поля необходимо передать модель поля.

Параметр	Тип данных	Описание	Обязательное	Поддерживаемы типы полей
name	string	Название поля	✅	Доступно для всех полей
code	string	Код поля, по-которому можно обновлять значение в сущности, без передачи ID поля	❌	Доступно для всех полей
sort	int	Сортировка поля в группе полей	❌	Доступно для всех полей
group_id	string	ID группы полей	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
is_api_only	bool	Доступно ли поле для редактирования только через API	❌	Доступно для всех полей контактов, компаний и сделок
required_statuses	array null	Обязательные поля для смены этапа сделки	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0]	object	Модель обязательного поля для смены этапа сделки	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][status_id]	int	ID статуса, для перехода в который данное поле обязательно к заполнению	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
required_statuses[0][pipeline_id]	int	ID воронки, для перехода в который данное поле обязательно к заполнению	❌	Доступно для всех полей контактов, компаний, сделок и покупателей
settings	object	Настройки поля	❌	Доступно для всех полей списков (каталогов)
is_visible	bool	Отображается ли поле в интерфейсе списка	❌	Доступно для всех полей списков (каталогов)
is_required	bool	Обязательно ли поле для заполнения при создании элемента списка	❌	Доступно для всех полей списков (каталогов)
remind	string null	Когда напоминать о дне рождения (never – никогда, day – за день, week – за неделю, month – за месяц)	❌	Доступно для типа поля birthday
enums	array	Доступные значения поля	✅	Доступно для полей: multiselect radiobutton select
enums[0]	object	Модель доступного значения поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][id]	int	ID значения необходимо передавать, если вы хотите обновить предыдущие данные без удаления актуальных ID. В случае, если вы не передадите это поле, предыдущие ID будут удалены	❌	Доступно для полей: multiselect radiobutton select
enums[0][value]	string	Значение одного из доступных значений поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][sort]	int	Сортировка среди других доступных значений поля	✅	Доступно для полей: multiselect radiobutton select
enums[0][code]	string	Символьный код значения	❌	Доступно для полей: multiselect radiobutton select
nested	array	Вложенные значения	❌	Доступно для полей: category
nested[0]	object	Модель вложенного значения	❌	Доступно для полей: category
nested[0][id]	int	ID вложенного значения. Для создания нового значение не нужно передавать	❌	Доступно для полей: category
nested[0][parent_id]	int	ID родительского вложенного значения	❌	Доступно для полей: category
nested[0][value]	string	Значение вложенного значения	❌	Доступно для полей: category
nested[0][sort]	int	Сортировка вложенного значения	❌	Доступно для полей: category
nested[0][request_id]	string	Временный идентификатор вложенного значения, должен быть уникальным в пределах запроса, нигде не сохраняется, используется для создания больше одного уровня вложенности за запрос	❌	Доступно для полей: category
nested[0][parent_request_id]	string	Временный идентификатор родителя вложенного значения, используется только на момент запроса, нигде не сохраняется, определяет на какой уровень вложенности добавлять элемент, если родительский элемент еще не был создан	❌	Доступно для полей: category
tracking_callback	string	Сallback js-функция, которая будет выполнена на странице с CRM Plugin и формой amoCRM при отправке данных	❌	Доступно для полей: tracking_data
hidden_statuses	array	Настройка скрытия полей. Поля скрываются в интерфейсе в зависимости от статуса. Данный ключ возвращается только при получении списка полей сделок.	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0]	object	Модель настройки скрытия полей.	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0][status_id]	int	ID статуса, в котором поле скрыто	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
hidden_statuses[0][pipeline_id]	int	ID воронки, в котором поле скрыто	❌	Доступно для всех полей сделок, но только, если в аккаунте подключена функция Супер-поля
chained_lists	array null	Настройка поля типа chained_list. Данный ключ возвращается только при получении списка полей сделок и покупателей.	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0]	object	Модель настройки связанного списка.	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][title]	string null	Название связанного списка, которое отображается в карточке	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][catalog_id]	int	ID каталога	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
chained_lists[0][parent_catalog_id]	int	ID родительского каталога	✅	Доступно для полей: chained_list , но только, если в аккаунте подключена функция Супер-поля
search_in	string null	ID списка или символьный код (contacts, companies, contacts_and_companies) для поля типа Связь с другим элементов (linked_entity).	✅	Доступно для полей: linked_entity
currency	string null	Код валюты поля.	✅	Доступно для полей: monetary , но только, если в аккаунте подключена функция Супер-поля

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

В примере ниже обновим 2 поля у каталога, сделав запрос к методу /api/v4/catalogs/{catalog_id}/custom_fields.

[
    {
        "id": 1278898087,
        "name": "Новое имя для дополнительного поля",
        "sort": 560,
        "is_visible": false,
        "is_required": true
    },
    {
        "id": 1278898091,
        "name": "Новое имя для поля Категория",
        "nested": [
            {
                "id": 197,
                "parent_id": null,
                "value": "категория 1",
                "sort": 0
            },
            {
                "parent_id": null,
                "value": "новая категория 2",
                "sort": 1
            },
            {
                "parent_id": 197,
                "value": "новая подкатегория 1",
                "sort": 1
            }
        ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

Код ответа	Условие
201	Запрос выполнен успешно
422	Запрос не может быть обработан, подробности в теле ответа
401	Пользователь не авторизован
400	Переданы некорректные данные. Подробности доступны в теле ответа

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

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

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

{
    "_total_items": 2,
    "_embedded": {
        "custom_fields": [
            {
                "id": 1278898087,
                "name": "Новое имя для дополнительного поля",
                "type": "textarea",
                "account_id": 17079858,
                "code": "DESCRIPTION",
                "sort": 560,
                "is_api_only": false,
                "enums": null,
                "request_id": "0",
                "catalog_id": 1095,
                "is_visible": false,
                "is_deletable": true,
                "is_required": false,
                "nested": null,
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1095/custom_fields/1278898087"
                    }
                }
            },
            {
                "id": 1278898091,
                "name": "Новое имя для поля Категория",
                "type": "category",
                "account_id": 17079858,
                "code": "GROUP",
                "sort": 500,
                "is_api_only": false,
                "enums": null,
                "request_id": "1",
                "catalog_id": 1095,
                "is_visible": true,
                "is_deletable": false,
                "is_required": false,
                "nested": [
                    {
                        "id": 197,
                        "parent_id": null,
                        "value": "категория 1",
                        "sort": 0
                    },
                    {
                        "id": 215,
                        "parent_id": 197,
                        "value": "новая подкатегория 1",
                        "sort": 0
                    },
                    {
                        "id": 217,
                        "parent_id": 197,
                        "value": "новая категория 2",
                        "sort": 1
                    }
                ],
                "entity_type": "catalogs",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/catalogs/1095/custom_fields/1278898091"
                    }
                }
            }
        ]
    }
}

Удаление дополнительного поля

Метод

DELETE /api/v4/leads/custom_fields/{id}

DELETE /api/v4/contacts/custom_fields/{id}

DELETE /api/v4/companies/custom_fields/{id}

DELETE /api/v4/customers/custom_fields/{id}

DELETE /api/v4/customers/segments/custom_fields/{id}

DELETE /api/v4/catalogs/{catalog_id}/custom_fields/{id}

Описание

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

Ограничения

Метод доступен только с правами администратора аккаунта
Значения поля будут удалены

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

Content-Type: application/json

HTTP коды ответа

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

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

Метод не возвращает тело

Список групп полей сущности

Метод

GET /api/v4/leads/custom_fields/groups

GET /api/v4/contacts/custom_fields/groups

GET /api/v4/companies/custom_fields/groups

GET /api/v4/customers/custom_fields/groups

GET /api/v4/catalogs/{catalog_id}/custom_fields/groups

Описание

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

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	string	ID группы полей
name	string	Название группы полей
sort	int	Сортировка группы полей в карточке сущности
entity_type	string	Тип сущности (leads, contacts, companies, customers, catalogs)
is_predefined	bool	Является ли группа предустановленной. Такие группы нельзя удалить
type	string	Тип группы (linked_group – группы товаров, custom_field_group – группы полей). Для списков – только custom_field_group

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

{
    "id": "leads_29741591099841",
    "name": "Группа полей",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "sort": 3,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_29741591099841"
        }
    }
}

Получение группы полей сущности по ID группы

Метод

GET /api/v4/leads/custom_fields/groups/{id}

GET /api/v4/contacts/custom_fields/groups/{id}

GET /api/v4/companies/custom_fields/groups/{id}

GET /api/v4/customers/custom_fields/groups/{id}

GET /api/v4/catalogs/{catalog_id}/custom_fields/groups/{id}

Описание

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

Ограничения

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	string	ID группы полей
name	string	Название группы полей
sort	int	Сортировка группы полей в карточке сущности
entity_type	string	Тип сущности (leads, contacts, companies, customers, catalogs)
is_predefined	bool	Является ли группа предустановленной. Такие группы нельзя удалить
type	string	Тип группы (linked_group – группы товаров, custom_field_group – группы полей). Для списков – только custom_field_group

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

{
    "_total_items": 4,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "default",
                "name": "Основное",
                "is_predefined": true,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/default"
                    }
                }
            },
            {
                "id": "4521",
                "name": "Товары",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 1,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/4521"
                    }
                }
            },
            {
                "id": "statistic",
                "name": "Статистика",
                "is_predefined": true,
                "type": "linked_group",
                "entity_type": "leads",
                "sort": 2,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/statistic"
                    }
                }
            },
            {
                "id": "leads_29741591099841",
                "name": "Группа полей",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 3,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_29741591099841"
                    }
                }
            }
        ]
    }
}

Создание групп полей

Метод

POST /api/v4/leads/custom_fields/groups

POST /api/v4/contacts/custom_fields/groups

POST /api/v4/companies/custom_fields/groups

POST /api/v4/customers/custom_fields/groups

POST /api/v4/catalogs/{catalog_id}/custom_fields/groups

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Параметр	Тип данных	Описание
name	string	Название группы. Обязательный параметр
sort	int	Сортировка группы. Обязательный параметр
request_id	string	Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр

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

[
    {
        "name": "group 1",
        "sort": 4
    },
    {
        "name": "group 2",
        "sort": 5
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

{
    "_total_items": 2,
    "_embedded": {
        "custom_field_groups": [
            {
                "id": "leads_2745158",
                "name": "group 1",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 4,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_2745158/"
                    }
                }
            },
            {
                "id": "leads_609315",
                "name": "group 2",
                "is_predefined": false,
                "type": "custom_field_group",
                "entity_type": "leads",
                "sort": 5,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_609315/"
                    }
                }
            }
        ]
    }
}

Редактирование группы полей

Метод

PATCH /api/v4/leads/custom_fields/groups/{id}

PATCH /api/v4/contacts/custom_fields/groups/{id}

PATCH /api/v4/companies/custom_fields/groups/{id}

PATCH /api/v4/customers/custom_fields/groups/{id}

PATCH /api/v4/catalogs/{catalog_id}/custom_fields/groups/{id}

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Для изменения группы необходимо передать хотя бы один параметр

Параметр	Тип данных	Описание
name	string	Название группы
sort	int	Сортировка группы
fields	array	Массив полей, которые должны быть перенесены в группу

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

{
    "sort": 6,
    "fields": [
        14563, 
        12575
    ]
}

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

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

{
    "id": "leads_2745",
    "name": "group 1",
    "is_predefined": false,
    "type": "custom_field_group",
    "entity_type": "leads",
    "fields": [
        13478, 
        14563, 
        12575
    ],
    "sort": 6,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/leads/custom_fields/groups/leads_2745/"
        }
    }
}

Удаление группы дополнительных полей

Метод

DELETE /api/v4/leads/custom_fields/groups/{id}

DELETE /api/v4/contacts/custom_fields/groups/{id}

DELETE /api/v4/companies/custom_fields/groups/{id}

DELETE /api/v4/customers/custom_fields/groups/{id}

DELETE /api/v4/catalogs/{catalog_id}/custom_fields/groups/{id}

Описание

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

Ограничения

Метод доступен только с правами администратора аккаунта
Предустановленные группы недоступны для удаления

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

Content-Type: application/json

HTTP коды ответа

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

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

Метод не возвращает тело

Доступные типы полей

Возможные типы дополнительных полей

Тип	Название
text	Текст
numeric	Число
checkbox	Флаг
select	Список
multiselect	Мультисписок
date	Дата
url	Ссылка
textarea	Текстовая область
radiobutton	Переключатель
streetaddress	Короткий адрес
smart_address	Адрес
birthday	День рождения
legal_entity	Юр. лицо
date_time	Дата и время
price	Цена
category	Категория
items	Предметы
tracking_data	Отслеживаемые данные
linked_entity	Связь с другим элементом
chained_list	Каталоги и списки (платная опция Супер-поля)
monetary	Денежное (платная опция Супер-поля)
file	Файл
payer	Плательщик (только в списке Счета-покупки)
supplier	Поставщик (только в списке Счета-покупки)

Таблица доступности разных типов полей для разных сущностей

Тип поля	Контакт	Сделка	Компания	Покупатель	Каталог	Сегмент
Текст	✅	✅	✅	✅	✅	✅
Число	✅	✅	✅	✅	✅	✅
Флаг	✅	✅	✅	✅	✅	✅
Список	✅	✅	✅	✅	✅	✅
Мультисписок	✅	✅	✅	✅	✅	✅
Мультитекст	✅	❌	❌	❌	❌	❌
Дата	✅	✅	✅	✅	✅	✅
Ссылка	✅	✅	✅	✅	✅	✅
Дата и время	✅	✅	✅	✅	✅	✅
Текстовая область	✅	✅	✅	✅	✅	✅
Переключатель	✅	✅	✅	✅	✅	✅
Короткий адрес	✅	✅	✅	✅	✅	✅
Адрес	✅	✅	✅	❌	❌	❌
День рождения	✅	✅	✅	❌	❌	❌
Юр. лицо	✅	✅	✅	❌	❌	❌
Цена	❌	❌	❌	❌	✅	❌
Категория	❌	❌	❌	❌	✅	❌
Предметы	❌	❌	❌	❌	✅	❌
Отслеживаемые данные	❌	✅	❌	❌	❌	❌
Связь с другим элементом	❌	❌	❌	❌	✅	❌
Каталоги и списки	❌	✅	❌	✅	❌	❌
Денежное	✅	✅	✅	✅	❌	❌
Файл	✅	✅	✅	✅	✅	❌
Поставщик (Счета/покупки)	❌	❌	❌	❌	✅	❌
Плательщик (Счета/покупки)	❌	❌	❌	❌	✅	❌

Примеры заполнения разных типов полей через API

Ниже рассмотрим примеры запросов на заполнение значений разных типов полей.

Не зависимо от типа полей все значения находятся передаются в объектах массива custom_fields_values. Для заполнения поля нужно передать его ID или символьный код, а также сами значения.

Параметр	Тип данных	Описание
custom_fields_values	array	Массив, содержащий информацию по значениям дополнительных полей, задаваемых для сущности
custom_fields_values[0]	object	Объект, содержащий информацию по значению дополнительного поля, задаваемых для сущности
custom_fields_values[0][field_id]	int	ID поля, значение которого вы заполняете
custom_fields_values[0][field_code]	string	Символьный код поля, значение которого вы заполняете (для заполнения нужно передать или field_id или field_code
custom_fields_values[0][values]	array	Массив заполняемых значений
custom_fields_values[0][values][0]	object	Объект значения поля. Структура объекта зависит от типа поля

Типы полей:

text
numeric
checkbox
select
multiselect
date
url
textarea
radiobutton
streetaddress
smart_address
legal_entity
birthday
date_time
price
category
items
multitext
tracking_data
linked_entity
chained_list
monetary
file
payer
supplier

text, numeric, textarea, price, streetaddress, tracking_data, monetary

В данном примере рассмотрим запрос на заполнение полей типа text, numeric, textarea, price, streetaddress, tracking_data, monetary.

Параметр	Тип данных	Описание
value	string	Значение поля

    ...
    "custom_fields_values": [
        {
            "field_id": 3,
            "values": [
                {
                    "value": "Значение поля"
                }
            ]
        },
        {
            "field_id": 103,
            "values": [
                {
                    "value": "1.5"
                }
            ]
        },
        {
            "field_id": 203,
            "values": [
                {
                    "value": "Строка1\nСтрока2"
                }
            ]
        },
        {
            "field_id": 303,
            "values": [
                {
                    "value": "100"
                }
            ]
        },
        {
            "field_id": 403,
            "values": [
                {
                    "value": "г. Москва, Николоямская улица 28/60 стр. 1"
                }
            ]
        }
    ],
    ...

checkbox

В данном примере рассмотрим запрос на заполнение полей типа checkbox.

Параметр	Тип данных	Описание
value	bool	Значение поля

    ...
    "custom_fields_values": [
        {
            "field_id": 5,
            "values": [
                {
                    "value": true
                }
            ]
        }
    ],
    ...

url

В данном примере рассмотрим запрос на заполнение полей типа url.

Параметр	Тип данных	Описание
value	string	Значение поля. Делегированный URL

    ...
    "custom_fields_values": [
        {
            "field_id": 7,
            "values": [
                {
                    "value": "https://www.amocrm.ru/"
                }
            ]
        }
    ],
    ...

date, date_time, birthday

В данном примере рассмотрим запрос на заполнение полей типа date, date_time, birthday.

Параметр	Тип данных	Описание
value	int \| string	Значение поля – Unix Timestamp отметка или время в формате RFC-3339

    ...
    "custom_fields_values": [
        {
            "field_id": 9,
            "values": [
                {
                    "value": 1577836800
                }
            ]
        },
        {
            "field_id": 109,
            "values": [
                {
                    "value": 1591965296
                }
            ]
        },
        {
            "field_id": 209,
            "values": [
                {
                    "value": 1586476800
                }
            ]
        }
    ],
    ...

select, multiselect, radiobutton, category

В данном примере рассмотрим запрос на заполнение полей типа select, multiselect, radiobutton, category. В качестве значения может быть передано как значение, как символьный код значения, так и ID значения.

Параметр	Тип данных	Описание
value	string	Значение поля
enum_id	int	ID значения поля (enum).
enum_code	string	Символьный код значения поля (enum).

    ...
    "custom_fields_values": [
        {
            "field_id": 11,
            "values": [
                {
                    "value": "Значение 1"
                }
            ]
        },
        {
            "field_id": 111,
            "values": [
                {
                    "enum_id": 17
                },
                {
                    "enum_id": 19
                }
            ]
        },
        {
            "field_id": 211,
            "values": [
                {
                    "value": "Значение 4"
                }
            ]
        }
    ],
    ...

smart_address

В данном примере рассмотрим запрос на заполнение полей типа smart_address. Поле принимает множественные значения. В значении необходимо передать поля value и enum_id или enum_code.

Параметр	Тип данных	Описание
value	string	Значение поля
enum_id	int	ID значения поля. Доступные значения: 1 – Первая строка адреса, 2 – Вторая строка адреса, 3 – Город, 4 – Регион, 5 – Почтовый индекс, 6 – Страна
enum_code	string	Код значения поля. Доступные значения: address_line_1 – Первая строка адреса, address_line_2 – Вторая строка адреса, city – Город, state – Регион, zip – Почтовый индекс, country – Страна

    ...
    "custom_fields_values": [
        {
            "field_id": 13,
            "values": [
                {
                    "value": "Николоямская улица 28/60",
                    "enum_id": 1
                },
                {
                    "value": "Москва",
                    "enum_code": "city"
                },
                {
                    "value": "Москва",
                    "enum_code": "state"
                },
                {
                    "value": "109004",
                    "enum_id": 5
                },
                {
                    "value": "RU",
                    "enum_code": "country"
                }
            ]
        }
    ],
    ...

multitext

В данном примере рассмотрим запрос на заполнение полей типа multitext (Телефон, Email). Поле принимает множественные значения. В значении необходимо передать поля value и enum_id или enum_code.

Параметр	Тип данных	Описание
value	string	Значение поля
enum_id	int	ID значения поля.
enum_code	string	Код значения поля. Доступные значения для поля Телефон: WORK – рабочий, WORKDD – рабочий прямой, MOB – мобильный, FAX – факс, HOME – домашний, OTHER – другой. Доступные значение для поля Email: WORK – рабочий, PRIV – личный, OTHER – другой.

    ...
    "custom_fields_values": [
        {
            "field_id": 31,
            "values": [
                {
                    "value": "+79121234567",
                    "enum_id": 48224
                },
                {
                    "value": "+74991234567",
                    "enum_code": "HOME"
                }
            ]
        }
    ],
    ...

legal_entity

В данном примере рассмотрим запрос на заполнение полей типа legal_entity. В значении необходимо обязательно передать поля name.

Параметр	Тип данных	Описание
value	object	Значение поля
value[name]	string	Название организации
value[entity_type]	int	Тип юридического лица. 1 – Частное, 2 – Юридическое.
value[address]	string	Адрес организации
value[real_address]	string	Фактический адрес
value[bank_account_number]	string	Рассчетный счет
value[director]	string	ФИО директора организации
value[vat_id]	string	ИНН организации (Россия)
value[tax_registration_reason_code]	string	ОГРНИП (Россия)
value[kpp]	string	КПП организации (Россия)
value[bank_code]	string	БИК (Россия)
value[unp]	string	УНП организации (Белоруссия)
value[bin]	string	БИН организации (Казахстан)
value[egrpou]	string	ЕГРПОУ организации (Украина)
value[mfo]	string	МФО организации (Украина/Узбекистан)
value[oked]	string	ОКЭД организации (Узбекистан)
value[external_uid]	string	Идентификатор внешней системы

    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "name": "ООО Рога и копыта",
                        "entity_type": 1,
                        "vat_id": "123123123",
                        "tax_registration_reason_code": 213,
                        "address": "Moscow",
                        "kpp": "23123123",
                        "external_uid": "uuid"
                    }
                }
            ]
        }
    ],
    ...

items

В данном примере рассмотрим запрос на заполнение полей типа items. Поле доступно в списке счетов для хранения состава товара.

Параметр	Тип данных	Описание
value	object	Значение поля
value[sku]	string	SKU товара
value[description]	string	Описание товара
value[unit_price]	int\|float	Цена за единицу товара
value[quantity]	int\|float	Количество товара в счете
value[unit_type]	string	Единица измерения
value[discount]	object	Объект скидки на товар
value[discount][type]	string	Тип скидки (percentage – процентная или amount количественная)
value[discount][value]	int\|float	Размер скидки
value[vat_rate_id]	int	Идентификатор налога (0 – Без НДС, 1 – 10%, 2 – 10/110, 3 – 18%, 4 – 18/118, 5 – 0)
value[external_uid]	string	Идентификатор внешней системы
value[is_discount_recalculated]	bool	Произошел ли перерасчет скидки товарной позиции. Свойство доступно только для чтения
value[is_total_sum_recalculated]	bool	Произошел ли перерасчет суммы товарной позиции (только в том случае, если скидка не установлена). Свойство доступно только для чтения
value[total_sum]	float	Сумма товарной позиции. Свойство доступно только для чтения

    ...
    "custom_fields_values": [
        {
            "field_id": 25,
            "values": [
                {
                    "value": {
                        "sku": "34N4124",
                        "description": "Описание товара",
                        "unit_price": 10,
                        "quantity": 2,
                        "unit_type": "шт.",
                        "discount": {
                            "type": "amount",
                            "value": 25
                        },
                        "vat_rate_id": 18,
                        "external_uid": "uid"
                    }
                }
            ]
        }
    ],
    ...

linked_entity

В данном примере рассмотрим запрос на заполнение поля типа linked_entity.

Параметр	Тип данных	Описание
value	object	Значение поля
value[name]	string	Отображаемое значение поля. Передается для моментального отображения.
value[entity_id]	int	ID связанной сущности
value[entity_type]	string	Тип сущности (catalog_elements, contacts, companies)
value[catalog_id]	int\|null	ID списка, если указывается связь со списком

  ...
  "custom_fields_values": [
    {
      "field_id": 1150977,
      "values": [
        {
          "value": {
            "name": "Ivan Ivanov",
            "entity_id": 24833339,
            "entity_type": "contacts",
            "catalog_id": null
          }
        }
      ]
    },
    {
      "field_id": 1150979,
      "values": [
        {
          "value": {
            "name": "Товар 1",
            "entity_id": 527597,
            "entity_type": "catalog_elements",
            "catalog_id": 6319
          }
        }
      ]
    }
  ],
  ...

chained_list

В данном примере рассмотрим запрос на заполнение поля типа chained_list.
Поле поддерживает множественные значения, до 5 элементов.

Параметр	Тип данных	Описание
catalog_id	int	ID списка, если указывается связь со списком
catalog_element_id	int	ID элемента списка, если указывается связь со списком

  ...
  "custom_fields_values": [
    {
      "field_id": 1150985,
      "values": [
        {  
          "catalog_id": 1001,
          "catalog_element_id": 12235
        },
        {  
          "catalog_id": 1007,
          "catalog_element_id": 12243
        }
      ]
    }
  ],
  ...

file

В данном примере рассмотрим запрос на заполнение поля типа file.

Параметр	Тип данных	Описание
value	object	Значение поля
value[file_uuid]	string	UUID файла в сервисе файлов
value[version_uuid]	string	UUID версии файла в сервисе файлов
value[file_name]	string	Название файла. можно не передавать, но
value[file_size]	int	Размер файла в байтах

  ...
  "custom_fields_values": [
    {
      "field_id": 1150985,
      "values": [
        {
          "value": { 
            "file_uuid": "3b454645-5c7f-4539-9ef9-0dd1b3638dad",
            "version_uuid": "13db6652-b3ed-4fff-aed8-0c6f3c43b887",
            "file_name": "wiki.odt",
            "file_size": 20763,
          }
        }
      ]
    }
  ],
  ...

payer

В данном примере рассмотрим запрос на заполнение поля типа payer. Поле доступно только в списке счетов-покупок и хранит в себе информацию о покупателе.

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

Примеры хранения информации, как свободный набор:

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

  ...
  "custom_fields_values": [
    {
      "field_id": 1164361,
      "values": [
        {
          "value": { 
            "name": "Иван",
            "address": "Москва, Вымышленная набережная, дом 1"
          }
        }
      ]
    }
  ],
  ...

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

Параметр	Тип данных	Описание
name	string	Название организации
address	string	Адрес организации
real_address	string	Фактический адрес
bank_account_number	string	Рассчетный счет
director	string	ФИО директора организации
vat_id	string	ИНН организации (Россия)
tax_registration_reason_code	string	ОГРН/ОГРНИП (Россия)
kpp	string	КПП организации (Россия)
bank_code	string	БИК (Россия)
unp	string	УНП организации (Белоруссия)
bin	string	БИН организации (Казахстан)
egrpou	string	ЕГРПОУ организации (Украина)
mfo	string	МФО организации (Украина/Узбекистан)
oked	string	ОКЭД организации (Узбекистан)

  ...
  "custom_fields_values": [
    {
      "field_id": 1164361,
      "values": [
        {
          "value": { 
            "name": "ООО Рога и копыта",
            "address": "Москва, Вымышленная набережная, дом 1",
            "real_address": "Москва, Вымышленная улица, дом 99",
            "vat_id": "0000111122"
          }
        }
      ]
    }
  ],
  ...

Если вы хотите в плательщике указать связь с контактом или компанией, достаточно передать entity_id и entity_type (contacts/companies).

  ...
  "custom_fields_values": [
    {
      "field_id": 1164361,
      "values": [
        {
          "value": { 
            "name": "Василий", // Имя для отображения в счете
            "entity_type": "contacts",
            "entity_id": 17615543
          }
        }
      ]
    }
  ],
  ...

Также можно принудительно задать тип покупателя с помощью свойства type, например, если какой-то информации не хватает, чтобы четко сказать, что покупатель юр лицо.
В данный момент свойство является не обязательным. Возможные значения для свойства: legal – юр лицо, individual – физ лицо.

  ...
  "custom_fields_values": [
    {
      "field_id": 1164361,
      "values": [
        {
          "value": { 
            "name": "ООО Рога и копыта",
            "address": "Москва, Вымышленная набережная, дом 1",
            "type": "legal"
          }
        }
      ]
    }
  ],
  ...

supplier

В данном примере рассмотрим запрос на заполнение поля типа supplier. Поле доступно только в списке счетов-покупок и хранит в себе ссылку на сущность из списка Мои Юр лица. Поле всегда имеет символьный код – SUPPLIER.

  ...
  "custom_fields_values": [
    {
      "field_id": 1042517,
      "values": [
        {
          "value": { 
            "entity_id": 521717,
          }
        }
      ]
    }
  ],
  ...

Оглавление

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

Список полей сущности

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

Получение поля сущности по его ID

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

Создание дополнительных полей сущности

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Редактирование дополнительных полей сущности

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Удаление дополнительного поля

Метод

Описание

Ограничения

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

HTTP коды ответа

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

Список групп полей сущности

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

Получение группы полей сущности по ID группы

Метод

Описание

Ограничения

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

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

HTTP коды ответа

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

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

Создание групп полей

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа