# Сотрудники, запланированные на инструктаж — выгрузка в JSON

Сервис возвращает **список сотрудников, которым назначен (запланирован) инструктаж** в модуле инструктажей. Ответ приходит в формате **JSON**, кодировка UTF-8.

Отбор строк **такой же**, как у внутреннего отчёта **«Сотрудники, запланированные на инструктаж»** (фильтры, организации и т.д.).

**Авторизация** у сервиса **своя**: при включённом токене доступ только по **секретному токену**, который задаёт администратор (раздел ниже).

```text
https://esmo-app.corp.tander.ru/services/esmo_magnit_instruction/personals_planned_instruction/
```

Метод: **GET** (параметры можно дублировать в **POST** — как принято в вашей интеграции).

---

## Настройки сайта (раздел «Выгрузка инструктажей (JSON)»)

| Настройка | Переменная (для справки) | Значение по умолчанию | Смысл |
|-----------|--------------------------|------------------------|--------|
| **Токен доступа к сервису…** | `LS_esmo_magnit_planned_instruction_access_token` | пусто | Секрет для запросов. Пусто — проверка токена **отключена**. |
| **Максимум строк в одном ответе этого сервиса** | `LS_esmo_magnit_planned_instruction_max_rows_per_response` | **10000** | Верхняя граница параметра **`limit`**: сколько записей максимум может вернуться в **`items`** за один запрос. Если в настройке указано некорректное или неположительное число, используется **10000**. |

---

## Авторизация: токен

| Ситуация | Что делать |
|----------|------------|
| Токен **не задан** | Проверка по токену отключена; запрос может проходить без заголовка (уточняйте у администратора политику доступа к URL). |
| Токен **задан** | Нужно **каждый раз** передавать верный токен (см. ниже). Иначе — отказ (**401**). |

**Как передать токен** (достаточно одного способа):

1. **Заголовок** (предпочтительно — токен не попадает в адресную строку и реже остаётся в логах):

   ```http
   Authorization: Bearer <ваш_токен>
   ```

   Допустимо указать в `Authorization` только сам токен, **без** слова `Bearer`.

2. **Параметр** в запросе: **`access_token`** (в конце URL после `?` или в теле запроса — как настроит ваша программа).

**Если токен в настройках включён, а вы его не передали или передали неверно:**

- код ответа **401**;
- в теле JSON: `{"error":"Unauthorized"}`.

**Пример запроса** (типичный случай с токеном в заголовке):

```bash
curl -sS -H 'Authorization: Bearer ВАШ_СЕКРЕТ' \
  'https://ваш-сайт/services/esmo_magnit_instruction/personals_planned_instruction/'
```

---

## Пагинация и лимит размера ответа

Параметры запроса (query string или POST):

| Параметр | Описание |
|----------|----------|
| **`limit`** | Сколько записей вернуть в **`items`**. Если не указан — **1000**. Не может превышать значение настройки **«Максимум строк в одном ответе…»** (по умолчанию **10000**). |
| **`page`** | Номер страницы, начиная с **1**. Используется вместе с `limit`, если не задан **`offset`**. |
| **`offset`** | Смещение от начала выборки (0 — с первой записи). Если задан явно, имеет приоритет над расчётом через `page`. |

Фильтры отчёта передаются так же, как в интерфейсе (например **`filter[type]`**, **`event_id`**, **`name`**, **`uid`**, списки **`org_ids`**, **`otdel_ids`** и т.д.).

---

## Ответ: формат

Тип содержимого: **`application/json`**. Корень объекта:

- **`meta`** — служебные поля (включая общее число записей и параметры страницы);
- **`items`** — массив записей; каждый элемент — один сотрудник с назначенным инструктажем.

**Пример:**

```json
{
    "meta": {
        "total": 42,
        "count": 10,
        "limit": 10,
        "offset": 0,
        "page": 1,
        "pages": 5,
        "has_next": 1,
        "max_rows_per_response": 10000
    },
    "items": [
        {
            "ФИО": "Иванов Иван Иванович",
            "UID сотрудника": "12345",
            "тип инструктажа": "Вводный инструктаж",
            "ID типа инструктажа": 2,
            "наименование инструктажа": "Вводный инструктаж по ОТ",
            "ID инструктажа": 87,
            "дата блокировки": "15.04.2026"
        }
    ]
}
```

### Поля `meta`

| Поле | Смысл |
|------|--------|
| **total** | Общее число записей по текущим фильтрам (без учёта `limit`/`offset`) |
| **count** | Число записей в **`items`** в этом ответе |
| **limit** | Фактически применённый лимит (не больше **max_rows_per_response**) |
| **offset** | Смещение выборки |
| **page** | Номер страницы |
| **pages** | Оценка числа страниц при текущем **limit** |
| **has_next** | **1**, если после этой порции есть ещё записи; иначе **0** |
| **max_rows_per_response** | Верхний предел **limit** на этом сайте (из настройки, по умолчанию 10000) |

### Поля в элементах `items`

| Поле в ответе | Смысл |
|---------------|--------|
| **ФИО** | Фамилия, имя, отчество |
| **UID сотрудника** | Уникальный код сотрудника в системе |
| **тип инструктажа** | Вид инструктажа текстом (сезонный, вводный, специальный, учебная программа и т.д.) |
| **ID типа инструктажа** | Числовой код вида; для стандартных видов обычно **1–4** |
| **наименование инструктажа** | Название мероприятия в расписании |
| **ID инструктажа** | Внутренний номер мероприятия в расписании |
| **дата блокировки** | Дата в формате **дд.мм.гггг**; пустая строка, если даты нет |

Пустой **`items`** — ничего не найдено по фильтрам.

---

## Если что-то не работает

- Пустой **`items`** — сравните с одноимённым отчётом в системе.
- **401** и `{"error":"Unauthorized"}` — задан токен, но не передан или неверен; укажите **`Authorization`** или **`access_token`**.
- Ответ не похож на JSON — смотрите код ответа и текст страницы (возможна ошибка сайта).

Об остальном — к **администратору системы**.
