Работа с планированием

Создание планирования

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

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

Указанные в запросе задачи будут распределены между выбранными абонентами, а также будет предложена последовательность их выполнения.

Планирование задач для Сотрудников доступно на тарифах «Премиум» и «Платинум» при подключенной опции «Автопланирование».

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

Параметр	Описание
planningDate	Дата и время планирования (обязательный параметр). Подробнее о формате времени
planningInterval	Продолжительность планирования в днях (обязательный параметр).
withDetailedRoutes	Опция формирования детального маршрута выполнения задач: true — формировать детальный маршрут; false — формирование детального маршрута не требуется.
withVerification	Проверка попадания даты начала задачи в интервал планирования: true — дата начала задачи проверяется; false — проверка не требуется.
ignoreAllRestrictions	Учет ограничительных критериев (рабочее время, компетенции и пр.). Параметр действует, если isRearrangement = true: true — ограничительные критерии не учитываются; false — учитываются все критерии.
isRearrangement	Требуется ли пересчет маршрута: true — выполнить пересчет маршрута; false — пересчет не требуется.
solutionCount	Количество вариантов решений маршрутов: 1, 2 или 3. Передается только при планировании на один день.
zoneIDs	ИД гео-зон. Подробнее о передаче нескольких идентификаторов
competenceIDs	ИД компетенций. Подробнее о передаче нескольких идентификаторов
Сотрудники, между которыми распределяются задачи (subscribers)
subscriberID	ИД Сотрудника (обязательный параметр).
latitude	Географическая широта начальной точки Сотрудника. Если параметр не передан, используются актуальные или заданные в настройках координаты.
longitude	Географическая долгота начальной точки Сотрудника. Если параметр не передан, используются актуальные или заданные в настройках координаты.
Задачи для планирования (tasks)
taskID	ИД задачи.
priority	Приоритет задачи. При равных приоритетах распределение происходит по оптимальному маршруту.
preferredPositionInRoute	Позиция задачи в маршруте (1–10). Если параметр передан, задача обязательно включается в маршрут (переопределяет isMandatoryInRoute).
isMandatoryInRoute	Обязательность включения задачи в маршрут: true — задача обязательно должна быть в маршруте; false — включение не обязательно.
Параметры переопределения настроек шаблона планирования (inputSettings). Передаются в формате ключ/значение.
calculationTimeout	Максимальное время расчета планирования (в секундах).
isRoundTrip	Требуется ли возврат Сотрудника в исходную точку: true — возврат обязателен; false — маршрут завершается в точке последней задачи.
isHomeZoneTasksPreferred	Нужно ли сначала назначать задачи из основной гео-зоны: true — сначала задачи основной зоны, затем дополнительной; false — задачи обеих зон могут выполняться сразу.
automaticClusteringEnabled	Кластеризация задач по гео-зонам. Существуют следующие значения: true – кластеризация задач по гео-зонам применяется. Если за абонентом были уже закреплены гео-зоны, то они будут переопределены. false – кластеризация гео-зон не применяется.
automaticClusteringWithAdditionalZones	Нужно ли после кластеризации назначать абонентам дополнительные гео-зоны других Сотрудников. Существуют следующие значения: 0 – дополнительные гео-зоны не назначаются. 1 – назначаются ближайшие гео-зоны. 2 – назначаются все гео-зоны.
automaticClusteringNearestZonesDelta	Дельта учета ближайших дополнительных зон (в градусах, 1 градус ≈111 км).
automaticClusteringZonesStartPoint	Выбор начальной точки для алгоритма кластеризации. Существуют следующие значения: 0 – центр масс начальных координат Сотрудников. 1 – центр масс координат задач. 2 – начальная точка выбирается случайно из списка задач. 3 – начальная точка выбирается из координат Сотрудников.
automaticClusteringWithPointApproximation	Аппроксимация центров зон по задачам при кластеризации для использования матрицы расстояний. Существуют следующие значения: true – кластеризация выполняется с матрицей расстояний с приближением к точкам задач. false – кластеризация выполняется без матрицы расстояний.
maxSubscriberRouteDistance	Максимальное расстояние, которое может быть преодолено абонентом за весь маршрут (в километрах).
routerType	Тип маршрута. Существуют следующие значения: 1 – линейный маршрут; 2 – детальный маршрут; 3 – детальный маршрут с учетом пробок.

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

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

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

Параметр	Описание
planningID	ИД планирования
planningDate	Дата и время планирования (подробнее о формате времени).
planningInterval	Продолжительность планирования (дни)
withDetailedRoutes	Опция формирования детального маршрута выполнения задач. Существуют следующие значения: true – детальный маршрут выполнения задач будет сформирован. false – формирование детального маршрута выполнения задач не требуется.
withVerification	Проверка даты начала задачи на попадание в указанный интервал планирования. Существуют следующие значения: true – дата начала задачи будет проверяться на попадание в интервал. false – проверка даты начала задачи не требуется.
ignoreAllRestrictions	Учет ограничительных критериев при планировании (например, рабочее время, компетенции). Существуют следующие значения: true – при распределении задач не учитываются ограничительные критерии. false – при планировании учитываются все критерии, в том числе ограничительные.
isRearrangement	Необходимо ли пересчитать маршрут планирования. Существуют следующие значения: true – необходимо пересчитать маршрут планирования для Сотрудника. false – пересчет маршрута планирования не требуется.
solutionCount	Количество вариантов решений по маршрутам. Возможные значения — 1, 2, 3.
zoneIDs	ИД гео-зон.
competenceIDs	ИД компетенций.
Ошибки, возникшие при планировании задач (warnings)
сode	Ошибка назначения задач (описание ошибок )
entityID	ИД сущности, по которой возникла ошибка
message	Текст ошибки
Абоненты, между которыми надо распределить задачи (subscribers)
subscriberID	ИД Сотрудника
latitude	Географическая широта начальной точки Сотрудника (в градусах)
longitude	Географическая долгота начальной точки Сотрудника (в градусах)
Задачи для планирования (tasks)
taskID	ИД задачи
priority	Приоритет задачи. Чем выше приоритет, тем раньше будет задача в очереди на выполнение.
preferredPositionInRoute	Порядок задачи в маршруте. Допустимые значения: от 1 до 10. Если параметр передан, то задача обязательно будет поставлена в маршрут (переопределяет параметр isMandatoryInRoute).
isMandatoryInRoute	Должна ли задача быть обязательно поставлена в маршрут. Существуют следующие значения: true – задача должна быть обязательно в маршруте. false – задача может не быть в маршруте.
Параметры для переопределения настроек шаблона планирования (inputSettings)
calculationTimeout	Максимальное время для расчета планирования (в секундах).
isRoundTrip	Нужно ли Сотруднику в конце возвращаться в исходную точку. Существуют следующие значения: true – в конце планирования Сотрудник возвращается в исходную точку. false – Сотрудник остаётся в точке выполнения последней задачи.
isHomeZoneTasksPreferred	Нужно ли Сотруднику назначать задачи сначала из основной гео-зоны. Существуют следующие значения: true – Сотрудник сначала выполняет задачи из основной гео-зоны, затем — из дополнительной. false – Сотрудник может выполнять задачи из любой гео-зоны.
automaticClusteringEnabled	Кластеризация задач по гео-зонам. Существуют следующие значения: true – кластеризация задач по гео-зонам применяется. Если за абонентом были уже закреплены гео-зоны, то они будут переопределены. false – кластеризация гео-зон не применяется.
automaticClusteringWithAdditionalZones	Нужно ли после кластеризации назначать абонентам дополнительные гео-зоны других Сотрудников. Существуют следующие значения: 0 – дополнительные гео-зоны не назначаются. 1 – назначаются ближайшие гео-зоны. 2 – назначаются все гео-зоны.
automaticClusteringNearestZonesDelta	Дельта учета ближайших дополнительных зон (в градусах, 1 градус ≈111 км).
automaticClusteringZonesStartPoint	Выбор начальной точки для алгоритма кластеризации. Существуют следующие значения: 0 – центр масс начальных координат Сотрудников. 1 – центр масс координат задач. 2 – начальная точка выбирается случайно из списка задач. 3 – начальная точка выбирается из координат Сотрудников.
automaticClusteringWithPointApproximation	Аппроксимация центров зон по задачам при кластеризации для использования матрицы расстояний. Существуют следующие значения: true – кластеризация выполняется с матрицей расстояний с приближением к точкам задач. false – кластеризация выполняется без матрицы расстояний.
maxSubscriberRouteDistance	Максимальное расстояние, которое может быть преодолено абонентом за весь маршрут (в километрах).

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

POST /v6/api/planningManagement/plannings HTTP/1.1
Host: host
Authorization: Bearer token

\{
    "planningDate": "dateTime",
    "planningInterval": integer,
    "subscribers": [
        \{
            "subscriberID": integer,
            "latitude": number,
            "longitude": number
        }
    ],
    "tasks": [
        \{
            "taskID": integer,
            "priority": integer,
            "preferredPositionInRoute": integer,
            "isMandatoryInRoute": boolean
        }
    ],
    "inputSettings": [
        \{
            "name": "string",
            "value": "string"
        }
    ],
    "withDetailedRoutes": boolean,
    "withVerification": boolean,
    "ignoreAllRestrictions": boolean,
    "isRearrangement": boolean,
    "solutionCount": integer,
    "zoneIDs": [
        integer
    ],
    "competenceIDs": [
        integer
    ]
}

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

POST /v6/api/planningManagement/plannings HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
    "planningDate": "2020-12-09T11:02:11Z",
    "planningInterval": 1,
    "subscribers": [
        \{
            "subscriberID": 1,
            "latitude": 37.61775044433594,
            "longitude": 55.735528725106505
        },
        \{
            "subscriberID": 2,
            "latitude": 37.61775044433512,
            "longitude": 55.735858725106505
        }

    ],
    "tasks": [
        \{
            "taskID": 1,
            "priority": 0,
            "preferredPositionInRoute": 1,
            "isMandatoryInRoute": true
        },
        \{
            "taskID": 2,
            "priority": 1
            "preferredPositionInRoute": 2,
        },
        \{
            "taskID": 3,
            "priority": 2
        }
    ],
    "inputSettings": [
        \{
            "name": "isRoundTrip",
            "value": "true"
        }
    ],
    "withDetailedRoutes": true,
    "withVerification": true,
    "ignoreAllRestrictions": false,
    "isRearrangement": false,
    "solutionCount": 1,
    "zoneIDs": [
        1
    ],
    "competenceIDs": [
        1
    ]
}

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

\{
    "planningID": integer,
    "warnings": [
        \{
            "code": "string",
            "entityID": integer,
            "message": "string"
        }
    ],
    "planningDate": "dateTime",
    "planningInterval": integer,
    "subscribers": [
        \{
            "subscriberID": integer,
            "latitude": number,
            "longitude": number
        }
    ],
    "tasks": [
        \{
            "taskID": integer,
            "priority": integer,
            "preferredPositionInRoute": integer,
            "isMandatoryInRoute": boolean
        }
    ],
    "inputSettings": [
        \{
            "name": "string",
            "value": "string"
        }
    ],
    "withDetailedRoutes": boolean,
    "withVerification": boolean,
    "ignoreAllRestrictions": boolean,
    "isRearrangement": boolean,
    "solutionCount": integer,
    "zoneIDs": [
        integer
    ],
    "competenceIDs": [
        integer
    ]
}

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

\{
    "planningID": 1,
    "warnings": [
        \{
            "code": "NO_SUB_WITH_FREE_WORK_SCHEDULE_FOR_TASK",
            "entityID": 3,
            "message": "No subscribers with free work schedule for task 1"
        }
    ],
    "planningDate": "2020-11-19",
    "planningInterval": 2,
    "tasks": [
        \{
            "taskID": 1,
            "priority": 0,
            "preferredPositionInRoute": 1,
            "isMandatoryInRoute": true
        },
        \{
            "taskID": 2,
            "priority": 1,
            "preferredPositionInRoute": 2,
        },
        \{
            "taskID": 3,
            "priority": 2
        }
    ],
    "inputSettings": [
        \{
            "name": "isRoundTrip",
            "value": "true"
        }
    ],
    "withDetailedRoutes": true,
    "withVerification": true,
    "ignoreAllRestrictions": false,
    "isRearrangement": false,
    "solutionCount": 1,
    "zoneIDs": [
        1
    ],
    "competenceIDs": [
        1
    ]

}

Получение результата планирования

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

Функция GET /v6/api/planningManagement/plannings/{planningID}/results позволяет получить результаты планирования по его идентификатору.

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

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

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

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

Параметр	Описание
planningID	ИД планирования
status	Дата и время планирования
progress	Прогресс завершения планирования (в процентах)
Ошибки, возникшие при планировании задач (warnings)
code	Ошибка назначения задач
entityID	ИД сущности, по которой возникла ошибка
message	Текст ошибки
Результат планирования (solutions)
name	Название планирования
planningDate	Дата и время планирования (подробнее о формате времени).
solutionUUID	UUID варианта решения по маршруту
Маршруты планирования (routes)
subscriberID	ИД Сотрудника
Последовательность выполнения задач (visits)
taskID	ИД задачи
arrival	Дата и время начала выполнения задачи (подробнее о формате времени).
finish	Дата и время завершения задачи (ко времени начала задачи добавляется указанное время выполнения, подробнее о формате времени)
Детальный маршрут выполнения задачи (detailedRoute)
routeItemID	ИД отрезка маршрута
points	Широта и долгота каждой точки маршрута

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

GET /v6/api/planningManagement/plannings/\{planningID}/results HTTP/1.1
Host: host
Authorization: Bearer token

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

GET /v6/api/planningManagement/plannings/1/results HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

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

\{
    "planningID": integer,
    "status": "string",
    "progress": integer,
    "warnings": [
        \{
            "code": "string",
            "entityID": integer,
            "message": "string"
        }
    ],
    "solutions": [
        \{
            "name": "string",
            "routes": [
                \{
                    "subscriberID": integer,
                    "visits": [
                        \{
                            "taskID": integer,
                            "arrival": "dateTime",
                            "finish": "dateTime"
                        }
                    ],
                    "detailedRoute": [
                        \{
                            "routeItemID": integer,
                            "points": [
                                [
                                    number
                                ]
                            ]
                        }
                    ]
                }
            ],
            "planningDate": "dateTime",
            "solutionUUID": "string"
        }
    ]
}

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

\{
    "planningID": 0,
    "status": "string",
    "progress": 0,
    "warnings": [
        \{
            "code": "string",
            "entityID": 0,
            "message": "string"
        }
    ],
    "solutions": [
        \{
            "name": "Планирование",
            "routes": [
                \{
                    "subscriberID": 1,
                    "visits": [
                        \{
                            "taskID": 1,
                            "arrival": "2020-11-19T10:00:00+03:00",
                            "finish": "2020-11-1911:00:00+03:00"
                        },
                        \{
                            "taskID": 2,
                            "arrival": "2020-11-19T12:00:00+03:00",
                            "finish": "2020-11-19T13:10:00+03:00"
                        }
                    ],
                    "detailedRoute": [
                        \{
                            "routeItemID": 0,
                            "points": [
                                [
                                    55.7355728,
                                    37.61722
                                ],
                                [
                                    55.73501,
                                    37.61714
                                ],
                                [
                                    55.735508,
                                    37.65776
                                ]
                            ]
                        },
                        \{
                            "routeItemID": 1,
                            "points": [
                                [
                                    55.735508,
                                    37.65776
                                ],
                                [
                                    55.7357635,
                                    37.658287
                                ],
                                [
                                    55.7647934,
                                    37.6925774
                                ]
                            ]

                        }
                    ]
                }
            ],
            "planningDate": "2020-11-18T13:18:05+03:00",
            "solutionUUID": "6cd574b9-da56-4575-9e13-69a5d7035568"
        }
    ]
}

Назначение задач из планирования

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

Функция POST /v6/api/planningManagement/plannings/{planningID}/assignment позволяет назначить задачи из планирования Сотруднику.

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

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

Параметр	Описание
planningID	ИД планирования (обязательный параметр)
solutionUUID	UUID варианта решения по маршруту. Параметр следует передавать только при назначении задач из планирования на один день. При назначении задач из планирования на два дня и больше параметр передавать не требуется.
taskIDs	ИД задач. При передаче пустого массива будут назначены все задачи из планирования. Подробнее о передаче нескольких идентификаторов

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

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

Параметр	Описание
planningID	ИД планирования
status	Дата и время планирования
progress	Прогресс завершения планирования (в процентах)
Ошибки, возникшие при планировании задач (warnings)
code	Ошибка назначения задач
entityID	ИД сущности, по которой возникла ошибка
message	Текст ошибки
Результат планирования (solutions)
name	Название планирования
planningDate	Дата и время планирования (подробнее о формате времени).
solutionUUID	UUID варианта решения по маршруту
Маршруты планирования (routes)
subscriberID	ИД Сотрудника
Последовательность выполнения задач (visits)
taskID	ИД задачи
arrival	Дата и время начала выполнения задачи (подробнееk о формате времени).
finish	Дата и время завершения задачи (ко времени начала задачи добавляется указанное время выполнения, подробнее о формате времени)
Детальный маршрут выполнения задачи (detailedRoute)
routeItemID	ИД отрезка маршрута
points	Широта и долгота каждой точки маршрута

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

POST /v6/api/planningManagement/plannings/\{planningID}/assignment HTTP/1.1
Host: host
Authorization: Bearer token

\{
  "solutionUUID": "string",
  "taskIDs": [
    integer
  ]
}

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

POST /v6/api/planningManagement/plannings/1/assignment HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

\{
  "solutionUUID": "6cd574b9-da56-4575-9e13-69a5d7035568",
  "taskIDs": [
    1,
    2
  ]
}

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

\{
    "planningID": integer,
    "status": "string",
    "progress": integer,
    "warnings": [
        \{
            "code": "string",
            "entityID": integer,
            "message": "string"
        }
    ],
    "solutions": [
        \{
            "name": "string",
            "routes": [
                \{
                    "subscriberID": integer,
                    "visits": [
                        \{
                            "taskID": integer,
                            "arrival": "dateTime",
                            "finish": "dateTime"
                        }
                    ],
                    "detailedRoute": [
                        \{
                            "routeItemID": integer,
                            "points": [
                                [
                                    number
                                ]
                            ]
                        }
                    ]
                }
            ],
            "planningDate": "dateTime",
            "solutionUUID": "string"
        }
    ]
}

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

\{
    "planningID": 0,
    "status": "string",
    "progress": 0,
    "warnings": [
        \{
            "code": "string",
            "entityID": 0,
            "message": "string"
        }
    ],
    "solutions": [
        \{
            "name": "Планирование",
            "routes": [
                \{
                    "subscriberID": 1,
                    "visits": [
                        \{
                            "taskID": 1,
                            "arrival": "2020-11-19T10:00:00+03:00",
                            "finish": "2020-11-1911:00:00+03:00"
                        },
                        \{
                            "taskID": 2,
                            "arrival": "2020-11-19T12:00:00+03:00",
                            "finish": "2020-11-19T13:10:00+03:00"
                        }
                    ],
                    "detailedRoute": [
                        \{
                            "routeItemID": 0,
                            "points": [
                                [
                                    55.7355728,
                                    37.61722
                                ],
                                [
                                    55.73501,
                                    37.61714
                                ],
                                [
                                    55.735508,
                                    37.65776
                                ]
                            ]
                        },
                        \{
                            "routeItemID": 1,
                            "points": [
                                [
                                    55.735508,
                                    37.65776
                                ],
                                [
                                    55.7357635,
                                    37.658287
                                ],
                                [
                                    55.7647934,
                                    37.6925774
                                ]
                            ]
                        }
                    ]
                }
            ],
            "planningDate": "2020-11-18T13:18:05+03:00",
            "solutionUUID": "6cd574b9-da56-4575-9e13-69a5d7035568"
        }
    ]
}

Остановка планирования

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

Функция PUT /v6/api/planningManagement/plannings/{planningID}/termination позволяет остановить процесс планирования.

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

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

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

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

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

PUT /v6/api/planningManagement/plannings/\{planningID}/termination HTTP/1.1
Host: host
Authorization: Bearer token

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

PUT /v6/api/planningManagement/plannings/1/termination HTTP/1.1
Host: api.mpoisk.ru
Authorization: Bearer token

Работа с планированием

Создание планирования

Получение результата планирования

Назначение задач из планирования

Остановка планирования

Содержание