В данном разделе описываются доступные методы для работы с пользователями аккаунта и их ролями
Оглавление
- Список пользователей
- Получение пользователя по ID
- Добавление пользователей
- Активация пользователей
- Деактивация пользователей
- Список ролей пользователей
- Получение роли по ID
- Добавление ролей
- Редактирование роли
- Удаление роли
- Общие обозначения прав пользователей
- Зависимости прав пользователей
Список пользователей
Метод
GET /api/v4/users
Описание
Метод позволяет получить список состоящих в аккаунте пользователей.
Ограничения
Метод доступен только с правами администратора аккаунта.
GET параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| with | string | Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры. |
| page | int | Страница выборки |
| limit | int | Количество возвращаемых сущностей за один запрос (Максимум – 250) |
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
Параметры ответа
Метод возвращает коллекцию моделей пользователей, рассмотрим ниже свойства пользователя.
Объекты прав имеют общую структуру. В зависимости от типа сущности, имеют в себе доступные действия, как ключи, и право на действие, как значение. Например, rights[leads][view]=A.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID пользователя |
| name | string | Полное имя пользователя |
| string | E-mail пользователя | |
| lang | string | Язык пользователя. Один из вариантов: ru, en, es |
| rights | object | Права пользователя |
| rights[leads] | object | Объект прав доступа к сделкам |
| rights[contacts] | object | Объект прав доступа к контактам |
| rights[companies] | object | Объект прав доступа к компаниям |
| rights[tasks] | object | Объект прав доступа к задачам |
| rights[mail_access] | bool | Доступ к функционалу почты |
| rights[catalog_access] | bool | Доступ к функционалу списков |
| rights[is_admin] | bool | Является ли пользователь администратором |
| rights[is_free] | bool | Является ли пользователь бесплатным |
| rights[is_active] | bool | Является ли пользователь активным |
| rights[group_id] | int/null | ID группы, к которой относится пользователь |
| rights[role_id] | int/null | ID роли, которая установлена у пользователя |
| rights[status_rights] | array | Массив из объектов, которые описывают права на статусы |
| rights[status_rights][0] | object | Объект прав на статус |
| rights[status_rights][0][entity_type] | string | Тип сущности. В данный момент поддерживаются только сделки |
| rights[status_rights][0][pipeline_id] | int | ID воронки, в которой находится статус |
| rights[status_rights][0][status_id] | int | ID статуса |
| rights[status_rights][0][rights] | object | Объект прав |
Пример ответа
{
"_total_items": 2,
"_page": 1,
"_page_count": 1,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/users/?with=role%2Cgroup"
}
},
"_embedded": {
"users": [
{
"id": 123123,
"name": "Пользователь для примера 2",
"email": "example2@mail.com",
"lang": "en",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"companies": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": false,
"catalog_access": false,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 2194576,
"status_id": 30846277,
"rights": {
"view": "A",
"edit": "A",
"delete": "A"
}
},
{
"entity_type": "leads",
"pipeline_id": 2212201,
"status_id": 30965377,
"rights": {
"view": "A",
"edit": "A",
"delete": "A"
}
}
],
"is_admin": false,
"is_free": false,
"is_active": true,
"group_id": null,
"role_id": null
},
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/users/123123/"
}
},
"_embedded": {
"roles": [
{
"id": 3141,
"name": "Менеджер",
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/roles/3141"
}
}
}
],
"groups": [
{
"id": 267688,
"name": "Менеджеры"
}
]
}
},
{
"id": 321321,
"name": "Пользователь для примера 2",
"email": "example2@mail.com",
"lang": "ru",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "G",
"delete": "D",
"export": "M"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "G",
"delete": "M",
"export": "D"
},
"companies": {
"view": "A",
"edit": "G",
"add": "G",
"delete": "D",
"export": "D"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": true,
"catalog_access": true,
"status_rights": null,
"is_admin": true,
"is_free": false,
"is_active": true,
"group_id": null,
"role_id": null
},
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/users/321321"
}
},
"_embedded": {
"roles": [],
"groups": []
}
}
]
}
}
Параметры для GET-параметра with
| Параметр | Описание |
|---|---|
| role | Добавляет в ответ роль к которой принадлежит пользователь |
| group | Добавляет в ответ группу к которой принадлежит пользователь |
| uuid | Добавляет в ответ UUID пользователя, может быть null, в данный момент uuid не используется для работы сторонних интеграций |
| amojo_id | Добавляет в ответ ID пользователя в сервисе чатов, может быть null |
| user_rank | Добавляет в ответ ранг пользователя. Возможные варианты: newbie candidate master |
| phone_number | Добавляет в ответ номер пользователя |
Получение пользователя по ID
Метод
GET /api/v4/users/{id}
Описание
Метод позволяет получить данные конкретного пользователя, состоящего в аккаунте, по ID.
Ограничения
Метод доступен только с правами администратора аккаунта.
GET параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| with | string | Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры. |
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
Параметры ответа
Метод возвращает модель пользователя, рассмотрим ниже свойства пользователя.
Объекты прав имеют общую структуру. В зависимости от типа сущности, имеют в себе доступные действия, как ключи, и право на действие, как значение. Например, rights[leads][view]=A.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID пользователя |
| name | string | Полное имя пользователя |
| string | E-mail пользователя | |
| lang | string | Язык пользователя. Один из вариантов: ru, en, es |
| rights | object | Права пользователя |
| rights[leads] | object | Объект прав доступа к сделкам |
| rights[contacts] | object | Объект прав доступа к контактам |
| rights[companies] | object | Объект прав доступа к компаниям |
| rights[tasks] | object | Объект прав доступа к задачам |
| rights[mail_access] | bool | Доступ к функционалу почты |
| rights[catalog_access] | bool | Доступ к функционалу списков |
| rights[is_admin] | bool | Является ли пользователь администратором |
| rights[is_free] | bool | Является ли пользователь бесплатным |
| rights[is_active] | bool | Является ли пользователь активным |
| rights[group_id] | int/null | ID группы, к которой относится пользователь |
| rights[role_id] | int/null | ID роли, которая установлена у пользователя |
| rights[status_rights] | array | Массив из объектов, которые описывают права на статусы |
| rights[status_rights][0] | object | Объект прав на статус |
| rights[status_rights][0][entity_type] | string | Тип сущности. В данный момент поддерживаются только сделки |
| rights[status_rights][0][pipeline_id] | int | ID воронки, в которой находится статус |
| rights[status_rights][0][status_id] | int | ID статуса |
| rights[status_rights][0][rights] | object | Объект прав |
Пример ответа
{
"id": 185848,
"name": "Алексей Поимцев",
"email": "test@example.com",
"lang": "ru",
"rights": {
"leads": {
"view": "M",
"edit": "M",
"add": "D",
"delete": "M",
"export": "M"
},
"contacts": {
"view": "M",
"edit": "M",
"add": "D",
"delete": "M",
"export": "M"
},
"companies": {
"view": "M",
"edit": "M",
"add": "D",
"delete": "M",
"export": "M"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": false,
"catalog_access": true,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 3166396,
"status_id": 142,
"rights": {
"view": "D",
"edit": "D",
"delete": "D",
"export": "D"
}
},
{
"entity_type": "leads",
"pipeline_id": 3166396,
"status_id": 32311027,
"rights": {
"view": "D",
"edit": "D",
"delete": "D"
}
},
{
"entity_type": "leads",
"pipeline_id": 3104455,
"status_id": 31881115,
"rights": {
"view": "D",
"edit": "D",
"delete": "D"
}
}
],
"is_admin": false,
"is_free": false,
"is_active": true,
"group_id": null,
"role_id": null
},
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/users/185848"
}
}
}
Параметры для GET-параметра with
| Параметр | Описание |
|---|---|
| role | Добавляет в ответ роль к которой принадлежит пользователь |
| group | Добавляет в ответ группу к которой принадлежит пользователь |
| uuid | Добавляет в ответ UUID пользователя, может быть null, в данный момент uuid не используется для работы сторонних интеграций |
| amojo_id | Добавляет в ответ ID пользователя в сервисе чатов, может быть null |
| user_rank | Добавляет в ответ ранг пользователя. Возможные варианты: newbie candidate master |
| phone_number | Добавляет в ответ номер пользователя |
Добавление пользователей
Метод
POST /api/v4/users
Описание
Метод позволяет добавлять пользователей в аккаунт пакетно.
Ограничения
- Метод доступен только с правами администратора аккаунта.
- Метод позволяет добавлять не более 10 пользователей за один запрос.
- Метод становится недоступен, когда количество пользователей превышает 100. На Enterprise тарифе ограничение не распространяется.
Заголовок запроса
Content-Type: application/json
Параметры запроса
В данном методе параметры запроса имеют зависимости:
- Если передано валидное значение role_id,то значения полей rights[leads], rights[tasks], rights[contacts], rights[companies], rights[status_rights], rights[mail_access], rights[catalog_access] будут проигнорированы
- Если передано значение true в поле is_free, то значения полей rights[leads], rights[tasks], rights[contacts], rights[companies], rights[status_rights], rights[mail_access], rights[catalog_access], rights[role_id], rights[group_id] будут проигнорированы
- В случае передачи значение null в поле rights[group_id], пользователь будет добавлен в группу по-умолчанию – "Отдел продаж"
- "Администратор" и "Бесплатные пользователи" не являются ролями, для обозначения заведены отдельные флаги rights[is_free] и rights[is_admin]
- Если передать поле rights[status_rights] со значением null, пользователь получит права на статусы неразобранного без доступа к ним
- Поля rights[leads], rights[tasks], rights[contacts], rights[companies] должны учитывать зависимость прав.
| Параметр | Тип данных | Описание |
|---|---|---|
| name | string | Полное имя пользователя. Значение не должно содержать спец символов кроме .@-_, состоять из пробелов, содержать ссылок, а также не может быть более 50 символов. При создании нового пользователя, поле является обязательным |
| string | E-mail пользователя. Поле является обязательным | |
| password | string | Пароль пользователя, должно состоять минимум из 6 символов и иметь хотя бы 1 цифру, маленькую и заглавную букву. При создании нового пользователя, поле является обязательным |
| lang | string | Язык пользователя. Выбор из вариантов: en, ru, es. Поле не является обязательным, по умолчанию – язык аккаунта (ru или en) |
| rights | object | Права пользователя. Поле не является обязательным, по умолчанию все доступы запрещены |
| rights[leads] | object | Права пользователя на сделки. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[contacts] | object | Права пользователя на контакты. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[companies] | object | Права пользователя на компании. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[tasks] | object | Права пользователя на задачи. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[status_rights] | array/null | Права пользователя на статусы. Необязательное поле, по умолчанию: null |
| rights[mail_access] | bool | Доступ к функционалу почты. Необязательное поле, по умолчанию: false |
| rights[catalog_access] | bool | Доступ к функционалу списков. Необязательное поле, по умолчанию: false |
| rights[is_free] | bool | Показатель, является ли пользователь бесплатным. Необязательное поле, по умолчанию: false |
| rights[role_id] | int/null | ID роли, к которой принадлежит пользователь. Необязательное поле, по умолчанию: null |
| rights[group_id] | int/null | ID группы, к которой принадлежит пользователь. Необязательное поле, по умолчанию: null |
| request_id | string | Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр |
Пример запроса
[
{
"name": "Иван Иванов",
"email": "user_add-test@team.amocrm.com",
"password": "aBcde1@345",
"lang": "ru",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "D"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "D"
}
}
}
]
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 201 | Пользователи были успешно созданы |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод возвращает коллекцию пользователя, которые были созданы. Параметры аналогичны тем, что возвращаются при запросе списка пользователей.
Пример ответа
{
"_total_items": 1,
"_embedded": {
"users": [
{
"id": 6029791,
"name": "testUser",
"email": "user_add-test@team.amocrm.com",
"lang": "en",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "D"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "D"
},
"companies": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "D"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": false,
"catalog_access": false,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 2020444,
"status_id": 29652544,
"rights": {
"view": "D",
"edit": "D",
"delete": "D"
}
},
{
"entity_type": "leads",
"pipeline_id": 2275606,
"status_id": 31411840,
"rights": {
"view": "D",
"edit": "D",
"delete": "D"
}
}
],
"is_admin": false,
"role_id": null,
"is_free": false,
"group_id": null,
"is_active": true
},
"request_id": "1",
"_links": {
"self": {
"href": "https://test.amocrm.ru/api/v4/users/6029791"
}
}
}
]
}
}
Активация пользователей
Метод
POST /api/v4/users/activate
Описание
Метод позволяет активировать пользователей в аккаунте пакетно.
Ограничения
- Метод доступен только с правами администратора аккаунта.
- Метод позволяет активировать не более 10 пользователей за один запрос.
- Метод не позволяет активировать пользователей с правами администратора.
- Метод доступен на Enterprise тарифе
Заголовок запроса
Content-Type: application/json
Параметры запроса
Для активации пользователей необходимо передать обязательный параметр id пользователя.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID пользователя, который состоит в аккаунте |
Пример запроса
[
{
"id": 123123
},
{
"id": 321321
}
]Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 202 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод не возвращает ответ при успешном запросе
Деактивация пользователей
Метод
POST /api/v4/users/deactivate
Описание
Метод позволяет деактивировать пользователей в аккаунте пакетно.
Ограничения
- Метод доступен только с правами администратора аккаунта.
- Метод позволяет деактивировать не более 10 пользователей за один запрос.
- Метод не позволяет деактивировать пользователей с правами администратора.
- Метод доступен на Enterprise тарифе
Заголовок запроса
Content-Type: application/json
Параметры запроса
Для деактивации пользователей необходимо передать обязательный параметр id пользователя.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID пользователя, который состоит в аккаунте |
Пример запроса
[
{
"id": 123123
},
{
"id": 321321
}
]Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 204 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод не возвращает ответ при успешном запросе
Список ролей пользователей
Метод
GET /api/v4/roles
Описание
Метод позволяет получить список ролей пользователей в аккаунте.
Ограничения
Метод доступен только с правами администратора аккаунта.
GET параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| with | string | Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры. |
| page | int | Страница выборки |
| limit | int | Количество возвращаемых сущностей за один запрос (Максимум – 250) |
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
Параметры ответа
Метод возвращает коллекцию моделей ролей, рассмотрим ниже свойства роли.
Объекты прав имеют общую структуру. В зависимости от типа сущности, имеют в себе доступные действия, как ключи, и право на действие, как значение. Например, rights[leads][view]=A.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID роли |
| name | string | Название роли |
| rights | object | Права пользователя |
| rights[leads] | object | Объект прав доступа к сделкам |
| rights[contacts] | object | Объект прав доступа к контактам |
| rights[companies] | object | Объект прав доступа к компаниям |
| rights[tasks] | object | Объект прав доступа к задачам |
| rights[mail_access] | bool | Доступ к функционалу почты |
| rights[catalog_access] | bool | Доступ к функционалу списков |
| rights[is_admin] | bool | Является ли пользователь администратором |
| rights[is_free] | bool | Является ли пользователь бесплатным |
| rights[is_active] | bool | Является ли пользователь активным |
| rights[group_id] | int/null | ID группы, к которой относится пользователь |
| rights[role_id] | int/null | ID роли, которая установлена у пользователя |
| rights[status_rights] | array | Массив из объектов, которые описывают права на статусы |
| rights[status_rights][0] | object | Объект прав на статус |
| rights[status_rights][0][entity_type] | string | Тип сущности. В данный момент поддерживаются только сделки |
| rights[status_rights][0][pipeline_id] | int | ID воронки, в которой находится статус |
| rights[status_rights][0][status_id] | int | ID статуса |
| rights[status_rights][0][rights] | object | Объект прав |
| _embedded[users] | array | Массив, содержащий в себе ID пользователей, у которых установленная данная роль |
Пример ответа
{
"_total_items": 1,
"_page": 1,
"_page_count": 1,
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/roles?with=users&page=1&limit=50"
}
},
"_embedded": {
"roles": [
{
"id": 107995,
"name": "Моя супер роль",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"companies": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": false,
"catalog_access": false,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 3104455,
"status_id": 31881115,
"rights": {
"edit": "A",
"view": "A",
"delete": "A"
}
},
{
"entity_type": "leads",
"pipeline_id": 3166396,
"status_id": 32311027,
"rights": {
"edit": "A",
"view": "A",
"delete": "A"
}
}
]
},
"_links": {
"self": {
"href": "https://example.amocrm.ru/api/v4/roles/107995"
}
},
"_embedded": {
"users": []
}
}
]
}
}
Параметры для GET-параметра with
| Параметр | Описание |
|---|---|
| users | Добавляет в ответ ID пользователей, у которых установлена роль |
Получение роли по ID
Метод
GET /api/v4/roles/{id}
Описание
Метод позволяет получить данные конкретной роли аккаунта по ID.
Ограничения
Метод доступен только с правами администратора аккаунта.
GET параметры
| Параметр | Тип данных | Описание |
|---|---|---|
| with | string | Данный параметр принимает строку, в том числе из нескольких значений, указанных через запятую. Данный метод поддерживает следующие параметры. |
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 200 | Запрос выполнен успешно |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
Параметры ответа
Метод возвращает модель роли, рассмотрим ниже её свойства.
Объекты прав имеют общую структуру. В зависимости от типа сущности, имеют в себе доступные действия, как ключи, и право на действие, как значение. Например, rights[leads][view]=A.
| Параметр | Тип данных | Описание |
|---|---|---|
| id | int | ID роли |
| name | string | Название роли |
| rights | object | Права пользователя |
| rights[leads] | object | Объект прав доступа к сделкам |
| rights[contacts] | object | Объект прав доступа к контактам |
| rights[companies] | object | Объект прав доступа к компаниям |
| rights[tasks] | object | Объект прав доступа к задачам |
| rights[mail_access] | bool | Доступ к функционалу почты |
| rights[catalog_access] | bool | Доступ к функционалу списков |
| rights[is_admin] | bool | Является ли пользователь администратором |
| rights[is_free] | bool | Является ли пользователь бесплатным |
| rights[is_active] | bool | Является ли пользователь активным |
| rights[group_id] | int/null | ID группы, к которой относится пользователь |
| rights[role_id] | int/null | ID роли, которая установлена у пользователя |
| rights[status_rights] | array | Массив из объектов, которые описывают права на статусы |
| rights[status_rights][0] | object | Объект прав на статус |
| rights[status_rights][0][entity_type] | string | Тип сущности. В данный момент поддерживаются только сделки |
| rights[status_rights][0][pipeline_id] | int | ID воронки, в которой находится статус |
| rights[status_rights][0][status_id] | int | ID статуса |
| rights[status_rights][0][rights] | object | Объект прав |
| _embedded[users] | array | Массив, содержащий в себе ID пользователей, у которых установленная данная роль |
Пример ответа
{
"id": 107995,
"name": "Роль",
"rights": {
"leads": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"contacts": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"companies": {
"view": "A",
"edit": "A",
"add": "A",
"delete": "A",
"export": "A"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"mail_access": false,
"catalog_access": false,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 3104455,
"status_id": 31881115,
"rights": {
"edit": "A",
"view": "A",
"delete": "A"
}
},
{
"entity_type": "leads",
"pipeline_id": 3166396,
"status_id": 32311027,
"rights": {
"edit": "A",
"view": "A",
"delete": "A"
}
}
]
},
"_links": {
"self": {
"href": "https://shard151.amocrm.ru/api/v4/roles/107995"
}
}
}
Параметры для GET-параметра with
| Параметр | Описание |
|---|---|
| users | Добавляет в ответ ID пользователей, у которых установлена роль |
Добавление ролей
Метод
POST /api/v4/roles
Описание
Метод позволяет добавлять роли в аккаунт пакетно.
Ограничения
Метод доступен только с правами администратора аккаунта.
Заголовок запроса
Content-Type: application/json
Параметры запроса
| Параметр | Тип данных | Описание |
|---|---|---|
| name | string | Название роли |
| rights | object | Права пользователя. Поле не является обязательным, по умолчанию все доступы запрещены |
| rights[leads] | object | Права пользователя на сделки. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[contacts] | object | Права пользователя на контакты. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[companies] | object | Права пользователя на компании. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[tasks] | object | Права пользователя на задачи. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[status_rights] | array/null | Права пользователя на статусы. Необязательное поле, по умолчанию: null |
| rights[mail_access] | bool | Доступ к функционалу почты. Необязательное поле, по умолчанию: false |
| rights[catalog_access] | bool | Доступ к функционалу списков. Необязательное поле, по умолчанию: false |
| request_id | string | Поле, которое вернется вам в ответе без изменений и не будет сохранено. Необязательный параметр |
Пример запроса
{
"name": "role 3",
"rights": {
"leads": {
"add": "A",
"edit": "G",
"view": "G",
"delete": "G",
"export": "G"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"contacts": {
"add": "A",
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
},
"companies": {
"add": "A",
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
},
"mail_access": true,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 16056,
"status_id": 20542166,
"rights": {
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
}
}
],
"catalog_access": true
}
}
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 201 | Роли были успешно созданы |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод возвращает коллекцию ролей, которые были созданы. Параметры аналогичны тем, что возвращаются при запросе списка ролей.
Пример ответа
{
"_total_items": 1,
"_embedded": {
"roles": [
{
"id": 901,
"name": "role 3",
"rights": {
"leads": {
"add": "A",
"edit": "G",
"view": "G",
"delete": "G",
"export": "G"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"contacts": {
"add": "A",
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
},
"companies": {
"add": "A",
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
},
"mail_access": true,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 12730,
"status_id": 20542166,
"rights": {
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
}
},
{
"entity_type": "leads",
"pipeline_id": 16056,
"status_id": 20583101,
"rights": {
"edit": "D",
"view": "D",
"delete": "D"
}
}
],
"catalog_access": true
},
"_links": {
"self": {
"href": "https://test.amocrm.ru/api/v4/roles/901/"
}
}
}
]
}
}
Редактирование роли
Метод
PATCH /api/v4/roles/{id}
Описание
Метод позволяет редактировать роль в аккаунте.
Ограничения
Метод доступен только с правами администратора аккаунта.
Заголовок запроса
Content-Type: application/json
Параметры запроса
Обязательных полей нет, но запрос не может быть пустым.
Если параметр rights[status_rights] имеет значение null или [], то права на статусы сделок для данной роли будут удалены.
В таком случае права на статусы неразобранного останутся и на каждое действие будет выставлено значение запрещено.
| Параметр | Тип данных | Описание |
|---|---|---|
| name | string | Название роли |
| rights | object | Права пользователя. Поле не является обязательным, по умолчанию все доступы запрещены |
| rights[leads] | object | Права пользователя на сделки. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[contacts] | object | Права пользователя на контакты. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[companies] | object | Права пользователя на компании. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[tasks] | object | Права пользователя на задачи. Обязательное поле, если нет role_id и не выставлен флаг is_free |
| rights[status_rights] | array/null | Права пользователя на статусы. Необязательное поле, по умолчанию: null |
| rights[mail_access] | bool | Доступ к функционалу почты. Необязательное поле, по умолчанию: false |
| rights[catalog_access] | bool | Доступ к функционалу списков. Необязательное поле, по умолчанию: false |
Пример запроса
{
"name": "role 3 modified",
"rights": {
"contacts": {
"add": "A",
"edit": "D",
"view": "D",
"delete": "D",
"export": "D"
},
"status_rights": null
}
}
Заголовок типа данных при успешном результате
Content-Type: application/hal+json
Заголовок типа данных при ошибке
Content-Type: application/problem+json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 202 | Роль была успешно изменена |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод возвращает модель роли, которая были изменена. Параметры аналогичны тем, что возвращаются при запросе списка ролей.
Пример ответа
{
"id": 901,
"name": "role 3 modified",
"rights": {
"leads": {
"add": "A",
"edit": "G",
"view": "G",
"delete": "G",
"export": "G"
},
"tasks": {
"edit": "A",
"delete": "A"
},
"contacts": {
"add": "A",
"edit": "D",
"view": "D",
"delete": "D",
"export": "D"
},
"companies": {
"add": "A",
"edit": "A",
"view": "A",
"delete": "A",
"export": "A"
},
"mail_access": true,
"status_rights": [
{
"entity_type": "leads",
"pipeline_id": 16056,
"status_id": 20583101,
"rights": {
"edit": "D",
"view": "D",
"delete": "D"
}
}
],
"catalog_access": true
},
"_links": {
"self": {
"href": "https://test.amocrm.ru/api/v4/roles/901/"
}
}
}
Удаление роли
Метод
DELETE /api/v4/roles/{id}
Описание
Метод позволяет удалить роль в аккаунте.
Ограничения
Метод доступен только с правами администратора аккаунта.
Заголовок запроса
Content-Type: application/json
HTTP коды ответа
| Код ответа | Условие |
|---|---|
| 204 | Роль была успешно удалена |
| 403 | Не хватает прав для вызова данного метода |
| 401 | Пользователь не авторизован |
| 400 | Переданы некорректные данные. Подробности доступны в теле ответа |
Параметры ответа
Метод не возвращает тело
Общие обозначения прав пользователей
| Значение | Параметр | Описание |
|---|---|---|
| A | access | Доступен весь функционал |
| G | group | Функционал доступен, если ответственный состоит в той же группе, что и ответственный пользователь |
| M | main | Функционал доступен, если ответственным является текущий пользователь |
| D | denied | Функционал недоступен |
У пользователей доступны следующие права:
- Создание
- Просмотр
- Редактирование
- Удаление
- Экспорт
Приоритет расчета прав идет в следующем порядке (на примере сделок):
- Сначала применяются общие права
- Затем применяются права на статусы (ограничивают/расширяют права)
- Затем права на просмотр могут быть расширены, если пользователь является подписчиком в чате сделки
Особенности
- Права на создание и права на статусы могут иметь только одно из двух значений: A, D
- Статусы неразобранного не имеют прав на экспорт
- Права для покупателей наследуются от прав на сделки
Зависимости прав пользователей
Права на различные действия зависят друг от друга, например, если ограничить пользователю права на просмотр сделок, то редактирование, удаление и экспорт сделок автоматически перестанут быть доступны для него.
Таблица возможных значений прав с учетом зависимости прав друг от друга представлена ниже.
