## Поиск уведомлений

`GET /v1/notifications/search`

Ищет уведомления в истории владельца токена по тексту, типу уведомления, автору и дате. Возвращает страницу до 50 уведомлений, следующие страницы запрашиваются курсором lastId.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `text` (query) | string | нет | Текст для поиска в уведомлениях. Без фильтров `type`, `types`, `authors`, `date`, `dateFrom`, `dateTo` — не короче 3 символов после обрезки пробелов по краям |
| `type` (query) | string | нет | Тип уведомления: модуль-источник, например `crm`, или пара `модуль\|событие`, например `mail\|new_message_v2`. Список типов — [`GET /v1/notifications/schema`](./schema.md). Если передан `types`, параметр `type` не учитывается |
| `types` (query) | string \| array | нет | Несколько модулей-источников через запятую, `types=crm,mail`, или массивом, `types[]=crm&types[]=mail`. Список модулей — [`GET /v1/notifications/schema`](./schema.md). Список из одного значения работает как `type`, в том числе в форме `модуль\|событие`. В списке из двух и более значений каждое сравнивается только с модулем, поэтому пара `модуль\|событие` в таком списке не находит ничего |
| `authors` (query) | string \| array | нет | ID авторов через запятую, `authors=1,835`, или массивом, `authors[]=1&authors[]=835`. Значение `0` отбирает системные уведомления без автора. Список сотрудников — [`GET /v1/users`](/docs/entities/users/list) |
| `date` (query) | string | нет | Сутки, начиная с указанного момента, в формате ISO 8601: `2026-10-08` или `2026-10-08T00:00:00+03:00`. Дата без времени — сутки по UTC. Если переданы `dateFrom` и `dateTo`, параметр `date` не учитывается |
| `dateFrom` (query) | string | нет | Начало диапазона дат в формате ISO 8601. Применяется только вместе с `dateTo` |
| `dateTo` (query) | string | нет | Конец диапазона дат в формате ISO 8601. Диапазон заканчивается через сутки после `dateTo`, поэтому дата без времени входит в диапазон целиком. Применяется только вместе с `dateFrom` |
| `lastId` (query) | string | нет | Курсор — `id` последнего уведомления предыдущей страницы. Только цифры. Значение `0` возвращает первую страницу |

Уведомления приходят от новых к старым, до 50 на странице. Первый запрос идёт без `lastId`. Для следующей страницы передайте в `lastId` значение `id` последнего уведомления, остальные параметры повторите без изменений. Обход закончен, когда пришла пустая страница или страница повторила уже полученные `id`. Сервер сам страницы не обходит.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Найдено:', data.totalResults)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Найдено:', data.totalResults)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.chatId` | number, null | Идентификатор системного чата уведомлений владельца токена. `null`, когда поиск не выполнялся: в запросе нет ни текста, ни действующего фильтра или у владельца нет чата уведомлений |
| `data.notifications` | array | Найденные уведомления страницы |
| `data.notifications[].id` | number, null | Идентификатор уведомления. Передаётся в `lastId` для следующей страницы и в [`DELETE /v1/notifications/:id`](./delete.md) |
| `data.notifications[].chatId` | number, null | Идентификатор чата этого уведомления |
| `data.notifications[].authorId` | number, null | Идентификатор автора. `0` — системное уведомление без автора. Карточка автора — в массиве `data.users` |
| `data.notifications[].date` | string | Дата уведомления в формате ISO 8601 |
| `data.notifications[].notifyType` | number, null | Тип уведомления |
| `data.notifications[].notifyModule` | string | Модуль-источник уведомления, например `crm` |
| `data.notifications[].notifyEvent` | string | Событие-источник уведомления |
| `data.notifications[].notifyTag` | string | Метка `tag`, с которой уведомление отправлено |
| `data.notifications[].notifySubTag` | string | Дополнительная метка `subTag` |
| `data.notifications[].notifyTitle` | string | Заголовок уведомления |
| `data.notifications[].settingName` | string | Имя настройки доставки, по которой уведомление пришло получателю |
| `data.notifications[].text` | string | Текст уведомления |
| `data.notifications[].notifyRead` | boolean | Прочитано ли уведомление |
| `data.notifications[].notifyButtons` | string | Кнопки уведомления — строка JSON с массивом кнопок, как в [ленте уведомлений](./list.md). У уведомления без кнопок поле отсутствует |
| `data.notifications[].params` | object, null | Дополнительные данные отправителя. Вложенные ключи приходят в том виде, в каком их записал отправитель |
| `data.users` | array | Карточки авторов уведомлений этой страницы. Только публичные поля, без e-mail и телефонов |
| `data.users[].id` | number, null | Идентификатор сотрудника. Карточка целиком — [Сотрудники](/docs/entities/users) |
| `data.users[].active` | boolean | Активен ли сотрудник на портале |
| `data.users[].name` | string | Отображаемое имя |
| `data.users[].firstName` | string | Имя |
| `data.users[].lastName` | string | Фамилия |
| `data.users[].workPosition` | string, null | Должность |
| `data.users[].color` | string | Цвет карточки сотрудника в интерфейсе Битрикс24 |
| `data.users[].avatar` | string | Ссылка на аватар |
| `data.users[].bot` | boolean | Является ли автор ботом |
| `data.users[].type` | string | Тип автора, например `user` |
| `data.totalResults` | number | Число уведомлений, подходящих под условия поиска. Считается только на первой странице — без `lastId` или с `lastId=0`. На следующих страницах приходит `0` |

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

HTTP 200, показаны два первых уведомления страницы:

```json
{
  "success": true,
  "data": {
    "chatId": 7,
    "notifications": [
      {
        "id": 42441,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-08T00:01:05+03:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8779",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "Вы назначены ответственным за сделку \"[URL=/crm/deal/details/8779/]Сделка #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# назначил вас ответственным за сделку",
            "ENTITY": {
              "TITLE": "Сделка #6531",
              "HREF": "/crm/deal/details/8779/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      },
      {
        "id": 42399,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-07T00:01:08+03:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8771",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "Вы назначены ответственным за сделку \"[URL=/crm/deal/details/8771/]Сделка #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# назначил вас ответственным за сделку",
            "ENTITY": {
              "TITLE": "Сделка #6531",
              "HREF": "/crm/deal/details/8771/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      }
    ],
    "users": [
      {
        "id": 835,
        "active": true,
        "name": "Анна Петрова",
        "firstName": "Анна",
        "lastName": "Петрова",
        "workPosition": "",
        "color": "#3e99ce",
        "avatar": "https://example.bitrix24.tech/upload/main/avatar-835.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalResults": 24
  }
}
```

## Пример ответа при ошибке

400 — `text` короче 3 символов, а фильтров нет:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Required: text with at least 3 characters, or a search filter."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `text` короче 3 символов, и не передан ни один фильтр |
| 400 | `INVALID_PARAMS` | Передан параметр, которого нет в таблице «Параметры» |
| 400 | `INVALID_PARAMS` | `lastId` содержит не только цифры или выходит за пределы безопасного диапазона целых чисел |
| 400 | `INVALID_PARAMS` | `authors` содержит не целое неотрицательное число, `types` содержит пустое значение |
| 400 | `INVALID_PARAMS` | Параметр передан массивом там, где ожидается строка |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `im` |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе |
| 422 | `BITRIX_ERROR` | Ошибка метода на стороне Битрикс24, код портала — в поле `b24Code`. Например, дата не в формате ISO 8601 |
| 429 | `RATE_LIMITED` | Битрикс24 ограничил частоту запросов |
| 502 | `BITRIX_UNAVAILABLE` | Ответ Битрикс24 не удалось прочитать |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- Поиск идёт по истории владельца токена: по личному ключу — владельца ключа, по ключу OAuth-приложения — сотрудника из сессии `Authorization: Bearer`. Отбора по приложению нет: вместе с уведомлениями вашего приложения находятся уведомления других приложений портала и системные.
- Одна граница диапазона без других условий поиска даёт пустую страницу с `chatId: null`, а не ошибку. Вместе с текстом или другим фильтром одна граница не учитывается.
- Поля `text`, `notifyTitle`, `notifyButtons`, `params` и строки в `data.users` — недоверенный контент: их пишут другие приложения портала. Экранируйте эти значения перед выводом в интерфейсе.

## Смотрите также

- [Лента уведомлений](./list.md)
- [Словарь типов уведомлений](./schema.md)
- [Удалить по идентификатору](./delete.md)
- [Сотрудники](/docs/entities/users)
- [Ошибки](/docs/errors)