Описание протокола API для обмена заказами

Содержание

1. Версии
2. Определение терминов
3. Общие положения
4. Запросы к СЛУЖБЕ
5. Запросы к КЛИЕНТУ

1. Версии

03.10.2019 - версия протокола 1.2
12.07.2019 - версия протокола 1.1
24.10.2018 - версия протокола 1.0

2. Определение терминов

СЛУЖБА - сервис "Резидент Такси", принимающий и передающий информацию о заказах и статусах их обработки
КЛИЕНТ - сервис партнера "Резидент Такси", передающий и принимающий информацию о заказах и статусах их обработки

3. Общие положения

Для использования протокола обмена заказами КЛИЕНТУ необходимо получить ключ API.
Ключ API передается в HTTP-заголовке параметром X-API-KEY.
Пример заголовка:

GET /api/tariffs/ HTTP/1.1
User-Agent: Fiddler
Host: rezidenttaxi.loc
Content-Length: 0
X-API-KEY: EB65D37B-F4C6-45C9-EBB8-16F19A0CCBF1

Для передачи заказов КЛИЕНТУ необходимо предоставить:

URL обратного запроса для передачи статусов заказов

Для приема заказов КЛИЕНТУ необходимо предоставить:

URL запроса для передачи заказов
URL запроса для отмены заказов

Примечание: API обратных запросов пассивно.
То есть, если СЛУЖБЕ не удалось доставить запрос об изменении статуса заказа КЛИЕНТУ, то повторы не делаются.

4. Запросы к СЛУЖБЕ

4.1. Получить список доступных тарифов

GET /api/tariffs/ Получить список доступных тарифов

Возвращается JSON с полями, описывающий все доступные тарифы.

						
{
  "status": "success",
  "message": "Список доступных тарифов сформирован",
  "tariffs": [
    {
      "id": "0a59d65bc8724be1b33077b2b5b605f3",
      "description": "Тестовый тариф"
    }
  ]
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
tariffs - Список доступных тарифов
- id - Идентификатор тарифа
- description - Описание тарифа

4.2. Отправить заказ на исполнение

POST /api/orders/add/ Отправить заказ на исполнение

В теле запроса необходимо отправить JSON вида:

						
{
  "externalId": "test_5bc84f4a2b5dv",
  "clientName": "Иван",
  "clientPhone": "79285001011",
  "feedTime": "2018-10-23T09:53:00",
  "comment": "Тестовый комментарий",
  "autoClass": 1,
  "payType": 0,
  "tariffCost": 58000,
  "passengersNumber": 3,
  "pointStart": {
    "city": "Москва",
    "street": "Тверская",
    "home": "15",
    "latitude": 55.761710,
    "longitude": 37.608246,
    "comment": "Комментарий к точке старта"
  },
  "routePoints": [
    {
      "city": "Москва",
      "street": "Большой Каретный переулок",
      "home": "21с1",
      "latitude": 55.773172,
      "longitude": 37.615965,
      "comment": "Комментарий к конечной точке"
    }
  ],
  "comission": 2.5,
  "comissionType": "percent",
  "services": {
    "baby_chair": true
  }
}

Где поля:

externalId - ID заказа в системе КЛИЕНТА
clientName - Имя клиента
clientPhone - Телефон клиента

Телефон клиента clientPhone может не передаваться при создании.
В этом случае, в ответе на запрос обновления статуса DriverAssigned должен быть указан параметр clientPhone с номером телефона клиента.

feedTime - Дата и время подачи по Гринвичу в формате ISO 8601
comment - Комментарий к заказу
autoClass - Класс автомобиля
- 0 - Стандарт
- 1 - Комфорт
- 2 - Бизнес
- 3 - Универсал
- 4 - Минивэн
- 5 - Микроавтобус
payType - Форма оплаты
- 0 - Наличная
- 1 - Безналичная
- 2 - Карта
tariffId - Идентификатор тарифа
tariffCost - Цена заказа в минимальных единицах валюты

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

passengersNumber - Количество пассажиров
pointStart - Точка отправления
- city - Населенный пункт
- street - Улица
- home - Дом
- building - Корпус
- structure - Строение
- entrance - Подъезд
- latitude - Широта
- longitude - Долгота
- comment - Комментарий к точке маршрута
routePoints - Дополнительные точки маршрута (кроме точки отправления)
Структура каждой точки аналогична структуре точки отправления
comission - Фиксированная сумма или процент комиссии
comissionType - Тип комиссии
- fix - сумма
- percent - процент

При наличии комиссии по заказу необходимо передать оба параметра comission и comissionType.

services - Дополнительные услуги
- baby_chair - детское кресло

services - не обязательный атрибут.

При успешном добавлении заказа возвращается JSON с полями:

						
{
  "status": "success",
  "message": "Заказ создан",
  "id": 82019
}

В случае возникновения ошибок при добавлении заказа возвращается JSON с полями:

						
{
  "status": "error",
  "message": "Отсутствуют обязательные параметры заказа"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
id - ID заказа в системе СЛУЖБЫ

4.3. Отменить заказ

POST /api/orders/cancel/ Отменить заказ

4.3.1. Отменить заказ по ID заказа в системе СЛУЖБЫ

В теле запроса необходимо отправить JSON вида:

						
{
  "id": 82023
}

Где поля:

id - ID заказа в системе СЛУЖБЫ

При успешном удалении заказа возвращается JSON с полями:

						
{
  "status": "success",
  "message": "Заказ отменен",
  "externalId": "test_5bc84f4a2b5dv",
  "id": 82019
}

В случае возникновения ошибок при удалении заказа возвращается JSON с полями:

						
{
  "status": "error",
  "message": "Заказ выполняется"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
externalId - ID заказа в системе КЛИЕНТА
id - ID заказа в системе СЛУЖБЫ

4.3.2. Отменить заказ по ID заказа в системе КЛИЕНТА

В теле запроса необходимо отправить JSON вида:

						
{
  "externalId": "test_5bc84f4a2b5dv"
}

Где поля:

externalId - ID заказа в системе КЛИЕНТА

При успешном удалении заказа возвращается JSON с полями:

						
{
  "status": "success",
  "message": "Заказ отменен",
  "externalId": "test_5bc84f4a2b5dv",
  "id": 82019
}

В случае возникновения ошибок при удалении заказа возвращается JSON с полями:

						
{
  "status": "error",
  "message": "Заказ выполняется"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
externalId - ID заказа в системе КЛИЕНТА
id - ID заказа в системе СЛУЖБЫ

4.4. Обновление статуса заказа

POST /api/orders/status/ Обновление статуса заказа

В теле запроса необходимо отправить JSON вида:

						
{
  "id": "test_5bcdd17c8e542",
  "externalId": 82019,
  "costPay": 35000,
  "message": "Заказ выполнен",
  "status": "Finished",
  "driverInfo": {
    "name": "Василий Уткин",
    "phone": "79280010203"
  },
  "carInfo": {
    "model": "Mazda",
    "color": "серо-бурый",
    "number": "М528965"
  }
}

Где поля:

id - ID заказа в системе КЛИЕНТА
externalId - ID заказа в системе СЛУЖБЫ
costPay - Сумма поездки в минимальных единицах валюты

Поле Сумма поездки обязательна к передаче со стаусом Finished.

status - Статус заказа
- New - Водитель не назначен
- DriverAssigned - Водитель назначен
- DriverMoved - Водитель выехал
- DriverArrived - Водитель на месте
- Phoned - Отзвонились
- Riding - Исполняется
- Finished - Выполнен
- CanceledDriver - Отменен водителем
- CanceledCustomer - Отменен клиентом
- Expired - Просрочен
message - Комментарий
driverInfo - Информация о водителе
- name - ФИО
- phone - Телефон
carInfo - Информация о автомобиле
- mark - Марка
- model - Модель
- color - Цвет
- number - Гос. номер

Поля Информация о водителе и Информация о автомобиле обязательны к передаче со стаусами

DriverAssigned

DriverMoved

DriverArrived

Phoned

Riding

При успешном изменении статуса заказа возвращается JSON с полями:

						
{
  "status": "success",
  "message": "Статус заказа установлен"
}

В случае возникновения ошибок при изменении статуса заказа возвращается JSON с полями:

						
{
  "status": "error",
  "message": "Не обнаружен заказ с указанным ID"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке

4.5. Изменение данных заказа

POST /api/orders/edit/ Изменение данных заказа

В теле запроса необходимо отправить JSON вида:

						
{
  "id": 82023,
  "payType": 1
}

Где поля:

id - ID заказа в системе КЛИЕНТА
payType - Форма оплаты
- 0 - Наличная
- 1 - Безналичная
- 2 - Карта

При успешном изменении данных заказа возвращается JSON с полями:

						
{
  "status": "success",
  "message": "Успешно изменена форма оплаты заказа",
  "id": 82019
}

В случае возникновения ошибок при изменении данных заказа возвращается JSON с полями:

						
{
  "status": "error",
  "message": "Указанная форма оплаты совпадает с текущей формой оплаты заказа"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке

5. Запросы к КЛИЕНТУ

5.1. Обновление статуса заказа

POST URL обратного запроса для передачи статусов заказов Обновление статуса заказа

В теле запроса будет отправлен JSON вида:

						
{
  "id": 82019,
  "externalId": "test_5bcdd17c8e542",
  "costPay": 35000,
  "message": "Заказ выполнен",
  "status": "Finished",
  "driverInfo": {
    "name": "Василий Уткин",
    "phone": "79280010203"
  },
  "carInfo": {
    "model": "Mazda",
    "color": "серо-бурый",
    "number": "М528965"
  },
  "fleetInfo": {
    "name": "Твой перевозчик",
    "inn": "123456789012",
    "phone": "79280010203",
    "orderId": "c096bc08-52e5-430f-9ad8-5161e00f01ae"
  }
}

Где поля:

id - ID заказа в системе СЛУЖБЫ
externalId - ID заказа в системе КЛИЕНТА
costPay - Сумма поездки в минимальных единицах валюты

Поле Сумма поездки обязательна к передаче со стаусом Finished.

status - Статус заказа
- New - Водитель не назначен
- DriverAssigned - Водитель назначен
- DriverMoved - Водитель выехал
- DriverArrived - Водитель на месте
- Phoned - Отзвонились
- Riding - Исполняется
- Finished - Выполнен
- CanceledDriver - Отменен водителем
- CanceledCustomer - Отменен клиентом
- Expired - Просрочен
message - Комментарий
driverInfo - Информация о водителе
- name - ФИО
- phone - Телефон
carInfo - Информация о автомобиле
- mark - Марка
- model - Модель
- color - Цвет
- number - Гос. номер
fleetInfo - Информация о службе, исполняющей заказ
- name - Наименование
- inn - ИНН
- phone - Телефон
- orderId - ID заказа в системе партнерской службы

Поля Информация о водителе и Информация о автомобиле обязательны к передаче со стаусами

DriverAssigned

DriverMoved

DriverArrived

Phoned

Riding

Поля Информация о службе, исполняющей заказ обязательны к передаче со стаусами

DriverAssigned

При успешном изменении статуса заказа необходимо вернуть JSON с полями:

						
{
  "status": "success",
  "message": "Статус заказа установлен"
}

В случае возникновения ошибок при изменении статуса заказа необходимо вернуть JSON с полями:

						
{
  "status": "error",
  "message": "Не обнаружен заказ с указанным ID"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке

5.2. Обновление координат водителя по заказу

POST URL обратного запроса для передачи координат водителя по заказу Обновление координат водителя по заказу

В теле запроса будет отправлен JSON вида:

						
{
  "id": "test_5bcdd17c8e542",
  "externalId": 82019,
  "latitude": 55.69909,
  "longitude": 37.56722,
  "direction": 270,
  "speed": 50
}

Где поля:

id - ID заказа в системе СЛУЖБЫ
externalId - ID заказа в системе КЛИЕНТА
latitude - Широта
longitude - Долгота
direction - Направление движения в градусах. (Направление на север – 0 градусов)
speed - Скорость в км/ч

При успешном изменении статуса заказа необходимо вернуть JSON с полями:

						
{
  "status": "success",
  "message": "Координаты водителя приняты"
}

В случае возникновения ошибок при изменении статуса заказа необходимо вернуть JSON с полями:

						
{
  "status": "error",
  "message": "Не обнаружен заказ с указанным ID"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке

5.3. Отправить заказ на исполнение

POST URL запроса для передачи заказов Отправить заказ на исполнение

В теле запроса будет отправлен JSON вида:

						
{
  "externalId": "test_5bc84f4a2b5dv",
  "clientName": "Иван",
  "clientPhone": "79285001011",
  "feedTime": "2018-10-23T09:53:00",
  "comment": "Тестовый комментарий",
  "autoClass": 1,
  "payType": 0,
  "tariffCost": 58000,
  "passengersNumber": 3,
  "pointStart": {
    "city": "Москва",
    "street": "Тверская",
    "home": "15",
    "latitude": 55.761710,
    "longitude": 37.608246,
    "comment": "Комментарий к точке старта"
  },
  "routePoints": [
    {
      "city": "Москва",
      "street": "Большой Каретный переулок",
      "home": "21с1",
      "latitude": 55.773172,
      "longitude": 37.615965,
      "comment": "Комментарий к конечной точке"
    }
  ],
  "comission": 2.5,
  "comissionType": "percent",
  "services": {
    "baby_chair": true
  }
}

Структура JSON аналогична структуре, описанной в методе /api/orders/add/

Где поля:

id - ID заказа в системе СЛУЖБЫ
externalId - ID заказа в системе КЛИЕНТА

При успешном добавлении заказа необходимо вернуть JSON с полями:

						
{
  "status": "success",
  "message": "Заказ создан",
  "id": 82019
}

В случае возникновения ошибок при добавлении заказа необходимо вернуть JSON с полями:

						
{
  "status": "error",
  "message": "Отсутствуют обязательные параметры заказа"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
id - ID заказа в системе КЛИЕНТА

5.4. Отменить заказ

POST URL запроса для отмены заказов Отменить заказ

В теле запроса будет отправлен JSON вида:

						
{
  "id": 82023
}

Структура JSON аналогична структуре, описанной в методе /api/orders/cancel/

Где поля:

id - ID заказа в системе КЛИЕНТА

При успешном удалении заказа необходимо вернуть JSON с полями:

						
{
  "status": "success",
  "message": "Заказ отменен",
  "externalId": "test_5bc84f4a2b5dv",
  "id": 82019
}

В случае возникновения ошибок при удалении заказа необходимо вернуть JSON с полями:

						
{
  "status": "error",
  "message": "Заказ выполняется"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
id - ID заказа в системе КЛИЕНТА

5.5. Изменение атрибутов заказа

POST URL запроса для изменения заказов Изменить заказ

В теле запроса будет отправлен JSON вида:

						
{
  "id": "82019",
  "externalId": "test_5bc84f4a2b5dv",
  "clientPhone": "79285001011",
  "feedTime": "2018-10-23T09:53:00",
  "comment": "Тестовый комментарий",
  "payType": 0,
  "tariffCost": 58000,
  "pointStart": {
    "city": "Москва",
    "street": "Тверская",
    "home": "15",
    "latitude": 55.761710,
    "longitude": 37.608246,
    "comment": "Комментарий к точке старта"
  },
  "routePoints": [
    {
      "city": "Москва",
      "street": "Большой Каретный переулок",
      "home": "21с1",
      "latitude": 55.773172,
      "longitude": 37.615965,
      "comment": "Комментарий к точке маршрута"
    }
  ],
  "services": {
    "baby_chair": true
  }
}

Где поля:

id - ID заказа в системе СЛУЖБЫ
externalId - ID заказа в системе КЛИЕНТА
clientPhone - Телефон клиента
feedTime - Дата и время подачи по Гринвичу в формате ISO 8601
comment - Комментарий к заказу
payType - Форма оплаты
- 0 - Наличная
- 1 - Безналичная
- 2 - Карта
tariffCost - Цена заказа в минимальных единицах валюты

pointStart - Точка отправления
- city - Населенный пункт
- street - Улица
- home - Дом
- latitude - Широта
- longitude - Долгота
- comment - Комментарий к точке маршрута
routePoints - Дополнительные точки маршрута (кроме точки отправления)
Структура каждой точки аналогична структуре точки отправления
services - Дополнительные услуги
- baby_chair - детское кресло

При успешном изменении заказа необходимо вернуть JSON с полями:

						
{
  "status": "success",
  "message": "Заказ изменен",
  "externalId": "test_5bc84f4a2b5dv",
  "id": 82019
}

В случае возникновения ошибок при изменении заказа необходимо вернуть JSON с полями:

						
{
  "status": "error",
  "message": "Ошибка изменения заказа"
}

Где поля:

status - Статус выполнения запроса
message - Сообщение о результате выполнения запроса или ошибке
externalId - ID заказа в системе КЛИЕНТА
id - ID заказа в системе СЛУЖБЫ