TM API
TMAPI - специальный набор инструментов Такси-Мастер, который позволит объединить систему с вашим сайтом и различными полезными сервисами. Он предоставляется вам на свободных условиях.
Благодаря этому набору вы сможете:
- Создать механизм приема заказов через интернет.
- Сделать ваш сайт более информативным: публиковать полезную для клиентов информацию прямо из системы - список ближайших экипажей, предварительный расчет стоимости поездки, мониторинг движения автомобиля такси в процессе выполнения заказа, карты города и контактную информацию.
- Расширить возможности своей службы за счет популярного онлайн-сервиса Яндекс Такси.
Содержание
Общее описание протокола
Формат запроса
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 | Строка | Сумма позиции дополнительной информации по расчету суммы заказа | |
