## Формат запроса {#query}
Перед выполнением запроса [получите доступ к API](https://yandex.ru/support/tracker/ru/api-ref/access.md).
Чтобы добавить комментарий к сущности, используйте HTTP-запрос с методом `POST`. В теле запроса укажите параметры в формате JSON.
```json translate=no
POST /v3/entities/<тип_сущности>//comments
Host: api.tracker.yandex.net
Authorization: OAuth
Content-Type: application/json
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
"text": "<текст_комментария>",
"summonees": ["<логины_или_идентификаторы_призванных>"]
}
```
{% cut "Заголовки" %}
* `Host`: адрес узла, предоставляющего API.
*
`Authorization`: токен для авторизации в одном из форматов:
- `OAuth ` при авторизации по протоколу OAuth 2.0. [Читать подробнее](https://yandex.ru/support/tracker/ru/api-ref/access.md#about_OAuth)
- `Bearer ` при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Identity Hub. [Читать подробнее](https://yandex.ru/support/tracker/ru/api-ref/access.md#iam-token)
*
`Content-Type`: формат тела запроса. Должен иметь значение `application/json`.
*
`X-Org-ID` или `X-Cloud-Org-ID`: идентификатор организации.
- если к Трекеру привязана организация Яндекс 360 для бизнеса, используйте заголовок `X-Org-ID`,
- если к Трекеру привязана организация Yandex Identity Hub, используйте заголовок `X-Cloud-Org-ID`.
Чтобы узнать идентификатор организации, перейдите на страницу **Администрирование** → [**Организации**](https://tracker.yandex.ru/admin/orgs) и скопируйте значение поля **идентификатор**.
{% endcut %}
{% cut "Ресурс" %}
Параметр | Описание | Тип данных
-------- | -------- | ----------
\<тип_сущности> | Тип сущности:
project — проект;
portfolio — портфель;
goal — цель
| Строка
\ | Идентификатор сущности. Чтобы получить идентификатор, посмотрите [список сущностей](../search-entities.md). В качестве идентификатора можно использовать параметр `id` или `shortId`.| Строка
{% endcut %}
{% cut "Параметры запроса" %}
**Дополнительные параметры**
Параметр | Описание | Тип данных
-------- | -------- | ----------
isAddToFollowers | Добавить автора комментария в наблюдатели. Значение по умолчанию — `true`. | Логический
notify | Уведомлять пользователей, которые указаны в полях **Автор**, **Ответственный**, **Участники**, **Заказчики** и **Наблюдатели**. Значение по умолчанию — `true`. | Логический
notifyAuthor | Уведомлять автора изменений. Значение по умолчанию — `false`. | Логический
expand | Дополнительная информация, которая будет включена в ответ:
`all` — все;
`html` — HTML-разметка комментария;
`attachments` — вложенные файлы;
`reactions` — реакции на комментарий.
| Строка
{% endcut %}
{% cut "Параметры тела запроса" %}
Тело запроса содержит информацию, необходимую для добавления комментария:
**Обязательные параметры**
Параметр | Описание | Тип данных
----- | ----- | -----
text | Текст комментария. | Строка
**Дополнительные параметры**
Параметр | Описание | Тип данных
----- | ----- | -----
attachmentIds | Идентификаторы [временных файлов](../../issues/temp-attachment.md), которые будут добавлены как вложения. | Массив строк
summonees | Идентификаторы или логины призванных пользователей. | Массив объектов или строк
maillistSummonees | Список рассылок, призванных в комментарии. | Массив строк
{% endcut %}
> Пример: Добавить комментарий
>
> - Используется HTTP-метод POST.
> - В сущность (проект) добавляется комментарий: «Текст комментария».
> - Призывается пользователь.
>
> ```json translate=no
> POST /v3/entities/project//comments
> Host: api.tracker.yandex.net
> Authorization: OAuth y0__xAbc******
> Content-Type: application/json
> X-Org-ID: 1234******
>
> {
> "text":"<текст_комментария>",
> "summonees": [<идентификатор_пользователя>]
> }
> ```
## Формат ответа {#answer}
{% list tabs %}
- Запрос выполнен успешно
В случае успешного выполнения запроса API возвращает ответ с кодом `201 Created`.
Тело ответа содержит информацию о комментарии в формате JSON.
```json translate=no
{
"self": "https://api.tracker.yandex.net/v3/entities/project/6586d6fee2b9ef74********/comments/22",
"id": 22,
"longId": "65a1ba7b46b9746d********",
"text": "Текст комментария.",
"createdBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
},
"updatedBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp53********",
"passportUid": 11********
},
"createdAt": "2024-01-12T22:17:31.176+0000",
"updatedAt": "2024-01-12T22:17:31.176+0000",
"summonees": [
{
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajeppa7dgp32********",
"passportUid": 11********
}
],
"version": 1,
"type": "standard",
"transport": "internal"
}
```
{% cut "Параметры ответа" %}
Параметр | Описание | Тип данных
----- | ----- | -----
self | Ссылка на объект комментария. | Строка
id | Идентификатор комментария. | Число
longId | Идентификатор комментария в виде строки. | Строка
text | Текст комментария. | Строка
textHtml | HTML-разметка комментария. | Строка
attachments | Вложения. | Строка
[createdBy](#created-by) | Объект с информацией о создателе комментария. | Объект
[updatedBy](#updated-by) | Объект с информацией о сотруднике, внесшем последнее изменение в комментарий. | Объект
createdAt | Дата и время создания комментария в формате: ``` YYYY-MM-DDThh:mm:ss.sss±hhmm ```. | Строка
updatedAt | Дата и время обновления комментария в формате: ``` YYYY-MM-DDThh:mm:ss.sss±hhmm ```. | Строка
summonees | Список вызываемых в комментарии пользователей. | Список объектов
maillistSummonees | Список рассылок, призванных в комментарии. | Список объектов
version | Версия комментария. Каждое изменение комментария увеличивает номер версии. | Число
type | Тип комментария:
`standart` — отправлен через интерфейс Трекера;
`incoming` — создан из входящего письма;
`outcoming` — создан из исходящего письма.
| Строка
transport | Способ добавления комментария:
`internal` — через интерфейс Трекера;
`email` — через письмо.
| Строка
**Поля объекта** `createdBy` {#created-by}
Параметр | Описание | Тип данных
----- | ----- | -----
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка
id | Идентификатор пользователя. | Строка
display | Отображаемое имя пользователя. | Строка
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число
cloudUid | Уникальный идентификатор пользователя в Yandex Identity Hub. | Строка
**Поля объекта** `updatedBy` {#updated-by}
Параметр | Описание | Тип данных
----- | ----- | -----
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка
id | Идентификатор пользователя. | Строка
display | Отображаемое имя пользователя. | Строка
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число
cloudUid | Уникальный идентификатор пользователя в Yandex Identity Hub. | Строка
{% endcut %}
- Запрос выполнен с ошибкой
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
400
: Один или несколько параметров запроса имеют недопустимое значение.
404
: Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
422
: Ошибка валидации JSON, запрос отклонен.
{% endlist %}