Description of API Protocol for Order Exchange

Versions

  • 24.10.2018 - first version of the protocol

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"
}					
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
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": "Заказ отменен",
  "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
    • 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"
}					
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": "Заказ отменен",
  "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