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

В данном разделе описывается работа с дополнительными полями и группами полей через 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, 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. В значении необходимо обязательно передать поля 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,
          }
        }
      ]
    }
  ],
  ...