Компании

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

Список компаний

Метод

GET /api/v4/companies

Описание

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

Ограничения

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

GET параметры

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID компании
name	string	Название компании
responsible_user_id	int	ID пользователя, ответственного за компанию
group_id	int	ID группы, в которой состоит ответственны пользователь за компанию
created_by	int	ID пользователя, создавший компанию
updated_by	int	ID пользователя, изменивший компанию
created_at	int	Дата создания компании, передается в Unix Timestamp
updated_at	int	Дата изменения компании, передается в Unix Timestamp
closest_task_at	int	Дата ближайшей задачи к выполнению, передается в Unix Timestamp
custom_fields_values	array null	Массив, содержащий информацию по значениям дополнительных полей, заданных для данной компании
is_deleted	bool	Удален ли элемент
account_id	int	ID аккаунта, в котором находится компания
_embedded	object	Данные вложенных сущностей
_embedded[tags]	array	Данные тегов, привязанных к компании
_embedded[tags][0]	object	Модель тега, привязанного к компании
_embedded[tags][0][id]	int	ID тега
_embedded[tags][0][name]	string	Название тега
_embedded[tags][0][color]	null	Цвет тега, доступен только для сделок
_embedded[contacts]	array	Требуется GET параметр with. Данные контактов, привязанных к компании.
_embedded[contacts][0]	object	Данные контакта
_embedded[contacts][0][id]	int	ID контакта
_embedded[customers]	array	Требуется GET параметр with. Данные покупателей, привязанных к компании
_embedded[customers][0]	object	Данные покупателя
_embedded[customers][0][id]	int	ID покупателя
_embedded[leads]	array	Требуется GET параметр with. Данные сделок, привязанных к компании
_embedded[leads][0]	object	Данные сделки
_embedded[leads][0][id]	int	ID сделки
_embedded[catalog_elements]	array	Требуется GET параметр with. Данные элементов списков, привязанных к компании
_embedded[catalog_elements][0]	object	Данные элемента списка, привязанного к компании
_embedded[catalog_elements][0][id]	int	ID элемента, привязанного к компании
_embedded[catalog_elements][0][metadata]	object	Мета-данные элемента
_embedded[catalog_elements][0][quantity]	int float	Количество элементов у компании
_embedded[catalog_elements][0][catalog_id]	int	ID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id]	int	ID поля типа Цена, которое установлено для привязанного элемента в сущности

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

{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/companies?limit=2&page=1"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/companies?limit=2&page=2"
        }
    },
    "_embedded": {
        "companies": [
            {
                "id": 7767077,
                "name": "Компания Васи",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1586359618,
                "updated_at": 1586359618,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/7767077"
                    }
                },
                "_embedded": {
                    "tags": []
                }
            },
            {
                "id": 7767457,
                "name": "Example",
                "responsible_user_id": 504141,
                "group_id": 0,
                "created_by": 504141,
                "updated_by": 504141,
                "created_at": 1586360394,
                "updated_at": 1586360394,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 28805383,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/7767457"
                    }
                },
                "_embedded": {
                    "tags": []
                }
            }
        ]
    }
}

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

Параметр	Описание
catalog_elements	Добавляет в ответ связанные с компанией элементы списков
leads	Добавляет в ответ связанные с компанией сделки
customers	Добавляет в ответ связанных с компанией покупателей
contacts	Добавляет в ответ связанные с компанией контакты

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

Метод

GET /api/v4/companies/{id}

Описание

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

Ограничения

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

GET параметры

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

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID компании
name	string	Название компании
responsible_user_id	int	ID пользователя, ответственного за компанию
group_id	int	ID группы, в которой состоит ответственны пользователь за компанию
created_by	int	ID пользователя, создавший компанию
updated_by	int	ID пользователя, изменивший компанию
created_at	int	Дата создания компании, передается в Unix Timestamp
updated_at	int	Дата изменения компании, передается в Unix Timestamp
closest_task_at	int	Дата ближайшей задачи к выполнению, передается в Unix Timestamp
is_deleted	bool	Удален ли элемент
custom_fields_values	array null	Массив, содержащий информацию по значениям дополнительных полей, заданных для данной компании
account_id	int	ID аккаунта, в котором находится компания
_embedded	object	Данные вложенных сущностей
_embedded[tags]	array	Данные тегов, привязанных к компании
_embedded[tags][0]	object	Модель тега, привязанного к компании
_embedded[tags][0][id]	int	ID тега
_embedded[tags][0][name]	string	Название тега
_embedded[tags][0][color]	null	Цвет тега, доступен только для сделок
_embedded[contacts]	array	Требуется GET параметр with. Данные контактов, привязанных к компании.
_embedded[contacts][0]	object	Данные контакта
_embedded[contacts][0][id]	int	ID контакта
_embedded[customers]	array	Требуется GET параметр with. Данные покупателей, привязанных к компании
_embedded[customers][0]	object	Данные покупателя
_embedded[customers][0][id]	int	ID покупателя
_embedded[leads]	array	Требуется GET параметр with. Данные сделок, привязанных к компании
_embedded[leads][0]	object	Данные сделки
_embedded[leads][0][id]	int	ID сделки
_embedded[catalog_elements]	array	Требуется GET параметр with. Данные элементов списков, привязанных к компании
_embedded[catalog_elements][0]	object	Данные элемента списка, привязанного к компании
_embedded[catalog_elements][0][id]	int	ID элемента, привязанного к компании
_embedded[catalog_elements][0][metadata]	object	Мета-данные элемента
_embedded[catalog_elements][0][quantity]	int float	Количество элементов у компании
_embedded[catalog_elements][0][catalog_id]	int	ID списка, в котором находится элемент
_embedded[catalog_elements][0][price_id]	int	ID поля типа Цена, которое установлено для привязанного элемента в сущности

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

{
    "id": 1,
    "name": "АО Рога и копыта",
    "responsible_user_id": 504141,
    "group_id": 0,
    "created_by": 504141,
    "updated_by": 504141,
    "created_at": 1582117331,
    "updated_at": 1586361223,
    "closest_task_at": null,
    "custom_fields_values": [
        {
            "field_id": 3,
            "field_name": "Телефон",
            "field_code": "PHONE",
            "field_type": "multitext",
            "values": [
                {
                    "value": "123213",
                    "enum_id": 1,
                    "enum": "WORK"
                }
            ]
        }
    ],
    "account_id": 28805383,
    "_links": {
        "self": {
            "href": "https://exmaple.amocrm.ru/api/v4/companies/1"
        }
    },
    "_embedded": {
        "tags": []
    }
}

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

Параметр	Описание
catalog_elements	Добавляет в ответ связанные с компанией элементы списков
leads	Добавляет в ответ связанные с компанией сделки
customers	Добавляет в ответ связанных с компанией покупателей
contacts	Добавляет в ответ связанные с компанией контакты

Добавление компаний

Метод

POST /api/v4/companies

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательных полей для добавления нет

Параметр	Тип данных	Описание
name	string	Название компании
responsible_user_id	int	ID пользователя, ответственного за компанию
created_by	int	ID пользователя, создавшего компанию
updated_by	int	ID пользователя, изменившего компанию
created_at	int	Дата создания компании, передается в Unix Timestamp
updated_at	int	Дата изменения компании, передается в Unix Timestamp
custom_fields_values	array	Массив, содержащий информацию по значениям дополнительных полей, заданных для данной компании. Примеры заполнения полей
tags_to_add	array	Массив тегов для добавления.
tags_to_add[0]	object	Модель тега для добавления.
tags_to_add[0][id]	array	ID тега для добавления. Важно передать или id или name.
tags_to_add[0][name]	array	Название тега для добавления. Важно передать или id или name.
_embedded	object	Данные вложенных сущностей
_embedded[tags]	array	Данные тегов, привязанных к компании
_embedded[tags][0]	object	Модель тега, привязанного к компании
_embedded[tags][0][id]	int	ID тега
_embedded[tags][0][name]	string	Название тега
request_id	string	Поле, которое вернется вам в ответе без изменений и не будет сохранено. Поле не является обязательным

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

[
    {
        "name": "АО Рога и Копыта",
        "custom_fields_values": [
            {
                "field_code": "PHONE",
                "values": [
                    {
                        "value": "+7912322222",
                        "enum_code": "WORK"
                    }
                ]
            }
        ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID компании
request_id	string	Строка переданная при запросе или порядковый указатель, если параметр не передан

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/companies"
        }
    },
    "_embedded": {
        "companies": [
            {
                "id": 11090825,
                "request_id": "0",
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/11090825"
                    }
                }
            }
        ]
    }
}

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

Метод

PATCH /api/v4/companies

Описание

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

Ограничения

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

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

Content-Type: application/json

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

Обязательных полей для добавления нет

Параметр	Тип данных	Описание
name	string	Название компании
responsible_user_id	int	ID пользователя, ответственного за контакт
created_by	int	ID пользователя, создавший контакт
updated_by	int	ID пользователя, изменивший контакт
created_at	int	Дата создания контакта, передается в Unix Timestamp
updated_at	int	Дата изменения контакта, передается в Unix Timestamp
custom_fields_values	array	Массив, содержащий информацию по значениям дополнительных полей, заданных для данной компании. Примеры заполнения полей
tags_to_add	array	Массив тегов для добавления.
tags_to_add[0]	object	Модель тега для добавления.
tags_to_add[0][id]	array	ID тега для добавления. Важно передать или id или name.
tags_to_add[0][name]	array	Название тега для добавления. Важно передать или id или name.
tags_to_delete	array	Массив тегов для удаления.
tags_to_delete[0]	object	Модель тега для удаления.
tags_to_delete[0][id]	array	ID тега для удаления. Важно передать или id или name.
tags_to_delete[0][name]	array	Название тега для удаления. Важно передать или id или name.
_embedded	object	Данные вложенных сущностей
_embedded[tags]	array	Данные тегов, привязанных к компании
_embedded[tags][0]	object	Модель тега, привязанного к компании
_embedded[tags][0][id]	int	ID тега
_embedded[tags][0][name]	string	Название тега

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

[
    {
        "id": 11090825,
        "name": "Новое название компании",
        "custom_fields_values": [
            {
                "field_code": "EMAIL",
                "values": [
                    {
                        "value": "test@example.com",
                        "enum_code": "WORK"
                    }
                ]
            }
       ]
    }
]

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

Content-Type: application/hal+json

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

Content-Type: application/problem+json

HTTP коды ответа

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

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

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

Параметр	Тип данных	Описание
id	int	ID сделки
updated_at	int	Unix Timestamp изменения сделки

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

{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/companies"
        }
    },
    "_embedded": {
        "companies": [
            {
                "id": 11090825,
                "name": "Новое название компании",
                "updated_at": 1590998669,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/11090825"
                    }
                }
            }
        ]
    }
}

Оглавление

Список компаний

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

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

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Добавление компаний

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

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

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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