Пользователи

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

Список пользователей
Получение пользователя по 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	Полное имя пользователя
email	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

Получение пользователя по 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	Полное имя пользователя
email	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

Добавление пользователей

Метод

POST /api/v4/users

Описание

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

Ограничения

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

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

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 символов. При создании нового пользователя, поле является обязательным
email	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"
          }
        }
      }
    ]
  }
}

Список ролей пользователей

Метод

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
Статусы неразобранного не имеют прав на экспорт
Права для покупателей наследуются от прав на сделки

Зависимости прав пользователей

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

Таблица возможных значений прав с учетом зависимости прав друг от друга представлена ниже.

Оглавление

Список пользователей

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Получение пользователя по ID

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Добавление пользователей

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Список ролей пользователей

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Получение роли по ID

Метод

Описание

Ограничения

GET параметры

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

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

HTTP коды ответа

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

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

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

Добавление ролей

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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

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

Редактирование роли

Метод

Описание

Ограничения

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

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

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

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

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

HTTP коды ответа

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