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":false, // тип оплаты заказа, true - безналичный, false - наличный
  "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 - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

ConfirmOrder

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

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

Ответ:
В ответ строкой возвращается ID заказа в системе СервисВ. Результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

ConfirmOrderExecution

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

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

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

CancelOrder

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

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

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

UpdateOrder

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

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

Ответ:
В ответ строкой возвращается ID заказа в системе СервисВ. Результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
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 - Неявка клиента

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

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

RenewDriver

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

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

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.
 

RefuseOrder

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

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

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
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"
}

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
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"
}]}
}

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
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],
}
}]}
}

Ответ:
Ответ на предложение заказа не содержит тела, результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - в запросе не хватает параметров (в URI или теле запроса), значение параметров указано неверно, либо JSON-структура в теле запроса сформирована неправильно.
404 Not Found - указанный в запросе заказ не найден
500 Internal Server Error - возникла внутренняя ошибка сервера.