Description of API Protocol for Order Exchange

Versions

03.10.2019 - version of the protocol 1.2
12.07.2019 - version of the protocol 1.1
24.10.2018 - version of the protocol 1.0

Definition of terms

SERVICE - "Rezident Taxi" service which receives and sends information about orders and their processing statuses
CLIENT - "Rezident Taxi" partner service which receives and sends information about orders and their processing statuses

General Provisions

CLIENT Access to the protocol of order exchange requires an API key.
The key is sent as HTTP-header parameter X-API-KEY.
Example header:

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

To send an order, the CLIENT must provide:

>Callback URL for sending order status

To receice an order, the CLIENT must provide:

Request URL for sending orders
Request URL for cancelling orders

Note: The Callback API is passive.
That is if the SERVICE is unable to deliver a status change request to the CLIENT, it doesn't attempt to re-send it.

Requests to the SERVICE

GET /api/tariffs/ Get a list of available tariffs

A JSON response is returned with fields describing all available tariffs.

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

Где поля:

status - Request status
message - Message about the result of processing the request or about an error
tariffs - List of available tariffs
- id - Tariff ID
- description - Description of tariff

POST /api/orders/add/ Send an order to be executed

In the request body a JSON message is sent like the following:

						
{
  "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
  }
}

Where the fields are:

externalId - Order ID in the CLIENT's system
clientName - Client's name
clientPhone - Client's phone number
feedTime - Pickup date and time in ISO 8601 format
comment - Order notes
autoClass - Automobile class
- 0 - Standard
- 1 - Comfort
- 2 - Business
- 3 - Station wagon
- 4 - Minivan
- 5 - Minibus
payType - Form of payment
- 0 - Cash
- 1 - Cashless
- 2 - Card
tariffId - Tariff ID
tariffCost - Order price in minimal currency units

Either a fixed order price tariffCost or the id of an available tariff tariffId is sent.

passengersNumber - Number of passengers
pointStart - Point of departure
- city - City
- street - Street
- home - House
- building - Building
- structure - Structure
- entrance - Entrace
- latitude - Latitude
- longitude - Longitude
- comment - Comment to a route point
routePoints - Additional route points (apart from point of departure)
The structure of every point is the same as that of point of departure
comission - Fixed amount or percentage of commission
comissionType - Type of commission
- fix - the amount
- percent - percent
services - Additional services
- baby_chair - baby chair

services - optional attribute.

On successful order creation, a JSON response is sent consisting of the following fields:

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

If an error is encountered when creating an order, a JSON reponse is sent consisting of the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error
id - Order ID in the SERVICE's system

POST /api/orders/cancel/ Cancel the order

In the request boy a JSON message is sent like the following:

						
{
  "id": 82023
}

Where the fields are:

id - Order ID in the SERVICE's system

On successful order cancellation a JSON response with the following fields is returned:

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

If an error is encountered while cancelling an order, a JSON response is returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error
id - Order ID in the SERVICE's system

POST /api/orders/status/ Order status update

In the request body a JSON message is sent like the following:

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

Where the fields are:

id - Order ID in the CLIENT's system
externalId - Order ID in the SERVICE's system
costPay - Ride cost

The Ride cost field is a required parameter when sending the Finished status.

status - Order status
- New - No driver assigned
- DriverAssigned - A driver is assigned
- DriverMoved - The driver is en route
- DriverArrived - The driver has arrived
- Phoned - Phoned
- Riding - Riding
- Finished - Finished
- CanceledDriver - Cancelled by driver
- CanceledCustomer - Cancelled by client
- Expired - Expired
message - Comments
driverInfo - Information about the driver
- name - Name
- phone - Phone number
carInfo - Information about the vehicle
- model - Make
- color - Color
- number - Plate number

The Information about the driver и Information about the vehicle fields are required for statuses

DriverAssigned

DriverMoved

DriverArrived

Phoned

Riding

On successful order status update a JSON response with the following fields is returned:

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

If an error is encountered while performing an order status update, a JSON response is returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error

Requests to the CLIENT

POST Callback URL for sending order statuses Order status update

In the request body a JSON message is sent like the following:

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

The JSON structure is the same as that for the /api/orders/status/ method.

On successful order status update, a JSON response is sent consisting of the following fields:

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

If an error is encountered while performing an order status update, a JSON response should be returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error

POST Callback URL for sending driver coordinates by order Driver coordinates by order update

In the request body a JSON message is sent like the following:

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

Where the fields are:

id - Order ID in the CLIENT's system
externalId - Order ID in the SERVICE's system
latitude - Latitude
longitude - Longitude
direction - The direction of movement in degrees. (Direction to the north - 0 degrees)
speed - Speed in km/h

On successful order status update, a JSON response is sent consisting of the following fields:

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

If an error is encountered while performing an order status update, a JSON response should be returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error

POST Request URL for sending orders Send an order to be executed

In the request body a JSON message is sent like the following:

						
{
  "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
  }
}

The JSON structure is the same as that for the /api/orders/add/ method.

Where the fields are:

id - Order ID in the SERVICE's system
externalId - Order ID in the CLIENT's system

On successful order creation, a JSON response is sent consisting of the following fields:

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

If an error is encountered while creating an order, a JSON response should be returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error
id - Order ID in the CLIENT's system

POST Request URL запроса for order cancellation Cancel the order

In the request body a JSON message is sent like the following:

						
{
  "id": 82023
}

The JSON structure is the same as that for the /api/orders/cancel/ method.

Where the fields are:

id - Order ID in the CLIENT's system

On successful order cancellation, a JSON response is sent consisting of the following fields:

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

If an error is encountered while cancelling an order, a JSON response should be returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error
id - Order ID in the CLIENT's system

POST Request URL запроса for order update Update the order

In the request body a JSON message is sent like the following:

						
{
  "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
  }
}

Where the fields are:

id - Order ID in the SERVICE's system
externalId - Order ID in the CLIENT's system
clientPhone - Client's phone number
feedTime - Pickup date and time in ISO 8601 format
comment - Order notes
payType - Form of payment
- 0 - Cash
- 1 - Cashless
- 2 - Card
tariffCost - Order price in minimal currency units

pointStart - Point of departure
- city - City
- street - Street
- home - House
- latitude - Latitude
- longitude - Longitude
- comment - Comment to a route point
routePoints - Additional route points (apart from point of departure)
The structure of every point is the same as that of point of departure
services - Additional services
- baby_chair - baby chair

On successful order updated, a JSON response is sent consisting of the following fields:

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

If an error is encountered while updated an order, a JSON response should be returned containing the following fields:

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

Where the fields are:

status - Request status
message - Message about the result of processing the request or about an error
externalId - Order ID in the CLIENT's system
id - Order ID in the SERVICE's system