TM API — различия между версиями

Материал из TaxiMaster
Перейти к: навигация, поиск
Строка 103: Строка 103:
 
=== Запрос-пинг ===
 
=== Запрос-пинг ===
 
Для данного запроса не проверяется версия API, секретный ключ и тип запроса GET/ POST.
 
Для данного запроса не проверяется версия API, секретный ключ и тип запроса GET/ POST.
 +
 
Метод: GET или POST
 
Метод: GET или POST
 +
 
Название запроса: ping
 
Название запроса: ping
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса: нет
 
Возвращаемые данные в случае успешного выполнения запроса: нет
 +
 
Пример:
 
Пример:
  
Строка 123: Строка 129:
 
=== Запрос списка групп экипажей ===
 
=== Запрос списка групп экипажей ===
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_crew_groups_list
 
Название запроса: get_crew_groups_list
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса:
 
Возвращаемые данные в случае успешного выполнения запроса:
 
{|
 
{|
Строка 176: Строка 186:
  
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_uds_list
 
Название запроса: get_uds_list
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса:
 
Возвращаемые данные в случае успешного выполнения запроса:
  
Строка 231: Строка 245:
 
Метод: GET
 
Метод: GET
 
Название запроса: get_tariffs_list
 
Название запроса: get_tariffs_list
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса:
 
Возвращаемые данные в случае успешного выполнения запроса:
  
Строка 283: Строка 300:
 
=== Запрос списка услуг ===
 
=== Запрос списка услуг ===
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_services_list
 
Название запроса: get_services_list
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса:
 
Возвращаемые данные в случае успешного выполнения запроса:
  
Строка 348: Строка 369:
 
=== Запрос списка скидок ===
 
=== Запрос списка скидок ===
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_discounts_list
 
Название запроса: get_discounts_list
 +
 
Параметры: нет
 
Параметры: нет
 +
 
Специальные возвращаемые коды: нет
 
Специальные возвращаемые коды: нет
 +
 
Возвращаемые данные в случае успешного выполнения запроса:
 
Возвращаемые данные в случае успешного выполнения запроса:
  
Строка 413: Строка 438:
 
=== Создание нового заказа ===
 
=== Создание нового заказа ===
 
Метод: POST
 
Метод: POST
 +
 
Название запроса: create_order
 
Название запроса: create_order
 +
 
Параметры:
 
Параметры:
  
Строка 504: Строка 531:
  
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: calc_order_cost
 
Название запроса: calc_order_cost
 +
 
Параметры:
 
Параметры:
 
{|
 
{|
Строка 646: Строка 675:
 
=== Запрос информации о водителе ===
 
=== Запрос информации о водителе ===
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_driver_info
 
Название запроса: get_driver_info
 +
 
Параметры:
 
Параметры:
 
{|
 
{|
Строка 751: Строка 782:
 
=== Запрос информации об автомобиле ===
 
=== Запрос информации об автомобиле ===
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_car_info
 
Название запроса: get_car_info
 +
 
Параметры:
 
Параметры:
 
{|
 
{|
Строка 852: Строка 885:
 
== Запрос координат экипажей ==
 
== Запрос координат экипажей ==
 
Метод: GET
 
Метод: GET
 +
 
Название запроса: get_crews_coords
 
Название запроса: get_crews_coords
 +
 
Параметры:
 
Параметры:
 
{|
 
{|
Строка 909: Строка 944:
 
|Тип состояния экипажа. Может принимать значения:
 
|Тип состояния экипажа. Может принимать значения:
 
• "not_available" — экипаж не на линии
 
• "not_available" — экипаж не на линии
 +
 
• "waiting" — экипаж свободен, ожидает заказы
 
• "waiting" — экипаж свободен, ожидает заказы
 +
 
• "on_order" — экипаж на заказе
 
• "on_order" — экипаж на заказе
 +
 
• "on_break" — экипаж на перерыве
 
• "on_break" — экипаж на перерыве
 +
 +
|}
 +
 +
Пример:
 +
 +
<pre>
 +
 +
Запрос:
 +
GET https://ip:port/common_api/1.0/get_crews_coords HTTP/1.1
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "crews_coords":[
 +
      {
 +
        "crew_id":1,
 +
        "crew_code":"111",
 +
        "coords_time":"20120101101010",
 +
        "lat":11.111111,
 +
        "lon":22.222222,
 +
        "state_kind":"waiting"
 +
    },
 +
    {
 +
        "crew_id":2,
 +
        "crew_code":"222",
 +
        "coords_time":"20120101101010",
 +
        "lat":33.333333,
 +
        "lon":44.444444,
 +
        "state_kind":"on_order"
 +
      }
 +
    ]
 +
  }
 +
}
 +
 +
Запрос:
 +
 +
GET https://ip:port/common_api/1.0/get_crews_coords?crew_id=1 HTTP/1.1
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "crews_coords":[
 +
      {
 +
        "crew_id":1,
 +
        "crew_code":"111",
 +
        "coords_time":"20120101101010",
 +
        "lat":11.111111,
 +
        "lon":22.222222,
 +
        "state_kind":"waiting"
 +
      }
 +
    ]
 +
  }
 +
}
 +
</pre>
 +
 +
=== Запрос адресов, содержащих нужную строку ===
 +
Метод: GET
 +
 +
Название запроса: get_addresses_like
 +
 +
Параметры:
 +
 +
Параметры:
 +
{|
 +
!Параметры
 +
!Тип
 +
!Описание
 +
|-
 +
!Обязательные параметры
 +
|-
 +
|get_streets
 +
|true или false
 +
|Искать улицы
 +
|-
 +
|get_houses
 +
|true или false
 +
|Искать пункты
 +
|-
 +
|get_streets
 +
|true или false
 +
|Искать дома. Не может быть равно true, если get_streets = true или get_points = true.
 +
|-
 +
|street
 +
|Строка
 +
|Часть названия улицы или пункта, если идет поиск улиц или пунктов, или полное название улицы, если идет поиск домов
 +
|-
 +
!Необязательные параметры
 +
|-
 +
|house
 +
|Строка
 +
|Часть номера дома. Нужно только если get_houses = true.
 +
|-
 +
|max_addresses_count
 +
|Целое
 +
|Максимальное количество адресов в ответе
 +
|}
 +
 +
Специальные возвращаемые коды:
 +
{|
 +
!Код
 +
!Описание
 +
|-
 +
|100
 +
|Подходящие адреса не найдены
 +
|}
 +
 +
Возвращаемые данные в случае успешного выполнения запроса:
 +
{|
 +
!Параметр
 +
!Тип
 +
!Описание
 +
|-
 +
|addresses
 +
|Массив
 +
|Список подходящих адресов
 +
|-
 +
|&bull; street
 +
|Строка
 +
|Название улицы или пункта
 +
|-
 +
|&bull; house
 +
|Строка
 +
|Номер дома
 +
|-
 +
|&bull; kind
 +
|Строка
 +
|Тип адреса. Может принимать значения:
 +
 +
• "street" — улица
 +
 +
• "house" — дом
 +
 +
• "point" — пункт
 +
|-
 +
|&bull; comment
 +
|Строка
 +
|Комментарий
 +
|}
 +
 +
Пример:
 +
 +
<pre>
 +
 +
Запрос:
 +
 +
GET https://ip:port/common_api/1.0/get_addresses_like?get_streets=true&get_points=true&
 +
get_houses=false&street=STREE HTTP/1.1
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "addresses":[
 +
      {
 +
        "street":"STREET1",
 +
        "house":"",
 +
        "kind":"street",
 +
        "comment":""
 +
      },
 +
      {
 +
        "street":"STREET2",
 +
        "house":"",
 +
        "kind":"street",
 +
        "comment":""
 +
      },
 +
      {
 +
        "street":"POINT_STREET1",
 +
        "house":"",
 +
        "kind":"point",
 +
        "comment":"Point at street STREET1"
 +
      }
 +
    ]
 +
  }
 +
}
 +
 +
Запрос:
 +
 +
GET https://ip:port/common_api/1.0/get_addresses_like?get_streets=false&get_points=false&
 +
get_houses=true&street=STREET1&house=1&max_addresses_count=10 HTTP/1.1
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "addresses":[
 +
      {
 +
        "street":"STREET1",
 +
        "house":"1",
 +
        "kind":"house",
 +
        "comment":""
 +
      },
 +
      {
 +
        "street":"STREET1",
 +
        "house":"10",
 +
        "kind":"house",
 +
        "comment":""
 +
      },
 +
      {
 +
        "street":"STREET1",
 +
        "house":"11",
 +
        "kind":"house",
 +
        "comment":""
 +
      }
 +
    ]
 +
  }
 +
}
 +
</pre>
 +
 +
=== Анализ маршрута ===
 +
Метод: GET
 +
 +
Название запроса: analyze_route
 +
 +
Параметры:
 +
 +
{|
 +
!Параметры
 +
!Тип
 +
!Описание
 +
|-
 +
!Обязательные параметры
 +
|-
 +
|source
 +
|Строка
 +
|Адрес подачи
 +
|-
 +
|dest
 +
|Строка
 +
|Адрес назначения
 +
|}
 +
 +
Специальные возвращаемые коды:
 +
{|
 +
!Код
 +
!Описание
 +
|-
 +
|100
 +
|Адрес подачи не распознан
 +
|-
 +
|101
 +
|Адрес назначения не распознан
 +
|-
 +
|102
 +
|Маршрут не распознан
 +
|}
 +
 +
Возвращаемые данные в случае успешного выполнения запроса:
 +
{|
 +
!Параметр
 +
!Тип
 +
!Описание
 +
|-
 +
|source_lat 
 +
|Дробное
 +
|Широта адреса подачи
 +
|-
 +
|source_lon 
 +
|Целое
 +
|Долгота адреса подачи
 +
|-
 +
|source_zone_id 
 +
|Целое
 +
|ИД района подачи
 +
|-
 +
|dest_lat
 +
|Дробное
 +
|Широта адреса назначения
 +
|-
 +
|dest_lon 
 +
|Дробное
 +
|Долгота адреса назначения
 +
|-
 +
|dest_zone_id 
 +
|Целое
 +
|ИД района назначения
 +
|-
 +
|city_dist 
 +
|Дробное
 +
|Километраж по городу
 +
|-
 +
|country_dist 
 +
|Дробное
 +
|Километраж за городом
 +
|-
 +
|source_country_dist 
 +
|Дробное
 +
|Километраж до адреса подачи, если адрес подачи за городом
 +
|}
 +
 +
Пример:
 +
 +
<pre>
 +
Запрос:
 +
 +
GET https://ip:port/common_api/1.0/analyze_route?source=STREET1,1&dest=STREET2,2 HTTP/1.1
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "source_lat":11.111111,
 +
    "source_lon":22.222222,
 +
    "source_zone_id":1,
 +
    "dest_lat":33.333333,
 +
    "dest_lon":44.444444,
 +
    "dest_zone_id":2,
 +
    "city_dist":1.1,
 +
    "country_dist":2.2,
 +
    "source_country_dist":3.3
 +
  }
 +
}
 +
</pre>
 +
 +
=== Запрос информации о состоянии заказа ===
 +
 +
Метод: GET
 +
 +
Название запроса: get_order_state
 +
 +
Параметры:
 +
 +
{|
 +
!Параметры
 +
!Тип
 +
!Описание
 +
|-
 +
!Обязательные параметры
 +
|-
 +
|order_id 
 +
|Целое
 +
|ИД заказа
 +
|}
 +
 +
Специальные возвращаемые коды:
 +
{|
 +
!Код
 +
!Описание
 +
|-
 +
|100
 +
|Заказ не найден
 +
|}
 +
 +
Возвращаемые данные в случае успешного выполнения запроса:
 +
{|
 +
!Параметр
 +
!Тип
 +
!Описание
 +
|-
 +
|order_id 
 +
|Целое
 +
|ИД заказа
 +
|-
 +
|state_id 
 +
|Целое
 +
|ИД состояния заказа
 +
|-
 +
|state_kind
 +
|Строка
 +
|Тип состояния заказа. Может принимать значения:
 +
 +
• "new_order" — новый заказ
 +
 +
• "driver_assigned" — водитель назначен
 +
 +
• "car_at_place" — машина подъехала на место
 +
 +
• "client_inside" — клиент в машине
 +
 +
• "finished" — заказ успешно завершен
 +
 +
• "aborted" — заказ прекращен
 +
|-
 +
|crew_id 
 +
|Целое
 +
|ИД экипажа
 +
|-
 +
|driver_id 
 +
|Целое
 +
|ИД водителя
 +
|-
 +
|car_id 
 +
|Целое
 +
|ИД автомобиля
 
|}
 
|}
 +
 +
Пример:
 +
 +
<pre>
 +
Запрос:
 +
 +
GET https://ip:port/common_api/1.0/get_order_state?order_id=1 HTTP/1.1
 +
 +
Signature: <...>
 +
 +
Ответ:
 +
 +
{
 +
  "code":0,
 +
  "descr":"OK",
 +
  "data":{
 +
    "order_id":1,
 +
    "state_id":12,
 +
    "state_kind":"car_at_place",
 +
    "crew_id":1,
 +
    "driver_id":2,
 +
    "car_id":3
 +
  }
 +
}
 +
</pre>
 +
 +
[[Категория:ТМ2]]

Версия 15:18, 20 августа 2012

TMAPI - специальный набор инструментов Такси-Мастер, который позволит объединить систему с вашим сайтом и различными полезными сервисами. Он предоставляется вам на свободных условиях.

Благодаря этому набору вы сможете:

  1. Создать механизм приема заказов через интернет.
  2. Сделать ваш сайт более информативным: публиковать полезную для клиентов информацию прямо из системы - список ближайших экипажей, предварительный расчет стоимости поездки, мониторинг движения автомобиля такси в процессе выполнения заказа, карты города и контактную информацию.
  3. Расширить возможности своей службы за счет популярного онлайн-сервиса Яндекс Такси.

Общее описание протокола

Формат запроса

TMWeb принимает входящие запросы по протоколу HTTPS. В URI запроса после ip адреса и порта, который будет слушать TMWeb, должно идти название API (common_api) и версия API. Пример: 

GET https://ip:port/common_api/1.0/get_crew_groups_list HTTP/1.1

Для получения данных из БД используются запросы типа GET. Для записи данных в базу данных используются запросы типа POST. В запросе типа GET параметры запроса передаются в URI. Пример: 

GET https://ip:port/common_api/1.0/calc_order_cost?tariff_id=1&distance_city=10 HTTP/1.1
Signature: <...>

В запросе типа POST параметры передаются в теле запроса в формате application/x-wwwform-urlencoded. Пример: 

POST https://ip:port/common_api/1.0/create_order HTTP/1.1
Signature: <...>
Content-Type: application/x-www-form-urlencoded
Content-Length: 118

phone=89123456789&source=SOURCE&source_time=20120501100000&dest=DEST&customer=CUSTOMER&
comment=COMMENT&crew_group_id=1

В любом запросе обязательно должен быть заголовок Signature. В нем передается MD5 хэш, рассчитанный для строки, которая получается сцеплением строки параметров запроса с секретным ключом. Секретный ключ задается в настройках модуля TMWeb в ТМ2. Пример: 

Запрос:
GET https://ip:port/common_api/1.0/calc_order_cost?tariff_id=1&distance_city=10 HTTP/1.1

Секретный ключ:
1234567890

Signature = MD5("tariff_id=1&distance_city=10" + "1234567890") = d7b8fb11b5499b64d750b8efe53e2877

Формат ответа

TMWeb всегда возвращает HTTP код 200 ОК. Результат выполнения запроса содержится в теле ответа в формате JSON. Общий вид возвращаемого результата: 

{
"code":<Числовой код результата>,
"descr":"<Строковое описание результата>",
"data":{<Дополнительная информация>}
}

Существуют общие для всех запросов коды результатов:

Код Описание
0 Успешное выполнение запроса
1 Неизвестная ошибка
2 Неизвестный тип API
3 API отключено в настройках TMWeb
4 Не совпадает секретный ключ
5 Неподдерживаемая версия API
6 Неизвестное название запроса
7 Неверный тип запроса GET/POST
8 Не хватает входного параметра (в доп. информации ответа будет название отсутствующего параметра)
9 Некорректный входной параметр (в доп. информации ответа будет название некорректного параметра)
10 Внутренняя ошибка обработки запроса

Описание запросов

Запрос-пинг

Для данного запроса не проверяется версия API, секретный ключ и тип запроса GET/ POST.

Метод: GET или POST

Название запроса: ping

Параметры: нет

Специальные возвращаемые коды: нет

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

Пример: 

Запрос:
GET https://ip:port/common_api/1.0/ping HTTP/1.1
Ответ:
{
"code":0,
"descr":"OK",
"data":{}
}

Запрос списка групп экипажей

Метод: GET

Название запроса: get_crew_groups_list

Параметры: нет

Специальные возвращаемые коды: нет

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
crew_groups Массив Список групп экипажей
• id Целое ИД группы экипажей
• name Строка Название группы экипажей

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_crew_groups_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "crew_groups":[
     {
       "id":1,
       "name":"CREW_GROUP1"
     },
     {
       "id":2,
       "name":"CREW_GROUP2"
     }
    ]
  }
}

Запрос списка служб ЕДС

Метод: GET

Название запроса: get_uds_list

Параметры: нет

Специальные возвращаемые коды: нет

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
uds Массив Список служб ЕДС
• id Целое ИД службы ЕДС
• name Строка Название службы ЕДС

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_uds_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "uds":[
      {
        "id":1,
        "name":"UDS1"
      },
      {
        "id":2,
        "name":"UDS2"
      }
    ]
  }
}

Запрос списка тарифов

Метод: GET Название запроса: get_tariffs_list

Параметры: нет

Специальные возвращаемые коды: нет

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
tariffs Массив Список тарифов
• id Целое ИД тарифа
• name Строка Название тарифа

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_tariffs_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "tariffs":[
      {
        "id":1,
        "name":"TARIFF1"
      },
      {
         "id":2,
         "name":"TARIFF2"
      }
    ]
  }
}

Запрос списка услуг

Метод: GET

Название запроса: get_services_list

Параметры: нет

Специальные возвращаемые коды: нет

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
services Массив Список услуг
• id Целое ИД услуги
• name Строка Название услуги
• sum Дробное Абсолютна сумма услуги, руб
• percent Дробное Процент услуги от стоимости заказа, %

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_services_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "services":[
      {
        "id":1,
        "name":"SERVICE1",
        "sum":100,
        "percent":0
      },
      {
        "id":2,
        "name":"SERVICE2"
        "sum":0,
        "percent":10
      }
    ]
  }
}

Запрос списка скидок

Метод: GET

Название запроса: get_discounts_list

Параметры: нет

Специальные возвращаемые коды: нет

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
services Массив Список скидок
• id Целое ИД скидки
• name Строка Название скидки
• sum Дробное Абсолютна сумма скидки, руб
• percent Дробное Процент скидки от стоимости заказа, %

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_discounts_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "discounts":[
      {
        "id":1,
        "name":"DISCOUNT1",
        "sum":100,
        "percent":0
      },
      {
        "id":2,
        "name":"DISCOUNT2"
        "sum":0,
        "percent":10
      }
    ]
  }
}

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

Метод: POST

Название запроса: create_order

Параметры:

Параметр Тип Описание
Обязательные параметры
phone Строка, <= 16 символов Номер телефона
source Строка Адрес подачи
source_time ГГГГММДДччммсс Время подачи
Необязательные параметры
dest Строка Адрес назначения
customer Строка Заказчик
comment Строка Комментарий
crew_group_id Целое ИД группы экипажей
uds_id Целое ИД службы ЕДС

Специальные возвращаемые коды:

Код Описание
100 Заказ с такими параметрами уже создан

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
order_id Целое ИД созданного заказа

Пример: 

Запрос:

POST https://ip:port/common_api/1.0/create_order HTTP/1.1
Signature: <...>
Content-Type: application/x-www-form-urlencoded
Content-Length: 127
phone=89123456789&source=SOURCE&source_time=20120501100000&dest=DEST&customer=CUSTOMER&
comment=COMMENT&crew_group_id=1&uds_id=1

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "order_id":12345
  }
}

Расчет суммы заказа

Метод: GET

Название запроса: calc_order_cost

Параметры:

Параметр Тип Описание
Обязательные параметры
tariff_id Целое ИД тарифа
Необязательные параметры
source_time ГГГГММДДччммсс Время подачи
is_prior true или false Предварительный заказ
client_id Целое ИД клиента
discount_id Целое ИД скидки
disc_card_id Целое ИД дисконтной карты
source_zone_id Целое ИД района подачи
dest_zone_id Целое ИД района назначения
distance_city Дробное Километраж по городу
distance_country Дробное Километраж за городом
source_distance_country Дробное Километраж до подачи за городом
is_country true или false Загородный заказ
waiting_minutes Целое Время ожидания посадки клиента в минутах
is_hourly true или false Почасовой заказ
hourly_minutes Целое Длительность почасового заказа в минутах
is_prize true или false Призовой заказ
back_way true или false Обратный путь за городом
services Строка Список ИД услуг через точку с запятой, пример: «1;2;3»

Специальные возвращаемые коды:

Код Описание
Тариф не найден Ошибка при расчете по тарифу

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
sum Дробное Рассчитанная общая сумма заказа
info Массив Дополнительная информация по расчету суммы заказа
• comment Строка Описание позиции дополнительной информации по расчету суммы заказа
• sum Строка Сумма позиции дополнительной информации по расчету суммы заказа

Пример: 

Запрос: 

GET https://ip:port/common_api/1.0/get_crew_info?crew_id=1 HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "crew_id":1,
    "code":"123",
    "name":"CREW_NAME",
    "driver_id":1,
    "car_id":1,
    "crew_group_id":1
  }
}

Запрос информации о водителе

Метод: GET

Название запроса: get_driver_info

Параметры:

Параметры Тип Описание
Обязательные параметры
driver_id Целое ИД водителя
Необязательные параметры
need_photo true или false Нужна ли фотография водителя

Специальные возвращаемые коды:

Код Описание
100 Водитель не найден

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

Параметр Тип Описание
driver_id Целое ИД водителя
name Целое ФИО водителя
birthday ДД.ММ.ГГГГ День рождения водителя
car_id Целое ИД основного автомобиля водителя
license Строка Удостоверение водителя
home_phone Строка Домашний телефон водителя
mobile_phone Строка Мобильный телефон водителя
is_locked true или false Водитель заблокирован
is_dismissed true или false Водитель уволен
driver_photo Base64 Фото водителя (только если need_photo = true)

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_driver_info?driver_id=1&need_photo=false HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "driver_id":1,
    "name":"DRIVER_NAME",
    "birthday":"01.01.1980",
    "car_id":1,
    "license":"1234567890",
    "home_phone":"123456",
    "mobile_phone":"+79123456789",
    "is_locked":false,
    "is_dismissed":false
  }
}

Запрос информации об автомобиле

Метод: GET

Название запроса: get_car_info

Параметры:

Параметры Тип Описание
Обязательные параметры
car_id Целое ИД автомобиля
Необязательные параметры
need_photo true или false Нужна ли фотография автомобиля

Специальные возвращаемые коды:

Код Описание
100 Автомобиль не найден

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
car_id Целое ИД автомобиля
name Строка Наименование автомобиля
code Строка Позывной автомобиля
gos_number Строка Государственный номер автомобиля
color Строка Цвет автомобиля
mark Строка Марка автомобиля
short_name Строка Краткое название автомобиля
production_year true или false Год выпуска автомобиля
car_photo Base64 Фото автомобиля (только если need_photo = true)

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_car_info?car_id=1&need_photo=false HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "car_id":1,
    "code":"123",
    "name":"CAR_NAME",
    "gos_number":"a123bc",
    "color":"COLOR",
    "mark":"MARK",
    "model":"MODEL",
    "short_name":"SHORT_NAME",
    "production_year":2000
  }
}

Запрос координат экипажей

Метод: GET

Название запроса: get_crews_coords

Параметры:

Параметры Тип Описание
Необязательные параметры
crew_id Целое ИД экипажа, по которому нужно вернуть координаты. Если не задано, то будут возвращены координаты всех экипажей на линии.

Специальные возвращаемые коды:

Код Описание
100 Координаты не найдены

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
crews_coords Массив Список координат экипажей
• crew_id Целое ИД экипажа
• crew_code Строка Позывной экипажа
• coords_time ГГГГММДДччммсс Время получения координат
• lat Дробное Долгота
• lon Дробное Широта
• state_kind Строка Тип состояния экипажа. Может принимать значения:

• "not_available" — экипаж не на линии

• "waiting" — экипаж свободен, ожидает заказы

• "on_order" — экипаж на заказе

• "on_break" — экипаж на перерыве

Пример: 


Запрос:
GET https://ip:port/common_api/1.0/get_crews_coords HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "crews_coords":[
      {
        "crew_id":1,
        "crew_code":"111",
        "coords_time":"20120101101010",
        "lat":11.111111,
        "lon":22.222222,
        "state_kind":"waiting"
     },
     {
        "crew_id":2,
        "crew_code":"222",
        "coords_time":"20120101101010",
        "lat":33.333333,
        "lon":44.444444,
        "state_kind":"on_order"
      }
    ]
  }
}

Запрос:

GET https://ip:port/common_api/1.0/get_crews_coords?crew_id=1 HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "crews_coords":[
      {
        "crew_id":1,
        "crew_code":"111",
        "coords_time":"20120101101010",
        "lat":11.111111,
        "lon":22.222222,
        "state_kind":"waiting"
      }
    ]
  }
}

Запрос адресов, содержащих нужную строку

Метод: GET

Название запроса: get_addresses_like

Параметры:

Параметры:

Параметры Тип Описание
Обязательные параметры
get_streets true или false Искать улицы
get_houses true или false Искать пункты
get_streets true или false Искать дома. Не может быть равно true, если get_streets = true или get_points = true.
street Строка Часть названия улицы или пункта, если идет поиск улиц или пунктов, или полное название улицы, если идет поиск домов
Необязательные параметры
house Строка Часть номера дома. Нужно только если get_houses = true.
max_addresses_count Целое Максимальное количество адресов в ответе

Специальные возвращаемые коды:

Код Описание
100 Подходящие адреса не найдены

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
addresses Массив Список подходящих адресов
• street Строка Название улицы или пункта
• house Строка Номер дома
• kind Строка Тип адреса. Может принимать значения:

• "street" — улица

• "house" — дом

• "point" — пункт

• comment Строка Комментарий

Пример: 


Запрос:

GET https://ip:port/common_api/1.0/get_addresses_like?get_streets=true&get_points=true&
get_houses=false&street=STREE HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "addresses":[
      {
        "street":"STREET1",
        "house":"",
        "kind":"street",
        "comment":""
      },
      {
        "street":"STREET2",
        "house":"",
        "kind":"street",
        "comment":""
      },
      {
        "street":"POINT_STREET1",
        "house":"",
        "kind":"point",
        "comment":"Point at street STREET1"
      }
    ]
  }
}

Запрос:

GET https://ip:port/common_api/1.0/get_addresses_like?get_streets=false&get_points=false&
get_houses=true&street=STREET1&house=1&max_addresses_count=10 HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "addresses":[
      {
        "street":"STREET1",
        "house":"1",
        "kind":"house",
        "comment":""
      },
      {
        "street":"STREET1",
        "house":"10",
        "kind":"house",
        "comment":""
      },
      {
        "street":"STREET1",
        "house":"11",
        "kind":"house",
        "comment":""
      }
    ]
  }
}

Анализ маршрута

Метод: GET

Название запроса: analyze_route

Параметры:

Параметры Тип Описание
Обязательные параметры
source Строка Адрес подачи
dest Строка Адрес назначения

Специальные возвращаемые коды:

Код Описание
100 Адрес подачи не распознан
101 Адрес назначения не распознан
102 Маршрут не распознан

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
source_lat Дробное Широта адреса подачи
source_lon Целое Долгота адреса подачи
source_zone_id Целое ИД района подачи
dest_lat Дробное Широта адреса назначения
dest_lon Дробное Долгота адреса назначения
dest_zone_id Целое ИД района назначения
city_dist Дробное Километраж по городу
country_dist Дробное Километраж за городом
source_country_dist Дробное Километраж до адреса подачи, если адрес подачи за городом

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/analyze_route?source=STREET1,1&dest=STREET2,2 HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "source_lat":11.111111,
    "source_lon":22.222222,
    "source_zone_id":1,
    "dest_lat":33.333333,
    "dest_lon":44.444444,
    "dest_zone_id":2,
    "city_dist":1.1,
    "country_dist":2.2,
    "source_country_dist":3.3
  }
}

Запрос информации о состоянии заказа

Метод: GET

Название запроса: get_order_state

Параметры:

Параметры Тип Описание
Обязательные параметры
order_id Целое ИД заказа

Специальные возвращаемые коды:

Код Описание
100 Заказ не найден

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
order_id Целое ИД заказа
state_id Целое ИД состояния заказа
state_kind Строка Тип состояния заказа. Может принимать значения:

• "new_order" — новый заказ

• "driver_assigned" — водитель назначен

• "car_at_place" — машина подъехала на место

• "client_inside" — клиент в машине

• "finished" — заказ успешно завершен

• "aborted" — заказ прекращен

crew_id Целое ИД экипажа
driver_id Целое ИД водителя
car_id Целое ИД автомобиля

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_order_state?order_id=1 HTTP/1.1

Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "order_id":1,
    "state_id":12,
    "state_kind":"car_at_place",
    "crew_id":1,
    "driver_id":2,
    "car_id":3
  }
}
Источник — «http://help.taximaster.kz/index.php?title=TM_API&oldid=8573»