Услуга «Мобильные сотрудники» позволяет отслеживать перемещения разъездных сотрудников на карте, планировать и контролировать их работу с помощью задач.

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

Поддерживаемые тарифы: «Бизнес», «Премиум», «Платинум». Подробнее: https://www.mpoisk.ru/info/pricing.

Что нужно для начала работы с услугой и API:

1. Создайте тестовую компанию: https://www.mpoisk.ru/signup. 
   Если вы уже пользуетесь услугой — переходите к следующему шагу.
2. Авторизуйтесь под администратором в веб-интерфейсе: https://enter.mpoisk.ru
3. Получите токен для API (подробнее см. Выпуск токена).
   Важно: если у вас уже есть токен, то при выпуске нового старый становится недействительным.
4. Добавьте сотрудника через метод POST /v6/api/subscriberManagement/subscribers.
   Ему придёт SMS с запросом на разрешение определения местоположения или ссылкой на установку приложения. После установки приложения и подтверждения вы сможете отслеживать его местоположение.
   Если сотрудник уже добавлен, получите список через
   GET /v6/api/subscriberManagement/subscribers и найдите его ID по имени (см. ССЫЛКА).
5. Заведите задачу сотруднику через POST /v6/api/taskManagement/tasks, передав его ID (см. ССЫЛКА).
6. Получите список задач сотрудника через GET /v6/api/taskManagement/tasks (см. ССЫЛКА).
7. Продолжайте работу с другими возможностями API.
   Например, отправьте сотруднику сообщение (см. ССЫЛКА) или узнайте его местоположение (см. ССЫЛКА).

Получение токена

При работе с API используется Bearer-аутентификация по токену.

Выпуск токена

1. Нажмите на имя пользователя в правом верхнем углу.
2. Нажмите Настройки.
3. Перейдите на вкладку Интеграция по API.
4. Включите Создать токен.
   
5. Введите код подтверждения. Он придёт в SMS на номер, указанный в настройках профиля. Код действителен 5 минут.
   
   
6. Нажмите кнопку Продолжить.
7. Скопируйте токен. Обратите внимание: в целях безопасности токен не отображается повторно после закрытия этого окна. Скопируйте и сохраните его сразу — при утере придётся создать новый и повторно настроить интеграцию.
8. Нажмите кнопку Сохранить.

Перевыпуск токена

Если токен утерян, не был сохранён или вы хотите его обновить — вы можете выпустить новый.

Обратите внимание: при перевыпуске токена старый токен перестанет работать, и интеграцию по API нужно будет перенастроить.

Чтобы перевыпустить токен:

1. Нажмите на имя пользователя в правом верхнем углу.
2. Нажмите Настройки.
3. Перейдите на вкладку Интеграция по API.
4. Нажмите кнопку Сменить токен.
5. В открывшемся окне подтвердите действие и нажмите кнопку Да, сменить токен.
6. Введите код подтверждения. Он придёт в SMS на номер, указанный в настройках профиля. Код действителен 5 минут.
   
   
7. Нажмите кнопку Продолжить.
8. Скопируйте токен. Обратите внимание: в целях безопасности токен не отображается повторно после закрытия этого окна. Скопируйте и сохраните его сразу — при утере придётся создать новый и повторно настроить интеграцию.
9. Нажмите кнопку Сохранить.

Отзыв токена

Если токен больше не нужен или вы хотите прекратить интеграцию с «Мобильными сотрудниками» по API — его можно отозвать. После отзыва токена текущая интеграция по API перестаёт работать.

Чтобы удалить токен:

1. Нажмите на имя пользователя в правом верхнем углу.
2. Нажмите Настройки.
3. Перейдите на вкладку Интеграция по API.
4. Выключите Создать токен.
   

5. В открывшемся окне подтвердите действие и нажмите кнопку Да, удалить токен.
   
   
6. Введите код подтверждения. Он придёт в SMS на номер, указанный в настройках профиля. Код действителен 5 минут.
   
   
7. Нажмите кнопку Продолжить. Токен будет отозван.

Аутентификация

Чтобы пройти аутентификацию, в запросах нужно указывать токен в заголовке, используя формат Bearer:

GET /v6/api/resource HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Пример запроса

GET /v6/api/subscriberManagement/subscribers HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer eyJhbGciOeJFQ0RILUVTK0EyNTZLVyIsImVuYyI6IkEyNTZDQkMtSFM1MTIiLCJ4NXQiOiJRdERVS1RzVzlqRBlGUkdkSVBwTHhGWU92dUUiLCJlcGsiOnsia3R5IjoiRUMiLCJ4IjoiRXd0RmxWNWZESlo5a3dWbnR4MUhFODRIV3dJSEI3ZlE4LXc2N0J6STloNCIsInkiOiJQSzBHdlFxMDczWlVJWnNqTUxHWFlPc2xqMGVDVFNEaFU3X1hneGNTcVpRIiwiY3J2IjoiUC0yNTYifX0.hBi6qYXal0q5anJoXpWZcie9xNuCoXZN2swnkMw8We_1kyhg6gVUHAzPkq52d8KB-Qv0R_k4KGOz1BpyUsTkhJ0yrtEZZdM5.noCgDYZMF0xtJHVy9_eL5A.wnqtmTgCGiLB9ZfqrxCqmxNfOmJd-7Mg8sKD9owSWfNMhZXQ09nvD3Andy6uTifnnyHZv8-tHg7Wzki4tFTutII79aQNmmRYrE9rOj1kq4DOcDihkcYYWf-frWBdRJfNgPPWKetQg_qZOWz5tO5dhFT6LxWOpB1q6zTXhUdgAiOmyTYmZtVq-q2_iv5TJQ6Q-pMmzjqNfGPKL5LeoiqxmfEQa90gJuJCUDYNG11mV8Fji6Wxh-SFPluFxOs9Bx9P5PrnXrRdcyXKsv3AbxLf9JijwvZb70dJVRN8Cgsbsu5kKJSGgvxMzWrBa_Zr3VF6qSDcqc7G8jqBb4n5TQ_NdN6R8U3OusKYag6HYMbWwg0oaeVe7G4slWg2_H0WtWL1sEZSgjSGZwe4MlaL6BN96A.CLXCmbWcheB8gnk3bo4tmtkXl3_VxeMM1L9EjRolkBA

Передача нескольких идентификаторов одной сущности

GET-запросы

Если нужно передать несколько идентификаторов одной сущности в GET-запросе (например, см. 10.1), то идентификаторы следует указывать, повторяя параметр в запросе.

Формат запроса:

GET /v6/api/mapObjectManagement/mapObjects?mapObjectGroupIDs=\{long}&mapObjectGroupIDs=\{long} HTTP/1.1
Host: host
Authorization: Bearer token

Пример запроса:

GET /v6/api/mapObjectManagement/mapObjects?mapObjectGroupIDs=1&mapObjectGroupIDs=2 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

POST, PATCH-запросы

Если нужно передать несколько идентификаторов одной сущности в POST или PATCH-запросе (например, см. Ссылки на методы), то идентификаторы следует указывать в JSON-массиве через запятую.

Формат запроса:

POST /v6/api/planningManagement/plannings/\{planningID}/assignment HTTP/1.1
Host: host
Authorization: Bearer token
 
\{
  "taskIDs": [
	integer,
	integer
  ]
}

Пример запроса:

POST /v6/api/planningManagement/plannings/1/assignment HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token
 
\{
  "taskIDs": [
	1,
	2
  ]
}

Сжатие данных

Если в запросе передаётся много данных, рекомендуем сжимать тело запроса с помощью алгоритмов gzip или deflate.

Для этого укажите заголовок Content-Encoding: gzip или Content-Encoding: deflate, а также корректную длину сжатого тела.

Если вы хотите получать сжатые ответы, укажите в заголовке запроса Accept-Encoding: gzip или Accept-Encoding: deflate.

Формат времени

При работе с API поддерживаются несколько форматов времени. Важно использовать один формат во всех параметрах запроса — иначе вернется ошибка в ответе на запрос.

Поддерживаемые форматы:

1. Время по часовому поясу пользователя 
   Пример: 2021-01-07T00:00:00
   Используется часовой пояс пользователя, токен которого передан в заголовке запроса.
   В ответе время будет возвращено с указанием смещения от UTC в формате 2021-01-07T00:00:00+03:00
2. Время в формате UTC
   Например: 2021-01-07T00:00:00Z
   Для передачи времени в формате UTC укажите Z после секунд. В ответе время вернется в таком же формате.
   Если Z не указано, в ответе вернется время с указанием смещения от UTC в формате 2021-01-07T00:00:00+03:00.
3. Время с указанием смещения от UTC
   Пример: 2021-01-07T00:00:00+03:00
   В ответе время вернется в таком же формате.

Важно: все параметры в запросе должны быть в одинаковом формате времени. Иначе вернется ошибка:

\{
    "status": 400,
    "code": 225,
    "description": "REQUEST_DATE_TIME_INCONSISTENT_FORMAT",
    "message": "Разные форматы времени в запросе"
}

В ответе время может быть возвращено с точностью до миллисекунд, например, 2021-01-07T00:00:00.000+03:00.

Как учитываются часовые пояса

По умолчанию все действия выполняются с учётом часового пояса пользователя, чей токен используется в запросе. Часовой пояс сотрудника при этом не учитывается.

Пример:

• Пользователь из Москвы (UTC+3) назначает задачу сотруднику из Владивостока (UTC+10).
• Если указать начало задачи в 10:00 (по Москве), то у сотрудника она отобразится как 17:00.
• Чтобы у сотрудника задача началась в 10:00 по его времени, нужно в запросе указать 03:00 по Москве.

Если в настройках веб-интерфейса включен учет часового пояса сотрудника, то указывать время нужно уже по его времени — тогда и в приложении будет отображаться именно оно.

Параметр subsciberID

В рамках услуги «Мобильные сотрудники» параметр subscriberID используется для работы как с сотрудниками, так и с транспортными средствами:

• сотрудник — это работник компании-клиента МТС. Местоположение сотрудников определяется в «Мобильных сотрудниках».
• транспортное средство — это автомобиль или другой транспорт, оснащенный специальным оборудованием. Оно определяет координаты с помощью GPS/ГЛОНАСС и передает данные через сеть оператора.

Параметр subscriberID — это уникальный идентификатор, который позволяет различать сотрудников и транспортные средства в API.

Для транспортных средств дополнительно используется параметр vehicleID, который указывает на характеристики транспорта, например VIN-номер или государственный регистрационный номер.

В описаниях функций всегда указано, к чему относится параметр subscriberID — к сотруднику или к транспортному средству.

Скачивание файлов

Чтобы скачать прикрепленный к задаче файл, добавьте полученный URN в конец следующего URL: https://cds1.mpoisk.ru/cds1/d/.

Например, в параметре attachmentURNs было получено значение abc12d, то URL для скачивания файла будет таким: https://cds1.mpoisk.ru/cds1/d/abc12d.

Обработка ошибок

Для определения успешности результата вызова используется HTTP-статус ответа. 

Если запрос выполнен успешно, функция возвращает результат — или ничего не возвращает, если её задача просто выполнить действие.

Если при выполнении запроса произошла ошибка, в ответе вернётся информация об ошибке: статус, код, название и описание.

Пример ответа с ошибкой:

\{
    "status": 400,
    "code": 2,
    "description": "BAD_REQUEST",
    "message": "Неправильный формат запроса",
    "validationErrors": \{
        "subscriberID": [
            "The value 'string' is not valid for Int64."
        ]
    }
}

Ссылки на актуальную документацию