API обменника для исполнителя заказов
ДАННЫЙ ПРОТОКОЛ НАХОДИТСЯ В СТАДИИ РАЗРАБОТКИ! Использование данного протокола не доступно!
Версии
- 2016-11-28 - Изменена структура
statusдля соответствияack - 2016-11-11 - Изменена структура
ackдля устранения дублирования и добавление новых полей - 2016-10-31 - предварительная версия
Введение
Работа с заказами состоит из следующих стадий
- Обменник предлагает заказ (
request) - Внешняя система сообщает о том, что у нее есть исполнитель для данного заказа (
ack) - Обменник назначает заказ внешней системе (
setorder), либо отменяет заказ (cancel) - По завершении заказа Обменник сообщает внешней системе дополнительные данные (оценку клиента, коментарий клиента по заказу)
В процессе работы обменник может передавать показания таксометра на выбранный URL (если он прописан)
Запросы к внешней системе
Предложение заказа (request)
В POST-теле запроса будет JSON вида:
{
"id": "9d88e3ee976e11e69add6f31c648b566",
"version": 1,
"from": {
"address": "Россия, Москва, Таганрогская улица, 29",
"porch": 3,
"lon": 33,
"lat": 55
},
"to": {
"address": "Россия, Московская область, Домодедово аэропорт",
"porch": 2,
"lon": 33,
"lat": 55
},
"client": {
"name": "Пупкин Василий",
"comment": "Можно приехать минут на 10 пораньше"
},
"booking_time": "2013-01-02 23:00:00 +0400",
"booking_time_exact": 1,
"status": "request",
"messenger": {
"tariff": 1,
"category": "business",
"comment": "Сказать клиенту пароль: я от Семена",
"minprice": 450,
"inctime": 30,
"incdist": 20,
"timecost": 11,
"distcost": 22,
"transfer": 1,
"algorithm": "max",
"distcost_cad": 20,
"distcost_out": 30,
"timecost_cad": 10,
"timecost_out": 15,
"distcost_service_out": 200,
"add_minprice": 400,
"add_minprice_transfer": 500,
"included_req_costs": 1,
"distcost_unit": 15,
"timecost_unit": 20,
"speed": 20,
"speed_time_markup": 12.1,
"time_free": 10,
"time_cost_wait": 11,
"hide_client_phone": 1,
"ready_disable": 1,
"waiting_included": 0,
"contact": {
"phone": "+79261234567",
"title": "гендиректор диспетчерской Такси-супер"
}
},
"requirement": {
"has_conditioner": 1,
"no_smoking": 0,
"child_chair": 0,
"childseat_amount": 0,
"childcradle_amount": 2,
"childbooster_amount": 3,
"animal_transport": 1,
"universal": 0,
"wifi": 1,
"check": 0,
"card": 1,
"noncash": 0,
"special_number": 1,
"no_brand": 0,
"car_license": 1,
"driver_license": 1,
"driver_rating": 1
},
"fee": {
"fix": 10,
"relative": 5
}
}
Расшифровку полей можно посмотреть в put
Пояснения по передаваемым полям:
- Клиент передается без телефона.
-
statusдля предложения всегдаrequest -
version- номер версии заказа. Запросы доставляются асинхронно, поэтому могут прийти в разном порядке. Если Вы приняли запрос сversion=7, то можете смело игнорировать запросы сversion=6и ниже. Данные в заказе от версии к версии могут изменяться.
Закрепление заказа (setorder)
В POST-теле запроса будет JSON аналогичный Предложение заказа:
{
...
"client": {
...
"phone": "+7123456789",
},
"status": "confirm",
}
Расшифровку полей можно посмотреть в put
Пояснения по передаваемым полям:
- Передается телефон клиента.
-
statusвсегдаconfirm
Отмена заказа (cancel)
Вызывается если заказ был отменен, просрочен или ушел в другую службу. POST-тело будет содержать следующие данные:
{
"id": 12345,
"status": "cancelled",
"comment": "Клиент отменил заказ"
}
где поля:
-
id- ID заказа -
status- статус заказа:cancelled- отменен клиентомcancelled_user- отменен создателемfailed- отменен исполнителемassigned- распределен другому клиентуtimeout- просрочен
-
comment- коментарий к отмене заказа
Передача показаний таксометра
Вызывается для заказов в статусе transporting с частотой примерно 1 раз в минуту.
Важно: на показания таксометра влияет то передаются ли координаты водителя, выполняющего данный заказ или нет. Если координаты по какой-то причине не передаются, то стоимости дистанций, а так же стоимости движения за городом, указанные в тарифах могут быть определены неверно (занижены).
POST-тело запроса будет содержать следующие данные:
[
{
"id": 1234,
"txm": {
"point": {
"lon": 37.234,
"lat": 55.345,
"dist": 12345
},
"time": {
"total": 27,
"pause": 11,
"begin": '2016-10-30 21:23:12 +0300',
"cost": 73.00
},
"dist": {
"total": 6300,
"begin": 6045,
},
"cost": {
"total": 143.34,
"time": 73.00,
"universal": 20.11,
"dist": 50.23
}
}
}
]
где поля:
id- идентификатор заказа (в одном запросе могут передаваться таксометры по нескольким заказам)txm- расчитанный таксометр
Отзыв по заказу (feedback)
Если клиент оценил поездку то передается отзыв по ней. POST-тело будет содержать следующие данные:
{
"id": 12345,
"rating": 4,
"comment": "Поездка прошла хорошо"
}
Оценки будут отправляться только в статусах:
-
complete- выполнен -
cancelled- отменен клиентом -
cancelled_user- отменен создателем -
failed- сорван
Обратные запросы к ОБМЕННИКУ
api/APIKEY/order/ack
При получении предложения заказа КЛИЕНТ решает будет он выполнять этот заказ или нет. Если КЛИЕНТ хочет выполнить данный заказ он отпраляет в ОБМЕННИК согласие. Это POST запрос с телом в формате JSON:
{
"id": 12345,
"tariff":[1,2],
"driver_details": {
"sign": "007",
"name": "Васисуалий Пупкин",
"phone": "+79876543210",
"license": "A1234556"
},
"car_details": {
"brand": "Мерседес",
"model": "600",
"color": "зеленый",
"age": 1991,
"number": "762",
"license": "МО 123456"
},
"point": {
"lon": 37.123,
"lat": 55.345,
"time": "2014-01-02 23:22:21 +0400"
},
"service": {
"title": "Название службы",
"phone": "+79876543211"
}
}
Описание полей можно посмотреть: При изменении статуса заказа.
где:
-
id- идентификатор заказа который хочется взять -
tariff- тарифы по которым согласен исполнить заказ -
driver/name- имя водителя -
driver/phone- телефон водителя -
driver/license- лицензия водителя
В ответ на запрос возвращаются следующие коды HTTP:
-
200- статус успешно изменен -
400- не хватает обязательного параметра в запросе -
410- согласие уже есть -
404- заказ не найден
api/APIKEY/order/status
При изменении статуса в программном обеспечении КЛИЕНТА, он должен уведомлять ОБМЕННИК об этом изменении. Ожидается POST запрос с телом в формате JSON:
{
"id": 12345,
"status": "complete",
"payment": 1500
}
при переназначении аналогично ack:
{
"id": 12345,
"tariff":[1],
"status": "driving",
"driver_details": {
"sign": "007",
"name": "Васисуалий Пупкин",
"phone": "+79876543210",
"license": "A1234556"
},
"car_details": {
"brand": "Мерседес",
"model": "600",
"color": "зеленый",
"age": 1991,
"number": "762",
"license": "МО 123456"
},
"point": {
"lon": 37.123,
"lat": 55.345,
"time": "2014-01-02 23:22:21 +0400"
},
"service": {
"title": "Название службы",
"phone": "+79876543211"
}
}
Описание полей можно посмотреть: При изменении статуса заказа.
status- текущий статус заказа. Возможны следующие варианты:-
driving- водитель выехал на заказ -
waiting- водитель ожидает клиента -
transporting- водитель везет клиента -
complete- клиент доставлен -
failed- водитель сообщил о невозможности выполнить заказ (срыв) -
confirm- при переназначении - назначен водителю
-
payment- (актуально только при статусе ‘complete’)comment- коментарий службы или водителя при отмене заказа (cancelled) или при срыве заказа (failed)
Секции tariff, driver_details, car_details, service присылаются при переназначении машины аналогично запросу ack.
В случае, если присутствует хотя бы одна из этих секций, обязаны присутствовать
остальные. Статус при этом должен быть confirm, либо driving (назначена, выехал).
Переназначение возможно только в статусах
confirm- заказ назначенdriving- водитель выехал на заказwaiting- водитель ожидает клиента
Переназначение в статусе transporting запрещено.
Статусы заказа могут меняться в описанном выше порядке, за исключением
failed который может быть отправить в любой момент.
В ответ на запрос возвращаются следующие коды HTTP:
-
200- статус успешно изменен -
400- не хватает обязательного параметра в запросе -
410- статус уже изменен или более поздний -
404- заказ не найден
api/APIKEY/order/tracks
По всем заказам в работе передаются точки. Рекомендуемое время: раз в 15 сек. POST запрос с телом в формате JSON:
[
[ "7e968f6279d846d19d69a6c0bc9d291e",
37.2123,
55.32222,
"2014-01-02 23:22:21 +0400"
],
[ "c8dc47f9c8b545ab8bc79369a19a4382",
37.1233, 55.77226,
"2014-01-02 23:22:22 +0400"
]
]
Передается в виде массива, состоящего из элементов, каждый из которых описывает один заказ:
- Идентификатор заказа
- Долгота водителя, исполняющего заказ
- Широта водителя, исполняющего заказ
- Полная дата/время точки