TM API — различия между версиями
Материал из TaxiMaster
м (→Описание запросов) |
(Поправлена опечатка в "Запрос адресов, содержащих нужную строку") |
||
| Строка 1201: | Строка 1201: | ||
|get_streets | |get_streets | ||
|true или false | |true или false | ||
| − | |Искать дома. Не может быть равно true, если get_streets = true или | + | |Искать дома. Не может быть равно true, если get_streets = true или get_houses = true. |
|- | |- | ||
|street | |street | ||
Версия 09:37, 10 января 2014
TM API - специальный набор инструментов Такси-Мастер, который позволит объединить систему с вашим сайтом и различными полезными сервисами. Он предоставляется вам на свободных условиях.
Благодаря этому набору вы сможете:
- Создать механизм приема заказов через интернет.
- Сделать ваш сайт более информативным: публиковать полезную для клиентов информацию прямо из системы - список ближайших экипажей, предварительный расчет стоимости поездки, мониторинг движения автомобиля такси в процессе выполнения заказа, карты города и контактную информацию.
- Расширить возможности своей службы за счет популярного онлайн-сервиса Яндекс Такси.
Содержание
- 1 Параметры TM API
- 2 Общее описание протокола
- 3 Описание запросов
- 3.1 Запрос-пинг
- 3.2 Запрос списка групп экипажей
- 3.3 Запрос списка служб ЕДС
- 3.4 Запрос списка тарифов
- 3.5 Запрос списка услуг
- 3.6 Запрос списка скидок
- 3.7 Создание нового заказа
- 3.8 Расчет суммы заказа
- 3.9 Запрос информации об экипаже
- 3.10 Запрос информации о водителе
- 3.11 Запрос информации об автомобиле
- 3.12 Запрос координат экипажей
- 3.13 Запрос адресов, содержащих нужную строку
- 3.14 Анализ маршрута
- 3.15 Запрос информации о состоянии заказа
- 3.16 Создание задачи СМС серверу
- 3.17 Проверка авторизации
- 3.18 Регистрация клиента
- 3.19 Запрос информации по клиенту
- 3.20 Изменение информации по клиенту
- 3.21 Запрос текущих заказов
- 3.22 Запрос выполненных заказов
- 3.23 Проведение операции по клиенту
- 3.24 Запрос операций по клиенту
- 4 Описание протокола TMTAPI Версия 1.0
- 5 Пример формы для заказа такси
Параметры TM API
Задать настройки для корректной работы TM API вы сможете в программе Такси-Мастер в меню Настройки в одноименной ветке TM API. Параметры организуют и контролируют работу модуля «Интернет-заказы».
- Установите флажок
Использовать TM API, чтобы приступить к его использованию. - В поле Локальный порт введите номер порта подключения к интернету, на котором работает и будет ожидать запросы о новых заказах TMServer. Рекомендуется оставить номер порта по умолчанию.
- Установите флажок Можно использовать данное рабочее место TMServer для распознавания адресов для того, чтобы конкретно с данного рабочего места происходило распознавание адресов модулем "Интернет-заказы".
- Перезапустите Такси-Мастер и TMServer для запуска работы модуля.
Ветка «Открытое API»
В данной ветке регулируется доступ к синхронизации Такси-Мастер со сторонним сервисом (сайтом), с помощью которого клиенты будут создавать интернет-заказы. С примером кода для работы вы можете ознакомиться в данной статье в разделе Общее описание протокола.
- Установите флажок Использовать открытое API для того, чтобы запустить работу по обслуживанию модуля «Интернет-заказы». При установленном флажке сервер модуля «Интернет-заказы» запускается и ожидает запросы о новых заказах.
- В поле Секретный ключ укажите номер секретного ключа для работы с модулем «Интернет-заказы», который будет выслан вам в письме от менеджера.
- Перезапустите Такси-Мастер и TMServer для запуска работы модуля.
Ветка «API для телефонии»
В данной ветке регулируются настройки API для телефонии, т.е. взаимодействие Такси-Мастер с call-центром через программный интерфейс. С его помощью call-центр может дать команду Такси-Мастер создать заказ или запросить информацию о статусе текущего заказа.
- Установите флажок Использовать открытое API для телефонии для того, чтобы запустить работу по обслуживанию телефонии через API.
- В поле Секретный ключ укажите номер секретного ключа для работы.
- Перезапустите Такси-Мастер и TMServer для запуска работы модуля.
Ветка «Платежные терминалы»
Ранее для связи платежных систем и Такси-Мастер служила такая утилита, как TMWeb. В данный момент мы отказались от ее использования, а функции были распределены между двумя компонентами системы: TM API и TMServer.
Параметры этой ветки отвечают за работу модуля интеграции с платежными системами.
- Установите флажок Включить прием терминальных платежей. Данная функция позволит отображать все платежные операции по приходу средств от водителей через терминалы в базе данных программы.
- В поле Секретный ключ укажите номер секретного ключа для работы с платежными системами и сверки платежей, который будет выслан вам в письме от менеджера. Секретный ключ - это определенный набор символов, необходимый для формирования подписи при передаче информации о платеже.
- В полях Логин и Пароль введите данные учетной записи на сайте http://term.bitmaster.ru.
- Кнопка Задать всем водителям терминальный аккаунт по их ИД служит для соединения TM API с сервером Такси-Мастер. В результате соединения записи о терминальных аккаунтах генерируются, заносятся (для тех водителей, у которых они отсутствуют) и обновляются (для тех водителей, у которых уже существуют терминальные аккаунты) в Такси-Мастер.
- Перезапустите Такси-Мастер и TMServer для запуска работы модуля.
Обратите внимание, что для платежных систем также существует открытый и свободно распространяемый API, с помощью которого есть возможность связать Такси-Мастер и платежные системы. Обратитесь в отдел дополнительных услуг, написав на odu@bitmaster.ru, за получением кода для данного компонента системы.
Общее описание протокола
Формат запроса
TMAPI принимает входящие запросы по протоколу 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 | Строка | Название тарифа |
| • is_active | true или false | Активный тариф |
Пример:
Запрос:
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"
"is_active":true
},
{
"id":2,
"name":"TARIFF2"
"is_active":true
}
]
}
}
Запрос списка услуг
Метод: 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
Параметры: нет
Специальные возвращаемые коды: нет
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| discounts | Массив | Список скидок |
| • 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 | Целое | ИД службы ЕДС |
| tariff_id | Целое | ИД тарифа |
| is_prior | true или false | Предварительный заказ |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Заказ с такими параметрами уже создан |
| 101 | Тариф не найден |
| 102 | Группа экипажа не найдена |
| 103 | Служба ЕДС не найдена |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| 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&tariff_id=3&is_prior=false
Ответ:
{
"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» |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Тариф не найден |
| 101 | Ошибка при расчете по тарифу |
| 102 | Скидка не найдена |
| 103 | Клиент не найден |
| 104 | Район подачи не найден |
| 105 | Район назначения не найден |
| 106 | Дисконтная карта не найдена |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| sum | Дробное | Рассчитанная общая сумма заказа |
| info | Массив | Дополнительная информация по расчету суммы заказа |
| • comment | Строка | Описание позиции дополнительной информации по расчету суммы заказа |
| • sum | Строка | Сумма позиции дополнительной информации по расчету суммы заказа |
Пример:
Запрос:
GET https://ip:port/common_api/1.0/calc_order_cost?
tariff_id=1&source_time=20120501100000&is_prior=false&client_id=1&discount_id=1&disc_card_id=1&sour
ce_zone_id=1&dest_zone_id=2&distance_city=10&distance_country=20&source_distance_country=5&is_count
ry=true&waiting_minutes=10&is_hourly=false&hourly_minutes=60&is_prize=true&back_way=false&services=
1;2;3 HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"sum":1000,
"info":[
{
"comment":"SUM1",
"sum":"100"
},
{
"comment":"SUM2",
"sum":"200"
}
]
}
}
Запрос информации об экипаже
Метод: GET
Название запроса: get_crew_info
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| crew_id | Целое | ИД экипажа |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Экипаж не найден |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| crew_id | Целое | ИД экипажа |
| code | Строка | Позывной экипажа |
| name | Строка | Наименование экипажа |
| driver_id | Целое | ИД водителя |
| car_id | Целое | ИД автомобиля |
| crew_group_id | Целое | ИД группы экипажа |
Пример:
Запрос:
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 | Целое | Год выпуска автомобиля |
| 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_houses = 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 | Целое | ИД экипажа |
| prior_crew_id | Целое | ИД предварительного экипажа |
| driver_id | Целое | ИД водителя |
| car_id | Целое | ИД автомобиля |
| start_time | ГГГГММДДччммсс | Время создания заказа |
| source_time | ГГГГММДДччммсс | Время подачи |
| finish_time | ГГГГММДДччммсс | Время завершения заказа |
| source | Строка | Адрес подачи |
| destination | Строка | Адрес назначения |
| passenger | Строка | Пассажир |
| phone | Строка | Номер телефона |
Пример:
Запрос:
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,
"prior_crew_id":0,
"driver_id":2,
"car_id":3
"start_time":"17.01.2013 12:56:41",
"source_time":"17.01.2013 13:26:17",
"finish_time":"17.01.2013 13:03:43",
"source":"1",
"destination":"2",
"passenger":"Слепаков",
"phone":"8800"
}
}
Создание задачи СМС серверу
Метод: POST
Название запроса: send_sms
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| phone | Строка, <= 16 символов | Номер телефона |
| message | Строка | Текст СМС |
Специальные возвращаемые коды: нет
Возвращаемые данные в случае успешного выполнения запроса: нет
Пример:
Запрос:
POST /common_api/1.0/send_sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 33
Signature: <...>
message=SMSText&phone=89050057216
Ответ:
{
"code":0,
"descr":"OK",
"data":{}
}
Проверка авторизации
Метод: GET
Название запроса: check_authorization
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| login | Строка, <= 60 символов | Логин |
| password | Строка, <= 60 символов | Пароль |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент с логином LOGIN и/или неверный пароль |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| client_id | Целое | ИД клиента |
Пример:
Запрос:
GET https://ip:port/common_api/1.0/check_authorization?login=LOGIN&password=PASSWORD HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"client_id":131
}
}
Регистрация клиента
Метод: POST
Название запроса: register_client
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| name | Строка, <= 60 символов | ФИО |
| login | Строка, <= 60 символов | Логин |
| password | Строка, <= 60 символов | Пароль |
| phones | Строка | Номера телефонов (через запятую) |
| Необязательные параметры | ||
| address | Строка | Домашний адрес |
| birthday | Строка | Дата рождения |
| gender | Строка | Пол. Может принимать значения:
• "male" - мужской • "female" - женский |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Клиент с номером телефона=PHONE уже существует |
| 101 | Клиент с логином=LOGIN уже существует |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| client_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
name=NAME&phones=88,99&login=LOGIN&password=PASSWORD&birthday=19930218115517&gender=male&address=ADDRESS
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"client_id":140
}
}
Запрос информации по клиенту
Метод: GET
Название запроса: get_client_info
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент ИД=CLIENT_ID |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| client_id | Целое | ИД клиента |
| name | Строка | ФИО |
| number | Строка | Номер договора |
| address | Строка | Домашний адрес |
| gender | Строка | Пол. Может принимать значения:
• "male" - мужской • "female" - женский |
| birthday | ДД.ММ.ГГГГ | Дата рождения |
| phones | Строка | Номера телефонов (через запятую) |
| balance | Дробное | Баланс |
| login | Строка | Логин |
| password | Строка | Пароль |
Пример:
Запрос:
GET https://ip:port/common_api/1.0/get_client_info?client_id=140 HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"client_id":140,
"name":"Васильев Артём",
"number":"000140",
"address":"Бутово,45",
"gender":"male",
"birthday":"18.02.1993",
"phones":"[\"88\",\"99\"]",
"balance":1467,
"login":"artem",
"password":"vasilev"
}
}
Изменение информации по клиенту
Метод: POST
Название запроса: update_client_info
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента |
| Необязательные параметры | ||
| name | Строка, <= 60 символов | ФИО |
| login | Строка, <= 60 символов | Логин |
| password | Строка, <= 60 символов | Пароль |
| phones | Строка | Номера телефонов (через запятую) |
| address | Строка | Домашний адрес |
| birthday | Строка | Дата рождения |
| gender | Строка | Пол. Может принимать значения:
• "male" - мужской • "female" - женский |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Клиент с номером телефона=PHONE уже существует |
| 101 | Клиент с логином=LOGIN уже существует |
Возвращаемые данные в случае успешного выполнения запроса: нет
Пример:
Запрос:
POST https://ip:port/common_api/1.0/create_order HTTP/1.1
Signature: <...>
Content-Type: application/x-www-form-urlencoded
Content-Length: 127
client_id=140&name=NAME&phones=88,99&login=LOGIN&password=PASSWORD&birthday=19930218115517&gender=male&address=ADDRESS
Ответ:
{
"code":0,
"descr":"OK",
"data":{}
}
Запрос текущих заказов
Метод: GET
Название запроса: get_current_orders
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента (может отсутствовать, если phone заполнен) |
| phone | Строка, <= 16 символов | Телефон клиента (может отсутствовать, если client_id заполнен) |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент ИД=CLIENT_ID |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| id | Целое | ИД заказа |
| state_id | Целое | ИД состояния заказа |
| start_time | ГГГГММДДччммсс | Дата создания заказа |
| source_time | ГГГГММДДччммсс | Время подачи |
| source | Строка | Адрес подачи |
| destination | Строка | Адрес назначения |
| passenger | Строка | Пассажир |
| crew_id | Целое | ИД экипажа |
| prior_crew_id | Целое | ИД предварительного экипажа |
| driver_id | Целое | ИД водителя |
Пример:
Запрос:
GET https://ip:port/common_api/1.0/get_current_orders?client_id=140&phone=18 HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"orders":[
{
"id":20648,
"state_id":44,
"start_time":"20130204181111",
"source_time":"20130204181111",
"source":"1-й пр-т \/Москва\/,",
"destination":"12-й мкр,",
"passenger":"маша",
"crew_id":0,
"prior_crew_id":0,
"driver_id":0
},
{
"id":20670,
"state_id":44,
"start_time":"20130207153022",
"source_time":"20130207153022",
"source":"11-й мкр,",
"destination":"1-й пр-т \/Москва\/,",
"passenger":"саша",
"crew_id":0,
"prior_crew_id":0,
"driver_id":0
}
]
}
}
Запрос выполненных заказов
Метод: GET
Название запроса: get_finished_orders
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента (может отсутствовать, если phone заполнен) |
| phone | Строка, <= 16 символов | Телефон клиента (может отсутствовать, если client_id заполнен) |
| start_time | ГГГГММДДччммсс | Начало периода |
| finish_time | ГГГГММДДччммсс | Конец периода |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент ИД=CLIENT_ID |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| id | Целое | ИД заказа |
| state_id | Целое | ИД состояния заказа |
| start_time | ГГГГММДДччммсс | Время создания заказа |
| source_time | ГГГГММДДччммсс | Время подачи |
| finish_time | ГГГГММДДччммсс | Время завершения заказа |
| source | Строка | Адрес подачи |
| destination | Строка | Адрес назначения |
| passenger | Строка | Пассажир |
| sum | Дробное | Стоимость заказа без учета скидок(наценок) |
| crew_id | Целое | ИД экипажа |
| prior_crew_id | Целое | ИД предварительного экипажа |
| driver_id | Целое | ИД водителя |
| car_id | Целое | ИД автомобиля |
Пример:
Запрос:
GET https://ip:port/common_api/1.0/get_finished_orders?client_id=140&phone= HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"orders":[
{
"id":20651,
"state_id":34,
"source_time":"20130205110812",
"start_time":"20130205110812",
"finish_time":"20130205115618",
"source":"прпроп",
"destination":"рррррр",
"passenger":"вера",
"sum":"908",
"crew_id":"6",
"prior_crew_id":0,
"driver_id":"4",
"car_id":"6"
},
{
"id":20669,
"state_id":34,
"source_time":"20130205130500",
"start_time":"20130205130500",
"finish_time":"20130205134511",
"source":"1",
"destination":"2",
"passenger":"маша",
"sum":"454",
"crew_id":"6",
"prior_crew_id":0,
"driver_id":"4",
"car_id":"6"
}
]
}
}
Проведение операции по клиенту
Метод: POST
Название запроса: create_client_operation
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента |
| oper_time | ГГГГММДДччммсс | Время создания операции |
| sum | Дробное | Сумма |
| oper_type | Целое | Тип операции:
• "receipt" - приход • "expense" - расход |
| pay_type | Целое | Тип оплаты:
• "cash" - наличный • "nocash" - безналичный |
| Необязательные параметры | ||
| comment | Строка | Комментарий |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент ИД=CLIENT_ID |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| oper_id | Целое | ИД операции |
Пример:
Запрос:
POST https://ip:port/common_api/1.0/create_client_operation HTTP/1.1
Signature: <...>
Content-Type: application/x-www-form-urlencoded
Content-Length: 127
client_id=112&oper_time=20130221100719&oper_sum=300&oper_type=receipt&pay_type=cash&comment=COMMENT
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"oper_id":31
}
}
Запрос операций по клиенту
Метод: GET
Название запроса: get_client_operations
Параметры:
| Параметры | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| client_id | Целое | ИД клиента (может отсутствовать, если phone заполнен) |
| phone | Целое | Телефон клиента (может отсутствовать, если client_id заполнен) |
| start_time | ГГГГММДДччммсс | Начало периода |
| finish_time | ГГГГММДДччммсс | Конец периода |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Не найден клиент ИД=CLIENT_ID |
Возвращаемые данные в случае успешного выполнения запроса:
| Параметр | Тип | Описание |
|---|---|---|
| oper_id | Целое | ИД операции |
| oper_time | ГГГГММДДччммсс | Время создания операции |
| sum | Дробное | Сумма |
| order_id | Целое | Заказ, связанный с операцией |
| oper_type | Целое | Тип операции:
• "receipt" - приход • "expense" - расход |
| pay_type | Целое | Тип оплаты:
• "cash" - наличный • "nocash" - безналичный |
Пример:
Запрос:
GET
https://ip:port/common_api/1.0/get_client_operations?client_id=112&start_time=20130201092112&finish_time=20130221092112 HTTP/1.1
Signature: <...>
Ответ:
{
"code":0,
"descr":"OK",
"data":{
"operations":[
{
"oper_id":112,
"oper_time":"20130219091328",
"sum":"21,8",
"order_id":11800,
"oper_type":"receipt",
"pay_type":"cash",
"comment":"jgznm"
},
{
"oper_id":112,
"oper_time":"20130220112245",
"sum":"4500",
"order_id":11801,
"oper_type":"receipt",
"pay_type":"cash",
"comment":"блин"
}
]
}
}
Описание протокола TMTAPI Версия 1.0
Общее описание протокола
Формат запроса
TM API принимает входящие запросы по протоколу HTTPS. В URI запроса после ip адреса и порта, который будет слушать TM API, должно идти название API (tm_tapi) и версия API.
Пример:
GET https://ip:port/tm_tapi/1.0/get_info_by_phone HTTP/1.1
Для получения данных из БД используются запросы типа GET. Для записи данных в БД используются запросы типа POST. В запросе типа GET параметры запроса передаются в URI.
Пример:
GET https://ip:port/tm_tapi/1.0/get_info_by_phone?phone=89058800565&fields=PHONE_TYPEPHONE_ TO_DIAL&signature=661ce071eeefcb4f7fc8bc1f17bd520b HTTP/1.1
В запросе типа POST параметры передаются в теле запроса в формате application/x-wwwform- urlencoded.
Пример:
POST https://ip:port/tm_tapi/1.0/change_order_state HTTP/1.1 Content-Type: application/x-www-form-urlencoded Content-Length: 71 order_id=98798&need_state=12&signature=a204c50c7e48f0c6849a87485fe5e171
В любом запросе обязательно, с другими полями, должно передаваться поле signature. В нем передается MD5 хэш, рассчитанный для строки, которая получается сцеплением строки параметров запроса с секретным ключом. Секретный ключ задается в настройках модуля TMAPI в Такси-Мастер.
Пример:
Запрос:
GET https://ip:port/tm_tapi/1.0/get_info_by_phone?phone=89058800565&fields=PHONE_TYPE
&signature=ef17ea682d09e452af544a5758dba396 HTTP/1.1
Секретный ключ:
321
Signature = MD5("phone=89058800565&fields=PHONE_TYPE" + "321") = ef17ea682d09e452af544a5758dba396
HTTP/1.1
Формат ответа
TM API всегда возвращает HTTP код 200 ОК. Результат выполнения запроса содержится в теле ответа в формате XML. Общий вид возвращаемого результата:
<response> <code>Числовой код результата</code> <descr>Строковое описание результата</descr> <data>Дополнительная информация</data> </response>
Существуют общие для всех запросов коды результатов:
| Код | Описание |
|---|---|
| 0 | Успешное выполнение запроса |
| 1 | Неизвестная ошибка |
| 2 | Неизвестный тип API |
| 3 | API отключено в настройках модуля TM API в Такси-Мастер |
| 4 | Не совпадает секретный ключ |
| 5 | Неподдерживаемая версия API |
| 6 | Неизвестное название запроса |
| 7 | Неверный тип запроса GET |
| 8 | Не хватает входного параметра (в доп. информации ответа будет название
отсутствующего параметра) |
| 9 | Некорректный входной параметр (в доп. информации ответа будет название некорректного параметра) |
| 10 | Внутренняя ошибка обработки запроса |
Описание запросов
Запрос информации по номеру телефона
Метод: GET
Название запроса: get_info_by_phone
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| phone | Строка, <= 16 символов | Номер телефона |
| fields | Строка | Список полей, которые необходимо вернуть. Поля перечисляются через - |
| signature | Строка | Поле для проверки секретного ключа. |
Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса: зависит от того какие поля были переданы в поле fields.
| Параметр | Тип | Описание |
|---|---|---|
| PHONE_TYPE | Целое | Тип телефона звонящего
(1 - если звонит водитель; 2 - если звонит физлицо; 3 - если звонит юрлицо; 4 - если звонит номер из справочника телефоны; 0 - неизвестный номер) |
| PHONE_TO_DIAL | Строка, <= 16 символов | Номер телефона для отзвона по заказу |
| CREW_ID | Целое | ИД экипажа |
| IS_PRIOR | true или false | Признак предварительного заказа |
| ORDER_CLIENT_ID | Целое | ИД клиента из заказа |
| DRIVER_PHONE | Строка, <= 16 символов | Номер телефона водителя |
| CREW_SYSTEMSTATE | Целое | Состояние экипажа |
| CLIENT_ID | Целое | ИД клиента. |
| CLIENT_TYPE | Целое | Тип клиента |
| CATEGORYID | Целое | ИД категории телефона |
| PHONE_SYSTEM_CATEGORY | Целое | Системное значение категории телефона (0 - обычный, 1 - черный, 2 - белый, 3 - серый) |
| ORDER_ID | Целое | ИД заказа |
| DRIVER_ID | Целое | ИД водителя |
| ORDER_STATE | Целое | Состояние заказа |
| DRIVER_REMAINDER | Дробное | Баланс счета водителя |
| DISCOUNTEDSUMM | Строка | Сумма заказа с учетом всех скидок |
| CREW_GROUP_ID | Целое | ИД группы экипажа |
| CLIENT_BALANCE | Дробное | Баланс клиента |
| DRIVER_TIMECOUNT | Целое | Время пути водителя до адреса подачи в минутах |
| SOURCE_TIMECOUNT | Целое | Время оставшееся до подачи в минутах |
| SOUND_COLOR | Строка | Запись с информацией о цвете |
| SOUND_GOSNUMBER | Строка | Запись с информацией о государственном номере автомобиля |
| SOUND_MARK | Строка | Запись с информацией о марке автомобиля |
| GOSNUMBER | Строка | Государственный номер автомобиля |
| CAR_COLOR | Строка | Цвет автомобиля |
| CAR_MARK | Строка | Марка автомобиля |
| ORDER_COORDS | Строка | Координаты места подачи |
| CREW_COORDS | Строка | Координаты назначенного экипажа |
Пример:
Запрос:
GET https://ip:port/tm_tapi/1.0/get_info_by_phone?phone=89058800565l&fields=PHONE_TYPEPHONE_
TO_DIAL-CREW_ID-ORDER_ID&signature=d35ab2765f2968d48c096d5f5327db26 HTTP/1.1
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<PHONE_TYPE>0</PHONE_TYPE>
<PHONE_TO_DIAL></PHONE_TO_DIAL>
<CREW_ID>3</CREW_ID>
<ORDER_ID>6</ORDER_ID>
</data>
</response>
Запрос информации по ИД заказа
Метод: GET Название запроса: get_info_by_order_id Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| order_id | Целое | ИД заказа |
| fields | Строка | Список полей, которые необходимо вернуть. Поля перечисляются через - |
| signature | Строка | Поле для проверки секретного ключа. |
Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса: зависит от того какие поля были переданы в поле fields.
| Параметр | Тип | Описание |
|---|---|---|
| DRIVER_TIMECOUNT | Строка, <= 16 символов | Время до подачи в минутах, указанное водителем |
| SOUND_COLOR | Строка | Запись с информацией о цвете |
| CAR_MARK | Строка | Марка автомобиля |
| CAR_COLOR | Строка | Цвет автомобиля |
| GOSNUMBER | Строка | Государственный номер автомобиля |
| SOUND_MARK | Строка | Запись с информацией о марке автомобиля |
| CREW_GROUP_ID | Целое | ИД группы экипажа |
| IS_PRIOR | true или false | Признак предварительного заказа |
| DISCOUNTEDSUMM | Строка | Сумма заказа с учетом всех скидок |
| DRIVER_PHONE | Строка, <= 16 символов | Номер телефона водителя |
| CATEGORYID | Целое | ИД категории телефона |
| SOURCE_TIMECOUNT | Целое | Время до подачи в минутах |
| ORDER_COORDS | Строка | Координаты места подачи |
| CREW_COORDS | Строка | Координаты назначенного экипажа |
| ORDER_STATE | Целое | ИД состояния заказа |
Пример:
Запрос:
GET https://ip:port/tm_tapi/1.0/get_info_by_order_id?order_id=60&fields=DRIVER_SOURCETIME-MARKCOLOR-GOSNUMBER-IS_PRIOR-MOBILE_PHONE-SOURCE_TIME&signature=fdcd04e570443b56176b83f44748dc23
HTTP/1.1
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<DRIVER_SOURCETIME></DRIVER_SOURCETIME>
<MARK></MARK>
<COLOR></COLOR>
<GOSNUMBER></GOSNUMBER>
<IS_PRIOR></IS_PRIOR>
<MOBILE_PHONE></MOBILE_PHONE>
<SOURCE_TIME></SOURCE_TIME>
</data>
</response>
Смена состояния заказа
Метод: POST
Название запроса: change_order_state
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| order_id | Целое | ИД заказа |
| need_state | Целое | Новое состояние заказа |
| signature | Строка | Поле для проверки секретного ключа. |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Заказ с таким ИД не найден. |
| 101 | Изменение состояния не соответствует необходимым условиям. |
Возвращаемые данные в случае успешного выполнения запроса
| Параметр | Тип | Описание |
|---|---|---|
| ORDER_ID | Целое | ИД созданного заказа |
| NEW_STATE | Целое | Новое состояние заказа |
Пример:
Запрос:
POST https://ip:port/tm_tapi/1.0/change_order_state HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 71
order_id=18561&need_state=14&signature=3e8107e0c044e55d983db1fbed82fd8c
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<ORDER_ID>18561</ORDER_ID>
<NEW_STATE>14</NEW_STATE>
</data>
</response>
Запись пути к файлу разговора в базу данных
Метод: POST
Название запроса: create_record_link
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| RECORD_DATE | ГГГГММДДччммсс | Дата записи |
| RECORD_LENGTH | Целое | Продолжительность записи (в секундах) |
| PHONE | Строка, <= 16 символов | Номер телефона |
| FILE_PATH | Строка,<=255 символов | Путь к файлу записи |
| signature | Строка | Поле для проверки секретного ключа. |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Заказ по такому номеру телефона не найден. |
Возвращаемые данные в случае успешного выполнения запроса
| Параметр | Тип | Описание |
|---|---|---|
| RECORD_ID | Целое | ИД созданной записи |
Пример:
Запрос:
POST https://ip:port/tm_tapi/1.0/create_record_link HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 171
RECORD_DATE=20130122180949&RECORD_LENGTH=215&PHONE=8987564&FILE_PATH=d%3A%5Ctemp%5CTM%5Ctrunk
%5CSource%5CDevUtils%5CTMAPITest%5C&signature=56851c4e8d2d4bb9ba615615f76ad7f7
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<RECORD_ID>25</RECORD_ID>
</data>
</response>
Создать новый заказ
Метод: POST
Название запроса: make_new_order
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| PHONE | Строка, <= 16 символов | Номер телефона |
| ORDER_STATE_ID | Целое | ИД состояния заказа |
| signature | Строка | Поле для проверки секретного ключа. |
| Необязательные параметры | ||
| CREWGROUPID | Целое | ИД группы экипажа |
| TARIF_ID | Целое | ИД тарифа |
| DISCOUNTEDSUMM | Дробное | Фиксированная сумма за заказ |
| NAME | Строка, <=80 символов | Наименование (заказчик + адрес назначения) |
| CUSTOMER | Строка, <=80 символов | Заказчик |
| SOURCE | Строка, <=80 символов | Адрес подачи |
| SOURCE_STREET | Целое | ИД улицы подачи |
| SOURCE_HOUSE | Строка, <=10 символов | Дом подачи |
| SOURCE_FLAT | Строка, <=10 символов | Квартира подачи |
| SOURCE_POINT | Целое | ИД пункта подачи |
| DESTINATION | Строка, <=80 символов | Адрес назначения |
| DESTINATION_STREET | Целое | ИД улицы назначения |
| DESTINATION_HOUSE | Строка, <=10 символов | Дом назначения |
| DESTINATION_FLAT | Строка, <=10 символов | Квартира назначения |
| DESTINATION_POINT | Целое | ИД пункта назначения |
| CREWID | Целое | ИД экипажа |
| SUMM | Дробное | Стоимость заказа без учета скидок(наценок) |
| STARTUSER | Целое | Пользователь, создавший заказ |
| STARTTIME | ГГГГММДДччммсс | Дата создания заказа |
| FINISHUSER | Целое | Пользователь, завершивший заказ |
| FINISHTIME | ГГГГММДДччммсс | Дата завершения заказа |
| SOURCE_ZONE | Целое | Район подачи |
| DESTINATION_ZONE | Целое | Район назначения |
| SOURCE_PARKING | Целое | Стоянка подачи |
| DESTINATION_PARKING | Целое | Стоянка назначения |
| SOURCE_TIME | ГГГГММДДччммсс | Дата подачи |
| SOURCE_COUNTRY | 0 или 1 (false или true) | Признак междугороднего заказа |
| IS_PRIOR | 0 или 1 (false или true) | Признак предварительного заказа |
| PRIZE | 0 или 1 (false или true) | Признак призового заказа |
| NOTE | Строка, <=80 символов | Примечание |
| BONUSPOINT | Дробное | Бонусные баллы, начисленные водителю за заказ |
| STARTSMEN | Целое | Смена пользователей, в которой был создан заказ |
| FINISHSMEN | Целое | Смена пользователей, в которой заказ был завершен |
| DISTANCE | Дробное | Километраж по городу (в километрах) |
| HOURLY_LEN | Целое | Длительность исполнения почасового заказа (в минутах) |
| HOURLY_START | ГГГГММДДччммсс | Дата начала отсчета при почасовом заказе |
| HOURLY_PAY | 0 или 1 (false или true) | Признак почасового заказа |
| PHONE_TO_DIAL | Строка, <=16 символов | Номер телефона для отзвона по заказу |
| STOPS | Строка, <=80 символов | Остановки |
| STOPS_COUNT | Целое | Количество остановок |
| SERVICEID | Целое | ИД услуги |
| STATE_TIME | ГГГГММДДччммсс | Дата смены состояния |
| IS_LOCKED | 0 или 1 (false или true) | Признак блокировки заказа от редактирования |
| TIME_LOCKED | ГГГГММДДччммсс | Дата блокировки заказа |
| LOCKED_BY | Целое | Пользователь, заблокировавший заказ |
| FROMBORDER | 0 или 1 (false или true) | Признак заказа "с бордюра" |
| DRIVERID | Целое | ИД водителя |
| CLIENT_NOTIFIED | 0 или 1 (false или true) | Признак успешного отзвона клиенту колцентром |
| PREFERENTIAL | 0 или 1 (false или true) | Признак льготного заказа |
| LAST_CREW | Целое | ИД предыдущего экипажа |
| FSUMM | Дробное | Часть стоимости заказа, которая оплачена наличными |
| OLDCREW | Целое | Предыдущий экипаж |
| TIMEOUT | ГГГГММДДччммсс | Период времени, прошедший с момента последней смены состояния |
| WAITING_START | ГГГГММДДччммсс | Дата начала ожидания заказчика водителем |
| WAITING_LENGTH | Целое | Общая длина периода ожидания заказчика водителем (в минутах) |
| BACKFREE | Целое | Признак применения скидки в 50% на обратный путь |
| INPUTTIME | ГГГГММДДччммсс | Дата принятия заказа [от даты создания заказа отличается тем, что может быть задана пользователем] |
| MONEY_RECEIVE | 0 или 1 (false или true) | Подтверждение принятия денег наличными |
| NOTIFY_BEFORE | Целое | Период времени, за который пользователь оповещается о наступлении даты подачи |
| WANTCREWID | Целое | ИД желаемого экипажа |
| DRIVER_SOURCETIME | ГГГГММДДччммсс | Дата подачи, указанная водителем с мобильного устройства |
| DRIVE_TIME | Целое | Приблизительное время доезда до адреса подачи, указываемое водителем через мобильное устройство |
| DISTANCE_COUNTRY | Дробное | Километраж за границами города (в километрах) |
| STOPS_LEN | Целое | Общая продолжительность остановок в минутах |
| DISTANCE_CHECK | 0 или 1 (false или true) | Разрешение ручного ввода километража |
| CLIENTID | Целое | ИД постоянного клиента |
| INFRA_STATE | Целое | Состояние заявки в исходящей кампании колцентра INFRA (1 - заявка передана в исходящую кампанию, 2 - отзвон успешно произведен, 3 - занято, 4 - не берут трубку) |
| INFRA_ORDER | Целое | INFRA-заказ [спец. поле для работы с колцентром компании Инфрател] |
Специальные возвращаемые коды:
| Код | Описание |
|---|---|
| 100 | Клиент не найден |
Возвращаемые данные в случае успешного выполнения запроса
| Параметр | Тип | Описание |
|---|---|---|
| ORDER_ID | Целое | ИД созданного заказа |
Пример:
Запрос:
POST https://ip:port/tm_tapi/1.0/make_new_order HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 206
PHONE=89058770593&ORDER_STATE_ID=10&DISCOUNTED_SUMM=100&signature=afc947f610eba380df6d0e441b03ddad
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<order_id>27</order_id>
</data>
</response>
Поиск улицы в базе и создание нового заказа.
Метод: POST
Название запроса: new_order_by_voice
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
| Обязательные параметры | ||
| PHONE | Строка, <= 16 символов | Номер телефона |
| CALL_ID | Целое | ИД звонка |
| VOICE_STREET | Строка, <= 60 символов | Название улицы или пункта полученное через преобразование голоса в текст |
| FIND_STREET | 0 или 1 (false или true) | Признак того, что улица найдена. |
| API_FIND_STREET | Строка, <= 60 символов | Наименование улицы или пункта найденное в базе данных. |
| NUM_HOUSE | Строка,<=10 символов | Номер дома |
| signature | Строка | Поле для проверки секретного ключа. |
Специальные возвращаемые коды: нет
Возвращаемые данные в случае успешного выполнения запроса
1) Если FIND_SREET = 0, тогда
| Параметр | Тип | Описание |
|---|---|---|
| CALL_ID | Целое | ИД звонка |
| PHONE | Строка, <= 16 символов | Номер телефона |
| FIND_STREET | 0 или 1 (false или true) | Признак того, что улица найдена |
| API_FIND_STREET | Строка, <= 60 символов | Наименование улицы или пункта найденное в базе данных |
2) Если FIND_SREET = 1, тогда
| Параметр | Тип | Описание |
|---|---|---|
| ORDER_ID | Целое | ИД созданного заказа |
Пример:
1) FIND_STREET = 0
Запрос:
POST https://ip:port/tm_tapi/1.0/new_order_by_voice HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 175
PHONE=89058770593&CALL_ID=56&VOICE_STREET=пушкинск&FIND_STREET=0&API_FIND_STREET=&NUM_HOUSE=&signat
ure=9204a53e0f4842bb623c3a5f7683520a
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<CALL_ID>56</CALL_ID>
<PHONE>89058770593</PHONE>
<FIND_STREET>1</FIND_STREET>
<API_FIND_STREET>Пушкинская</API_FIND_STREET>
</data>
</response>
1) FIND_STREET = 1
Запрос:
POST https://ip:port/tm_tapi/1.0/new_order_by_voice HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 244
PHONE=89058770593&CALL_ID=56&VOICE_STREET=пушкинск&FIND_STREET=1&API_FIND_STREET=Пушкинская&NUM_HOUSE=155&signature=6dd9edcb8284bf36f9856dd2018f42e5
Ответ:
<response>
<code>0</code>
<descr>OK</descr>
<data>
<order_id>114</order_id>
</data>
</response>
Пример формы для заказа такси
Данная форма является примером, на основе которого можно построить собственную форму для принятия интернет-заказов. Форму можно использовать либо в исходном варианте, либо применяя запросы TM API. Для того, чтобы данная форма функционировала, необходимо открыть файл в любом текстовом редакторе и указать корректные IP-адрес сервера Такси-Мастер, порт TM API и секретный ключ. Далее вам следует загрузить файл на хостинг.
Именно так будет выглядеть данная форма для заказа такси.
