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

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

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

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

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

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

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

TMWeb принимает входящие запросы по протоколу HTTPS. В URI запроса после ip адреса и порта, который будет слушать TMWeb, должно идти название API (common_api) и версия API. Пример:

GET https://ip:port/common_api/1.0/get_crew_groups_list HTTP/1.1

Для получения данных из БД используются запросы типа GET. Для записи данных в базу данных используются запросы типа POST. В запросе типа GET параметры запроса передаются в URI. Пример:

GET https://ip:port/common_api/1.0/calc_order_cost?tariff_id=1&distance_city=10 HTTP/1.1
Signature: <...>

В запросе типа POST параметры передаются в теле запроса в формате application/x-wwwform-urlencoded. Пример:

POST https://ip:port/common_api/1.0/create_order HTTP/1.1
Signature: <...>
Content-Type: application/x-www-form-urlencoded
Content-Length: 118

phone=89123456789&source=SOURCE&source_time=20120501100000&dest=DEST&customer=CUSTOMER&
comment=COMMENT&crew_group_id=1

В любом запросе обязательно должен быть заголовок Signature. В нем передается MD5 хэш, рассчитанный для строки, которая получается сцеплением строки параметров запроса с секретным ключом. Секретный ключ задается в настройках модуля TMWeb в ТМ2. Пример:

Запрос:
GET https://ip:port/common_api/1.0/calc_order_cost?tariff_id=1&distance_city=10 HTTP/1.1

Секретный ключ:
1234567890

Signature = MD5("tariff_id=1&distance_city=10" + "1234567890") = d7b8fb11b5499b64d750b8efe53e2877

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

TMWeb всегда возвращает HTTP код 200 ОК. Результат выполнения запроса содержится в теле ответа в формате JSON. Общий вид возвращаемого результата:

{
"code":<Числовой код результата>,
"descr":"<Строковое описание результата>",
"data":{<Дополнительная информация>}
}

Существуют общие для всех запросов коды результатов:

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

Запрос-пинг

Для данного запроса не проверяется версия 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 Параметры: нет Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса:

Пример:

Запрос:

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 Параметры: нет Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса:

Пример:

Запрос:

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 Параметры: нет Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса:

Пример:

Запрос:

GET https://ip:port/common_api/1.0/get_tariffs_list HTTP/1.1
Signature: <...>

Ответ:

{
  "code":0,
  "descr":"OK",
  "data":{
    "tariffs":[
      {
        "id":1,
        "name":"TARIFF1"
      },
      {
         "id":2,
         "name":"TARIFF2"
      }
    ]
  }
}

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

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

Пример:

Запрос:

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 Параметры: нет Специальные возвращаемые коды: нет Возвращаемые данные в случае успешного выполнения запроса:

Пример:

Запрос:

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 Параметры: