Диспетчерские заявки из внешней системы

В документации мы постарались ответить на частые вопросы по работе TesLab, с которыми сталкиваются пользователи.
Если Вы не нашли ответ на свой вопрос, напишите нам.

Личный кабинет

Диспетчерские заявки из внешней системы

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

В этой статье

Порядок обмена

  1. Сопоставьте объект внешней системы с ID лифта в TesLab.
  2. Подготовьте содержание, код источника и при необходимости тип неисправности.
  3. Создайте собственный идентификатор операции и сохраните его вместе с телом запроса и ключом повтора.
  4. Отправьте один запрос и разберите ответ, включая was, если он есть.
  5. Прочитайте заявку по возвращённому id, сверьте данные и сохраните подтверждённую связь.

Создание запускает обработку заявки и штатные уведомления. Проверяйте обмен в согласованной тестовой среде с учебными объектами. Для проверки соединения и сессии используйте auth/check, а не создание обращения на рабочем лифте.

Создание диспетчерской заявки. Учебный маршрут: выполнение может запускать штатные уведомления.
Сначала сопоставление лифта, затем создание и проверка возвращённого id; was выделяет существующую заявку.

Что подготовить

  • Адрес 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 и не является сквозным уникальным номером за всё время.

Номер 31 и внутренний ID 900701 в шапке учебной заявки
1: отображаемый номер. 2: внутренний 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}
}
  1. Сравните elevator.id с отправленным lift.
  2. Проверьте request.id, номер, содержание, тип, время и внешний номер.
  3. Сверьте источник и контакты в блоке filed. Название этого блока нужно использовать именно так.
  4. Проверьте состояние лифта и назначение исполнителя. Доступ к чтению может ограничиваться участком сотрудника.
  5. Сохраните соответствие внешнего обращения и request.id, а также подтверждённый итог операции.
Содержание, тип неисправности и внешний номер в учебной карточке
1: содержание обращения. 2: тип неисправности. 3: номер внешней диспетчерской. Эти значения нужно сверить после создания или ответа с was=true.
Состояние лифта и учебные контакты заявителя
1: состояние лифта. 2: источник, имя и телефон заявителя.

Основная заявка, непринятое обращение us/* и сообщение о выполнении или закрытии mc/* являются разными записями. Их методы и ID не взаимозаменяемы. Работа диспетчера описана в статье «Новая заявка: от сообщения заявителя до регистрации».

Повтор после сбоя

Для метода с поддержкой Idempotency-Key используйте один ключ для одной операции. Допускаются от 8 до 64 латинских букв, цифр, символов _ и -. Удобно создавать случайный UUID и сохранять его до отправки.

  • Повтор выполняется тем же сотрудником, в тот же метод, с тем же ключом и неизменённым телом.
  • Ключ завершённой операции возвращает сохранённый ответ в течение 24 часов. Это не бессрочная связь с внешним обращением.
  • Неопределённый исход не разрешает новое создание. При idempotencyPending дождитесь проверки результата; такой незавершённый ключ автоматически не освобождается.
  • Без ключа эта защита не работает. Поле ids_num её не заменяет.
  1. Если получили внутренний ID, сначала прочитайте именно эту заявку.
  2. Если ответ потерян целиком, сохраните время отправки, свой ID операции и прежний ключ. Проверьте журнал и существующие заявки по согласованным признакам.
  3. При подтверждённой поддержке защиты повторите прежнюю операцию с тем же ключом и телом. Не запускайте параллельно новую отправку.
  4. Если получен подтверждённый отказ, исправьте причину. Для исправленного тела используйте новую операцию и новый ключ.
  5. Если прошло больше срока хранения ответа или исход остаётся неясным, сначала выполните сверку с ответственным сотрудником.

В журнале интеграции храните собственный ID операции, время, метод, ключ повтора, возвращённые id, num и итог проверки. Не записывайте пароль или заголовок auth.

Связанные материалы