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

Материал из TaxiMaster
Перейти к: навигация, поиск
Строка 643: Строка 643:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
=== Запрос информации о водителе ===
 +
Метод: 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)
 +
|}
 +
 +
Пример:
 +
 +
<pre>
 +
Запрос:
 +
 +
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
 +
  }
 +
}
 +
</pre>
 +
 +
=== Запрос информации об автомобиле ===
 +
Метод: 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)
 +
|}
 +
 +
Пример:
 +
 +
<pre>
 +
Запрос:
 +
 +
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
 +
  }
 +
}
 +
</pre>
 +
 +
== Запрос координат экипажей ==
 +
Метод: GET
 +
Название запроса: get_crews_coords
 +
Параметры:
 +
{|
 +
!Параметры
 +
!Тип
 +
!Описание
 +
|-
 +
!Необязательные параметры
 +
|-
 +
|crew_id
 +
|Целое
 +
|ИД экипажа, по которому нужно вернуть координаты. Если не задано, то будут возвращены координаты всех экипажей на линии.
 +
|}
 +
 +
Специальные возвращаемые коды:
 +
{|
 +
!Код
 +
!Описание
 +
|-
 +
|100
 +
|Координаты не найдены
 +
|}
 +
 +
Возвращаемые данные в случае успешного выполнения запроса:
 +
{|
 +
!Параметр
 +
!Тип
 +
!Описание
 +
|-
 +
|crews_coords
 +
|Массив
 +
|Список координат экипажей
 +
|-
 +
|&bull; crew_id
 +
|Целое
 +
|ИД экипажа
 +
|-
 +
|&bull; crew_code
 +
|Строка
 +
|Позывной экипажа
 +
|-
 +
|&bull; coords_time
 +
|ГГГГММДДччммсс
 +
|Время получения координат
 +
|-
 +
|&bull; lat
 +
|Дробное
 +
|Долгота
 +
|-
 +
|&bull; lon
 +
|Дробное
 +
|Широта
 +
|-
 +
|&bull; state_kind
 +
|Строка
 +
|Тип состояния экипажа. Может принимать значения:
 +
• "not_available" — экипаж не на линии
 +
• "waiting" — экипаж свободен, ожидает заказы
 +
• "on_order" — экипаж на заказе
 +
• "on_break" — экипаж на перерыве
 +
|}

Версия 14:21, 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" — экипаж на перерыве

Источник — «http://help.taximaster.ru/index.php?title=TM_API&oldid=8572»