API POIS

API POIS служит для взаимодействия между Провайдером (Такси Сервисом) и Порталом Открытого Информационного Сервиса.
Для начала работы Провайдеру нужно обратиться в Техподдержку ПОИС с запросом на регистрацию на Портале. После регистрации выдается ключ (ProviderApiKey), который будет идентифицировать Провайдера в системе. Со своей стороны Провайдеру нужно реализовать API POIS и предоставить его адрес при регистрации (ProviderPOISUrl).
Важное требование: на уровне Провайдера идентификатор водителя должен быть уникальным.
Далее инфообмен происходит по следующей схеме:

Запросы от Провайдера к POIS:

SendMoisUrl

Отправка Провайдером своего URL для MOIS, с указанием сервера, если необходимо. POST-запрос вида https://POISUrl/SendMoisUrl?apiKey=ProviderApiKey&serverId=ServerId&url=newUrl
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId – ID сервера, если у провайдера несколько серверов. Если нет – 0,
newUrl – URL, куда другим Провайдерам следует обращаться для обмена MOIS-запросами с данным Провайдером.

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

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

GetProperties

Запрос у POIS набора свойств, которым можно оперировать для описания свойств водителей и заказов. GET-запрос вида https://POISUrl/GetProperties?apiKey=ProviderApiKey&language=ru
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ru – локализация языка для отображения свойств.

Ответ:
Ответ от POIS - JSON с массивом свойств и допустимых значений вида:
[
  {
    "Name":"Places", // имя свойства - ключ, по которому это свойство будет опознаваться при передаче в методах
    "Description":"Количество мест", //  локализованное название свойства
    "Type":"int", // тип свойства, допустимые варианты: int - числовое, string - строковое, bool - логическое
    "AllowedValues":["4","5","7"] //  допустимые значения свойства
  }
]
 

SendDriverProperties

Отправка на POIS информации по свойствам водителя (при изменении свойств). POST-запрос вида https://POISUrl/SendDriverProperties?apiKey=ProviderApiKey&driverId=DriverId&serverId=ServerId
где ProviderApiKey – API ключ для POIS, полученный провайдером,
DriverId – ID водителя,
ServerId – ID сервера, если у провайдера несколько серверов. Если нет – 0.
 
Тело запроса (JSON):
[
  {
    "PropertyName":"Places","PropertyValue":"4"
  },
  {
    "PropertyName":"CarModel","PropertyValue":"Toyota Rav4"
  }
] // массив свойств автомобиля

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

SendDriverInfo

Отправка на POIS текущей информации по водителю (при изменении координаты или статуса). POST-запрос вида https://POISUrl/SendDriverInfo?apiKey=ProviderApiKey
где ProviderApiKey – API ключ для POIS, полученный провайдером.
 
Тело запроса (JSON):
{
  "DriverId":1, // Id водителя
  "ServerId":25, // Id сервера, если у провайдера несколько серверов. Если нет – 0
  "Free":true, // свободен ли водитель (true – свободен, false – занят)
  "Position":{“Latitude”:55.7672,”Longitude":37.588073} // координата текущего местонахождения водителя
}

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

SendDriverInfos

Отправка на POIS текущей информации по водителям(при изменении координаты или статуса). POST-запрос вида https://POISUrl/SendDriverInfos?apiKey=ProviderApiKey
где ProviderApiKey – API ключ для POIS, полученный провайдером.
 
Тело запроса (JSON):
{[{
  "DriverId":1, // Id водителя
  "ServerId":25, // Id сервера, если у провайдера несколько серверов. Если нет – 0
  "Free":true, // свободен ли водитель (true – свободен, false – занят)
  "Position":{“Latitude”:55.7672,”Longitude":37.588073} // координата текущего местонахождения водителя
},
{
  "DriverId":2, // Id водителя
  "ServerId":25, // Id сервера, если у провайдера несколько серверов. Если нет – 0
  "Free":true, // свободен ли водитель (true – свободен, false – занят)
  "Position":{“Latitude”:55.7672,”Longitude":37.588073} // координата текущего местонахождения водителя
}]}

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

GetDrivers

Запрос Провайдером указанного количества подходящих водителей с указанными свойствами, в заданном радиусе. Также можно передавать несколько фильтров. POST-запрос с двумя фильтрами по свойствам, применяются по или вида https://POISUrl/GetDrivers?apiKey=ProviderApiKey
где ProviderApiKey – API ключ для POIS, полученный провайдером.
 
Тело запроса (JSON):
{
  "Coordinate":{“Latitude”:55.8028,“Longitude”:37.6369}, // координаты точки, вокруг которой запрашиваются водители
  "Properties":null, // массив требуемых свойств автомобиля (устарело)
  "PropertiesFilter":[{
    "Properties":[{"PropertyName":"Places","PropertyValue":"4"},{"PropertyName":"YearOfManufacture","PropertyValue":"2018"}],
    "Properties":[{"PropertyName":"Places","PropertyValue":"4"},{"PropertyName":"YearOfManufacture","PropertyValue":"2016"},{"PropertyName":"CarModel","PropertyValue":"Mercedes, Hyundai"}]}], // массив требуемых свойств автомобиля
  "Radius":3.5, // радиус, в котором требуются свободные водители. Максимально допустимо 4 км
  "MaxCount":100 // максимальное возвращаемое количество водителей. Максимально допустимо - 100
 
}

Ответ:
Ответ от POIS - JSON вида (водители сгруппированы в массив по провайдерам):
[
  {
    "ProviderId":2, // ID провайдера
    "ProviderName":"Такси СуперСервис", // Название провайдера
    "Drivers":[{"ServerId":71,"DriverId":1,"Coordinate": {"Latitude":54.7265642,"Longitude":20.525276}},{"ServerId":71,"DriverId":2,"Coordinate": {"Latitude":54.7265642,"Longitude":20.525276}}] // список ID водителей, с указанием сервера (сервер необязателен, если у провайдера он один)
  },
  {
    "ProviderId":3,
    "ProviderName":"Какой-то провайдер3",
    "Drivers": [ {"ServerId":1,"DriverId":78,"Coordinate": {"Latitude":54.7265642,"Longitude":20.525276}},{"ServerId":2,"DriverId":95,"Coordinate": {"Latitude":54.7265642,"Longitude":20.525276}}]
  }
]
Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey, переданы некорректные параметры или несуществующие координаты.
 

GetMoisData

Запрос Провайдером информации по MOIS, с указанием своего сервера (если необходимо), для другого Провайдера2 и его сервера (куда обращаться к Провайдеру2 и его серверу для работы по MOIS). GET-запрос вида https://POISUrl/GetMoisData?apiKey=ProviderApiKey&serverId=ServerId&providerIdFor=ProviderIdFor&serverIdFor=ServerIdFor
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId - ID сервера запрашивающего провайдера,
ProviderIdFor - ID провайдера, по которому требуется информация,
ServerIdFor - ID сервера, по которому требуется информация.

Ответ:
Ответ от POIS - JSON вида:
{
  "ProviderId":2, // ID провайдера для которого запрашивается ключ
  "ProviderName":"Такси СуперСервис", // имя провайдера для которого запрашивается ключ
  "ServerId":71, // ID сервера провайдера (может отсутствовать, либо 0)
  "ProviderMoisUrl":"http://localhost:9010", // MOIS-Url для связи с указанным в параметрах Провайдером и сервером
  "YourMoisApiKeyForProvider":"3591098164444b12b13163b8913de258", // ключ, с которым следует обращаться к указанному Провайдеру и серверу
  "ProviderMoisApiKeyForYou":"d45e37706bbb4e64905c501aad58f727" // ключ, с которым к запрашивающему Провайдеру будет обращаться указанные в запросе Провайдер с указанного сервера
}

Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey или не найден провайдер с переданным параметром providerIdFor.

GetMoisDataByKey

Запрос Провайдером информации по MOIS, с указанием ключа другого Провайдера2 (куда обращаться к Провайдеру2 и его серверу для работы по MOIS). GET-запрос вида https://POISUrl/GetMoisDataByKey?apiKey=ProviderApiKey&serverId=ServerId&moisKey=MoisKey
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId - ID сервера запрашивающего провайдера,
MoisKey - ключ MOIS провайдера, по которому нужна информация.
 
Ответ:
Ответ от POIS - JSON вида:
{
  "ProviderId":2, // ID провайдера для которого запрашивается ключ
  "ProviderName":"Такси СуперСервис", // имя провайдера для которого запрашивается ключ
  "ServerId":71, // ID сервера провайдера (может отсутствовать, либо 0)
  "ProviderMoisUrl":"http://localhost:9010", // MOIS-Url для связи с указанным в параметрах Провайдером и сервером
  "YourMoisApiKeyForProvider":"3591098164444b12b13163b8913de258", // ключ, с которым следует обращаться к указанному Провайдеру и серверу
  "ProviderMoisApiKeyForYou":"d45e37706bbb4e64905c501aad58f727" // ключ, с которым к запрашивающему Провайдеру будет обращаться указанные в запросе Провайдер с указанного сервера
}
Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey или не найден провайдер с переданным параметром providerIdFor.
 

Запросы от POIS к Провайдеру:

GetMoisUrl

Запрос от POIS к Провайдеру и его определенному серверу, чтобы получить URL для Mois (POIS URL всех своих серверов или общий, при их отсутствии, Провайдер предоставляет заранее). GET-запрос вида http://ServerPOISUrl/GetMoisUrl?apiKey=ProviderApiKey&serverId=ServerId
где ServerPOISUrl – URL определенного сервера определенного Провайдера, где работает водитель,
ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId – ID сервера (необязательно).

Ответ:
Ответ от POIS – строка, содержащая URL для обращения к Api MOIS вида: "http://Provider1Mois.ru:8525"
Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey.
 

GetDriverProperties

Запрос от POIS к Провайдеру, чтобы получить свойства водителя (делается один раз, когда POIS первый раз получает информацию о положении водителя, о котором до этого POIS ничего не было известно). GET-запрос вида http://ServerPOISUrl/GetDriverProperties?apiKey=ProviderApiKey&driverId=driverId&serverId=ServerId
где ServerPOISUrl – URL определенного сервера определенного Провайдера, где работает водитель,
ProviderApiKey – API ключ для POIS, полученный провайдером,
driverId – ID водителя,
serverId – ID сервера (необязательно).

Ответ:
Ответ от POIS - JSON вида:
[
  {
    "PropertyName":"Places","PropertyValue":"4"
  },
  {
    "PropertyName":"CarModel","PropertyValue":"Toyota Rav4"
  }
] // массив свойств автомобиля
Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey.
404 Not Found - указанный в запросе водитель не найден.
 

SendMoisData

Запрос от POIS к Провайдеру и его определенному серверу, чтобы обновить ключи для взаимодействия по Mois с другим провайдером. POST-запрос вида http://ServerPOISUrl/SendMoisData?apiKey=ProviderApiKey&serverId=ServerId
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId  – ID сервера (необязательно).
Тело запроса (JSON):
{
  "ProviderId":4, // ID провайдера для которого надо обновить ключ
  "ProviderName":"Такси БыстроВезу", // имя провайдера
  "ServerId":85, // ID сервера провайдера (может 0)
  "ProviderMoisUrl":"http://ProviderServer85.ru:8796", // MOIS-Url для связи с ProviderId и его ServerId
  "YourMoisApiKeyForProvider":"d45e37706bbb4e64905c501aad58f727", // ключ, с которым следует обращаться к ProviderId и его ServerId
  "ProviderMoisApiKeyForYou":"3591098164444b12b13163b8913de258" // ключ, с которым к Провайдеру будет обращаться ProviderId и его ServerId
}

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

SendAdditionalDrivers

Когда сервер запрашивает у ПОИС данные по водителям для какого-то заказа, ПОИС у себя некоторое время(5 минут) хранит этот запрос с параметрами и если подлкючатся новые подходящие водители, он отправит SendAdditionalDrivers тому, кто их запрашивал. POST-запрос вида http://ServerPOISUrl/SendAdditionalDrivers?apiKey=ProviderApiKey&serverId=ServerId
где ProviderApiKey – API ключ для POIS, полученный провайдером,
ServerId – ID сервера (необязательно).
Тело запроса (JSON):
{
  "Orders": [
    {
      "OrderId":"A111",
      "Drivers": [ {"ProviderId":1,"ServerId":0,"DriverId":13},{"ProviderId":2,"ServerId":1,"DriverId":10},{"ProviderId":2,"ServerId":2,"DriverId":10}]
    },
    {
      "OrderId":"B111",
      "Drivers": [ {"ProviderId":1,"ServerId":0,"DriverId":13},{"ProviderId":2,"ServerId":1,"DriverId":10},{"ProviderId":2,"ServerId":2,"DriverId":10}]
    }
  ]
}

Ответ:
Ответ - массив неактуальных на данном сервере айди заказа(чтобы больше ПОИС не досылал водителей) - уже взятых, отмененных и т.д.:
[
  "A111"
]
Дополнительно результат описывается кодом HTTP-ответа.
200 OK - запрос выполнен полностью без ошибок.
400 Bad Request - некорректный или пустой ключ ProviderApiKey, переданы некорректные параметры или несуществующие координаты.