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

Версия 13:16, 20 августа 2012

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

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

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

Содержание

1 Общее описание протокола
- 1.1 Формат запроса
- 1.2 Формат ответа
2 Описание запросов

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

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

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

@@ Строка 136: / Строка 136: @@
 |Список групп экипажей
 |-
-|id
+|&bull; id
 |Целое
 |ИД группы экипажей
 |-
-|name
+|&bull; name
 |Строка
 |Название группы экипажей
@@ Строка 190: / Строка 190: @@
 |Список служб [[Модуль «Единая диспетчерская служба»|ЕДС]]
 |-
-|id
+|&bull; id
 |Целое
 |ИД службы [[Модуль «Единая диспетчерская служба»|ЕДС]]
 |-
-|name
+|&bull; name
 |Строка
 |Название службы [[Модуль «Единая диспетчерская служба»|ЕДС]]
@@ Строка 244: / Строка 244: @@
 |Список [[Справочник «Тарифы»|тарифов]]
 |-
-|id
+|&bull; id
 |Целое
 |ИД [[Справочник «Тарифы»|тарифа]]
 |-
-|name
+|&bull; name
 |Строка
 |Название [[Справочник «Тарифы»|тарифа]]
@@ Строка 297: / Строка 297: @@
 |Список [[Справочник «Услуги»|услуг]]
 |-
-|id
+|&bull; id
 |Целое
 |ИД [[Справочник «Услуги»|услуги]]
 |-
-|name
+|&bull; name
 |Строка
 |Название [[Справочник «Услуги»|услуги]]
 |-
-|sum
+|&bull; sum
 |Дробное
 |Абсолютна сумма [[Справочник «Услуги»|услуги]], руб
 |-
-|percent
+|&bull; percent
 |Дробное
 |Процент [[Справочник «Услуги»|услуги]] от стоимости заказа, %
@@ Строка 362: / Строка 362: @@
 |Список [[Справочник «Скидки клиентов»|скидок]]
 |-
-|id
+|&bull; id
 |Целое
 |ИД [[Справочник «Скидки клиентов»|скидки]]
 |-
-|name
+|&bull; name
 |Строка
 |Название [[Справочник «Скидки клиентов»|скидки]]
 |-
-|sum
+|&bull; sum
 |Дробное
 |Абсолютна сумма [[Справочник «Скидки клиентов»|скидки]], руб
 |-
-|percent
+|&bull; percent
 |Дробное
 |Процент [[Справочник «Скидки клиентов»|скидки]] от стоимости заказа, %
@@ Строка 603: / Строка 603: @@
 !Описание
 |-
-|colspan="2"|sum
+|sum
 |Дробное
 |Рассчитанная общая сумма заказа
 |-
-|colspan="2"|info
+|info
 |Массив
 |Дополнительная информация по расчету суммы заказа
 |-
-|comment
+| &bull; comment
 |Строка
 |Описание позиции дополнительной информации по расчету суммы заказа
 |-
-|sum
+| &bull; sum
 |Строка
 |Сумма позиции дополнительной информации по расчету суммы заказа
 |}
+Пример:
+<pre>
+Запрос:
+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
+  }
+}
+</pre>

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

Версия 13:16, 20 августа 2012

Содержание

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

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

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

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

Запрос-пинг

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

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

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

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

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

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

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

Навигация

Просмотры

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

Навигация

Поиск

Инструменты