TM API
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 для запуска работы модуля.
Ветка «Платежные терминалы»
Параметры этой ветки отвечают за работу модуля интеграции с платежными системами.
- Установите флажок
Включить прием терминальных платежей . Данная функция позволит отображать все платежные операции по приходу средств от водителей через терминалы в базе данных программы.
- В поле Секретный ключ укажите номер секретного ключа для работы с платежными системами и сверки платежей, который будет выслан вам в письме от менеджера. Секретный ключ - это определенный набор символов, необходимый для формирования подписи при передаче информации о платеже.
- В полях Логин и Пароль введите данные учетной записи на сайте http://term.bitmaster.ru.
- Кнопка Задать всем водителям терминальный аккаунт по их ИД служит для соединения TM API с сервером Такси-Мастер. В результате соединения записи о терминальных аккаунтах генерируются, заносятся (для тех водителей, у которых они отсутствуют) и обновляются (для тех водителей, у которых уже существуют терминальные аккаунты) в Такси-Мастер.
- Перезапустите Такси-Мастер и TMServer для запуска работы модуля.
Общее описание протокола
Формат запроса
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_points | 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>
2) 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 и секретный ключ. Далее вам следует загрузить файл на хостинг.
Именно так будет выглядеть данная форма для заказа такси.