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

Все запросы делаются через протокол HTTP по адресам, описанным ниже. Часть <pref> в каждом адресе должна быть заменена на настоящий префикс. Например, если <pref>="/foo/bar", то GET <pref>/index.html становится GET /foo/bar/index.html.

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

Все описанные здесь запросы приводят к ответу в формате JSON. Любой ответ содержит поля "errno" и "errstr", позволяющие проверить отсутствие ошибок.

{
"errno": <errno>,
"errstr": <errstr>,
<другие поля...>
}

Для каждого успешного запроса значение <errno> будет равно нулю (0), а значение <errstr> — "ok". В случае ошибки <errno> будет иметь положительное значение, а <errstr> будет содержать сообщение об ошибке.

Работа

Суть работы сводится к циклу:

При наличии текущего заказа его можно отменить запросом cancel-order.

Registration

Каждый клиент проходит одноразовую регистрацию на сервере и получает уникальный идентификатор. Этот идентификатор следует сохранить и использовать в будущем.

POST <pref>/registration

Post-данные

uuid
Идентификатор копии приложения или устройства.
version
Версия клиента в форме «<имя> <число>». Например, «jscore 5»
host
"Платформа", на которой работает клиент. Если это веб-клиент, то имя сервера (например, "ontax.by"); если это приложение, то краткое описание операционной системы (например, "Android 4.4").
customer_name
Имя клиента
customer_phone
Номер телефона клиента в полном формате (например, "+375121234567").

Ответ

{
user_id: <идентификатор клиента>
errno: <errno>
errstr: <errstr>
}

Init

Перед работой с заказами клиент должен открыть сеанс, послав запрос "init".

Адрес
GET <pref>/init?user_id=<user_id>
Ответ
{
token: <token>
errno: <errno>
errstr: <errstr>
}
<user_id>
идентификатор клиента, полученный при регистрации.
<token>
временный ключ для доступа к остальным запросам.

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

POST <pref>/order?t=<token>&order_id=<order_id>

<order_id> — UUID заказа, сгенерированный клиентом.

Post-данные
address_place, address_street, address_house, address_building Задают адрес заказа.
latitude, longitude GPS-координаты заказа.
comments Комментарии к заказу.

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

Ответ: стандартный с полями "errno" и "errstr".

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

POST <pref>/cancel-order?t=<token>&order_id=<order_id>

Post-данные
reason Причина отмены заказа.

Причина отмены может быть текстом, введённым пользователем, либо строкой, указанной приложением.

Ответ: стандартный с полями "errno" и "errstr".

Состояние заказа

При наличии заказа его состояние можно проверить с помощью запроса: GET <pref>/order-status?t=<token>&order_id=<order_id>

Формат ответа: {
errno: <errno>,
errstr: <errstr>,
status: <order status>
}

Состояния заказов
searching Идёт поиск машин, нужно подождать.
no_cars Не удалось найти машины, заказ закрыт.
found_cars Машины найдены, идёт опрос водителей, нужно подождать.
assigned Заказ принят водителем.
arrived Машина прибыла к месту подачи, нужно сообщить пользователю.
started Таксометр запущен, заказ начался.
finished Таксометр остановлен, заказ завершён.
cancelled Заказ отменён.

Положение машины

Положение заказанной машины можно получить с помощью запроса: GET <pref>/car-position?t=<token>&order_id=<order_id>

Формат ответа: {
errno: <errno>,
errstr: <errstr>,
position: [lat, lon],
distance: <car distance>
}

<car distance> — расстояние от машины до места подачи в метрах.

Положение машины можно получить только для заказа, который принят, но ещё не начат.

Список заказов

GET <pref>/last-orders?t=<token>[&num=<orders number>]

Необязательный параметр "num" задаёт количество заказов. По умолчанию он принимается равным 1.

Формат ответа: {
errno: <errno>,
errstr: <errstr>,
list: [
{
uid: <order uid>,
status: <order status>,
address_place: <place>,
address_street: <street>,
address_house: <house>,
address_building: <building>,
address_entrance: <entrance>,
comments: <comments>,
car_name: <car name>,
car_color: <car color>,
car_plate: <car plate>,
car_driver: <car driver>,
service_id: <service id>,
service_name: <service name>,
time_created: <time>

},
...
]
}

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

Отправка отзыва

POST <pref>/order-feedback?t=<token>&order_id=<order_uid>

Post-данные
mark Оценка, число от 0.0 до 1.0
comments Комментарии к оценке

Ответ: стандартный с полями "errno" и "errstr".

К одному заказу можно оставить не более одного отзыва. Отзыв и оценку можно изменить, отправив запрос ещё раз.

Получение отправленного отзыва

Получить отправленный ранее отзыв можно по тому же адресу, только вместо действия POST следует использовать GET:

GET <pref>/order-feedback?t=<token>&order_id=<order_id>

Ответ будет иметь формат:

{
timestamp: <time>,
comments: <text>,
mark: <mark>,
errno: <errno>,
errstr: <errstr>

}