TM API

Материал из TaxiMaster
Версия от 16:52, 1 октября 2013; AnnaNikolskih (обсуждение | вклад) (→‎Расчет суммы заказа)

Перейти к: навигация, поиск

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

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

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

Содержание

Параметры TM API

Задать настройки для корректной работы TM API вы сможете в программе Такси-Мастер в меню «Настройки» в одноименной ветке «TM API». Параметры организуют и контролируют работу модуля «Интернет-заказы».

  1. Установите флажок «Template-checkbox-off.png Использовать TM API», чтобы приступить к его использованию.
  2. В поле «Локальный порт» введите номер порта подключения к интернету, на котором работает и будет ожидать запросы о новых заказах TMServer. Рекомендуется оставить номер порта по умолчанию.
  3. Установите флажок «Template-checkbox-off.png Можно использовать данное рабочее место TMServer для распознавания адресов» для того, чтобы конкретно с данного рабочего места происходило распознавание адресов модулем "Интернет-заказы".
  4. Перезапустите Такси-Мастер и TMServer для запуска работы модуля.

Ветка «Открытое API»

В данной ветке регулируется доступ к синхронизации Такси-Мастер со сторонним сервисом (сайтом), с помощью которого клиенты будут создавать интернет-заказы. С примером кода для работы вы можете ознакомиться в данной статье в разделе Общее описание протокола.

  1. Установите флажок «Template-checkbox-off.png Использовать открытое API» для того, чтобы запустить работу по обслуживанию модуля «Интернет-заказы». При установленном флажке сервер модуля «Интернет-заказы» запускается и ожидает запросы о новых заказах.
  2. В поле «Секретный ключ» укажите номер секретного ключа для работы с модулем «Интернет-заказы», который будет выслан вам в письме от менеджера.
  3. Перезапустите Такси-Мастер и TMServer для запуска работы модуля.

Ветка «API для телефонии»

В данной ветке регулируются настройки API для телефонии, т.е. взаимодействие Такси-Мастер с call-центром через программный интерфейс. С его помощью call-центр может дать команду Такси-Мастер создать заказ или запросить информацию о статусе текущего заказа.

  1. Установите флажок «Template-checkbox-off.png Использовать открытое API для телефонии» для того, чтобы запустить работу по обслуживанию телефонии через API.
  2. В поле «Секретный ключ» укажите номер секретного ключа для работы.
  3. Перезапустите Такси-Мастер и TMServer для запуска работы модуля.

Ветка «Платежные терминалы»

Интересная информация
Ранее для связи платежных систем и Такси-Мастер служила такая утилита, как TMWeb. В данный момент мы отказались от ее использования, а функции были распределены между двумя компонентами системы: TM API и TMServer.

Параметры этой ветки отвечают за работу модуля интеграции с платежными системами.

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

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
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 true или false Год выпуска автомобиля
car_photo Base64 Фото автомобиля (только если need_photo = true)

Пример: 

Запрос:

GET https://ip:port/common_api/1.0/get_car_info?car_id=1&need_photo=false HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "car_id":1,
    "code":"123",
    "name":"CAR_NAME",
    "gos_number":"a123bc",
    "color":"COLOR",
    "mark":"MARK",
    "model":"MODEL",
    "short_name":"SHORT_NAME",
    "production_year":2000
  }
}

Запрос координат экипажей

Метод: GET

Название запроса: get_crews_coords

Параметры:

Параметры Тип Описание
Необязательные параметры
crew_id Целое ИД экипажа, по которому нужно вернуть координаты. Если не задано, то будут возвращены координаты всех экипажей на линии.

Специальные возвращаемые коды:

Код Описание
100 Координаты не найдены

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
crews_coords Массив Список координат экипажей
• crew_id Целое ИД экипажа
• crew_code Строка Позывной экипажа
• coords_time ГГГГММДДччммсс Время получения координат
• lat Дробное Долгота
• lon Дробное Широта
• state_kind Строка Тип состояния экипажа. Может принимать значения:

• "not_available" — экипаж не на линии

• "waiting" — экипаж свободен, ожидает заказы

• "on_order" — экипаж на заказе

• "on_break" — экипаж на перерыве

Пример: 


Запрос:
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_points = 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 Целое ИД экипажа
driver_id Целое ИД водителя
car_id Целое ИД автомобиля

Пример: 

Запрос:

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,
    "driver_id":2,
    "car_id":3
  }
}

Создание задачи СМС серверу

Метод: 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 Клиент с ИД=ID имеет такой же номер телефона=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

Параметры:

Параметры Тип Описание
Обязательные параметры
get_client_info Целое ИД клиента

Специальные возвращаемые коды:

Код Описание
100 Не найден клиент ИД=CLIENT_ID

Возвращаемые данные в случае успешного выполнения запроса:

Параметр Тип Описание
client_id Целое ИД клиента
number Строка Номер договора
address Строка Домашний адрес
gender Строка Пол. Может принимать значения:

• "male" - мужской

• "female" - женский

birthday ДД.ММ.ГГГГ Дата рождения
phones Строка Номера телефонов (через запятую)
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\"]",
    "login":"artem",
    "password":"vasilev"
  }
}

Изменение информации по клиенту

Метод: POST

Название запроса: register_client

Параметры:

Параметры Тип Описание
Обязательные параметры
client_id Целое ИД клиента
Необязательные параметры
name Строка, <= 60 символов ФИО
login Строка, <= 60 символов Логин
password Строка, <= 60 символов Пароль
phones Строка Номера телефонов (через запятую)
address Строка Домашний адрес
birthday ДД.ММ.ГГГГ Дата рождения
gender Строка Пол. Может принимать значения:

• "male" - мужской

• "female" - женский

Специальные возвращаемые коды:

Код Описание
100 Клиент с номером телефона=PHONE уже существует
101 Клиент с ИД=ID имеет такой же номер телефона=PHONE
102 Клиент с логином=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 ГГГГММДДччммсс Время подачи
birthday ДД.ММ.ГГГГ Дата рождения
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 ГГГГММДДччммсс Время завершения заказа
birthday ДД.ММ.ГГГГ Дата рождения
source Строка Адрес подачи
destination Строка Адрес назначения
sum Дробное Стоимость заказа без учета скидок(наценок)
passenger Строка Пассажир
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 Строка, <= 16 символов Телефон клиента (может отсутствовать, если 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 Строка Марка автомобиля

Пример: 

Запрос:
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_SOURCETIME Строка, <= 16 символов Время до подачи в минутах, указанное водителем
SOUND_COLOR Строка Запись с информацией о цвете
MARK Строка Марка автомобиля
COLOR Строка Цвет автомобиля
GOSNUMBER Строка Государственный номер автомобиля
SOUND_MARK Строка Запись с информацией о марке автомобиля
CREWGROUPID Целое ИД группы экипажа
IS_PRIOR true или false Признак предварительного заказа
DISCOUNTEDSUMM Строка Сумма заказа с учетом всех скидок
MOBILE_PHONE Строка, <= 16 символов Номер телефона водителя
CATEGORYID Целое ИД категории телефона
SOURCE_TIME Целое Время до подачи в минутах

Пример: 

Запрос:

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 символов Номер телефона
ORDERID Целое Заказ, с которого сделана запись
USERID Целое Пользователь, сделавший запись
FILE_PATH Строка,<=255 символов Путь к файлу записи
RECORD_GUID Строка,<= 80 символов GUID звонка
signature Строка Поле для проверки секретного ключа.

Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса

Параметр Тип Описание
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: 206
RECORD_DATE=20121108145953&RECORD_LENGTH=6546&PHONE=654321&ORDERID=654&USERID=564&FILE_PATH=d%3A
%5CProjects%5Ctrunk%5C%5Ftrunk%5CTM%5CBin
%5C&RECORD_GUID=GUID456258&signature=cd11d50d65fa7e8ad73f80cdc7d296c7

Ответ:

<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 Строка Поле для проверки секретного ключа.
Необязательные параметры
CREW_GROUP_ID Целое ИД группы экипажа
TARIFF_ID Целое ИД тарифа
PHONE_PREFIX Строка Префикс, отрезаемый от номера телефона при поиске в базе данных. Для входящих звонков это код города с префиксом входящих номеров, обычно "8". Например, "83412"
DISCOUNTED_SU MM Строка Фиксированная сумма за заказ

Специальные возвращаемые коды:

Код Описание
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>

Пример формы для заказа такси

Download.png
Для скачивания Вы можете воспользоваться ссылкой:
http://files.bitmaster.ru/TM/forms/zakaz_taxi.zip

Данная форма является примером, на основе которого можно построить собственную форму для принятия интернет-заказов. Форму можно использовать либо в исходном варианте, либо применяя запросы TM API. Для того, чтобы данная форма функционировала, необходимо открыть файл в любом текстовом редакторе и указать корректные IP-адрес сервера Такси-Мастер, порт TM API и секретный ключ. Далее вам следует загрузить файл на хостинг.

Именно так будет выглядеть данная форма для заказа такси.

Картинка
Форма для заказа такси.jpg
Источник — «http://help.taximaster.ru/index.php?title=TM_API&oldid=9515»