API для роботов-уборщиков: от задачи бизнеса до проверки интеграции

API помогает связать систему управления роботами с другими программами: передать результат уборки в отчёт, создать задание из системы эксплуатации или получить статус машины. Но наличие API ещё не означает, что через него доступны все функции приложения. Начинать интеграцию стоит с конкретного действия, которое сегодня выполняет сотрудник, и понятного результата, который должен появиться после автоматизации.

Разберём задачу на простом примере

Предположим, управляющая компания хочет получать в своей учётной системе результат вечерней уборки. Сейчас администратор открывает кабинет робота, находит задание и переносит данные вручную. Для первого этапа достаточно чтения сведений: объект, зона, время начала и завершения, обработанная площадь, итоговый статус. Запускать робота через внешнюю систему пока не требуется.

Такой узкий сценарий проще проверить. После одной смены сотрудник сравнивает запись в учётной системе с исходным заданием. Важно заранее договориться, что считать завершением. Робот мог закончить часть маршрута, прервать работу или выполнить всё задание. Одного поля «успешно» для этих случаев может оказаться мало.

Выясните, с какой системой предстоит обмен

Под словами «API для роботов-уборщиков» могут скрываться разные подключения. Одно API относится к конкретной машине, другое к облаку производителя, третье к FMS, объединяющей парк. Эти варианты различаются набором команд, идентификаторами и доступными данными. Уточните, где находится нужная информация и кто предоставляет документацию.

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

Составьте описание обмена до разработки

Для HTTP API удобно запросить спецификацию OpenAPI, если поставщик её предоставляет. Этот формат описывает операции, параметры, ответы и требования к доступу. Вместе со спецификацией нужны примеры сообщений и объяснение смысла полей. Наличие файла с перечнем методов ещё не отвечает на вопросы о неполной уборке, задержке данных или смене карты.

В описании вашего сценария зафиксируйте:

1. Какая программа отправляет запрос и какая отвечает.
2. Как определяются объект, робот, зона и задание.
3. Какие поля обязательны и в каких единицах указаны величины.
4. В каком часовом поясе передаётся время.
5. Как обозначаются ожидание, выполнение, прерывание и завершение.
6. Как передаются ошибки и как долго доступна история.
7. Какие ограничения действуют на частоту запросов и объём ответа.

Отдельно согласуйте изменения формата. Если поставщик добавит новый статус или переименует поле, принимающая система должна либо обработать изменение, либо сообщить о нём ответственному. Неизвестный статус нельзя автоматически превращать в успешное завершение уборки.

Получение данных и выдача команд требуют разных проверок

Статусы и отчёты

Данные можно запрашивать периодически или получать по событию, если API поддерживает такой способ. Для первого варианта согласуйте интервал опроса и ограничения нагрузки. Для второго нужны правила повторной доставки и сверки пропущенных событий. В обоих случаях сохраняйте идентификатор задания, чтобы одна миссия не появилась в итоговом отчёте дважды.

Продумайте исправление результатов. Например, отчёт о смене уже отправлен, а позднее пришло уточнение площади. Должна ли запись обновиться, получить новую версию или остаться неизменной? Ответ зависит от учёта заказчика. Его лучше записать до того, как данные начнут использовать для взаиморасчётов.

Запуск задания

Если требуется выдавать команды, сначала подтвердите доступность нужной операции. Успешный ответ на запрос может означать только приём задания сервером. Фактическое начало и окончание работы нужно проверять по предусмотренным статусам. Причина задержки должна оставаться видимой: робот занят, задание отклонено или требуется помощь оператора.

Особое внимание уделите повторным запросам. После потери ответа клиент не всегда знает, была ли команда выполнена. RFC 9110 предостерегает от автоматического повтора операций, для которых не подтверждена безопасность повторения. Для запуска уборки согласуйте способ исключения дублей: например, уникальный идентификатор команды и проверку её состояния, если API это поддерживает. Не отправляйте повторный запуск вслепую.

Ограничьте доступ конкретной задачей

Интеграции, которая только собирает отчёты, не нужны права на запуск робота или изменение карты. Выделите ей отдельную учётную запись, согласуйте срок действия и замену ключей. Секреты доступа не следует помещать в общие инструкции и журналы, доступные всем сотрудникам.

Проверяйте права не только на метод, но и на объект. Учётная запись одного бизнес-центра не должна получать сведения о другом при простой подстановке его идентификатора. OWASP выделяет такие ошибки объектного доступа в отдельный риск API. Для многоплощадочного проекта проверка этого ограничения должна входить в приёмку.

Как понять, что интеграция готова

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

Затем назначьте владельца обмена: кто замечает отсутствие данных, кому передаёт ошибку и как восстанавливается пропущенный период. Это позволяет использовать интеграцию в ежедневной работе, а не только показать успешный запрос на демонстрации.

В ROBO FMS состав методов API и передаваемых данных согласуется в интеграционном проекте. Публичная спецификация пока не опубликована. Для обсуждения подготовьте один рабочий сценарий, список полей и критерии проверки. По ним команда сможет подтвердить доступные операции и определить, какая доработка потребуется.