WebOrders WebAPI REST Documentation


Содержание

WebOrders.WebAPI предоставляет следующие возможности:

  1. Рассчет стоимость заказа.

  2. Создание заказ на поиск машины с возможностью его отмены.

  3. Получение истории заказов для авторизированного пользователя.

  4. Получение отчета по заказам для авторизированного пользователя.

  5. Просмотр профиля для авторизированного пользователя.

  6. Получение гео-данных (objects, streets).

Для использования данных функций необходимо сформировать и отправить Http-запрос по адресу расположения  WebOrders.WebAPI: http://<ip-addres>:<port>/api/. В ответ от  WebOrders.WebAPI приходит ответ в формате json. Для авторизации используется поддерживаемый протоколом Http Basic Authentication. Для отправки данных об авторизации необходимо использовать Authorization header (заголовок).

Authorization header (заголовок) формируется следующим образом:

  1. Получить SHA512 Hash пароля пользователя: хеш_пароля.

  2. Логин и хеш_пароля объединяются в одну строку в формате «логин:хеш_пароля».

  3. Полученная строка преобразовывается в Base64-строку («login_pswd_base64»).

  4. Сформировать header (заголовок) в формате «Authorization: Basic login_pswd_base64».

Например, для логин = «achumak» и пароль = «1» получим SHA512 хеш_пароля = «4dff4ea340f0a823f15d3f4f01ab62eae0e5da579ccb851f8db9dfe84c58b2b37b89903a740e1ee172da793a6e79d560e5f7f9bd058a12a280433ed6fa46510a». Далее объединяем в одну строку «achumak :4dff4ea340f0a823f15d3f4f01ab62eae0e5da579ccb851f8db9dfe84c58b2b37b89903a740e1ee172da793a6e79d560e5f7f9bd058a12a280433ed6fa46510a» и получаем Base64 представление

YWNodW1hazo0ZGZmNGVhMzQwZjBhODIzZjE1ZDNmNGYwMWFiNjJlYWUwZTVkYTU3OWNjYjg1MWY4ZGI5ZGZlODRjNThiMmIzN2I4OTkwM2E3NDBlMWVlMTcyZGE3OTNhNmU3OWQ1NjBlNWY3ZjliZDA1OGExMmEyODA0MzNlZDZmYTQ2NTEwYQ==


В итоге имеем header (заголовок) в виде:

Authorization Basic
YWNodW1hazo0ZGZmNGVhMzQwZjBhODIzZjE1ZDNmNGYwMWFiNjJlYWUwZTVkYTU3OWNjYjg1MWY4ZGI5ZGZlODRjNThiMmIzN2I4OTkwM2E3NDBlMWVlMTcyZGE3OTNhNmU3OWQ1NjBlNWY3ZjliZDA1OGExMmEyODA0MzNlZDZmYTQ2NTEwYQ==

Краткое описание запросов

Тип запроса

HTTP-метод

Url

Авторизация

POST

/api/account

Смена пароля

PUT

/api/account/changepassword

Восстановление пароля

POST

/account/restore/sendConfirmCode/

POST

/account/restore/checkConfirmCode/

POST

/account/restore

Получение кода подтверждения для регистрации

POST

/api/account/register/sendConfirmCode/

/api/account/register/confirmcode - устаревшее

Регистрация

POST

/api/account/register


Верификация телефона

GET

/api/approvedPhones?phone=380501234567

POST

/approvedPhones/sendConfirmCode/

POST

/approvedPhones/

Запрос версии

GET

/api/version

Расчет стоимости заказа

POST

/api/weborders/cost

Создание заказа на поиск машины

POST

/api/weborders

Получение списка тарифов

GET

/api/tariffs

Информация заказа (поиск машины)

GET

/api/weborders/<uid>

Добавочная стоимость

GET
POST
PUT
DELETE

/api/weborders/<uid>/cost.additional

Определить Geo положение машины на заказе

GET

/api/weborders/drivercarposition/<uid>

Отмена заказа

PUT

/api/weborders/cancel/<uid>

Профиль клиента

GET

/api/clients/profile

Обновление профиля

PUT

/api/clients/profile

Обновление информации для отправки push PUT /api/clients/credential

Смена телефона клиента

POST

/clients/changePhone/sendConfirmCode/

PUT

/clients/changePhone

Отчет по заказам клиента

GET

/api/clients/ordersreport?dateFrom=2013.08.13%2000:00:00&dateTo=2013.08.15%2000:00:00

Отчет по бонусам клиента

GET

/api/clients/bonusreport?limit=10&offset=0

История заказов клиента

GET

/api/clients/ordershistory?limit=10&offset=0

Geo данные (улицы)

GET

/api/geodata/streets?versionDateGratherThan=2013.07.11%2015:14:13.893

GET

/api/geodata/streets/search?q=search&fields=*

Geo данные (объекты)

GET

/api/geodata/objects?versionDateGratherThan=2013.07.11%2015:14:13.893

GET

/api/geodata/objects/search?q=search&fields=*

Geo данные (улицы и объекты)

GET

/api/geodata/search?q=search&fields=*

/api/geodata/search?lat=50.449361&lng=30.518495&r=500&fields=*

Запрос серверного времени

GET

/api/time

Запрос настроек

GET

/api/settings

Запрос пополнения баланса

POST

/api/clients/balance/transactions/

Получение транзакции оплаты

GET

/api/clients/balance/transactions/<transaction_id>

История изменения баланса GET /api/clients/balance/transactions/

Получение координат автомобилей в радиусе

GET

/api/drivers/position?lat=50.451063&lng=30.523891&radius=5

Авторизация пользователя

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

X-WO-API-APP-ID: your_app_id


Request (запрос):

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

Обязательный параметр

Описание

login

Да

Логин (или телефонный номер) для авторизации пользователя

password

Да

SHA512 Hash пароля пользователя.*

WebOrdersApiClientAppToken Да Токен для отправки пушей.

Пример тела запроса в формате json:

{

    "Login":"achumak"

    ,"Password":"4dff4ea340f0a823f15d3f4f01ab62eae0e5da579ccb851f8db9dfe84c58b2b37b89903a740e1ee172da793a6e79d560e5f7f9bd058a12a280433ed6fa46510a"

    ,"WebOrdersApiClientAppToken":"App_Token"

}


* При авторизации необходимо отправлять хеш пароля с алгоритмом хеширования SHA512. Ниже приводиться пример кода на C# для получения хеш SHA512 для паролей:

       public static String ComputeSha512Hash(String password)

       {

           // Create Byte array of password String

           Encoding encoder = new UTF8Encoding();

           Byte[] secretBytes = encoder.GetBytes(password);


           SHA512 sha512 = SHA512.Create();

           Byte[] computedHash = sha512.ComputeHash(secretBytes);


           StringBuilder computedHashStr = new System.Text.StringBuilder();

           foreach (Byte b in computedHash)

           {

               computedHashStr.Append(b.ToString("x2").ToLower());

           }

           return computedHashStr.ToString();


       }


Response (ответ):

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

Тип данных

Описание

user_full_name

String

Полное имя пользователя

user_phone

String

Телефон пользователя

user_balance

Decimal

Текущий баланс пользователя

route_address_from

String

Адрес пользователя

route_address_number_from

String

Номер дома адреса пользователя

route_address_entrance_from

Int32

Подъезд

route_address_apartment_from

Int32

Квартира

roles

String

Роли пользователя, разделенные запятыми

client_sub_cards

Int32

Номера дополнительных карточек пользователя

version

Int32

Версия WebOrders.Server

discount            (*)

Object

Текущая скидка клиента

discount/value

Decimal

Значение скидки

discount/unit

String

Тип скидки (в деньгах, или процентах от стоимости заказа)

payment_type

Int32

Категория оплаты пользователя.

0 — нал, 1 — безнал.

client_bonuses

Decimal

Кол-во бонусов клиента

(1 бонус = 1 денежной ед.)

{

    "roles":"WebOrdersClient"

    ,"version":"1.1.2"

    ,"user_full_name":"Иванов Александр"

    ,"user_phone":"0501234567"

    ,"user_balance":150.0

    ,"route_address_from":"ул. Край земли"

    ,"route_address_number_from":"3"

    ,"route_address_entrance_from":0

    ,"route_address_apartment_from":0

    ,"client_sub_cards":null

    ,"discount":{"value":15.00,"unit":"грн."}

    ,"payment_type":1

    ,"client_bonuses":885.0

}


Response (ответ):

Статус ответа

Id ошибки

Описание

200 (OK)


Авторизация прошла успешно.

401 (Unauthorized)

-2              (**)

Ошибка авторизации. Неправильно указан логин или пароль.

(* ) Информация о скидке клиента ("discount":{"value":15.00,"unit":"грн."})  возвращается также и в запросе /api/clients/profile. Значение в discount/unit указывает в каких еденицах измеряется значение (discount/value) скидки:

  • Скидка на определенную сумму (Например: 15 грн)

  • Скидка на определенный процент от стоимости заказа (Например: 15%)

(** ) Начиная с версии 1.6.16.1 при ошибке авторизации (HTTP статус код 401) в теле запроса возвращается также Id = -2.

Пример ответа при ошибке авторизации:

HTTP/1.1 401 Unauthorized

Content-Length: 103

Content-Type: application/json; charset=utf-8

Server: Microsoft-HTTPAPI/2.0

WWW-Authenticate: Basic

Date: Mon, 26 Jan 2015 18:03:09 GMT


{"Message":"В выполнении запроса отказано авторизацией.","Id":-2}

Регистрация пользователя

Регистрация нового клиента выполняется в 2 этапа:

  1. «Получение кода подтверждения». Пользователь указывает свой номер мобильного телефона, на который система отправляет сообщение (SMS) с кодом подтверждения.

  2. «Регистарция». Пользователь указывает свои данные вместе с полученным кодом подтверждения.

Для того, чтобы использовать данный функционал необходимо в настройках «Такси Навигатор» отметить опцию «Разрешить онлайн-регистрацию пользователей» (Настройки->WebOrders).

Получение кода подтверждения

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account/register/sendConfirmCode

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

X-WO-API-APP-ID: your_app_id

Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона, на который будет отправлен код подтверждения.

taxiColumnId

Нет

Номер колоны, из которой отправляется SMS (0, 1 или 2, по умолчанию 0).


Пример тела запроса в формате json:

{"phone":"380501234567"}

Response (ответ):

Статус ответа

Id ошибки

Описание

200 (OK)


Запрос успешно принят и обработан.

403 (Forbidden)

-31

Регистрация запрещена настройками «Такси Навигатор».

403 (Forbidden)

-33

Слишком много попыток получения кода.

400 (BadRequest)

-32

Пользователь с таким номером телефона уже зарегистрирован.

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest) -15 Неверный номер колонны такси.
403 (Forbidden) -17 Операция отправки SMS не поддерживается настройками колонны «Такси Навигатор» (Настройки → СМС). Опция "Колонны, которым разрешена отправка СМС".


Пример тела запроса в формате json в случае неверного формата телефона:

{"Id":-34,"Message":"Registration error. Invalid phone number."}

Регистрация

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account/register

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Request (запрос):

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

Тип данных

Обязательный параметр

Описание

phone

String

Да

Номер мобильного телефона, на который будет отправлен код подтверждения.

confirm_code

String

Да

Код подтверждения, полученный в SMS.

password

String

Да

Пароль.

confirm_password

String

Да

Пароль (повтор).

user_first_name

String

Нет

Имя клиента.


Пример тела запроса в формате json:

{

"phone":"380501234567",

"confirm_code":"492164",

"password":"i23f5%6o0",

"confirm_password":"i23f5%6o0",

"user_first_name":"Виктория"

}

Response (ответ):

Статус ответа

Id ошибки

Описание

201 (Created)


Пользователь успешно зарегистрирован.

403 (Forbidden)

-31

Регистрация запрещена настройками «Такси Навигатор».

400 (BadRequest)

-32

Пользователь с таким номером телефона уже зарегистрирован.

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest)

-35

Неверный код подтверждения.

400 (BadRequest)

-36

Не указан пароль, или пароль подтверждения не соответствует паролю.

Пример тела запроса в формате json в случае неверно указанного кода подтверждения:

{"Id":-35,"Message":"Registration error. Invalid confirmation code."}

Смена пароля

http://<ipaddress>:<port>/api/account/changepassword

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/account/changepassword

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Возможные значения

Описание

oldPassword

Да


Старый пароль

newPassword

Да


Новый пароль

repeatNewPassword

Да


Новый пароль

{

    "oldPassword":"oldpsw",

    "newPassword":"newpsw",

    "repeatNewPassword":"newpsw"

}

В случае успешной смены пароля сервер вернет HTTP/1.1 204 No Content.

В случае неверного заполнения паролей сервер вернет HTTP/1.1 400 Bad Request

Response (ответ) для HttpStatus 400 Bad Request:

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

Возможные значения

Описание

Message


Описание ошибки

ModelState


Описание ошибок в модели запроса.

changePassword.oldPassword



changePassword.newPassword



changePassword.repeatNewPassword




{

   "Message":"The request is invalid.",

   "ModelState":

    {

       "changePassword.OldPassword":

        ["Поле 'Пароль' повинно бути строкою з мінімальною довжиною 1 і максимальною довжиною 30.", "Необхідно вказати поле 'Пароль'."],

       "changePassword.NewPassword":

        ["Поле 'Пароль' повинно бути строкою з мінімальною довжиною 7 і максимальною довжиною 30."]

        }

}

Восстановление пароля

Восстановление (сброс) пароля выполняется в несколько этапов:

  1. «Получение кода подтверждения». Пользователь указывает свой номер мобильного телефона, привязанный к его карточке в ТН, на который система отправляет сообщение (SMS) с кодом подтверждения.

  2. «Проверка полученного кода».

  3. «Восстановление пароля» — пользователь указывает новый пароль.


Восстановление пароля может быть запрещенно настройками для конкретного «постоянного клиента» в «Такси Навигаторе» (Данные о постоянных клиентах-> Редактировать клиента -> Запретить смену пароля).

Получение кода подтверждения

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account/restore/sendConfirmCode

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона, на который будет отправлен код подтверждения.

taxiColumnId

Нет

Номер колоны, из которой отправляется SMS (0, 1 или 2, по умолчанию 0).


Пример тела запроса в формате json:

{"phone":"380501234567"}


Response (ответ):

Статус ответа

Id ошибки

Описание

200 (OK)


Запрос успешно принят и обработан.

404 (Not Found)

-3

Не удалось найти пользователя с таким номером телефона.

409 (Conflict)

-4

В системе более одного пользователя с таким номером телефона.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор» (Данные о постоянных клиентах-> Редактировать клиента -> Запретить смену пароля).

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest) -15 Неверный номер колонны такси.
403 (Forbidden) -17 Операция отправки SMS не поддерживается настройками колонны «Такси Навигатор» (Настройки → СМС). Опция "Колонны, которым разрешена отправка СМС".

Пример тела запроса в формате json в случае неверного формата телефона:

{"Id":-34,"Message":"Invalid phone number."}

Проверка кода подтверждения

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account/restore/checkConfirmCode

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:


Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона.

confirm_code

Да

Код подтверждения.

Пример тела запроса в формате json:

{

"phone":"380501234567",

"confirm_code":"492164",

}


Response (ответ):

Статус ответа

Id ошибки

Описание

200 (Ok)


Пользователь успешно зарегистрирован.

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest)

-35

Неверный код подтверждения.


Восстановление пароля

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/account/restore

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона.

confirm_code

Да

Код подтверждения.

password

Да

Новый пароль.

confirm_password

Да

Новый пароль (повтор).


Пример тела запроса в формате json:

{

"phone":"380501234567",

"confirm_code":"492164",

"password":"i23f5%6o0",

"confirm_password":"i23f5%6o0",

}



Response (ответ):

Статус ответа

Id ошибки

Описание

201 (Created)


Пользователь успешно зарегистрирован.

404 (Not Found)

-3

Не удалось найти пользователя с таким номером телефона.

409 (Conflict)

-4

В системе более одного пользователя с таким номером телефона.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор» (Данные о постоянных клиентах-> Редактировать клиента -> Запретить смену пароля).

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest)

-35

Неверный код подтверждения.

400 (BadRequest)

-36

Не указан пароль.

400 (BadRequest)

-37

Пароль подтверждения не соответствует паролю.

400 (BadRequest)

-38

Длина пароля не удовлетворяет условию от 7 до 30 символов.


Пример тела запроса в формате json в случае неверно указанного кода подтверждения:

{"Id":-35,"Message":"Invalid confirmation code."}

Верификация телефона

Верификация телефона может применяться для гостевого (анонимного) пользователя, у которого еще нет ни одного выполненного заказа (с данным номером телефона). Верификация подразумевает отправку на указанный клиентом телефон SMS с кодом. Таким образом можно проверить что указанный в заказе телефон действительно принадлежит клиенту.

Для того, чтобы использовать данный функционал необходимо в настройках «Такси Навигатор» отметить опцию «Требовать подтверждение телефона через SMS при первом заказе для анонимного пользователя» (Настройки->WebOrders).

Получение кода подтверждения

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/approvedPhones/sendConfirmCode

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:


Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона, на который будет отправлен код подтверждения.

taxiColumnId

Нет

Номер колоны, из которой отправляется SMS (0, 1 или 2, по умолчанию 0).


Пример тела запроса в формате json:

{"phone":"380501234567"}



Response (ответ):

Статус ответа

Id ошибки

Описание

200 (OK)


Запрос успешно принят и обработан.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор» (Настройки->WebOrders). Опция «Требовать подтверждение телефона через SMS при первом заказе для анонимного пользователя».

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest) -15 Неверный номер колонны такси.
403 (Forbidden) -17 Операция отправки SMS не поддерживается настройками колонны «Такси Навигатор» (Настройки → СМС). Опция "Колонны, которым разрешена отправка СМС".


Пример тела запроса в формате json в случае неверного формата телефона:

{"Id":-34,"Message":"Invalid phone number."}

Подтверждение телефона

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/approvedPhones/

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:


Request (запрос):

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

Обязательный параметр

Описание

phone

Да

Номер мобильного телефона.

confirm_code

Да

Код подтверждения.


Пример тела запроса в формате json:

{

"phone":"380501234567",

"confirm_code":"492164",

}



Response (ответ):

Статус ответа

Id ошибки

Описание

201 (Created)


Телефон успешно верифицирован.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор».

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest)

-35

Неверный код подтверждения.


Пример тела запроса в формате json в случае неверно указанного кода подтверждения:

{"Id":-35,"Message":"Invalid confirmation code."}

Запрос версии

http://<ipaddress>:<port>/api/version

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/version

Headers

Accept: application/json

Response (ответ):

Название параметра

Описание

version

Версия WebOrders.Server  в формате 1.2.3, где:

 1 - Старший разряд версии (Измениение API, без обратной совместимости).

 2 - Младший разряд версиию (Измениение API с обратной совместимостью).

 3 - Номер сборки (Исправление ошибок, без изменения API).


{"version":"1.1.2"}

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

Рассчет стоимости заказа

http://<ipaddress>:<port>/api/weborders/cost

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/weborders/cost

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Authorization:Basic YWNod...YQ==

X-WO-API-APP-ID: your_app_id

Request (запрос):

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

Тип данных

Обязательный параметр

Возможные значения

Описание

user_full_name

String

Нет


Полное имя пользователя

user_phone

String

Нет


Телефон пользователя

reservation

Boolean

Да

True, False

Признак предварительного заказа

required_time


Нет

"2015-08-24T19:15:00"

Время подачи предварительного заказа

comment

String

Нет


Комментарий к заказу

minibus *

Boolean

Нет

True, False

Микроавтобус

wagon *

Boolean

Нет

True, False

Универсал

premium *

Boolean

Нет

True, False

Машина премиум-класса

flexible_tariff_name *

String

Нет


Гибкий тариф

baggage

Boolean

Нет

True, False

Загрузка салона

animal

Boolean

Нет

True, False

Перевозка животного

conditioner

Boolean

Нет

True, False

Кондиционер

courier_delivery

Boolean

Нет

True, False

Курьер

route_undefined

Boolean

Нет

True, False

По городу

terminal

Boolean

Нет

True, False

Терминал

receipt

Boolean

Нет

True, False

Требование чека за поездку.

route


Да


Маршрут заказа. (См. Таблицу описания маршрута)

route_address_entrance_from

String

Нет

Номер подъезда

client_sub_card

String

Нет


Номер доп карточки

add_cost

Decimal

Нет

10

Дополнительная стоимость к заказу

calc_with_rec_add_cost Boolean Нет True, False Рассчитать стоимость с рекомендуемой дополнительной стоимостью

taxiColumnId

Int32

Да

0, 1 или 2

Номер колоны, в которую будут приходить заказы.

payment_type

Int32

Нет

Null, 0 или 1

Тип оплаты заказа (нал, безнал) (см. Приложение 4).

* Признаки «Гибкий тариф» (flexible_tariff_name), «Универсал» (wagon), «Микроавтобус» (minibus) и «Премиум» (premium) должны быть взаимоисключающими. Если одновременно  указать несколько из вышеперечисленных параметров, учитываться будет только один в порядке приоритета:

  • «Гибкий тариф» (flexible_tariff_name).

  • «Микроавтобус» (minibus).

  • «Универсал» (wagon).

  • «Премиум» (premium).

Создание маршрута может формироваться двумя способами:

  • Указание адресов или объектов, которые присутствуют в БД диспетчерской службы такси. Так как у диспетчерской службы такси есть своя карта развязок автомобильных дорог, указанные адреса переводятся в локальные координаты и по ним строиться маршрут заказа.

  • Указание адреса в свободной форме с указанием точного местоположения по географическим координатам (долгота и широта). В данном случае программа переводит указанные географические координаты в локальные и по ним строиться маршрут.

Описание параметров маршрута:

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

Тип данных

Обязательный параметр

Возможные значения

Описание

name

String

Да


Адрес или название объекта

number

String

Нет


Номер дома (только для адреса)

lat

Decimal

Нет

50.474613

Широта

lng

Decimal

Нет

30.506389

Долгота


Пример маршрута по гео-координатам.

"route":

   [

    {"name":"вход м.Шевченко.","lat":50.474613, "lng":30.506389}

    ,{"name":"м.Иподром.","lat":50.377615, "lng":30.468195}

   ]


Пример маршрута по адресам из БД диспетчерской службы такси.

"route":

   [

    {"name":"КРЕЩАТИК УЛ.","number":"1"}

    ,{"name":"Автосалон Лексус (кольцевая дорога 62)"}

   ]


Полный пример формирования пакета заказа.

{

    "user_full_name":"Иванов Александр"

    ,"user_phone":""

    ,"client_sub_card":null

    ,"required_time":null

    ,"reservation":false

    ,"route_address_entrance_from":null

    ,"comment":""

    ,"add_cost":12.0

    ,"wagon":false

    ,"minibus":false

    ,"premium":false

      ,"flexible_tariff_name": "гибкий тариф"

    ,"baggage":false

    ,"animal":false

    ,"conditioner":true

    ,"courier_delivery":false

    ,"route_undefined":false

    ,"terminal":false

    ,"receipt":false

    ,"route":

       [

        {"name":"КРЕЩАТИК УЛ.","number":"1"}

        ,{"name":"Автосалон Лексус (кольцевая дорога 62)"}

        ,{"name":"м.Иподром.","lat":50.377615, "lng":30.468195}

          ]

    ,"taxiColumnId":0

}

Response (ответ):

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

Тип данных

Возможные значения

Описание

dispatching_order_uid

String

1sdf234gh6j739dqa

Идентификатор заказа, присвоенный в ТН

order_cost

Decimal

71.50

Стоимость заказа (отображается в формате, в зависимости от настроек ТН).

currency

String

грн.

Аббревиатура валюты (из настроек ТН)

discount_trip

Boolean

FALSE

Указывает, является ли данный заказ акционным (применяется доп. скидка).

can_pay_bonuses

Boolean

TRUE

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


{

    "dispatching_order_uid":"f4f5a233f56a45e3a36de3001b1e9d18"

    ,"order_cost":"72"

    ,"currency":" грн."

    ,"discount_trip":false

    ,"can_pay_bonuses":true

}

Рассчет стоимости заказа для нескольких тарифов:

http://<ipaddress>:<port>api/weborders/tariffs/cost

Основные  параметры Http-запроса:

Http-метод

POST

Url

api/weborders/tariffs/cost

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Authorization:Basic YWNod...YQ==

X-WO-API-APP-ID: your_app_id

Request (запрос):

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

Тип данных

Обязательный параметр

Возможные значения

Описание

user_full_name

String

Нет


Полное имя пользователя

user_phone

String

Нет


Телефон пользователя

reservation

Boolean

Да

True, False

Признак предварительного заказа

required_time


Нет

"2015-08-24T19:15:00"

Время подачи предварительного заказа

comment

String

Нет


Комментарий к заказу

minibus

Boolean

Нет

True, False

Микроавтобус

wagon

Boolean

Нет

True, False

Универсал

premium

Boolean

Нет

True, False

Машина премиум-класса

flexible_tariff_name

String

Нет


Гибкий тариф

baggage

Boolean

Нет

True, False

Загрузка салона

animal

Boolean

Нет

True, False

Перевозка животного

conditioner

Boolean

Нет

True, False

Кондиционер

courier_delivery

Boolean

Нет

True, False

Курьер

route_undefined

Boolean

Нет

True, False

По городу

terminal

Boolean

Нет

True, False

Терминал

receipt

Boolean

Нет

True, False

Требование чека за поездку.

route


Да


Маршрут заказа. (См. Таблицу описания маршрута)

route_address_entrance_from

String

Нет

Номер подъезда

client_sub_card

String

Нет


Номер доп карточки

add_cost

Decimal

Нет

10

Дополнительная стоимость к заказу

calc_with_rec_add_cost Boolean Нет True, False Рассчитать стоимость с рекомендуемой дополнительной стоимостью

taxiColumnId

Int32

Да

0, 1 или 2

Номер колоны, в которую будут приходить заказы.

payment_type

Int32

Нет

Null, 0 или 1

Тип оплаты заказа (нал, безнал) (см. Приложение 4).

calculated_tariff_names String[] Да

[
"Базовый",
"Универсал",
"Бизнес-класс"
]

Список тарифов по которым нужно просчитать стоимость заказа

Параметры «Гибкий тариф» (flexible_tariff_name), «Микроавтобус» (minibus), «Универсал» (wagon), «Премиум» (premium) в отличии от "Рассчет стоимости заказа" на просчет стоимости не влияют.

Формат запроса аналогичен "Рассчет стоимости заказа" за исключением обязательного поля calculated_tariff_names. В него нужно передать список тарифов по которым нужно просчитать стоимость заказа.


Response (ответ):

В случае успешного просчета (статус код 200) возвращается массив  следующих объектов:

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

Тип данных

Возможные значения

Описание

flexible_tariff_name String Универсал Название тарифа
order_cost_details Object
Ниже перечислены свойства(аналогичные и для "Рассчет стоимости заказа")

dispatching_order_uid

String

1sdf234gh6j739dqa

Идентификатор заказа, присвоенный в ТН

order_cost

Decimal

71.50

Стоимость заказа (отображается в формате, в зависимости от настроек ТН).

currency

String

грн.

Аббревиатура валюты (из настроек ТН)

discount_trip

Boolean

FALSE

Указывает, является ли данный заказ акционным (применяется доп. скидка).

can_pay_bonuses

Boolean

TRUE

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

can_pay_cashless Boolean TRUE Возможность безналичного расчета

[

    {

        "flexible_tariff_name":"Универсал",

        "order_cost_details":

        {

                "dispatching_order_uid":"6653935bb234482f87fdce475daa277d",

                "order_cost":"55.00",

                "currency":"грн.",

                "discount_trip":false,

                "can_pay_bonuses":true,

                "can_pay_cashless":false}

        }

    },

    {

        "flexible_tariff_name":"Бизнес-класс",

        "order_cost_details":

        {

                "dispatching_order_uid":"6c93d6cff91c44bbad94471af534001e",

                "order_cost":"113.90",

                "currency":"грн.",

                "discount_trip":false,

                "can_pay_bonuses":false,

                "can_pay_cashless":false

        }

    }

]


Response (ответ):

В случае ошибок просчета (статус код 500) возвращается массив  следующих объектов:

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

Тип данных

Возможные значения

Описание

flexible_tariff_name String Универсал Название тарифа
error Object
Ниже перечислены свойства(аналогичные и для "Рассчет стоимости заказа" при ошибках просчета)

Id

Int32

-6

Идентификатор ошибки

Message

String

"error"

Описание ошибки

[

    {

        "flexible_tariff_name":"Универсал",

        "error":

        {

                "Id":-6,

                "Message":"Не удалось рассчитать стоимость заказа. Попробуйте немного позже."

        }

    },

    {

        "flexible_tariff_name":"Бизнес-класс",

        "error":

        {

                "Id":-6,

                "Message":"Не удалось рассчитать стоимость заказа. Попробуйте немного позже."

        }

    }

]


Response (ответ):

В случае ошибок в запросе (статус код 400) возвращается массив  следующих объектов, формат аналогичен "Рассчет стоимости заказа" при не правильно сформированном запросе:

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

Тип данных

Возможные значения

Описание

flexible_tariff_name String Универсал Название тарифа
error Object
Ниже перечислены свойства(аналогичные и для "Рассчет стоимости заказа" при ошибках валидации)

Id

Int32

-6

Идентификатор ошибки

Message

String

"error"

Описание ошибки

ModelState Object
Описание ошибок в модели запроса.

[

    {

    "flexible_tariff_name":null,

    "error":

        {

        "Message":"The request is invalid.",

        "ModelState":

        {

            "order.calculated_tariff_names":["Нужно указать список тарифов"]

        },

        "Id":-70,

        "description":"The request is invalid.",

        "Ids":[-70]

        }

    }

]

Создание заказа:

http://<ipaddress>:<port>/api/weborders

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/weborders

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:

Authorization:Basic YWNod...YQ==

X-WO-API-APP-ID: your_app_id


Request (запрос):

Параметры такие же как и в случае просчета стоимости.

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

Тип данных

Обязательный параметр

Возможные значения

Описание

user_full_name

String

Да


Полное имя пользователя

user_phone

String

Да


Телефон пользователя

client_sub_card

String

Да, если у постоянного клиента есть доп. карточка


Номер доп карточки

pay_bonuses

Decimal

Нет

94

Сумма, которую клиент хочет оплатить бонусами (на данный момент эта сумма должна полностью покрывать стоимость заказа).  Только для постоянных клиентов.

app_registration_token

String

Нет


Уникальный идентификатор получателя уведомления.


Response (ответ):

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

Тип данных

Возможные значения

Описание

dispatching_order_uid

String

44ebd09e5f224651bf3c8e2dd12ed890

Идентификатор заказа, присвоенный в БД ТН

find_car_timeout

Int32

120

Таймаут на поиск машины, в сек. По истечению таймаута, если машина не была найдена, заказ закрывается со статусом  “Нет машины” (CloseReason = 4)

find_car_delay

Int32

0

Задержка на поиск машины, в сек (в случае предварительного заказа). Время по истечении которого начнется выполняться поиск машины.

Для не предварительного заказа равняется 0.


{

    "dispatching_order_uid":"44ebd09e5f224651bf3c8e2dd12ed890"

    "find_car_timeout":120,

    "find_car_delay":0

}

Response (ответ):

Статус ответа

Id ошибки

Описание

200 (Ok)


Заказ успешно принят.

400 (BadRequest)


Неверные параметры запроса.

400 (BadRequest)

-13

Ошибка создания заказа, т.к. указанного адреса (улицы) нет в базе данных.

400 (BadRequest)

-14

Ошибка создания заказа, т.к. указанного адреса (объекта) нет в базе данных.

400 (BadRequest)

-15

Неверный номер колоны (taxiColumnId)

403 (Forbidden)

-11

Постоянный клиент заблокирован диспетчерской.

403 (Forbidden)

-12

У постоянного безнального клиента недостаточно денег на балансе

для выполнения заказа.

403 (Forbidden)

-23

Номер телефона в «Черном списке»

403 (Forbidden)

-40

Требуется подтверждение телефона для анонимного пользователя

(см. запрос POST api/approvedPhones/).

403 (Forbidden)

-50

Использование бонусов запрещено настройками «Такси Навигатор» или пользователь не авторизирован.

403 (Forbidden)

-51

У пользователя недостаточно бонусов для оплаты заказа.

403 (Forbidden)

-52

Бонусов для оплаты меньше, чем стоимость заказа.

403 (Forbidden)

-53

Оплата бонусами невозможна для заказа «по городу».

400 (BadRequest)

-54

Некорректное время подачи. (Дата и время подачи машины должно быть позже текущей даты)

400 (BadRequest)

-55

Добавочная сумма должна быть больше -100000 и меньше 100000

400 (BadRequest)

-65

Неверное имя тарифа 'тариф'

403 (Forbidden)

-66

Оплата по безналичному расчету невозможна для заказа «по городу».

Получение списка тарифов

http://<ipaddress>:<port>/api/tariffs

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/tariffs  

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Response (ответ):

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

Тип данных

Возможные значения

Описание

name

String

“Бизнес-класс”

Имя тарифа из БД ТН


[
   {
       "name":"Базовый"
   },
   {
       "name":"Универсал"
   },
   {
       "name":"Бизнес-класс"
   },
   {
       "name":"Премиум-класс"
    },
   {
       "name":"Эконом-класс"
   },
   {
       "name":"Микроавтобус"
   }
]


Запрос состояния заказа


http://<ipaddress>:<port>/api/weborders/44ebd09e5f224651bf3c8e2dd12ed890

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/weborders/<uid>

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

<uid>

Да

UID заказа в БД ТН (полученный в ответе на запрос создания заказа).


Response (ответ):

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

Тип данных

Возможные значения

Описание

dispatching_order_uid

String

QW12as3467fd38

UID заказа, присвоенный в БД ТН

order_cost

Decimal

94.09

Стоимость заказа (отображается в формате, в зависимости от настроек ТН).

add_cost Decimal 4 Добавочная стоимость

currency

String

грн.

Аббревиатура валюты (из настроек ТН)

order_car_info

String

АА64-72ЕН, белый (мал шашка), Lada 2010

Информация о машине, если машина найдена, иначе – пусто.

driver_phone

String

050-123-45-67

Телефон водителя, если машина найдена, иначе – пусто.

 required_time


"2015-08-24T19:15:00"

Дата и время подачи машины.

close_reason

Int32


Статус закрытия заказа (см. Приложение 1)

cancel_reason_comment

String

У Вас недостаточно денег на балансе.

Комментарий к причине отмены заказа. (Для close_reason = 6)

order_is_archive


True, False

Признак «архивного» заказа

drivercar_position

Object

Object или null

Текущее GPS положение машины, выполняющей заказ. Возвращается если есть актуальная информация о положении данной машины (status="gpsOk"). (См. )

route_address_from/name

String

ОЗЕРНАЯ УЛ. (ОБОЛОНЬ)

Адрес 1ой точки заказа (улица или объект).

oute_address_from/number

String

1

route_address_to/name

String

ЯНГЕЛЯ АКАДЕМИКА УЛ.

Адрес последней точки заказа (улица или объект).

oute_address_to/number

String

7

driver_execution_status

Int32


Статус выполнения  (см. Приложение 6)

execution_status String SearchesForCar Статус выполнения заказа (см. Приложение 2)


{

    "dispatching_order_uid":"44ebd09e5f224651bf3c8e2dd12ed890"

    ,"order_cost":"72"

    ,"currency":" грн."

    ,"order_car_info":"АА1172АА, синий, Ford C-Max"

    ,"driver_phone":"050-123-45-67"

    ,"required_time":"2013-08-14T17:01:57.303"

    ,"close_reason":-1

    ,"cancel_reason_comment":null

    ,"execution_status":"SearchesForCar"

    ,"order_is_archive":false

           ,"driver_execution_status":3

    ,"drivercar_position":{

        "lat":50.512383

        ,"lng":30.536734

        ,"time_positioned_utc":"2015-06-02T11:12:23.301"

        ,"altitude":null

        ,"accuracy":null

        ,"bearing":0

        ,"speed":60

        ,"status":"gpsOk"

    }

    ,"route_address_from":{

        "name":"ОЗЕРНАЯ УЛ. (ОБОЛОНЬ)"

        ,"number":"1"}

    ,"route_address_to":{

        "name":"ЯНГЕЛЯ АКАДЕМИКА УЛ."

        ,"number":"1"}

}

Запрос информации о позывном


http://<ipaddress>:<port>/api/weborders/44ebd09e5f224651bf3c8e2dd12ed890/driver


Основные  параметры Http-запроса:


Http-метод

GET

Url

/api/weborders/<uid>/driver

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):


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

Обязательный параметр

Описание

<uid>

Да

UID заказа в БД ТН (полученный в ответе на запрос создания заказа).

Response (ответ):


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

Тип данных

Возможные значения

Описание

is_own_driver

Boolean

true

true - свой водитель

false - чужой водитель

null - водитель не подтвердил заказ

signal

Int32

100

Позывной, если параметр is_own_driver равен true


Для того что бы в параметре is_own_driver было значение true или false должно выполнятся одно из условий:

  1.  Заказ выполнен
  2.  Заказ создан и водитель подтвердил выполнение


{

    "is_own_driver": true,

    "signal": 100

}

Добавочная стоимость

http://<ipaddress>:<port>/api/weborders/44ebd09e5f224651bf3c8e2dd12ed890/cost/additional

Основные параметры Http-запроса:

Http-методы

GET, POST, PUT, DELETE

Url

/api/weborders/<uid>/cost/additional

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Authorization:Basic YWNod...YQ==

GET

Получить значение добавочной стоимости.

POST

Добавить к добавочной стоимосте.

PUT

Обновить добавочную стоимость.

DELETE

Удалить добавочную стоимость.


Request (запрос):

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

Обязательный параметр

Описание

id

Да

Уникальный идентификатор заказа.

amount

Decimal

Добавочная стоимость.

Response (ответ):

См. Описание ответа для информации по заказу

Response в случае ошибок (ответ):

Статус ответа

Сообщение

401 (Unauthorized )

Клиент не авторизирован.

404 (Not Found)

Заказ не найден.

403 (Forbidden)

Данное действие отклонено. Пожалуйста, свяжитесь с нами. (при попытке изменить стоимость ОНЛАЙН заказа)

400 (Bad Request)

Неверная сумма. (При отрицательной сумме.)

400 (Bad Request)

Недопустимое значение в Добавочной стоимости. (Сумма больше 100000)

400 (Bad Request)

Данный заказ недоступен. (На заказе найдена машина.)

409 (Conflict)

Невозможно изменить стоимость заказа. (Заказ заблокирован другой транзакцией.)


{
    "amount": 20.50
}

Запрос GPS положения машины, выполняющей заказ:

http://<ipaddress>:<port>/api/weborders/drivercarposition/44ebd09e5f224651bf3c8e2dd12ed890

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/weborders/drivercarposition/<uid>

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

<uid>

Да

UID заказа в БД ТН (полученный в ответе на запрос создания заказа).

Response (ответ):

Статус ответа

Описание

200 (Ok)

Запрос успешно обработан.

404 (Not Found)

Заказ для данного идентификатора (uid) не найден.


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

Тип данных

Возможные значения

Описание

accuracy

Nullable<Int16>


Точность

altitude

Nullable<Int16>

250 или null

Высота (м)

bearing

Nullable<Int16>

153 или null

Направление (град.)

lat

Decimal

50.55612

Широта (град.)

lng

Decimal

30.05425

Долгота (град.)

speed

Nullable<Int16>

60

Скорость (км/ч)

status

String

gpsOk, gpsExpired или gpsUnavailable

Статус GPS координаты. (См. )

time_positioned_utc

DateTime

2015-06-02T11:12:23.301

UTC время позиционирования.

{

    "lat":50.5

    ,"lng":30.5

    ,"time_positioned_utc":"2015-06-02T11:12:47.586"

    ,"altitude":null

    ,"accuracy":null

    ,"bearing":0

    ,"speed":60

    ,"status":"gpsOk"

}

Запрос отмены заказа клиентом:


http://<ipaddress>:<port>/api/weborders/cancel/44ebd09e5f224651bf3c8e2dd12ed890

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/weborders/cancel/<uid>

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

<uid>

Да

UID заказа в БД ТН (полученный в ответе на запрос создания заказа).

Response (ответ):

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

Возможные значения

Описание

dispatching_order_uid

e81db0ff651148d8a4ce2b908e7915cc

UID заказа.

order_client_cancel_result

0, 1 или 2

Результат отмены (описание ниже).


{

    "dispatching_order_uid":"44ebd09e5f224651bf3c8e2dd12ed890"

    ,"order_client_cancel_result":1

}


Таблица. Описание значений order_client_cancel_result:

Значение

Описание

0

Заказ не удалось отменить.

1

Заказ отменен.

2

Требует подтвержение клиентом отмены в диспетчерскую.

Клиенты

Запрос отчета по заказам клиентом (Запрос типа GET):


http://<ipaddress>:<port>/api/clients/ordersreport?dateFrom=2013.08.13%2000:00:00&dateTo=2013.08.15%2000:00:00

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/clients/ordersreport

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

date_from

Да

Начальный интервал для отчета

date_to

Да

Конечный интервал для отчета

Response (ответ):

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

Возможные значения

Описание

report_name

Отчет по заказам клиента

Название отчета

columns

Массив пар «key-name».

Список колонок отчета

columns/key

Id, Phone, AddressTo

Ключ колонки

columns/name


Название колонки как в ТН

items


Массив заказов

items/properties

Массив пар «key-value».


items/properties/key

Id, Phone, AddressTo

Ключ свойства заказа

items/properties/value

12,0501234567, улица

Значение свойства заказа


{

    "report_name":"Отчет по заказам клиента"

    ,"columns":

    [

        {"key":"Id","name":"№"}

        ,{"key":"AddressFrom","name":"Адрес (начало)"}

        ,{"key":"AddressTo","name":"Адрес (конеч. точка)"}

        ,{"key":"AddressFromApartment","name":"Кв."}

        ,{"key":"AddressFromEntrance","name":"Подъезд"}

        ,{"key":"Phone","name":"Телефон"}

        ,{"key":"PhoneSecond","name":"Телефон 2"}

        ,{"key":"Cost","name":"Стоим."}

    ]

    ,"items":

    [

        {

        "properties":

        [

            {"key":"Id","value":"11094831"}

            ,{"key":"AddressFrom","value":"г. Акварель (пер. Столешников 3)"}

            ,{"key":"AddressTo","value":"Посольство Мексики (пер. Большой Левшинский 4)"}

            ,{"key":"AddressFromApartment","value":null}

            ,{"key":"AddressFromEntrance","value":"44"}

            ,{"key":"Phone","value":"050-123-45-67"}

            ,{"key":"PhoneSecond","value":null}

            ,{"key":"Cost","value":"26"}

        ]}

    ]

}

Запрос истории по заказам клиента:

http://<ipaddress>:<port>/api/clients/ordershistory?limit=10&offset=0&executionStatus=

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/ordershistory

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

limit

Нет

Вернуть количество записей

offset

Нет

Пропустить количество записей

executionStatus

Нет

Критерий выборки заказов в зависимости от статуса выполнения заказа (см. далее execution_status). В качестве параметра можно передавать перечень статусов выполнения заказа (Примечание 2) раздеденных запятой, которые необходимо получить. Например:

  • executionStatus=WaitingCarSearch,SearchesForCar,CarFound,Running,Canceled,Executed

  • или executionStatus=* - возвращает все заказы

  • отсутствующий параметр  executionStatus — эквивалентен executionStatus=Executed


Response (ответ):

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

Возможные значения

Описание

dispatching_order_uid

b8f3d3fa-0df0-4e0f-9def-725c7f1a2a40

GUID заказа

required_time

2013-08-13T12:02:10.689

Дата и время выполнения заказа

order_cost

Массив пар «key-name».

Стоимость заказа

user_full_name

Иванов Иван

Полное имя клиента

user_phone


Телефон клиента

route


Маршрут заказа

route/name

г. Акварель (пер. Столешников 3)

Улица или объект точки маршрута заказа

route/number

11а

Номер дома улицы точки маршрута заказа

close_reason

0

Статус закрытия заказа (см. Приложение 1)

execution_status

Executed

Статус выполнения заказа (см. Приложение 2)


[

    {

        "required_time":"2013-08-13T12:02:10.689"

        ,"order_cost":26.0

        ,"user_full_name":"Иванов Александр"

        ,"user_phone":"050-123-45-67"

        ,"route":

        [

            {"name":"г. Акварель (пер. Столешников 3)","number":null}

            ,{"name":"Посольство Мексики (пер. Большой Левшинский 4)","number":null}

        ]

    }

]

Запрос истории по изменениям бонусов клиента:

http://<ipaddress>:<port>/api/clients/bonusreport?limit=10&offset=0

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/bonusreport

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Обязательный параметр

Описание

limit

Нет

Вернуть количество записей

offset

Нет

Пропустить количество записей


Response (ответ):

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

Возможные значения

Описание

dispatching_order_uid

b8f3d3fa-0df0-4e0f-9def-725c7f1a2a40

GUID заказа

date

2013-08-13T12:02:10.689

Дата и время изменения бонуса

change_value

-115.0

Величина изменения бонуса

value_after_change

885.0 или null

Значение бонуса после изменения. Значение может быть Null для  reason_code = -1, т.к. бонусы могут быть списаны или возвращены клиенту.

reason_code              (*)

3

Причина изменения бонуса (код)

reason_descr


Причина изменения бонуса (описание)

order_route_info

ОЗЕРНАЯ УЛ. (ОБОЛОНЬ), 1 - ТУРОВСКАЯ УЛ., 1

Маршрут заказа, по которому произошло изменение бонуса

{"Items":[

{

    "date":"2015-04-27T11:56:55.071"

    ,"change_value":-115.0

    ,"value_after_change":885.0

    ,"reason_descr":"Закриття замовлення, сплаченого бонусом."

    ,"reason_code":3

    ,"order_route_info":"ОЗЕРНАЯ УЛ. (ОБОЛОНЬ), 1 - ТУРОВСКАЯ УЛ., 1"

    ,"dispatching_order_uid":"a7927211-b588-41c0-9285-455e61fb9240"}

]}


(* ) Данный параметр информирует о причине изменения бонуса. Возможные коды представлены в таблице:

Код

Описание

-1

«Замораживание» бонусов за выполняющиеся заказы. В случае закрытия заказа как «Выполненный» - бонусы будут окончательно списаны, иначе - возвращены клиенту.

0

Изменение диспетчером вручную

1

Закрытие выполненного заказа

2

Возврат выполненного заказа из архива

3

Отмена по вине диспетчера. Закрытие заказа, оплаченного бонусом

4

Возврат заказа, оплаченного бонусом, из архива


Запрос профиля клиента:

http://<ipaddress>:<port>/api/clients/profile

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/profile

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Response (ответ):

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

Тип данных

Возможные значения

Описание

user_login

String

user123

Логин пользователя в БД ТН.

user_first_name

String

Иванов

Фамилия

user_middle_name

String

Александр

Имя

user_last_name

String


Отчество

user_phone

String

050-123-45-67

Телефон

user_balance

Decimal

100

Текущий баланс пользователя

route_address_from

String


Адрес

route_address_number_from

String


Номер дома

route_address_entrance_from

Int32


Подъезд

route_address_apartment_from

Int32


Квартира

orders_count


0,15,121

Кол-во заказов постоянного клиента.

discount         (*)

Object


Текущая скидка клиента

discount/value

Decimal

15.00

Значение скидки

discount/unit

String

грн или %

Тип скидки (в деньгах, или процентах от стоимости заказа)

payment_type

Int32

0 или 1

Категория оплаты пользователя. 0 — нал, 1 — безнал.

client_bonuses

Decimal

885.00

Кол-во бонусов клиента (1 бонус = 1 денежной ед.)


{

    "user_login":"USER123"

    ,"user_first_name":"Александр"

    ,"user_middle_name":""

    ,"user_last_name":"Иванов"

    ,"user_phone":""

    ,"user_balance":0.0

    ,"route_address_from":"Край земли"

    ,"route_address_number_from":" 3"

    ,"route_address_entrance_from":0

    ,"route_address_apartment_from":0

    ,"orders_count":12

    ,"discount":{"value":15.00,"unit":"грн."}

    ,"payment_type":1

    , "client_bonuses":885.0

}


(* ) Информация о скидке клиента ("discount":{"value":15.00,"unit":"грн."})  возвращается также и в запросе авторизации /api/account. Значение в discount/unit указывает в каких единицах измеряется значение (discount/value) скидки:

  • Скидка на определенную сумму (Например: 15 грн)

  • Скидка на определенный процент от стоимости заказа (Например: 15%)

Запрос пяти самых новых адресов клиента:

Список самых новых адресов сформирован из 5 уникальных адресов, которые были использованы в выполненных заказах пассажира за последние 30 дней. Список отображается начиная с самых самых новых заказов, а также приоритет отдается начальным точкам в случае если в заказе больше пяти точек. 


http://<ipaddress>:<port>/api/clients/lastaddresses

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/lastaddresses

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Response (ответ):

Описание параметров маршрута:

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

Тип данных

Обязательный параметр

Возможные значения

Описание

name

String

Да


Адрес или название объекта

number

String

Нет


Номер дома (только для адреса)

lat

Decimal

Да. 0 - если не удалось сконвертировать

50.474613

Широта

lng

Decimal

Да. 0 - если не удалось сконвертировать

30.506389

Долгота


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

    [{
        "name":"ПОЛЕВАЯ УЛ.",
        "number":"22",
        "lat":50.4446405954674,
        "lng":30.4517342120499
    },
    {
        "name":"Маг ресторан (ул.Драгоманова 17)",
        "number":null,
        "lat":50.4085467285877,
        "lng":30.6397711113255
    },
    {
        "name":"МАГИСТРАЛЬНАЯ УЛ. (ВОСКРЕСЕНСКИЕ САДЫ ЗАЕЗД С ПР.ВАТУТИНА)",
        "number":"1",
        "lat":50.4856476589752,
        "lng":30.5707039640819
    },
    {
        "name":"Магелан трц (пр-т.Глушкова 13Б)",
        "number":null,
        "lat":50.3683475425517,
        "lng":30.4580907233347
    },
    {
        "name":"ПОЛЕВАЯ УЛ.",
        "number":"5",
        "lat":50.4452580988236,
        "lng":30.4522387353345
    }]

Обновление профиля клиента:

http://<ipaddress>:<port>/api/clients/profile

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/clients/profile

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Request (запрос):

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

Тип данных

Возможные значения

Описание

patch (*)


name, address

Обновление патчем.

user_first_name

String

Иван

Фамилия

user_middle_name

String

Иванович

Имя

user_last_name

String

Иванов

Отчество

route_address_from

String

пр. Шевченка

Адрес

route_address_number_from

String

Номер дома

route_address_entrance_from

Int32

2

Подъезд

route_address_apartment_from

Int32

3

Квартира

{

    "user_first_name":"Александр"

    ,"user_middle_name":""

    ,"user_last_name":"Иванов"

    ,"route_address_from":"Край земли"

    ,"route_address_number_from":" 3"

    ,"route_address_entrance_from":0

    ,"route_address_apartment_from":0

}

(*) Параметр «patch» требует дополнительного пояснения. «patch» - является необязательным параметром и позволяет выполнить частичное обновление (обновить только имя клиента, только адрес клиента, или и то и другое).

Возможный значения «patch»:

  • «name» - будет обновлена только группа полей: user_first_name, user_middle_name и user_last_name;

  • «address» - будет обновлена только группа полей: route_address_from, route_address_number_from, route_address_entrance_from и route_address_apartment_from;

  • Значения параметра «patch» можно объединять разделителем «,» (запятая);

  • Если «patch» не содержит значения — будут обновлены все поля.

Обновление информации для отправки push:

http://<ipaddress>:<port>/api/clients/credential

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/clients/credential

Headers

Content-Type: application/json; charset=utf-8

Authorization:Basic YWNod...YQ==

X-WO-API-APP-ID: App_name

Request (запрос):

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

Тип данных

Возможные значения

Описание

app_registration_token

String

не пустые значения

токен

{
"app_registration_token": "App_Token"
}


(*) Если значения X-WO-API-APP-ID нет в БД сервера или он пустой, он записан в профиль клиента не будет.

Смена телефона клиента

Получение кода подтверждения

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/clients/changePhone/sendConfirmCode

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:


Request (запрос):

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

Тип данных

Обязательный параметр

Описание

phone

String

Да

Номер мобильного телефона, на который будет отправлен код подтверждения.

taxiColumnId

Int32

Нет Номер колоны, из которой отправляется SMS (0, 1 или 2, по умолчанию 0).


Пример тела запроса в формате json:

{"phone":"380501234567"}



Response (ответ):

Статус ответа

Id ошибки

Описание

200 (OK)


Запрос успешно принят и обработан.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор».

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest) -15 Неверный номер колонны такси.
403 (Forbidden) -17 Операция отправки SMS не поддерживается настройками колонны «Такси Навигатор» (Настройки → СМС). Опция "Колонны, которым разрешена отправка СМС".


Пример тела запроса в формате json в случае неверного формата телефона:

{"Id":-34,"Message":"Invalid phone number."}

Смена телефона

Основные  параметры Http-запроса:

Http-метод

PUT

Url

/api/clients/changePhone/

Headers

Accept: application/json

Content-Type: application/json; charset=utf-8

Content-Length:


Request (запрос):

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

Тип данных

Обязательный параметр

Описание

phone

String

Да

Номер мобильного телефона.

confirm_code

String

Да

Код подтверждения.


Пример тела запроса в формате json:

{

"phone":"380501234567",

"confirm_code":"492164",

}



Response (ответ):

Статус ответа

Id ошибки

Описание

201 (Created)


Телефон успешно верифицирован.

429 (ToManyRequests)

-5

Слишком много запросов за короткое время.

403 (Forbidden)

-31

Операция запрещена настройками «Такси Навигатор».

400 (BadRequest)

-34

Неверный формат номера телефона.

400 (BadRequest)

-35

Неверный код подтверждения.


Пример тела запроса в формате json в случае неверно указанного кода подтверждения:

{"Id":-35,"Message":"Invalid confirmation code."}


Виртуальный баланс

Пополнение баланса клиента (прием платежей) через платежные системы

http://<ipaddress>:<port>/api/clients/balance/transactions/

Алгоритм приема платежей через платежную систему LiqPay.

1. Клиентское приложение, после успешной авторизации пользователя, присылает запрос на создание платежной транзакции.

2. После прохождения проверки на возможность создать транзакцию (пополнения баланс пользователя через платежную систему) - возвращается:

  • Уникальный идентификатор транзакции;

  • Сумма платежа;

  • Валюта платежа;

  • Описание платежа;

  • Уникальный идентификатор пользователя;

  • URL для получения изменений статуса платежа.

3. Клиентское приложение формирует запрос на проведение платежа через платежную систему LiqPay, указав все обязательные параметры.

4. Поле проведения оплаты через платежную систему, сервер ИДС получает от платежной системы информацию о статусе транзакции.

5. При успешном статусе транзакции - автоматически меняется статус транзакции и на баланс клиента зачисляется оплаченная сумма платежа.

6. Клиентское приложение опрашивает сервер для получения текущего статуса транзакции.

ВАЖНО! Необходимо обязательно указать параметр "server_url", иначе транзакция не будет завершена, и средства не будут автоматически начислены на баланс клиента.

Для LiqPay: http://<ipaddress>:<port>/api/liqpay/status/

Основные  параметры Http-запроса:

Http-метод

POST

Url

/api/clients/balance/transactions

Headers

Accept: application/json

Authorization:Basic YWNod...YQ

Request (запрос):

Название параметра

Обязательный параметр

Описание

amount

Да

Сумма платежа

{"amount": 25.75}

Response (ответ):

Название параметра

Возможные значения

Описание

id

37564

Уникальный идентификатор транзакции

amount

25.75

Сумма платежа

currency

UAH

Валюта платежа

description

Предоплата услуг.

Описание платежа

customer

10176

Уникальный идентификатор пользователя

statusCallbackURL

http://my_host.ua:6969/api/liqpay/status/

URL для получения изменеий статуса платежа


{

"id":37564,

"amount":25.75,

"currency":"UAH",

"description":"Предоплата услуг такси.",

"customer":10176,

"statusCallbackURL":"http://my_host.ua:6969/api/liqpay/status/"

}

Response в случае ошибок (ответ):

Статус ответа

Сообщение

401 (Unauthorized )

Клиент не авторизирован

503 (Service Unavailable)

Оплата через платежную систему запрещена.

400 (Bad Request)

Неверная категория клиента.

400 (Bad Request)

Вы заблокированы диспетчерской.

400 (Bad Request)

Пополнение для клиентов имеющих общий счет запрещено.

400 (Bad Request)

Минимально допустимая сумма пополнения через платежную систему составляет 5 UAH.

400 (Bad Request)

Максимально допустимая сумма пополнения через платежную систему составляет 1000 UAH.


{"Message":"Оплата через платежную систему запрещена."}

Получение транзакции оплаты

http://<ipaddress>:<port>/api/clients/balance/transactions/<id>

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/balance/transaction/<id>

Headers

Accept: application/json

Authorization:Basic YWNod...YQ

Request (запрос):

Название параметра

Обязательный параметр

Описание

id

Да

Уникальный идентификатор транзакции

Response (ответ):

Название параметра

Возможные значения

Описание

Id 37671 Идентификатор транзакции

status

Success

Статус транзакции

status_description Успешно проведенная транзакция Локализированное описание статуса
kind Dispatcher Вид транзакции
kind_description Начисление/Списание средств диспетчером такси Описание вида транзакции
balance 12.0 Текущий баланс
amount 12.0 Сумма транзакции
time 2017-05-23T16:42:53.742 Время проведения транзакции

Описание статусов транзакции:

Статус транзакции

Описание статуса

Created

Созданная транзакция.

Success

Успешно проведенная транзакция.

Processing

Транзакция в обработке.

Failure

Неуспешная транзакция.

Reversed

Транзакция возврата. (Платеж возвращен).

Sandbox

Тестовая транзакция.

Unknown

Тип транзакции не определен.

Описание видов транзакции:

Вид

Описание

Dispatcher Начисление/Списание средств диспетчером такси
Order Списание с баланса за выполненный заказ
Internet Пополнение баланса через интернет


{

   "id":37671,

   "amount":12.0,

   "balance":12.0,

   "time":"2017-05-23T16:42:53.742",

   "kind":"Dispatcher",

   "status":"Success",

   "status_description":"Успешно проведенная транзакция",

   "kind_description":"Начисление/Списание средств диспетчером такси"

}

История изменения баланса

http://<ipaddress>:<port>/api/clients/balance/transactions/

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/clients/balance/transactions/

Headers

Accept: application/json

Authorization:Basic YWNod...YQ


Request (запрос):

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

Обязательный параметр

Описание

limit

Нет

Вернуть количество записей

offset

Нет

Пропустить количество записей

Response (ответ):

Возвращается список последних транзакций клиента.

Описание полей ответа см. в Получение транзакции оплаты

Гео данные

Запрос гео-данных (всех объектов):

http://<ipaddress>:<port>/api/geodata/objects?versionDateGratherThan=03.01.2013 10:45:45.944

Данный запрос возвращает информацию о всех объектах.

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/objects

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):

Название параметра

Обязательный параметр

Описание

versionDateGratherThan

Нет

Дата версии гео-данных полученных ранее.*

Если параметр пропущен — возвращает  последние гео-данные.


Response (ответ):

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

Возможные значения

Описание

version_date


Версия гео-данных.

geo_object


Объект

geo_data_info



name

Крещатик

Название объекта (нейтральной локализации)

localizations

Массив значений

Массив локализированных названий

localizations/locale

en

Название локализации

localizations/name

Khreschatyk

Локализированное название


{

    "geo_object":

        [

            {"name":"м. Строгино",

                "localizations":[

                    {"locale":"UK","name":"м. Строгіно"},                                {"locale":"EN","name":"Strogino Station."}]

            }

            ,{"name":"м. Крылатское"}

            ,{"name":"м. Молодежная"}

            ,{"name":"м. Планерная"}

            ,{"name":"м. Тушинская"}

            ,{"name":"м. Сходненская"}

            ,{"name":"м. Кунцевская"}

            ,{"name":"м. Щукинская"}

    ,"version_date":"11.07.2013 15:14:13.887"

    ,"geo_data_info":null

}


* Возвращает гео-данные с датой создания позднее, чем данное значение version_date, иначе возвращает следующий результат:

{

    "geo_object":null

    ,"version_date":null

    ,"geo_data_info":"Гео данные отсутствуют."

}


Поиск гео-данных (объектов) по нескольким буквам

http://<ipaddress>:<port>/api/geodata/objects/search?q=search&offset=0&limit=10&translitetion=true&qwertySwitcher=true&fields=*

Данный запрос возвращает только те объекты, названия которых содержат заданное пользователем подслово.

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/objects/search

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Accept-Language: UA


В случае, если в комплексе «Такси Навигатор» ИДС присутствуют названия гео-данных (улицы, объекты) на разных языках, заданием HTTP-заголовка «Accept-Language» можно запросить предпочитаемые локализованные названия.

Request (запрос):

Название параметра

Обязательный параметр

Значение по-умолчанию

Описание

q

Да


Несколько букв для поиска объекта.

offset

Нет

0

Смещение при выборке (сколько пропустить).

limit

Нет

10

Кол-во возвращаемых записей (предел).

transliteration

Нет

TRUE

Разрешить транслитерацию запроса при поиске.

qwertySwitcher

Нет

TRUE

Разрешить преобразование строки запроса в случае ошибочного набора с неверной раскладкой клавиатуры (qwerty). Например, «ghbdtn» - это «привет».

fields

Нет

* (все поля)

Данным параметром можно указать перечень требуемых параметров, которые будут возвращаться в ответе. Разделяются запятой.

Возможные значения:

  • * (возвращает все поля)

  • name

  • lat

  • lng

  • locale


Response (ответ):

Ответ такой же как и для запроса всех объектов.

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

Возможные значения

Описание

version_date


Версия гео-данных.

geo_object


Объект

geo_data_info



name


Название объекта

locale

UK

Локализация названия


Запрос гео-данных (всех улиц):

http://<ipaddress>:<port>/api/geodata/streets?versionDateGratherThan=03.01.2013 10:45:45.944

Данный запрос возвращает информацию о всех улицах.

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/streets

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):

Название параметра

Обязательный параметр

Описание


versionDateGratherThan


Нет

Дата версии гео-данных полученных ранее.*

Если параметр пропущен — возвращает  последние гео-данные.

Response (ответ):

Название параметра

Возможные значения

Описание

version_date


Версия гео-данных.

geo_street


Объект

geo_data_info



name

Крещатик

Название улицы

localizations

Массив значений

Массив локализированных названий

localizations/locale

en

Название локализации

localizations/name

Khreschatyk

Локализированное название


{

    "geo_street":

    [

        { "name":"КРЕЩАТИК УЛ.","old_name":null,

                "localizations":[

                    {"locale":"UK","name":"Хрещатик Вул."},                                {"locale":"EN","name":"Khreschatyk  St."}] },

        { "name":"ТУРОВСКАЯ УЛ","old_name":null }

    ]

    ,"version_date":"11.07.2013 15:14:13.893"

    ,"geo_data_info":null

}


* Возвращает гео-данные с датой создания позднее, чем данное значение version_date, иначе возвращает следующий результат:

{

    "geo_street":null

    ,"version_date":null

    ,"geo_data_info":"Гео данные отсутствуют."

}

Поиск гео-данных (улиц) по нескольким буквам

http://<ipaddress>:<port>/api/geodata/streets/search?q=search&offset=0&limit=10  

Данный запрос возвращает только те улицы, названия которых содержат заданное пользователем подслово (но не больше 10 записей).

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/streets/search?q=search

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==

Accept-Language: UA

В случае, если в комплексе «Такси Навигатор» ИДС присутствуют названия гео-данных (улицы, объекты) на разных языках, заданием HTTP-заголовка «Accept-Language» можно запросить предпочитаемые локализованные названия.

Request (запрос):

Название параметра

Обязательный параметр

Значение по-умолчанию

Описание

q

Да


Несколько букв для поиска объекта.

offset

Нет

0

Смещение при выборке (сколько пропустить).

limit

Нет

10

Кол-во возвращаемых записей (предел).

transliteration

Нет

TRUE

Разрешить транслитерацию запроса при поиске.

qwertySwitcher

Нет

TRUE

Разрешить преобразование строки запроса в случае ошибочного набора с неверной раскладкой клавиатуры (qwerty). Например, «ghbdtn» - это «привет».

fields

Нет

* (все поля)

Данным параметром можно указать перечень требуемых параметров, которые будут возвращаться в ответе. Разделяются запятой.

Возможные значения:

  • * (возвращает все поля)

  • name

  • old_name

  • houses

  • lat

  • lng

  • locale

Response (ответ):

Ответ такой же как и для запроса всех улиц.

Название параметра

Возможные значения

Описание

version_date


Версия гео-данных.

geo_street


Объект

geo_data_info



name


Название улицы

locale

UK

Локализация названия


Поиск гео-данных (улиц и объектов) по нескольким буквам

http://<ipaddress>:<port>/api/geodata/search?q=search&offset=0&limit=10  

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/search?q=search

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):

Название параметра

Обязательный параметр

Значение по-умолчанию

Описание

q

Да


Несколько букв для поиска объекта.

offset

Нет

0

Смещение при выборке (сколько пропустить).

limit

Нет

10

Кол-во возвращаемых записей (предел).

transliteration

Нет

TRUE

Разрешить транслитерацию запроса при поиске.

qwertySwitcher

Нет

TRUE

Разрешить преобразование строки запроса в случае ошибочного набора с неверной раскладкой клавиатуры (qwerty). Например, «ghbdtn» - это «привет».

fields

Нет

* (все поля)

Данным параметром можно указать перечень требуемых параметров, которые будут возвращаться в ответе. Разделяются запятой.

Возможные значения:

  • * (возвращает все поля)

  • name

  • old_name

  • houses

  • lat

  • lng

  • locale

Response (ответ):

Ответ содержит объединение ответов как для объектов и улиц.

Название параметра

Возможные значения

Описание

version_date


Версия гео-данных.

geo_streets


Улицы

geo_streets/geo_street


Улица

geo_streets/name


Название улицы

geo_streets/house


Номер дома

geo_streets/locale

UK

Локализация названия

geo_objects


Объекты

geo_objects/geo_object


Объект

geo_objects/name


Название объекта

geo_objects/locale

UK

Локализация названия

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


{

    "geo_streets": {

        "geo_street": [

            {

                "name": "МЕТРОЛОГИЧЕСКАЯ УЛ.",

                "old_name": "",

                "houses": [

                    {

                        "house": "1",

                        "lat": 50.3498920971102,

                        "lng": 30.4785418170961

                    }

                ],

                "locale": ""

            },

            {

                "name": "МЕТРОСТРОЕВСКАЯ УЛ.",

                "old_name": "",

                "houses": [

                    {

                        "house": "1/33",

                        "lat": 50.4436917261033,

                        "lng": 30.4109354329844

                    }

                ],

                "locale": ""

            }

        ],

        "version_date": "14.02.2017 17:46:32.490",

        "geo_data_info": null

    },

    "geo_objects": {

        "geo_object": [

            {

                "name": "Метро гипермаркет (Кольцевая дорога 1В)",

                "lat": 50.3796959576459,

                "lng": 30.4437467371263,

                "locale": ""

            },

            {

                "name": "Метро гипермаркет (пр-т.Григоренко 43)",

                "lat": 50.390969480649,

                "lng": 30.6397351808339,

                "locale": ""

            },

            {

                "name": "Метро гипермаркет (пр-т.Московский 26В)",

                "lat": 50.4874368743464,

                "lng": 30.5175750660492,

                "locale": ""

            }

        ],

        "version_date": "14.02.2017 17:46:29.749",

        "geo_data_info": null

    }

}


geo_object


Объект

name


Название объекта

Поиск ближайших гео-данных (улиц и объектов) по  географическим координатам (долгота-широта)

http://<ipaddress>:<port>/api/geodata/search?lat=50.447878&lng=30.522925&r=500

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/search?lat=50/4478&lng=30.522925&r=500

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):

Название параметра

Обязательный параметр

Описание

lat

Да

Широта

lng

Да

Долгота

r

Нет

Радиус поиска. Значение от 0 до 1000 м. Если не указано — 500м.


Response (ответ):

Название параметра

Возможные значения

Описание

geo_streets


Массив улиц

geo_streets/geo_street


Улица

geo_streets/geo_street/name


Название улицы

geo_streets/geo_street/houses


Массив домов улицы

geo_streets/geo_street/houses/house


Номер дома

geo_streets/geo_street/houses/lng


Широта дома

geo_streets/geo_street/houses/lat


Долгота дома

geo_objects


Массив объектов

geo_objects/geo_object


Объект

geo_objects/geo_object/name


Название объекта

geo_objects/geo_object/lat


Широта объекта

geo_objects/geo_object/lng


Долгота объекта


{

 "geo_streets":

   {"geo_street":[

        {"name":"КРЕЩАТИК УЛ.","old_name":null,

            "houses":[

                {"house":"19А","lat":50.447059,"lng":30.523166},

                {"house":"28/2","lat":50.448310,"lng":30.521846}]},

        {"name":"ГОРОДЕЦКОГО АРХИТЕКТОРА УЛ.","old_name":null,

            "houses":[

                {"house":"2","lat":50.448844,"lng":30.523685},

                {"house":"4","lat":50.448802,"lng":30.524045}]}]}

 ,"geo_objects":

   {"geo_object":[

       {"name":"Р Мак Дональдз (ул.Крещатик 19-а)","lat":50.446979,"lng":30.522901},

       {"name":"Министерство аграрной политики","lat":50.448841,"lng":30.522176}]}

}

Поиск ближайшей геоточки (улицы или объекта) по  географическим координатам (долгота-широта).

http://<ipaddress>:<port>/api/geodata/nearest?lat=50.447878&lng=30.522925&r=500

Работает по тому же принципу что и "Поиск ближайших гео-данных (улиц и объектов) по географическим координатам (долгота-широта)." только возвращает один ближайшей объект или дом. Также если дом или объект не найден то свойства "geo_street" или "geo_object" будут содержать пустые масивы вместо null.

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/geodata/nearest?lat=50/4478&lng=30.522925&r=500

Headers

Accept: application/json

Authorization:Basic YWNod...YQ==


Request (запрос):

Название параметра

Обязательный параметр

Описание

lat

Да

Широта

lng

Да

Долгота

r

Нет

Радиус поиска. Значение от 0 до 1000 м. Если не указано — 500м.


Response (ответ):

Название параметра

Возможные значения

Описание

geo_streets


Массив улиц

geo_streets/geo_street


Улица

geo_streets/geo_street/name


Название улицы

geo_streets/geo_street/houses


Массив домов улицы

geo_streets/geo_street/houses/house


Номер дома

geo_streets/geo_street/houses/lng


Широта дома

geo_streets/geo_street/houses/lat


Долгота дома

geo_objects


Массив объектов

geo_objects/geo_object


Объект

geo_objects/geo_object/name


Название объекта

geo_objects/geo_object/lat


Широта объекта

geo_objects/geo_object/lng


Долгота объекта

Найден ближайший объект в радиусе:

{
    "geo_streets":{
        "geo_street":[],
        "version_date":null,
        "geo_data_info":null
    },
    "geo_objects":{
        "geo_object":[
            {
                "name":"Мистер Снек Сэндвич-бар (ул.Льва Толстого 1/24)",
                "lat":50.439333791428,
                "lng":30.5152751207382,
                "locale":""
            }],
        "version_date":null,
        "geo_data_info":null
    }
}


Найден ближайший дом в радиусе:

{
   "geo_streets":{
       "geo_street":[
           {
           "name":"ВАСИЛЬКОВСКАЯ УЛ.",
           "old_name":"",
           "houses":[
               {
               "house":"18",
               "lat":50.3956671952438,
               "lng":30.5006795200616
           }],
       "locale":""
       } ],
      "version_date":null,
      "geo_data_info":null
     },
      "geo_objects":{
      "geo_object":[],
      "version_date":null,
      "geo_data_info":null
      }
}


Ближайший дом или объект не найдены:

{
   "geo_streets":{
      "geo_street":[],
      "version_date":null,
      "geo_data_info":null
   },
   "geo_objects":{
      "geo_object":[],
      "version_date":null,
      "geo_data_info":null
   }
}

Запрос настроек

http://<ipaddress>:<port>/api/settings

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/settings


Response (ответ):

Название параметра

Возможные значения

Описание

currency

грн

Аббревиатура валюты

payment_terminal_permitted

True, false

Разрешена ли оплата заказа через платежный (экварийнговый) терминал для клиента.

payment_system_permitted 0, 1 Возможность оплаты через платежную систему
add_cost_increment_value 1, 5 Шаг изменения стоимости на widget.


{

    "currency":"грн",

    "payment_terminal_permitted":false ,

    "payment_system_permitted": 0,

    "add_cost_increment_value": 1

}

Запрос настроек шага добавочной стоимости

http://<ipaddress>:<port>/api/settings/addCostIncrementValue

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/settings/addCostIncrementValue


Response (ответ):

Название параметра

Возможные значения

Описание

- Decimal Шаг изменения стоимости на widget.


Запрос серверного времени

http://<ipaddress>:<port>/api/time

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/time


Response (ответ):

Название параметра

Возможные значения

Описание

datetime_now_utc

Thu, 24 Oct 2013 12:49:28 GMT

http://tools.ietf.org/html/rfc1123

datetime_now_unix

1382618968

http://ru.wikipedia.org/wiki/UNIX-%D0%B2%D1%80%D0%B5%D0%BC%D1%8F

Запрос версии TaxiNavigator

http://<ipaddress>:<port>/api/tnVersion

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/tnVersion


Response (ответ):

Название параметра

Возможные значения

Описание

tn_version

29.3.2.61


Получение координат автомобилей в радиусе

http://<ipaddress>:<port>/api/drivers/position?lat=<latitude>&lng=<longitude>&radius=<km>

Основные  параметры Http-запроса:

Http-метод

GET

Url

/api/drivers/position?lat=<latitude>&lng=<longitude>&radius=<km>

Headers

Accept: application/json

Authorization:Basic YWNod...YQ

Request (запрос):

Название параметра

Обязательный параметр

Описание

latitude

Да

Широта

longitude

Да

Долгота

radius

Да

Радиус поиска автомобилей (в км.)

Response (ответ):

Название параметра

Возможные значения

Описание

drivercar_position

Object

Текущее положение автомобиля. (См. Запрос GPS положения машины, выполняющей заказ)

car.types

["Wagon", "Minibus", "Truck", "Premium", "Elite"]

Тип автомобиля

car.options

["AirConditioning", "Terminal"]

Дополнительные опции

state

Closed, Free, Busy

Статус водителя.

[{ 
  "drivercar_position":{

     "lat":50.50768,

     "lng":30.602053,

     "time_positioned_utc":"2016-05-13T21:05:52.488",

     "altitude":190,

     "accuracy":31,

     "bearing":null,

     "speed":0,

     "status":"gpsOk"

  },

  "car":{

     "types":["Wagon", "Premium", "Elite"],

     "options":["AirConditioning"]

  },

  "state":"Free"
}]

ПРИЛОЖЕНИЕ 1. Описание статусов закрытия заказа «close_reason»:

-1

Выполняется

0

Выполнен

1

Отказ клиента

2

Отказ водителя

3

Отмена по вине диспетчера

4

Нет машины

5

Просчет

6

Отказ клиента не устроил тариф

7

Отказ клиента не устроило время

8

Перекинут на СОЗ (выполнен)

9

Перекинут на СОЗ (выполнен)


* СОЗ — сервер обмена заказами между ИДС.

ПРИЛОЖЕНИЕ 2. Описание статусов закрытия заказа «execution_status»:

WaitingCarSearch

Ожадается поиск машины (для предварительного заказа)

SearchesForCar

Выполняется поиск машины

CarFound

Машина найдена

Running

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

Canceled

Заказ отменен (клиентом, диспетчером, водителем)

Executed

Заказ успешно выполнен

CostCalculation Просчет

ПРИЛОЖЕНИЕ 3. Результат в виде ошибки выполнения операции

В случае неудовлетворения привалам бизнес процесса, сервер может возвращать ошибку в виде кода ошибки и ее описания. Ниже представлены 2 разных сообщения об ошибке:

{"Id":-11, "Message":"Вы заблокированы диспетчерской." }

{"Id":-2, "Message":"В выполнении запроса отказано авторизацией."}


Значения error id:

Id

Описание

0

Неизвестная ошибка.

-2

Ошибка авторизации пользователя. Неверно указан логин или пароль.

-3

Не удалось найти пользователя по запрошенному логину или номеру телефона.

-4

Не удалось найти пользователя по его номеру телефона, так как таких пользователей несколько.

-5

Слишком много запросов за короткое время.

-10

Неверные параметры запроса.

-11

Ошибка выполнения заказа, т.к. пользователь заблокирован диспетчерской.

-12

Ошибка выполнения заказа, т.к. недостаточно денег на балансе для выполнения заказа.

-13

Ошибка создания заказа, т.к. указанного адреса (улицы) нет в базе данных.

-14

Ошибка создания заказа, т.к. указанного адреса (объекта) нет в базе данных.

-15

Неверный номер колоны.

-16

Использование терминала запрещено настройками в диспетчерской.

-20

Дублирование запроса. Подобный запрос уже обрабатывается.

-21

Дублирование заказа. Вы не можете создавать подобный заказ, пока не нашлась машина на предыдущий заказ.

-22

Ошибка преобразования ид локальных координат в географические (долгота, широта), или наоборот.

-23

Номер телефона в черном списке.

-24

Оплата наличными запрещена.

-25

Безналичный расчет запрещен.

-30

Неизвестная ошибка регистрации.

-31

Операция запрещена настройками «Такси Навигатор».

-32

Пользователь с таким номером телефона уже зарегистрирован.

-34

Неверный формат номера телефона.

-35

Неверный код подтверждения.

-36

Не указан пароль.

-37

Пароль подтверждения не соответствует паролю.

-38

Длина пароля не удовлетворяет условию от 7 до 30 символов.

-40

Операция запрещена. Требуется подтверждение телефона.

-42

Ошибка верификации телефона. Телефон уже подтвержден.

-50

Использование бонусов запрещено настройками «Такси Навигатор» или пользователь неавторизирован.

-51

У пользователя недостаточно бонусов для оплаты заказа.

-52

Бонусов для оплаты меньше, чем стоимость заказа.

-53

Оплата бонусами невозможна для заказа «по городу».

-54

Дата и время подачи машины должно быть позже <даты>

-55

Добавочная сумма должна быть больше -100000 и меньше 100000

-100

Ошибка выполнения операции.

ПРИЛОЖЕНИЕ 4. Описание типов оплаты заказа «payment_type»:

Оплату заказа можно осуществить наличным или безналичным расчетом. Постоянные клиенты могут выполнять безналичный и наличный расчет . Не авторизированные пользователи могут выполнять только наличный расчет. Рекомендуется явно указывать тип оплаты для пользователя при создании заказа.

Описание значений поля payment_type:

null

Тип оплаты по-умолчанию.

  • Для не авторизированных клиентов и постоянных клиентов категории «наличные» - тип оплаты «наличный» Эквивалентен значению 0.

  • Для постоянных клиентов категории «безналичные» - тип оплаты «безналичный». Эквивалентен значению 1.

0

Наличный

1

Безналичный

ПРИЛОЖЕНИЕ 5. Описание статусов GPS координат:

Таблица. Описание статусов GPS координат.

Статус GPS координат

Описание

gpsOk

GPS точка актуальная.

gpsExpired

GPS точка устаревшая. Время позиционирования отличается от текущего времени более чем на 1 минуту.

gpsUnavailable

GPS точка отсутствует (на заказ еще не назначена машина или трекер отсутствует).

ПРИЛОЖЕНИЕ 6. Описание "Статус выполнения":

Таблица. Описание "Статус выполнения".

Статус выполнения

Описание

0

Значение по умолчанию.

1

Опоздание.

2

По адресу.

3

Выводите пассажиров.

4

Простаиваю.

5

С пассажиром.

6

Продление маршрута.

7

Закрыть заказ.

8

Сняться с заказа.

9

Не могу найти.

10

Вовремя буду на предварительном заказе.

11 Простой начат.
12 Простой завершен.

Настройка языковых предпочтений (локализация сообщений)

Для того чтобы получать локализированные сообщения в ответах от WebOrders,WebApi необходимо в заголовке запроса передать Accept-Language заголовок.

Поддерживаемые на данный момент локализации:

  • EN-US (используется по-умолчанию)

  • RU-RU

  • UK-UA

  • KA-GE

  • PL-PL


Например: Accept-Language: ru, uk-ua;q=0.8, en;q=0.7

Сжатие данных Http-ответа

При запросе ресурса клиент может сообщить серверу, какие алгоритмы сжатия он поддерживает в заголовке Accept-Encoding:

  • gzip

  • deflate


Например: Accept-Encoding: gzip, deflate


WebOrders.WebApi в случае выполнения сжатия добавит в ответ заголовок Content-Encoding с указанием используемого алгоритма сжатия.


Например: Content-Encoding: gzip

Установка идентификатора приложения

Для того чтобы иметь возможность в «Полном отчете по заказам» в «Такси навигаторе» видеть с какого приложения был оформлен заказ — необходимо добавить HTTP заголовок «X-WO-API-APP-ID», значение которого не должно превышать 20 символов.

Например:

X-WO-API-APP-ID: my_app_id

Так же, по значению этого хедера возможно начисление бонусов постоянному клиенту (пассажиру) за первую регистрацию/авторизацию.