API MOIS

API MOIS служит для прямого взаимодействия между такси сервисами. Считается, что на предыдущем этапе они получили от POIS ссылки друг друга (MOISUrl) и ключи ProviderApiKey для опознания и подтверждения безопасности, и теперь переходят к непосредственному предложению и взятию заказа.

Для упрощения обозначим эти два такси сервиса: СервисЗ - это сервис, который предлагает заказ, СервисВ - это сервис, который располагает исполнителями (водителями) для заказа.
Важное требование: на уровне Сервиса идентификатор водителя и такси-компании, в которой он работает должны быть уникальными.

Стандартная схема обмена методами при взятии заказа выглядит так (выделенные жирным методы обязательны к вызову):

Если необходимо редактирование заказа до взятия, то СервисЗ посылает последовательно Отмену заказа (CancelOrder), а затем новое Предложение (OfferOrder) с уже измененными данными.

Если необходимо редактирование заказа после взятия, то СервисЗ посылает Редактирование заказа (UpdateOrder).

OfferOrder

Предложение заказа конкретному участнику MOIS. POST-запрос вида https://MOISUrl/OfferOrder?apiKey=ProviderApiKey

Тело запроса (JSON):
{
"OrderId":1234, // внутренний номер (идентификатор) заказа СервисЗ
"CustomerPhones":["+79219212121","+79219212122"], // телефоны заказчика
"CustomerName":"Анатолий Петрович", // имя заказчика

"OwnerInfo":{"Id":555,"Name":"SuperTaxi","DispatcherPhone":"+74957770077"}, // информация о сервисе-владельце заказа СервисЗ

"Source":{"Index":0,"Country":"Россия","Locality":"Москва","Street":"Мира проспект","House":"106","PorchNumber":"2","Object":"","FullDescription":"Москва, Мира проспект 106","GeoPoint":{"Latitude":55.7672,"Longitude":37.588073}}, // адрес подачи машины
"Destinations" // массив адресов в маршруте, структура адреса такая же как у адреса подачи
"OrderTime":"2018-05-28T14:00", // время и дата подачи машины в формате ISO 8601
"RouteInfo":{"Distance":5200,"Duration":15}, // информация о маршруте, расстояние в метрах, длительность в минутах
"RentTime":0, // время аренды машины (если нужна аренда)

"OrderType":"rush", // тип заказа по срочности подачи машины, rush - чем быстрее, тем лучше, preliminary - строго на указанное время

"IsCashless":0, // тип оплаты заказа, 1 - безналичный, 0 - наличный

"OrderCost":540, // стоимость заказа

"OwnerCharge":15, // сбор владельца в процентах (от 0 до 100)
"FixedCharge":120, // сбор владельца в абсолютном денежном выражении (не должен превышать стоимость заказа)
"Tariff":"e/m/250/10/20", // описание тарифа (информация о способах описания тарифов приведена в конце документа)
"DriverIds":[124,836,140], // идентификаторы водителей СарвисаВ, которых СервисЗ выбрал предпочтительными исполнителями для заказа

"Properties":[{"PropertyName":"CountPlaces","PropertyValue":"4"},{"PropertyName":"CarModel","PropertyValue":"Toyota Rav4"}], // свойства заказа
"Comments":"Спасибо!" // комментарий к заказу
}

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.

400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.

500 Internal Server Error - возникла внутренняя ошибка сервера.

TakeOrderByDriver

Принятие заказа водителем. POST-запрос вида https://MOISUrl/TakeOrderByDriver?apiKey=ProviderApiKey&orderId=OrderId
где orderId - идентификатор заказа в СервисеЗ.

Тело запроса (JSON):
{
"DriverId":521, // внутренний идентификатор водителя в системе СервисВ
"DriverName":"Дмитрий Афанасьевич", // имя водителя
"DriverPhones":"+79251231212", // рабочие телефоны водителя
"CarNumber":"м123мм77", // госномер автомобиля водителя
"CarModel":"Toyota Rav4", // марка и модель автомобиля
"CarColor":"Красный", // цвет автомобиля
"GroupId":84, // внутренний идентификатор такси-группы водителя в системе СервисВ
"GroupName":"Fast Taxi", // название такси-группы водителя
"GroupPhone":"+74991231212" // диспетчерский телефон такси-группы водителя

}

Ответ:

Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.

404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.

ConfirmOrder

Подтверждение взятия со стороны СервисаЗ. POST-запрос вида https://MOISUrl/ConfirmOrder?apiKey=ProviderApiKey

Тело запроса (JSON):
Структура тела запроса аналогична структуре в методе OfferOrder.

Ответ:

В ответ строкой возвращается ID заказа в системе СервисВ. Результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

ConfirmOrderExecution

Подтверждение приступления к выполнению со стороны СервисаВ. GET-запрос вида https://MOISUrl/ConfirmOrderExecution?apiKey=ProviderApiKey&orderId=OrderId
где orderId - идентификатор заказа в СервисеЗ.

Тело запроса:
Отсутствует.

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

CancelOrder

Отмена заказа. Отменяться может как предложенный, так и уже принятый к выполнению заказ. GET-запрос вида https://MOISUrl/CancelOrder?apiKey=ProviderApiKey&orderId=OrderId&reason=Reason
где orderId - идентификатор заказа в СервисеЗ,
reason - причина отмены.

Тело запроса:
Отсутствует.

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.

500 Internal Server Error - возникла внутренняя ошибка сервера.

UpdateOrder

Редактирование заказа. Редактирование заказ следует использовать только для заказа, который уже принят в выполнению на СервисеВ. POST-запрос вида https://MOISUrl/UpdateOrder?apiKey=ProviderApiKey

Тело запроса (JSON):
Структура тела запроса аналогична структуре в методе OfferOrder.

Ответ:

500 Internal Server Error - возникла внутренняя ошибка сервера.

SetOrderStatus

Установка статуса заказа. GET-запрос вида https://MOISUrl/SetOrderStatus?apiKey=ProviderApiKey&orderId=OrderId&status=Status&extra=Extra&responsibleName

=ResponsibleName&responsibleId=responsibleId
где orderId - идентификатор заказа в СервисеЗ,
status - устанавливаемый статус заказа,
extra - в данном поле при завершении заказа передается итоговая стоимость. При перепроводке заказа (повторном завершении) аналогично передается стоимость. В случае, если заказ провален или отменен, в этом параметре передается причина.
responsibleId - идентификатор ответственного лица с СервисеВ,
responsibleName - имя ответственного за установку статуса в СервисеВ.

Допустимые статусы:

WaitTaxi - Ожидание выезда такси (для предварительных)

WaitConfirmInWayFromDriver - Ожидание подтверждения выезда от водителя по предварительному заказу(между статусом WaitTaxi и InWay)

InWay - На пути к заказчику

NearCustomer - Рядом с заказчиком

DriverWaitCustomer - Водитель ожидает клиента

CustomerNotifiedAboutDriverWait - Заказчик оповещен о подаче машины

Execute - Заказчик в машине

WaitComplete - Заказ ожидает завершения диспетчером (используется для безналичных заказов)

DoneOk - Заказ благополучно завершен

DoneFail - Заказ провален водителем

TryCancel - Заказ поставлен на отмену (используется, если от водителя нужно подтверждение отмены)

Cancelled - Заказ отменен

DoneNoClient - Неявка клиента

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

RenewDriver

Замена водителя, исполняющего заказ. В теле запроса передается информация о новом водителе. POST-запрос вида https://MOISUrl/RenewDriver?apiKey=ProviderApiKey&orderId=OrderId

где orderId - идентификатор заказа в СервисеЗ.

Тело запроса (JSON):
Структура тела запроса аналогична структуре в методе TakeOrderByDriver

Ответ:

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

RefuseOrder

Отказ от выполнения взятого заказа. GET-запрос вида https://MOISUrl/RefuseOrder?apiKey=ProviderApiKey&orderId=OrderId&reason=Reason
где orderId - идентификатор заказа в СервисеЗ,
reason - причина отмены.

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

Общая информация по тарифам, используемым в OIS

Тариф описывается строкой, в которой через символ "/" перечислены параметры тарифа.
Первый параметр - класс тарифа, допустимые варианты: "e" для класса эконом, "c" - комфорт, "b" - бизнес, "u" - универсал, "v" - минивен, "a" - микроавтобус.
Второй параметр - тип тарификации: "m" - поминутная, "k" - за пройденное расстояние, "f" - фиксированная стоимость за заказ.
Далее следуют дополнительные параметры тарификации, разделенные тем же символом "/".

Для поездок по фиксированной стоимости допустим только один дополнительный параметр - стоимость заказа (в целых денежных единицах).
Пример тарифа с фиксированной стоимостью: "e/f/350" - поездка по классу эконом, фикс за 350 рублей.

Для поездок с тарификацией по времени или по расстоянию допустимы следующие наборы дополнительных параметров (все параметры - целые числа):
"p1/p2/p3" - минимальная стомость/количество км (минут) включенных в минималку/стоимость каждого последующего км (минуты).
"p1/p2/p3/p4/p5/p6" - дополнительно к предыдущим добавлены параметры ожидания - длительность бесплатного ожидания (количество минут)/стоимость платного ожидания (ден.единицы в минуту)/стоимость километра за городом (ден.единицы).
"p1/p2/p3/p4/p5/p6/p7/p8/p9" - дополнительно к предыдущим добавлены параметры вынужденного простоя в пробках - количество включенных в заказ минут вынужденного простоя/стоимость каждой доп.минуты вынужденного простоя/скорость, ниже которой начинает считаться вынужденный простой (не более 25км/ч).

Примеры тарифа с тарификацией по времени: "c/k/1000/5/100" - поездка по классу комфорт, минималка 1000 рублей, в неё включены 5 км, каждый последующий км - 100 рублей.
"c/k/1000/5/100/10/50/0" - поездка по классу комфорт, минималка 1000 рублей, в неё включены 5 км, каждый последующий км - 100 рублей, бесплатное ожидание 10 минут, каждая последующая минута ожидания 50 рублей, без дополнительной доплаты за выезд за город.

SetDriverCoordinate

Передача координаты водителя от исполнителя владельцу. POST-запрос вида https://MOISUrl/SetDriverCoordinate?apiKey=ProviderApiKey

Тело запроса (JSON):
{
"DriverId":25,
"GeoPoint":{"Latitude":54.72652,"Longitude":20.52555},
"ChangingTime":"2019-03-14T18:28:59"

}

Ответ:

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

SetDriverCoordinates

Передача координат нескольких водителей от исполнителя владельцу. POST-запрос вида https://MOISUrl/SetDriverCoordinates?apiKey=ProviderApiKey

Тело запроса (JSON):
{
"DriverCoordinates":[
{
"DriverId":25,
"GeoPoint":{"Latitude":54.72652,"Longitude":20.52555},
"ChangingTime":"2019-03-14T18:28:59"
},
{
"DriverId":47,
"GeoPoint":{"Latitude":52.593114,"Longitude":39.542445},
"ChangingTime":"2019-03-14T18:25:05"
}]}

}

Ответ:

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.

SendAdditionalDrivers

В случае, если POIS отправил Провайдеру1 новых подходящих для запрошенного им ранее заказа, Провайдер1 может отправить дополнительное предложение другим Провайдерам-серверам-водителям, перечисленным в запросе от POIS. POST-запрос вида https://MOISUrl/SendAdditionalDrivers?apiKey=ProviderApiKey

Тело запроса (JSON):
{
"Orders":[
{
"OrderId":"OrderNumber1",
"DriverIds":[12, 99, 85],
},
{
"OrderId":"OrderNumber2",
"DriverIds":[45, 99, 85],
}
}]}

}

Ответ:

404 Not Found - указанный в запросе заказ не найден

500 Internal Server Error - возникла внутренняя ошибка сервера.