# Уведомления

Уведомления сотрудникам Битрикс24: отправка личных и системных уведомлений, чтение ленты со счётчиком непрочитанных, отметка о прочтении и удаление по идентификатору или метке. Уведомления приходят в раздел «Уведомления» портала.

**Скоуп:** `im` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

[Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)

## Быстрый старт

Отправьте уведомление сотруднику по его `userId`:

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/notifications" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1, "message": "Сделка №1024 перешла в стадию «Оплачено»" }'
```

Ответ (HTTP 201):

```json
{
  "success": true,
  "data": {
    "notificationId": 37421
  }
}
```

## Полный пример

Отправить уведомление, отметить его прочитанным и удалить:

```javascript
const BASE = 'https://vibecode.bitrix24.tech/v1'
const headers = {
  'X-Api-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json',
}

// 1. Отправить
const sendRes = await fetch(`${BASE}/notifications`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ userId: 1, message: 'Сделка №1024 перешла в стадию «Оплачено»' }),
})
const { data } = await sendRes.json()
const id = data.notificationId

// 2. Отметить прочитанным
await fetch(`${BASE}/notifications/read`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ id, onlyCurrent: true }),
})

// 3. Удалить
const delRes = await fetch(`${BASE}/notifications/${id}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
console.log('Удалено:', delRes.status === 204)
```

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| POST | [/v1/notifications](/docs/notifications/send) | im.notify.personal.add | Отправить уведомление сотруднику |
| GET | [/v1/notifications](/docs/notifications/list) | im.notify.get | Прочитать ленту уведомлений и счётчик непрочитанных |
| GET | [/v1/notifications/schema](/docs/notifications/schema) | im.notify.schema.get | Прочитать словарь типов уведомлений |
| POST | [/v1/notifications/read](/docs/notifications/read) | im.notify.read | Отметить уведомления прочитанными |
| DELETE | [/v1/notifications/:id](/docs/notifications/delete) | im.notify.delete | Удалить уведомление по идентификатору |
| DELETE | [/v1/notifications/by-tag/:tag](/docs/notifications/delete-by-tag) | im.notify.delete | Удалить уведомления по метке (только OAuth-приложение) |

Интерактивный переключатель методов с примерами и полями ответа — [Эндпоинты](/docs/notifications/endpoints).

## Коды ошибок

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `MISSING_PARAMS` | При отправке не передан `userId` или `message` |
| 400 | `INVALID_LIMIT` | При чтении ленты `limit` не целое число |
| 400 | `VALIDATION_ERROR` | При чтении ленты некорректны курсор `lastId` и `lastType` или значение `convertText` |
| 422 | `NOTIFICATION_NOT_DELIVERED` | Получателя нет на портале или он деактивирован |
| 403 | `BITRIX_ACCESS_DENIED` | Удаление по метке вызвано личным ключом вместо ключа OAuth-приложения |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `im` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме «только чтение» |
| 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов |
| 429 | `RATE_LIMITED` | Превышен темп чтения ленты — до 600 запросов в минуту на портал |
| 502 | `BITRIX_UNAVAILABLE` | Ответ Битрикс24 не удалось прочитать |

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

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

- [Отправить уведомление](/docs/notifications/send)
- [Сотрудники](/docs/entities/users)
- [Чаты](/docs/chats)
- [Ошибки](/docs/errors)