Работа с заявками

Создание объектов

Общее описание

Функция POST /v6/api/jobManagement/jobs/mapObjects позволяет создать объект.

Максимальное количество объектов, которое можно передать в запросе, — 1000.

Для создания одного объекта необходимо использовать функцию POST /v6/api/mapObjectManagement/mapObjects.

Параметры вызова

Функция имеет следующие параметры:

Параметр	Описание
radius	Радиус объекта (в метрах)
longitude	Географическая долгота (в градусах)
latitude	Географическая широта (в градусах)
mapObjectGroupID	ИД группы объекта (обязательный параметр)
imageIndex	Индекс иконки объекта
name	Название объекта (обязательный параметр)
address	Адрес объекта
enabled	Признак активности объекта. Существуют следующие значения: true — объект включен (учитывается при определении местоположения Сотрудников, в отчетах, отображается на карте, а также в приложении «МТС Координатор»); false — объект выключен.
customFieldFormTemplateID	ИД шаблона дополнительных полей задачи
Параметры дополнительных полей задачи (массив структур customFieldFormItem)
externalID	ИД дополнительного поля
value	Значение дополнительного поля

Результат выполнения

При успешном выполнении возвращается статус 201.

Функция возвращает структуру с параметрами созданной заявки на создание объектов:

Параметр	Описание
jobID	ИД заявки
rowsTotalNum	Общее количество элементов в заявке
rowsValidNum	Количество корректных элементов в заявке

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

POST /v6/api/jobManagement/jobs/mapObjects HTTP/1.1
Host: host
Authorization: Bearer token

[
    \{
        "radius": integer,
        "longitude": number,
        "latitude": number,
        "mapObjectGroupID": integer,
        "imageIndex": integer,
        "name": "string",
        "address": "string",
        "enabled": boolean,
        "customFieldsFormTemplateID": integer,
        "customFieldFormItems": [
            \{
                "externalID": "string",
                "value": "string"
            }
        ]
    }
    },
    \{
        "radius": integer,
        "longitude": number,
        "latitude": number,
        "mapObjectGroupID": integer,
        "imageIndex": integer,
        "name": "string",
        "address": "string",
        "enabled": boolean,
        "customFieldsFormTemplateID": integer,
        "customFieldFormItems": [
            \{
                "externalID": "string",
                "value": "string"
            }
        ]
    }
]

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

POST /v6/api/jobManagement/jobs/mapObjects HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

[
    \{
        "radius": 150,
        "longitude": 37.5765572127199,
        "latitude": 55.7387521301683,
        "mapObjectGroupID": 1,
        "imageIndex": 0,
        "name": "Типография",
        "address": "Россия, Москва, улица Плющиха, 53/25с1",
        "enabled": true,
        "customFieldsFormTemplateID": 1,
        "customFieldFormItems": [
            \{
                "externalID": "1",
                "value": "12:00-14:00"
            }
        ]
    }
    },
    \{
        "radius": 150,
        "longitude": 27.541002648247712,
        "latitude": 53.90313848510366,
        "mapObjectGroupID": 1,
        "imageIndex": 0,
        "name": "Пункт выдачи",
        "address": "Россия, Московская область, Химки, Молодёжная улица, 50",
        "enabled": true,
        "customFieldsFormTemplateID": 1,
        "customFieldFormItems": [
            \{
                "externalID": "1",
                "value": "12:00-14:00"
            }
        ]
    }
]

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

\{
    "jobID": integer,
    "rowsTotalNum": integer,
    "rowsValidNum": integer
}

Пример ответа

\{
    "jobID": 1,
    "rowsTotalNum": 2,
    "rowsValidNum": 2
}

Создание задач

Общее описание

Функция POST /v6/api/jobManagement/jobs/tasks позволяет создать сразу несколько задач.

Максимальное количество задач, которое можно передать в запросе, — 1000.

Для создания одной задачи необходимо использовать функцию POST /v6/api/taskManagement/tasks.

Параметры вызова

Функция имеет следующие параметры:

Параметр	Описание
subscriberID	ИД Сотрудника
deadline	Крайний срок завершения задачи
title	Название задачи (обязательное поле)
description	Описание задачи
address	Адрес задачи
longitude	Географическая долгота адреса (в градусах)
latitude	Географическая широта адреса (в градусах)
externalID	Внешний пользовательский ИД задачи
clientName	ФИО клиента
clientPhone	Телефон клиента
clientEmail	Адрес электронной почты клиента
priority	Приоритет задачи. Существуют следующие значения: 0 — низкий; 1 — средний; 2 — высокий.
rank	Ранг задачи. Допустимые значения: от 0 до 100.
startDate	Дата начала задачи (обязательное поле).
status	Статус задачи. Существуют следующие значения: 0 — новая; 1 — принята; 2 — отклонена; 3 — выполнена; 4 — в работе.
taskTypeID	ИД типа задачи
customStatusID	ИД пользовательского статуса задачи
customStatusReasonID	ИД причины смены пользовательского статуса задачи
mapObjectID	ИД объекта
commentPolicy	Требования к комментарию при завершении задачи. Значения: 0 — не обязателен; 1 — обязателен; 2 — обязателен при отклонении заявки; 3 — обязателен в обоих случаях.
serviceTime	Время выполнения задачи
startInterval	Интервал начала выполнения задачи
preferredPositionInRoute	Порядок задачи в маршруте. Допустимые значения: от 1 до 10.
isMandatoryInRoute	Должна ли задача быть обязательно поставлена в маршрут. Существуют следующие значения: true – задача должна быть обязательно в маршруте. false – задачи может не быть в маршруте.
isFixed	Является ли задача закрепленной (нельзя менять время начала выполнения в пределах допустимого времени опоздания, изменять или снимать исполнителя). Существуют следующие значения: true — задача закреплена; false — задача не закреплена.
Параметры компетенций задачи (competences)
competenceID	ИД компетенции
amount	Вес компетенции
Параметры измерений (структура dimensions)
weight	Вес (кг)
unit	Юниты
width	Ширина (м)
height	Высота (м)
length	Длина (м)
volume	Объем (м³)
Параметры дополнительных полей задачи (массив структур customFieldFormItems)
externalID	ИД дополнительного поля
value	Значение дополнительного поля
values	Значения поля в случае множественного выбора.
Параметры шаблоны формы, обязательного для заполнения при отклонении или завершении задачи (массив структур taskFormTemplates)
status	Статус задачи, при переводе в который необходимо заполнить форму. Существуют следующие значения: 2 — отклонена; 3 — выполнена. Если статус задачи не передан или передан равным null, то сотрудник сможет заполнить и прикрепить в комментарии только шаблоны форм со статусом null. Если таких нет — можно заполнить любой шаблон.
taskFormTemplateID	ИД шаблона формы.
isRequired	Является ли обязательным заполнение формы. Существуют следующие значения: true — заполнение формы является обязательным. false — заполнение формы является необязательным.
Параметры предзаполненных полей (массив структур prefillValues)
externalID	Внешний ИД поля.
value	Значение поля.
values	Значения поля в случае множественного выбора.
Параметры колонок таблицы (массив массивов rows)
externalID	Внешний ИД колонки.
value	Значение колонки.
values	Значения поля в случае множественного выбора.
Параметры общей ссылки на местоположение сотрудника (структура sharedLink)
isActive	Активность ссылки. Существуют следующие значения: true — ссылка активна, можно просматривать местоположение; false — ссылка неактивна.
sharingPeriod	Время действия ссылки. Существуют следующие значения: 1 — до окончания выполнения задачи; 2 — до указанного времени.
sharingEndDate	Дата и время окончания действия ссылки (если sharingPeriod = 2)
sendToEmail	Отправить ссылку на электронную почту клиента. Почта задаётся в clientEmail. Существуют следующие значения: true — нужно отправить ссылку; false — отправлять не нужно.
sendToSMS	Отправить ссылку по SMS клиенту. Телефон задаётся в clientPhone. Существуют следующие значения: true — нужно отправить ссылку; false — отправлять не нужно.
Параметры обратной связи (структура feedback)
formInvitationProfileID	ИД профиля обратной связи
formTemplateID	ИД формы обратной связи
sendToEmail	Отправить форму обратной связи на электронную почту клиента. Электронная почта должна быть указана в параметре clientEmail. Существуют следующие значения: true — необходимо отправить ссылку; false — ссылку не нужно отправлять.
sendToSMS	Отправить форму обратной связи по SMS клиенту. Телефон клиента должен быть указан в параметре clientPhone. Существуют следующие значения: true — необходимо отправить ссылку; false — ссылку не нужно отправлять.
Параметры чек-листа (массив структур checklists)
assetID	ИД актива
isRequired	Является ли заполнение чек-листа обязательным. Существуют следующие значения: true — заполнение чек-листа является обязательным; false — заполнение чек-листа не обязательно.
type	Тип чек-листа. Существуют следующие значения: 0 — тип по умолчанию.
checkListTemplateIDs	ИД шаблонов чек-листов
name	Название чек-листа
description	Описание чек-листа

Результат выполнения

Функция возвращает структуру с параметрами созданной заявки на создание задач:

Параметр	Описание
jobID	ИД заявки
rowsTotalNum	Общее количество элементов в заявке
rowsValidNum	Количество корректных элементов в заявке

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

POST /v6/jobManagement/jobs/tasks HTTP/1.1
Host: host
Authorization: Bearer token

[
    \{
        "subscriberID": integer,
        "deadline": "dateTime",
        "title": "string",
        "description": "string",
        "address": "string",
        "longitude": number,
        "latitude": number,
        "externalID": "string",
        "clientName": "string",
        "clientPhone": "string",
        "clientEmail": "string",
        "priority": integer,
        "startDate": "dateTime",
        "status": integer,
        "mapObjectID": integer,
        "commentPolicy": integer,
        "competences": [
            \{
                "competenceID": integer,
                "amount": number
            }
        ],
        "dimensions": \{
            "weight": number,
            "unit": number,
            "width": number,
            "height": number,
            "length": number,
            "volume": number
        },
        "serviceTime": integer,
        "startInterval": integer,
        "preferredPositionInRoute": integer,
        "isMandatoryInRoute": boolean,
        "isFixed": boolean,
        "customFieldsFormTemplateID": integer,
        "customFieldFormItems": [
            \{
                "externalID": "string",
                "value": "string",
                "values": [
                    "string"
                ],
                "rows": [
                     [
                         \{
                            "externalID": "string",
                            "value": "string",
                            "values": [
                                "string"
                            ],
                        }
                    ]
                ]
            }
        ],
        "taskFormTemplates": [
            \{
                "status": integer,
                "taskFormTemplateID": integer,
                "isRequired": boolean,
                "prefillValues": [
                    \{
                        "externalID": "string",
                        "value": "string",
                        "values": [
                            "string",
                        ]
                        "rows": [
                             [
                                 \{
                                     "externalID": "string",
                                     "value": "string",
                                     "value": [
                                         "string"
                                     ]
                                 }
                             ]
                        ]
                    }
                ]
            }
        ],
        "sharedLink": \{
            "isActive": boolean,
            "sharingPeriod": integer,
            "sharingEndDate": "dateTime",
            "sendToEmail": boolean,
            "sendToSMS": boolean
        },
        "feedback": \{
            "formInvitationProfileID": integer,
            "formTemplateID": integer,
            "sendToEmail": boolean,
            "sendToSMS": boolean
         }
    }
]

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

POST /v6/api/jobManagement/jobs/tasks HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

[
    \{
        "subscriberID": 1,
        "deadline": "2020-11-08T15:00:00",
        "title": "Задача 1",
        "description": "Описание",
        "address": "Москва, Кулакова ул,20,с.1 Минист. Энерг. МО здание г-ы\"Хилтон\" подъезд \"G\"",
        "longitude": 37.392895,
        "latitude": 55.804911,
        "externalID": "1",
        "clientName": "Сергей Алексеевич",
        "clientPhone": "79161234567",
        "clientEmail": "ivan@ivanov.ru",
        "priority": 1,
        "startDate": "2020-11-06T00:00:00",
        "status": 0,
        "mapObjectID": 1,
        "commentPolicy": 3,
        "competences": [
            \{
                "competenceID": 1,
                "amount": 4
            }
        ],
        "dimensions": \{
            "weight": 5,
            "unit": 5,
            "width": 5,
            "height": 5,
            "length": 5,
            "volume": 5
        },
        "serviceTime": 15,
        "startInterval": 30,
        "preferredPositionInRoute": true,
        "isMandatoryInRoute": 1,
        "isFixed": true,
        "customFieldsFormTemplateID": 1,
        "customFieldFormItems": [
            \{
                "externalID": "1",
                "value": "true"
            }
        ],
        "taskFormTemplates": [
            \{
                "status": 2,
                "taskFormTemplateID": 1,
                "isRequired": true
            }
        ],
        "sharedLink": \{
            "isActive": true,
            "sharingPeriod": 1,
            "sharingEndDate": "2022-06-20T09:00:08",
            "sendToEmail": true,
            "sendToSMS": true
        }
    },
    \{
        "subscriberID": 1,
        "deadline": "2020-11-08T15:00:00",
        "title": "Задача 2",
        "description": "Описание",
        "address": "Москва, Кулакова ул,20,с.1 Минист. Энерг. МО здание г-ы\"Хилтон\" подъезд \"G\"",
        "longitude": 37.392895,
        "latitude": 55.804911,
        "externalID": "1",
        "clientName": "Алексей Сергеевич",
        "clientPhone": "79161234567",
        "priority": 1,
        "startDate": "2020-11-06T00:00:00",
        "status": 0,
        "mapObjectID": 1,
        "commentPolicy": 3,
        "competences": [
            \{
                "competenceID": 1,
                "amount": 4
            }
        ],
        "serviceTime": 15,
        "startInterval": 30,
        "preferredPositionInRoute": 2,
        "isMandatoryInRoute": true,
        "isFixed": false,
        "customFieldsFormTemplateID": 1,
        "customFieldFormItems": [
            \{
                "externalID": "1",
                "value": "true"
            }
        ],
        "taskFormTemplates": [
            \{
                "status": 3,
                "taskFormTemplateID": 2,
                "isRequired": true
            }
        ],
        "sharedLink": \{
            "isActive": true,
            "sharingPeriod": 1,
            "sharingEndDate": "2022-06-20T09:00:08",
            "sendToEmail": true,
            "sendToSMS": true
        },
        "feedback": \{
            "formInvitationProfileID": 1,
            "formTemplateID": 1,
            "sendToEmail": true,
            "sendToSMS": true
         }
    }
]

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

\{
    "jobID": integer,
    "rowsTotalNum": integer,
    "rowsValidNum": integer
}

Пример ответа

\{
    "jobID": 1,
    "rowsTotalNum": 2,
    "rowsValidNum": 2
}

Добавление сотрудника

Общее описание

Функция POST /v6/api/jobManagement/jobs/subscribers позволяет добавить Сотрудника.

Параметры вызова

Функция имеет следующие параметры:

Параметр	Описание
subscriberTariffTypeID	ИД тарифа Сотрудника. Существуют следующие значения: 9 – М2М; 10 – тариф «Эконом»; 11 – тариф «Стандарт»; 12 – тариф «Бизнес»; 13 – тариф «Премиум»; 20 – тариф «Платинум». Подробнее о тарифах см. https://www.mpoisk.ru/info/pricing.
groupID	ИД группы, в которую нужно добавить Сотрудника. Подробнее о получении ИД группы
name	ФИО Сотрудника (обязательное поле)
msid	Номер телефона добавляемого Сотрудника в формате 7XXXXXXXXXX. Например: 79161234567 (обязательное поле)
isCoordinatorAvailable	Будет ли Сотрудник использовать «МТС Координатор» (доступно на тарифах «Бизнес», «Премиум», «Платинум»). Существуют два значения: true — абоненты добавляются для использования приложения «МТС Координатор». Абонентам МТС будет отправлено SMS-приглашение для получения их разрешения на определение местоположения. false — абоненты добавляются для отслеживания по базовым станциям. Абонентам МТС и Мегафон будет отправлено SMS-приглашение для получения разрешения на определение местоположения по базовым станциям. Подробнее о тарифах см. https://www.mpoisk.ru/info/pricing.
isDiscountAvailable	Статус применения опции «Мобильные сотрудники впрок». Имеет два значения: false — опция не применяется; true — опция применяется.

Результат выполнения

Функция возвращает структуру со следующими параметрами заявки:

Параметр	Описание
jobID	ИД заявки
operation	Тип заявки
state	Статус заявки

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

POST /v6/api/jobManagement/jobs/subscribers HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
    "subscriberTariffTypeID": integer,
    "groupID": integer,
    "name": "string",
    "msid": "string",
    "isCoordinatorAvailable": boolean,
    "isDiscountAvailable": boolean
}

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

POST /v6/api/jobManagement/jobs/subscribers HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
    "subscriberTariffTypeID": 13,
    "groupID": 132126,
    "name": "Иванов",
    "msid": "79161234567",
    "isCoordinatorAvailable": true,
    "isDiscountAvailable": true
}

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

\{
    "jobID": integer,
    "operation": integer,
    "state": integer
}

Пример ответа

\{
    "jobID": 1,
    "operation": 9,
    "state": 2
}

Получение статуса заявки

Общее описание

Функция GET /v6/api/jobManagement/jobs/{jobID} позволяет получить статус выполнения заявки.

Параметры запроса

В запросе используется обязательный параметр jobID — идентификатор заявки.

Результат выполнения

Функция возвращает структуру со следующими параметрами заявки:

Параметр	Описание
jobID	ИД заявки
operation	Тип заявки
state	Статус заявок
Параметры заявки (массив структур jobDetails, данные в массиве есть только для заявок на добавление сотрудников)
jobItemID	ИД элемента заявки
state	Статус элемента заявки
result	Информация об элементе заявки
subscriberID	ИД Сотрудника
subscriberName	Имя Сотрудника

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

GET /v6/api/jobManagement/jobs/\{jobID} HTTP/1.1
Host: host		
Authorization: Bearer token

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

GET /v6/api/jobManagement/jobs/1 HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

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

\{
    "jobID": integer,
    "operation": integer,
    "state": integer,
    "jobDetails": [
        \{
            "jobItemID": integer,
            "state": integer,
            "result": "string",
            "subscriberID": integer,
            "subscriberName": "string"
        }
    ]
}

Пример ответа

\{
    "jobID": 1,
    "operation": 9,
    "state": 2,
    "jobDetails": [
        \{
            "jobItemID": 1,
            "state": 2,
            "result": "Успешно добавлен",
            "subscriberID": 1,
            "subscriberName": "Иванов Иван"
        }
    ]
}

Получение статуса по отдельным элементам заявки

Общее описание

Функция GET /v6/api/jobManagement/jobs/{jobID}/jobItems позволяет получить статус по отдельным элементам заявки.

Параметры запроса

В запросе используется обязательный параметр jobID — идентификатор заявки.

Результат выполнения

Функция возвращает массив структур со следующими параметрами результатов операций по заявке:

Параметр	Описание
jobItemID	ИД элемента заявки
state	Статус заявок
result	Информация об элементе заявки
subscriberID	ИД Сотрудника
subscriberName	Имя Сотрудника

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

GET /v6/api/jobManagement/jobs/\{jobID}/jobItems HTTP/1.1
Host: host
Authorization: Bearer token

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

GET /v6/api/jobManagement/jobs/1/jobItems HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

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

[
    \{
        "jobItemID": integer,
        "state": integer,
        "result": "string",
        "subscriberID": integer,
        "subscriberName": "string"
    }
]

Пример ответа

[
    \{
        "jobItemID": 1,
        "state": 2,
        "result": "string",
        "subscriberID": 0,
        "subscriberName": "Иванов Иван"
    }
]

Работа с заявками

Создание объектов

Создание задач

Добавление сотрудника

Получение статуса заявки

Получение статуса по отдельным элементам заявки

Содержание