Диспетчерские заявки из внешней системы
Внешняя система может зарегистрировать диспетчерскую заявку через maintenance/requests/add. Для этого нужен внутренний ID лифта, описание неисправности и источник обращения. После отправки сохраните результат в своей системе и прочитайте созданную заявку, чтобы проверить объект, содержание и контакты.
В этой статье
Порядок обмена
- Сопоставьте объект внешней системы с ID лифта в TesLab.
- Подготовьте содержание, код источника и при необходимости тип неисправности.
- Создайте собственный идентификатор операции и сохраните его вместе с телом запроса и ключом повтора.
- Отправьте один запрос и разберите ответ, включая
was, если он есть. - Прочитайте заявку по возвращённому
id, сверьте данные и сохраните подтверждённую связь.
Создание запускает обработку заявки и штатные уведомления. Проверяйте обмен в согласованной тестовой среде с учебными объектами. Для проверки соединения и сессии используйте auth/check, а не создание обращения на рабочем лифте.

Что подготовить
- Адрес API своей организации и действующую сессию сотрудника интеграции.
- Право
maintenance/requests/add. Для последующей сверки нужно отдельное правоmaintenance/requests/infoс доступом к нужному объекту. - Сопоставление внешнего объекта с существующим
lift. Строка адреса или номер подъезда не заменяет ID лифта. - Договор на обслуживание, действующий на дату получения заявки. Приём без договора возможен, только если это разрешено настройками организации.
Согласуйте источник, тип неисправности, часовой пояс и действия при неопределённом результате. До включения рабочего обмена проверьте обработку этих условий на своей инсталляции, включая поддержку ключа повтора и возвращаемые поля.
Поля запроса и коды
| Поле | Что передать |
|---|---|
lift | Положительный целочисленный ID лифта. Обязателен. Адрес, подъезд и исходный механик определяются по карточке лифта. |
complaint | Строка с содержанием обращения, не менее трёх символов после удаления пробелов по краям. Обязательна. |
rtype | Целочисленный код источника из таблицы ниже. Ноль допускается только при разрешении приёма без источника. |
begindat | Дата и время получения. Необязательное поле: без значения используется текущее время сервера. Пример местного времени: 2026-11-14 10:30:00. Для однозначной передачи момента можно использовать ISO 8601 с Z или смещением, например 2026-11-14T10:30:00+03:00. Время со смещением переводится в часовой пояс сервера. Допустимое опережение текущего времени составляет не более 200 секунд. |
typecomplaint | Целочисленный код типа неисправности. Без значения или при нуле сервер пытается определить тип по тексту. Это подсказка по ключевым словам: для известного типа лучше передать точный код и проверить результат. |
rrname | Необязательная строка с именем заявителя. |
rphone | Необязательная строка с телефоном. Сервер удаляет оформление номера и нормализует его. Если телефона нет, передайте пустую строку или пропустите поле. |
ids_num | Необязательная строка с номером или номерами внешней диспетчерской. Это сведения для сопоставления, а не уникальный ключ и не защита от повторного создания. |
Не передавайте num: отображаемый номер назначает сервер в пределах месяца даты поступления. Для постоянной связи используйте id. Параметр edit не предназначен для создания; изменение существующей заявки выполняется отдельным методом с правом редактирования.
Источник обращения:
rtype | Источник |
|---|---|
| 1 | ОДС |
| 2 | Заказчик |
| 3 | Сотрудник |
| 9 | Житель |
| 0 | Не указан, если это разрешено настройками |
Тип неисправности:
typecomplaint | Тип |
|---|---|
| 1 | Не работает |
| 2 | Застревание |
| 3 | Кнопки в лифте |
| 4 | Кнопка вызова на этаже |
| 5 | Не останавливается на этаже |
| 6 | Двери |
| 7 | Шум, скрежет, вибрация, трясется |
| 9 | Освещение в лифте |
| 10 | Связь с диспетчером |
| 11 | Упавший предмет |
| 12 | Экран, табло, индикация этажей |
| 13 | Интерьер лифта |
| 80 | Другое |
| 90 | Лифт поставлен на замену |
При создании типы 1, 2 и 90 означают, что лифт не в работе. Остальные типы сами по себе не останавливают лифт. Назначенный механик может измениться с учётом аварийного дежурства вне рабочего времени.
Пример создания
В примере житель сообщает об освещении. ID лифта и другие значения учебные. Замените их данными своей тестовой среды, а ключ создайте заново для своей операции.
POST /api/maintenance/requests/add
auth: YOUR_AUTH_TOKEN
Content-Type: application/json
Out: json
Idempotency-Key: 0e22c391-66a1-4f02-bcc2-4cda12440401
{
"lift": 900601,
"complaint": "Не работает освещение кабины",
"rtype": 9,
"typecomplaint": 9,
"rrname": "Учебный заявитель",
"rphone": "70000000000",
"ids_num": "EXT-031"
}
Время здесь не задано, поэтому сервер использует момент приёма запроса. Если сообщение поступило раньше, передайте фактическое begindat: по нему проверяется обслуживание объекта.
Новая или найденная заявка
Успешная регистрация возвращает:
{
"ok": true,
"id": 900701,
"num": 31,
"title": "Зарегистрирована",
"mess": "Заявка №31"
}
id является внутренним ключом записи. num нужен для отображения и общения с диспетчером. Он не заменяет ID и не является сквозным уникальным номером за всё время.

Вместо создания сервер может вернуть найденную недавнюю заявку другого диспетчера:
{
"ok": true,
"id": 900701,
"num": 31,
"was": true,
"title": "Заявка №31",
"mess": "Найдена такая же недавняя заявка другого диспетчера"
}
was=true означает, что новая запись не создана. Прочитайте найденную заявку и сверьте лифт, текст, тип, источник, контакты и внешний номер. Новые значения из отправленного запроса к найденной записи автоматически не дописываются. Если данные не совпали, не связывайте обращения автоматически: передайте ситуацию ответственному за обмен.
Поиск недавнего обращения и повтор по ключу решают разные задачи. Не рассчитывайте, что was распознает любую повторную отправку вашего сотрудника или любой внешний номер.
Отказы и ограничения
| Ситуация | Что делать |
|---|---|
| 404: лифт не найден | Проверьте сопоставление ID и адрес сервера. |
| 400: аварийный простой или открытая заявка «Не работает» | Проверьте указанную существующую заявку. Ограничение действует и на новое обращение другого типа по тому же лифту. |
| 400: нет договора на дату поступления | Проверьте дату и обслуживание. Разрешение приёма без договора меняет ответственный администратор. |
| 400: содержимое, источник, тип или другое поле некорректны | Разберите сообщение и field, исправьте данные. Массивы вместо строк и произвольные коды не подходят. |
| 400: некорректная или слишком поздняя дата | Проверьте begindat, часы и часовой пояс. Не подменяйте дату, чтобы обойти проверку договора. |
| 401, 403 или завершённая сессия | Проверьте авторизацию, права и область доступа. Для уже отправленной записи сначала выясните результат. |
| 422: ключ использован с другим запросом | Не меняйте тело у незавершённой операции. Для исправленного запроса создавайте новую операцию после подтверждённого отказа прежней. |
409 с idempotencyPending, 503 или обрыв после отправки | Проверьте фактический исход по порядку ниже. Не создавайте новый ключ ради повторной отправки с неизвестным результатом. |
HTTP-код нужно оценивать вместе с пригодным JSON и полями ответа. Один HTTP 200 ещё не подтверждает регистрацию нужного обращения. Признак notificationPending в успешном ответе означает, что запись создана, а уведомления требуют отдельной проверки. Повторно создавать заявку из-за уведомления не нужно.
Проверка результата
С правом чтения отправьте:
POST /api/maintenance/requests/info
auth: YOUR_AUTH_TOKEN
Content-Type: application/json
Out: json
{"id": 900701}
Сокращённый пример ответа:
{
"request": {
"id": 900701,
"num": 31,
"complaint": "Не работает освещение кабины",
"typecomplaint": 9,
"begindat": "2026-11-14 10:30:00",
"ids_num": "EXT-031",
"isWork": true
},
"elevator": {"id": 900601},
"filed": {
"type": 9,
"name": "Учебный заявитель",
"phone": "70000000000"
},
"address": {"id": 900101, "front": 1}
}
- Сравните
elevator.idс отправленнымlift. - Проверьте
request.id, номер, содержание, тип, время и внешний номер. - Сверьте источник и контакты в блоке
filed. Название этого блока нужно использовать именно так. - Проверьте состояние лифта и назначение исполнителя. Доступ к чтению может ограничиваться участком сотрудника.
- Сохраните соответствие внешнего обращения и
request.id, а также подтверждённый итог операции.


Основная заявка, непринятое обращение us/* и сообщение о выполнении или закрытии mc/* являются разными записями. Их методы и ID не взаимозаменяемы. Работа диспетчера описана в статье «Новая заявка: от сообщения заявителя до регистрации».
Повтор после сбоя
Для метода с поддержкой Idempotency-Key используйте один ключ для одной операции. Допускаются от 8 до 64 латинских букв, цифр, символов _ и -. Удобно создавать случайный UUID и сохранять его до отправки.
- Повтор выполняется тем же сотрудником, в тот же метод, с тем же ключом и неизменённым телом.
- Ключ завершённой операции возвращает сохранённый ответ в течение 24 часов. Это не бессрочная связь с внешним обращением.
- Неопределённый исход не разрешает новое создание. При
idempotencyPendingдождитесь проверки результата; такой незавершённый ключ автоматически не освобождается. - Без ключа эта защита не работает. Поле
ids_numеё не заменяет.
- Если получили внутренний ID, сначала прочитайте именно эту заявку.
- Если ответ потерян целиком, сохраните время отправки, свой ID операции и прежний ключ. Проверьте журнал и существующие заявки по согласованным признакам.
- При подтверждённой поддержке защиты повторите прежнюю операцию с тем же ключом и телом. Не запускайте параллельно новую отправку.
- Если получен подтверждённый отказ, исправьте причину. Для исправленного тела используйте новую операцию и новый ключ.
- Если прошло больше срока хранения ответа или исход остаётся неясным, сначала выполните сверку с ответственным сотрудником.
В журнале интеграции храните собственный ID операции, время, метод, ключ повтора, возвращённые id, num и итог проверки. Не записывайте пароль или заголовок auth.
Связанные материалы
- API TesLab: адрес сервера и первый запрос.
- Ответы API и обработка ошибок.
- Повторные запросы и диагностика сбоев.