API

Протокол взаимодействия клиентского приложения/web-виджета с сервисом LigaTaxi

Версия: v1

Содержание

1 Основные положения.
2 Получение конфигураций компаний
3 Типы данных

Основные положения.

Сервис LigaTaxi (далее сервис), предоставляет REST API интерфейс, с помощью которого разработчики стороннего ПО могут авторизировать клиента, получить список предыдущих поездок клиента, просчитать и создать новый заказ, отслеживать статусы текущих заказов. Интерфейсы сервиса являются защищенными, что позволяет стороннему ПО напрямую взаимодействовать с сервисом. Сервис позволяет выполнять кросс доменные запросы, передавая соответствующие http заголовки.

Приложение для заказа такси или веб виджет (далее стороннее ПО), взаимодействует с сервисом по http протоколу. Стороннее ПО должно корректно обрабатывать статусы ошибок которые будет возвращать сервис.

Адрес API сервера.

API сервер всегда будет находится по адресу api-<адрес личного кабинета в сервисе>. Например, если адрес личного кабинета находится по адресу demo-city.ligataxi.com, то адрес API сервера будет находится по адресу api-demo-city.ligataxi.com.

Протокол взаимодействия.

Сервис предоставляет REST архитектуру, где метод (далее ресурс) имеет конечное состояние которое можно изменять с помощью методов GET, POST, PUT, DELETE.

Стороннее ПО взаимодействует с сервисом по протоколу json. Адрес каждого ресурса должен заканчиваться символом /. Каждый ресурс описанный ниже в данной документации будет иметь префикс /api/v1/client/. То есть для ресурса myresource полный url будет иметь вид http://api-demo-city.ligataxi.com/api/v1/client/myresource/.

Авторизация.

Авторизация происходит по двум критериями.

Авторизация стороннего ПО. Выполняется с помощью тега api-key. Данный тег должен передаваться в качестве http заголовка в каждом запроса стороннего ПО к сервису.
Авторизация клиента. Выполняется с помощью заголовка uuid. Не все ресурсы сервиса требуют авторизацию клиента.

Для получения api-key с помощью которого сервис будет авторизовать стороннее ПО, необходимо перейти в настройки сервиса, раздел Справочники -> API Ключи. После необходимо добавить новый ключ. В форме создания ключа в поле Название, необходимо вписать имя ключа. С таким же именем будет создан виртуальный пользователь от имени которого будет происходить все взаимодействие с сервисом. Компании - список виртуальный компаний с которыми можно производить взаимодействие по данному ключу. Права доступа - права для виртуального пользователя. В данном случае будет достаточно прав Рабочее место.

После нажатия кнопки Сохранить произойдет переадресация на список ключей. В списке возле вновь созданного ключа будет колонка API Ключ и значение вида fe948ee7c9424796580e1a3bb760f0ee. Данное значение и есть наш api-key.

Так же API Ключ можно отключить, тем самым запретив стороннему приложению взаимодействие с сервисом.

В случае если API Ключ отключен или указан неверно, сервис вернет ошибку 407 Proxy Authentication Required.

Конфигурация API.

После создания API Ключа, необходимо произвести настройку API сервиса и связать его с API ключом. Для этого необходимо перейти в раздел Администрирование(в случае если у вас несколько виртуальных компании - в настройки виртуальной компании) -> Настройки -> Клиентское приложение и добавить новую конфигурацию. В появившейся форме в поле API шлюз из выпадающего списка необходимо выбрать созданный вами API Ключ. В поле:

Населенные пункты - необходимо указать населенные пункты в которые возможна подача автомобиля.

Тип заказа - тип заказа который будет присвоен всем заказам созданным через данный API.

Мах. одновременных заказов - максимальное количество активных заказов которые может создать клиента через данное API.
Минимальное время подачи - минимальное время для подачи автомобиля. Будет рассчитано как текущее время + значение данного поля. Значение указывается в минутах.
Максимальное время подачи - ограничение максимального времени подачи автомобиля. Рассчитывается также, как минимальное время подачи. Значение указывается в минутах. Если указать 0, ограничение будет отключено.
Типы автомобилей - доступные клиенту для выбора при заказе такси.
Опции автомобиля - опции автомобиля доступные клиенту для выбора при заказе такси.
Требования к водителю - требования к водителю доступные клиенту для выбора при заказе такси.
Способ соединения с водителем - Выключен - клиент не сможет позвонить водителю, Клиент <-> Водитель - клиенту будет доступен номер телефона водителя и он сможет напрямую с ним созвонится.
Номера телефонов диспетчерской - список номеров диспетчерской службы такси. Введите номер и нажмите[ENTER]
Текст SMS сообщения - шаблон SMS сообщения которое будет отправлено клиенту при авторизации. Поле [code] будет автоматически изменено на произвольно сгенерированный код активации.
О такси - краткая информация о службе такси, которая будет видна на клиентском приложении в разделе О такси

Список основных ошибок которые может вернуть сервис

Каждый ресурс можем возвращать такие же коды ошибок, но они могут иметь другие значения. Данные ошибки будут описаны в описании ресурса.

400 Bad Request - в теле запроса переданы неверные параметры запроса.
403 Forbidden - ресурс требует авторизации клиента с помощью тега uuid. Тег не был передан либо указан неверно.
404 Not Found - указан неверный адрес ресурса.
405 Method Not Allowed - ресурс не поддерживает вызываемый метод. Например на ресурс который поддерживает только метод GET, был послан метод POST.
407 Proxy Authentication Required - переданный api-key неверный или отключён.
500 Internal Server Error - внутренняя ошибка сервера. Получив подобную ошибку, стоит обратиться в тех. поддержку сервиса.
502 Bad Gateway - отсутствует подключение к сети или доступ из вашего региона закрыт

Получение конфигураций компаний

Адрес ресурса:

company/

Метод: GET

Параметры запроса: отсутствуют

Необходима авторизация клиента: нет

Пример ответа:

[
   {
      "id":1,
      "name":"Демо",
      "max_pickup_time":0,
      "default_pickup_time":5,
      "driver_contact_method":1,
      "city":"Москва",
      "region":"Московская область",
      "map_center":{
         "lat":55.7425739894847,
         "lng":37.6611328125
      },
      "areas":[
         [
            {
               "lat":55.9983809553596,
               "lng":39.22119140625
            },
            {
               "lat":55.4850790375261,
               "lng":36.10107421875
            }
         ],
         [
            {
               "lat":60.1168821019816,
               "lng":31.1819458007812
            },
            {
               "lat":59.7868158061153,
               "lng":29.6548461914062
            }
         ]
      ],
      "car_types":[
         {
            "id":6,
            "name":"Легковая"
         },
         {
            "id":14,
            "name":"Грузовик"
         },
         {
            "id":25,
            "name":"Универсал"
         }
      ],
      "car_extras":[
         {
            "id":3,
            "name":"Детское кресло 100 р."
         }
      ],
      "driver_extras":[
         {
            "id":2,
            "name":"Знание английского"
         }
      ]
   }
]

Описание параметров:

В результате будет список конфигураций компаний с которыми возможно работать по данному API ключу. Если таких компаний будет больше одной, клиенту нужно дать возможность выбора компании с которой он хочет работать.

[
   {
      "id":1,
      Айди компании. В дальнейшем данный айди нужно будет передавать в url ресурсов к которым будут проводиться запросы.

      "name":"Демо",
      Назнвание компании

      "max_pickup_time":0,
      Максимальное время подачи. Рассчитывается как текущее время + значение в мн. Если 0 - без ограничений

      "default_pickup_time":5,
      Время подачи по умолчанию, оно же минимальное время подачи.

      "driver_contact_method":1,
      Метод соединения водителя с клиентом: 0 - выключено, 1 - Клиент <-> Водитель.

      "city":"Москва",
      Название основного населенного пункта в котором работает компания.

      "region":"Московская область",
      Область основного населенного пункта в котором работает компания.

      "map_center":{
         "lat":55.7425739894847,
         "lng":37.6611328125
      },
      Координаты центра карты основного населенного пункта в котором работает компания.

   "areas":[
            [
               {
                  "lat":55.9983809553596,
                  "lng":39.22119140625
               },
               {
                  "lat":55.4850790375261,
                  "lng":36.10107421875
               }
            ],
            [
               {
                  "lat":60.1168821019816,
                  "lng":31.1819458007812
               },
               {
                  "lat":59.7868158061153,
                  "lng":29.6548461914062
               }
            ]
         ],
   Список координат регионов в которые возможна подача автомобиля. Указывается как набор точек северо-востока и юго-запада региона. Точка вызова должна ходится в пределах данных регионов.

   "car_types":[
            {
               "id":6,
               "name":"Легковая"
            },
            {
               "id":14,
               "name":"Грузовик"
            },
            {
               "id":25,
               "name":"Универсал"
            }
         ],
   Список типов автомобилей, которые может выбрать клиента при заказе такси.

   "car_extras":[
            {
               "id":3,
               "name":"Детское кресло 100 р."
            }
         ],
   Список опций автомобиля, доступных клиенту при заказе такси.

   "driver_extras":[
            {
               "id":2,
               "name":"Знание английского"
            }
         ]
   Список требований к водителю, доступных клиенту при заказе такси
   }
]

Получение описания компании

Адрес ресурса:

company/<id_компании>/about/

Метод: GET

Параметры запроса: отсутствуют

Необходима авторизация клиента: нет

Пример ответа:

{
   "about":"Мы самая лучшая служба такси в мире."
}

Получение списка контактных номеров компании

Адрес ресурса:

company/<id_компании>/phones/

Метод: GET

Параметры запроса: отсутствуют

Необходима авторизация клиента: нет

Пример ответа:

[
   "23453452345",
   "52354545453",
   "34534534535"
]

Получение координат водителей компании для отображения на карте

Адрес ресурса:

company/<id_компании>/drivers/

Метод: GET

Параметры запроса: отсутствуют

Необходима авторизация клиента: нет

Пример ответа:

{
   "drivers":[
      {
         "lat":55.74933168637703,
         "lng":37.61841641582357
      },
      {
         "lat":54.793563168637704,
         "lng":39.32841641582357
      }
   ]
}

Получение списка возможных причин отмены заказа

Адрес ресурса:

cancel_reasons/

Метод: GET

Необходима авторизация клиента: нет

Параметры запроса: отсутствуют

Пример ответа:

[
   {
      "id":2,
      "name":"Ложный"
   },
   {
      "id":3,
      "name":"Передумал"
   }
]

Отправка SMS с кодом активации номера телефона

Адрес ресурса:

/company/<id_компании>/auth/

Метод: GET

Необходима авторизация клиента: нет

Параметры запроса: передаются как обычные параметры для GET запроса

Поле	Тип данных	Default	Описание
phone	string		Номер телефона клиента без кода страны
dev_type	int		Тип устройства: 1 - Android 2 - iOS 3 - Windows phone 4 - Web widget
dev_id	string		ID устройства

Пример ответа: В ответ будет возвращен http статус 200

Подтверждение телефона с помощью кода активации

Адрес ресурса:

company/<id_компании>/auth/

Метод: POST

Необходима авторизация клиента: нет

Параметры запроса: передаются как обычные параметры для POST запроса

Поле	Тип данных	Default	Описание
phone	string		Номер телефона клиента без кода страны
dev_type	int		Тип устройства: 1 - Android 2 - iOS 3 - Windows phone 4 - web widget
dev_id	string		ID устройства
code	string		Код подтверждения полученный в SMS

Пример ответа:

{
   "uuid":"123e4567-e89b-12d3-a456-426655440000"
}

Получить профиль клиента

Адрес ресурса:

company/<id_компании>/profile/

Метод: GET

Необходима авторизация клиента: да

Параметры запроса: отсутствуют

Пример ответа:

Просчет стоимости поездки

Адрес ресурса:

company/<id_компании>/calculate/

Метод: POST

Необходима авторизация клиента: не обязательно

Параметры запроса:

Все параметры должно быть упакованы json и отправлены в теле запроса.

Поле	Тип данных	Default	Описание
pickup_address	Address		Адрес подачи
pickup_time	string		Время подачи
car_type	int		Тип автомобиля
car_extras	int[]		Массив из идентификаторов опций автомобиля
driver_extras	int[]		Массив из идентификаторов требований к водителю
destinations	Address[]		Массив из адресов назначения
return_route	bool		Указывает нужно ли в ответе возвращать маршрут

Пример запроса:

{
   "pickup_address":{
      "street":"Киевский вокзал",
      "building":"",
      "comment":"",
      "lat":55.743299,
      "lng":37.567348
   },
   "pickup_time":"2016-09-30T15:49:26",
   "car_type":"6",
   "car_extras":[
      7
   ],
   "driver_extras":[
      1,
      5
   ],
   "destinations":[
      {
         "street":"Севастопольский проспект",
         "building":"",
         "comment":"",
         "lat":55.658865,
         "lng":37.573618
      }
   ],
   "return_route":true
}

Пример ответа:

{
   "distance":13941,
   Расчетное расстояние маршрута поездки (метры)

   "price":395.0,
   Расчетная стоимость поездки (с учетом скидок)

   "driving_time":15,
   Расчетное время выполнения заказа (минуты)

   "discount_price":0.0,
   Размер фиксированной скидки

   "discount_percent":0.0,
   Размер скидки в процентах

   "route":"mkfsI{nhdFgJoIsB__AlBeQ~j@iVjq@wvCnEmi@uAs_@bC{BhjChNvE~U|QzN|JeAbqBdhBx_DviDeMsO",
   Маршрут поездки закодированный с помощью алгоритма Encoded Polyline. Данный тег будет возвращен, если в запросе на просчет параметр return_route был отмечен как true
}

Создание заказа

Адрес ресурса:

company/<id_компании>/order/

Метод: POST

Необходима авторизация клиента: обязательно

Параметры запроса:

Все параметры должно быть упакованы json и отправлены в теле запроса.

Поле	Тип данных	Default	Описание
pickup_address	Address		Адрес подачи
pickup_time	string		Время подачи
car_type	int		Тип автомобиля
car_extras	int[]		Массив из идентификаторов опций автомобиля
driver_extras	int[]		Массив из идентификаторов требований к водителю
destinations	Address[]		Массив из адресов назначения
comment	string		Примечание к заказу

Пример запроса:

{
   "pickup_address":{
      "street":"Киевский вокзал",
      "building":"",
      "comment":"",
      "lat":55.743299,
      "lng":37.567348
   },
   "pickup_time":"2016-09-30T16:06:01",
   "car_type":"6",
   "car_extras":[
      "3"
   ],
   "driver_extras":[

   ],
   "comment":"Встречать с табличкой",
   "destinations":[
      {
         "street":"Севастопольский проспект",
         "building":"",
         "comment":"",
         "lat":55.658865,
         "lng":37.573618
      }
   ]
}

Пример ответа:

{
   "id":96,
   "company_id":1,
   "state":1,
   "price":395,
   "discount_price":0,
   "discount_percent":0,
   "distance":13941,
   "create_time":"2016-09-30T13:01:03",
   "done_time":null,
   "pickup_time":"2016-09-30T16:06:03",
   "car_type":6,
   "car_extras":[
      3
   ],
   "driver_extras":[

   ],
   "comment":"Встречать с табличкой",
   "pickup_address":{
      "street":"Киевский вокзал",
      "building":"",
      "comment":"",
      "lat":55.743299,
      "lng":37.567348
   },
   "destinations":[
      {
         "street":"Севастопольский проспект",
         "building":"",
         "comment":"",
         "lat":55.658865,
         "lng":37.573618
      }
   ]
}

Список заказов клиента

Адрес ресурса:

company/<id_компании>/order/

Метод: GET

Необходима авторизация клиента: обязательно

Параметры запроса: передаются в виде обычных параметров для GET запроса

Поле	Тип данных	Default	Описание
state	int[]	null	Статусы заказов
limit	int	10	Количество отображаемых заказов
offset	int	0	Смещение при выборке

Пример ответа:

[
   {
      "id":97,
      "company_id":1,
      "state":1,
      "price":15685.0,
      "discount_price":0.0,
      "discount_percent":0.0,
      "distance":709094,
      "create_time":"2016-09-30T13:55:34",
      "done_time":null,
      "pickup_time":"2016-09-30T17:00:34",
      "car_type":6,
      "car_extras":[
         3
      ],
      "driver_extras":[

      ],
      "comment":"",
      "pickup_address":{
         "street":"Киевский вокзал",
         "building":"",
         "comment":"",
         "lat":55.743299,
         "lng":37.567348
      },
      "destinations":[
         {
            "street":"Московский проспект",
            "building":"",
            "comment":"",
            "lat":59.88544,
            "lng":30.320036
         }
      ]
   }
]

Получение маршрута по заказу

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/route/

Метод: GET

Необходима авторизация клиента: обязательно

Параметры запроса: отсутствуют

Маршрут возвращается в формате Encoded Polyline

Пример ответа:

mkfsI{nhdFgJoIsB__AlBeQ~j@iVjq@wvCnEmi@uAs_@bC{BhjChNvE~U|QzN|JeAbqBdhBx_DviDeMsO

Получение статуса заказа

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/state/

Метод: GET

Необходима авторизация клиента: обязательно

Параметры запроса: отсутствуют

Пример ответа:

{
   "state":1
}

Возможные статусы заказа

1 - поиск водителя
2 - водитель выехал за клиентом
3 - на месте (ожидает клиента)
4 - по маршруту
5 - выполнен
6 - отменен
7 - просрочен, водитель не найден
8 - зарезервирован за водителем

Получение информации о водителе выполняющем заказ

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/driver/

Метод: GET

Необходима авторизация клиента: обязательно

Параметры запроса: отсутствуют

Пример ответа:

{
   "driver_name":"Иван Иванов",
   "phone":"+79772225588",
   "car_model":"Форд Фокус",
   "car_color":"Желтый",
   "car_number":"ЕН94377"
}

Получение координат водителя

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/driver/location/

Метод: GET

Необходима авторизация клиента: обязательно

Параметры запроса: отсутствуют

Пример ответа:

{
   "lat":51.685431666666666,
   "lng":35.27650666666667
}

Отмена заказа

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/

Метод: DELETE

Необходима авторизация клиента: обязательно

Параметры запроса: передаются как обычные параметры для DELETE запроса

Поле	Тип данных	Default	Описание
reason	int		Идентификатор причины отмены

Оценка поездки

Выполняется при статусе заказа Выполнен(5)

Адрес ресурса:

company/<id_компании>/order/<id_заказа>/evaluate/

Метод: POST

Необходима авторизация клиента: обязательно

Параметры запроса:

Все параметры должно быть упакованы json и отправлены в теле запроса.

Поле	Тип данных	Default	Описание
rating	float		Оценка. Значение от 1.0 до 5.0
comment	str		Комментарий к оценке

Типы данных

Order

Поле	Тип данных	Default	Описание
pickup_address	Address		Адрес подачи
pickup_time	string		Время подачи
car_type	int		Тип автомобиля
car_extras	int[]		Массив из идентификаторов опций автомобиля
driver_extras	int[]		Массив из идентификаторов требований к водителю
destinations	Address[]		Массив из адресов назначения
company_id	int		Идентификатор службы такси
state	int		Статус заказа 1 - поиск водителя 2 - принят водителем 3 - на месте 4 - по маршруту 5 - выполнен 6 - отменен 7 - просрочен, водитель не найден 8 - зарезервирован за водителем
price	float		Цена
discount_price	float		Сумма скидки
discount_percent	float		Процент скидки
distance	float		Длина маршрута в метрах
create_time	str		Время создания заказа
done_time	str		Время выполнения заказа

Address

Поле	Тип данных	Default	Описание
street	string		Улица
building	string		Дом
comment	string		Примечание к адресу
lat	float		Широта
lng	float		Долгота

API

Содержание

Основные положения.

Адрес API сервера.

Протокол взаимодействия.

Авторизация.

Конфигурация API.

Список основных ошибок которые может вернуть сервис

Получение конфигураций компаний

Получение описания компании

Получение списка контактных номеров компании

Получение координат водителей компании для отображения на карте

Получение списка возможных причин отмены заказа

Отправка SMS с кодом активации номера телефона

Подтверждение телефона с помощью кода активации

Получить профиль клиента

Просчет стоимости поездки

Создание заказа

Список заказов клиента

Получение маршрута по заказу

Получение статуса заказа

Получение информации о водителе выполняющем заказ

Получение координат водителя

Отмена заказа

Оценка поездки

Типы данных

Навигация

Персональные инструменты

Пространства имён

Варианты

Просмотры

Ещё

Поиск

Навигация

Инструменты