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

Содержание

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"
}					
Где поля:
  • 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.

При успешном добавлении заказа возвращается JSON с полями:
						
{
  "status": "success",
  "message": "Заказ создан",
  "id": 82019
}					
В случае возникновения ошибок при добавлении заказа возвращается JSON с полями:
						
{
  "status": "error",
  "message": "Отсутствуют обязательные параметры заказа"
}					
Где поля:
  • status - Статус выполнения запроса
  • message - Сообщение о результате выполнения запроса или ошибке
  • id - ID заказа в системе СЛУЖБЫ

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

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

В теле запроса необходимо отправить JSON вида:
						
{
  "id": 82023
}					
Где поля:
  • id - ID заказа в системе СЛУЖБЫ
При успешном удалении заказа возвращается JSON с полями:
						
{
  "status": "success",
  "message": "Заказ отменен",
  "id": 82019
}					
В случае возникновения ошибок при удалении заказа возвращается JSON с полями:
						
{
  "status": "error",
  "message": "Заказ выполняется"
}					
Где поля:
  • status - Статус выполнения запроса
  • message - Сообщение о результате выполнения запроса или ошибке
  • id - ID заказа в системе СЛУЖБЫ

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

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 - Статус заказа
    • 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 - Сообщение о результате выполнения запроса или ошибке

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"
  }
}					
Где поля:
  • id - ID заказа в системе СЛУЖБЫ
  • externalId - ID заказа в системе КЛИЕНТА
  • costPay - Сумма поездки в минимальных единицах валюты

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

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

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

  • 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"
}					
Структура 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": "Заказ отменен",
  "id": 82019
}					
В случае возникновения ошибок при удалении заказа необходимо вернуть JSON с полями:
						
{
  "status": "error",
  "message": "Заказ выполняется"
}					
Где поля:
  • status - Статус выполнения запроса
  • message - Сообщение о результате выполнения запроса или ошибке
  • id - ID заказа в системе КЛИЕНТА