API сервера такси
Материал из Таксомёт
Сервер такси имеет HTTP/HTTPS API с с помощью которого Вы можете произвести интеграцию сервера такси с Вашим сервисом или программой. С помощью HTTP API можно, например, создать заказ на сервер такси программно, который далее будет распределяться водителям и пройдет обычный цикл жизни заказа, так же через HTTP API можно управлять заказами, делать финансовые записи, работать с бонусами клиентов и выполнять практически все функции программно, которые есть в программе Такомёт.
Общее описание
HTTP API работает с GET запросами.
Для работы с API Вам предварительно необходимо создать учетную запись оператора и использовать логин и пароль этого оператора в запросах API.
URL адрес для API запросов располагается на том же домене, что и рабочее место оператора.
Создать заказ
Данный метод позволяет создать заказ со всеми необходимыми параметрами в системе.
URL для запроса:
https://***.taxomet.ru/api/v1/add_order?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&unit_id=<ID_службы>&tarif_id=<ID_тарифа>&phone=<телефон_пассажира>&to[]=<адрес_1>&to[]=<адрес_2>&car_option[]=<ID_дополнительной_опции_авто>&fix_price=<фикс_цена>&extern_id=<ID_заказа_в_Вашей_сситеме>&order_time=<время_заказа>&client_name=<имя_клиента>&comment=<комментарий_к_заказу>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- unit_id - ID службы такси на сервере такси. ID службы можно узнать в разделе программы "Службы такси и тарифы" (Настройки -> Службы такси и тарифы).
- tarif_id - ID тарифа, котый необходимо применить к заказу. ID тарифа можно узнать в разделе программы "Службы такси и тарифы" (Настройки -> Службы такси и тарифы). Если указать для tarif_id значение -1, то тариф будет выбран сервером такси автоматически из тарифов службы такси с учетом времени суток.
- phone - телефон клиента. Должен начинаться со знака +. Например, +70001112233
- to[] - адрес поездки. Параметр to[] необходимо добавить столько раз сколько адресов у поездки. Первый параметр to[] является адресом "Откуда", последующие - точками назначения.
- car_option[] - ID требующейся доп. опции к заказу (например "Детское кресло"). ID доп. опций можно посмотреть в интерфейся программы в разделе "Опции автомобилей" (Настройки -> Опции автомобилей). Необязательный параметр.
- fix_price - стоимость поездки. Необязательный параметр. Если не задавать или указать 0, то поездка будет по GPS-таксомётру.
- extern_id - ID заказа в Вашей системе. В дальнейшем может пердаваться в запросах от сервера такси к Вашей системе (Webhooks), например уведомление Вашей системы о смене статуса заказа.
- order_time - время заказа (UNIX TIMESTAMP), если заказ предварительный. Параметр не обязательный.
- print_receipt - сформировать кассовый чек после завершения поездки. Значение параметра может быть 0 или 1. Параметр не обязательный. По умолчанию - 0.
- client_name - имя клиента. Параметр не обязательный.
- comment - комментарий к заказу. Параметр не обязательный.
Ответ
Ответ в формате JSON:
{"result":"1", "error":"", "order_id":"2342"}
Параметры result, error, order_id всегда присутствуют в ответе. В случае успешного выполнения запроса и заказ создан параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Параметр order_id содержит ID созданного заказа на сервере такси, в случае если заказ не создан и произошла ошибка order_id будет равен 0.
Пример запроса
https://test.taxomet.ru/api/v1/add_order?operator_login=my-api&operator_password=******&unit_id=1&tarif_id=1&phone=+70001112233&to[]=Сочи, Тимирязева ул., 4&to[]=Сочи, Парковая ул., 42&car_option[]=1&fix_price=200&id=1234
Отменить заказ
Данный метод позволяет отменить заказ.
URL для запроса:
https://***.taxomet.ru/api/v1/cancel_order?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&id=<ID_заказа>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- id - ID заказа на сервере такси.
Ответ
Ответ в формате JSON:
{"result":"1", "error":"", "order_id":"2342"}
Параметры result, error, order_id всегда присутствуют в ответе. В случае успешного выполнения запроса и заказ отменён параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Параметр order_id содержит ID отменяемого заказа на сервере такси, в случае если заказ не удалось отменить и произошла ошибка order_id будет равен 0.
Пример запроса
https://test.taxomet.ru/api/v1/cancel_order?operator_login=my-api&operator_password=******&id=10
Получить текущую информацию о заказе
Данный метод позволяет получить текущую информацию о заказе по ID заказа.
URL для запроса:
https://***.taxomet.ru/api/v1/get_order?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&id=<ID_заказа>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- id - ID заказа на сервере такси.
Ответ
Ответ в формате JSON:
{"result":"1", "error":"", "order_id":"2342", "status":"4", "call_from":"+70000000000", "driver_id":"120","driver_title":"Иванов Иван Иванович", ...}
Параметры result, error, order_id всегда присутствуют в ответе. В случае успешного выполнения запроса и заказ отменён параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Параметр order_id содержит ID отменяемого заказа на сервере такси, в случае если заказ не удалось отменить и произошла ошибка order_id будет равен 0.
Пример запроса
https://test.taxomet.ru/api/v1/get_order?operator_login=my-api&operator_password=******&id=10
Назначить водителя
Данный метод позволяет назначить водителя принудительно.
URL для запроса:
https://***.taxomet.ru/api/v1/set_driver?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&id=<ID_заказа>&driver_id=<ID_водителя>&boarding_time=<время_подачи>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- id - ID заказа на сервере такси.
- driver_id - ID водителя на сервере такси. ID водителя можно посмотреть в интерфейсе программы в разделе "Водители".
- boarding_time - время в течение которого будет подана машина в минутах, целое число (например 5 минут). Параметр не обязательный. Не нужно указывать для предварительных заказов.
Ответ
Ответ в формате JSON:
{"result":"1", "error":"", "order_id":"2342"}
Параметры result, error, order_id всегда присутствуют в ответе. В случае успешного выполнения запроса и водитель назначен параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Параметр order_id содержит ID заказа на сервере такси, в случае если заказ не удалось отменить и произошла ошибка order_id будет равен 0.
Пример запроса
https://test.taxomet.ru/api/v1/set_driver?operator_login=my-api&operator_password=******&id=10&driver_id=3
Снять водителя с заказа
Данный метод позволяет назначить водителя принудительно.
URL для запроса:
https://***.taxomet.ru/api/v1/remove_driver?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&id=<ID_заказа>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- id - ID заказа на сервере такси.
Ответ
Ответ в формате JSON:
{"result":"1", "error":"", "order_id":"2342"}
Параметры result, error, order_id всегда присутствуют в ответе. В случае успешного выполнения запроса и водитель снят с заказа параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Параметр order_id содержит ID заказа на сервере такси, в случае если водителя не удалось снять и произошла ошибка order_id будет равен 0.
Пример запроса
https://test.taxomet.ru/api/v1/remove_driver?operator_login=my-api&operator_password=******&id=10
Отправить SMS-сообщение
Данный метод позволяет отправить SMS-сообщение через доступные SMS-каналы.
URL для запроса:
https://***.taxomet.ru/api/v1/send_sms?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&from=<имя_от_кого>&phone=<телефон_получателя>&msg=<текст_сообщения>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- from - Имя отправителя "от кого". Только латинские символы и цифры. Не более 11 знаков.
- phone - Телефон получателя. 11 знаков. Например, 79001112233
- msg - Текст SMS-сообщения.
Ответ
Ответ в формате JSON:
{"result":"1", "error":""}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса и SMS-сообщение отправлено параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки.
Пример запроса
https://test.taxomet.ru/api/v1/send_sms?operator_login=my-api&operator_password=******&from=taxomet&msg=test&phone=79670001122
Отправить код в голосовом сообщении
Данный метод позволяет отправить код в голосовом сообщении звонком через доступные Исходящие линии в программе. См. Настройки -> Настройки телефонии.
URL для запроса:
https://***.taxomet.ru/api/v1/send_voice_code?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&phone=<телефон_получателя>&code=<отправляемый_код>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- phone - Телефон получателя. 11 знаков. Например, 79001112233
- code - Цифровой код, который необходимо отправить голосовым сообщением. Только цифры.
Ответ
Ответ в формате JSON:
{"result":"1", "error":""}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса и голосовое сообщение принято к отправке параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки.
Пример запроса
https://test.taxomet.ru/api/v1/send_voice_code?operator_login=my-api&operator_password=******&phone=79670001122&code=12345
Добавить/отнять рейтинг водителя
Данный метод позволяет добавить или отнять рейтинг водителю. Для использования данной функции для учетной записи оператора (от которой делается данный API запрос) должно быть включено право на Администрирование.
URL для запроса:
https://***.taxomet.ru/api/v1/add_driver_rating?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&driver_id=<ID_водителя>&points=<количество_баллов>&lifetime_hours=<время_действия_баллов>&comment=<комментарий>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- driver_id - ID водителя, для которого необходимо добавить или отнять баллы рейтинга.
- points - Количество баллов, целое число (с минусом если нужно отнять баллы).
- lifetime_hours - Время действия баллов, целое число (количество часов).
- comment - Комментарий к создаваемой записи.
Ответ
Ответ в формате JSON:
{"result":"1", "error":""}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса и голосовое сообщение принято к отправке параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки.
Пример запроса
https://test.taxomet.ru/api/v1/add_driver_rating?operator_login=test-api&operator_password=******&driver_id=2&points=100&lifetime_hours=1000&comment=Тестовый%20рейтинг%20через%20API
Добавить/отнять бонусы клиенту
Данный метод позволяет добавить или отнять бонусы с бонусного счета клиента. Для использования данной функции для учетной записи оператора (от которой делается данный API запрос) должно быть включено право на Администрирование.
URL для запроса:
https://***.taxomet.ru/api/v1/add_client_bonuses?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&unit_id=<ID_службы>&phone=<телефон_клиента>&amount=<количество_бонусов>&comment=<комментарий>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- unit_id - ID службы такси, группу счетов которой нужно использовать.
- phone - Телефон клиента.
- amount - Количество бонусов, которое нужно зачислить. Если с минусом, то произойдет списание бонусов
- comment - Комментарий к создаваемой записи.
Ответ
Ответ в формате JSON:
{"result":"1", "bonuses":"50", "error":"","phone":"+79001112233"}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса и голосовое сообщение принято к отправке параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Поле bonuses содержит количество бонусов на бонусном счету клиента после выполнения запроса.
Пример запроса
https://test.taxomet.ru/api/v1/add_driver_rating?operator_login=test-api&operator_password=******&unit_id=1&amount=10&comment=тест%20123&phone=%2B79001112233
Получить информацию учетной записи клиента
Данный метод позволяет получить информацию учетной записи клиента по номеру телефона.
URL для запроса:
https://***.taxomet.ru/api/v1/get_client_info?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&unit_id=<ID_службы>&phone=<телефон_клиента>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- unit_id - ID службы такси, группу счетов которой нужно использовать при выборке информации.
- phone - Телефон клиента.
Ответ
Ответ в формате JSON:
{"phone":"+79001112233","bonuses":"60","max_discount":"0","with_bonuses":"0","tarif_id":"0","max_cashless_summ":0,"passphrase":"","name":"","cashless_account_id":"0","balance_threshold":0,"error":""}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса и голосовое сообщение принято к отправке параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки. Поле bonuses содержит количество бонусов на бонусном счету клиента после выполнения запроса. name - имя клиента. cashless_account_id - ID учетной записи корпоративного клиента.
Пример запроса
https://test.taxomet.ru/api/v1/get_client_info?operator_login=test-api&operator_password=******&unit_id=1&phone=%2B79001112233
Рассчитать маршрут и стоимость поездки по координатам точек поездки
Данный метод позволяет получить стоимость поездки, а так же расчетный маршрут по координатам точек поездки (координаты точек "Откуда" и "Куда", может быть больше точек поездки).
URL для запроса:
https://***.taxomet.ru/api/v1/get_distance?operator_login=<логин_оператора>&operator_password=<пароль_оператора>&unit_id=<ID_службы>&tarif_id=<ID_тарифа>&lon[]=<долгота_точки_1>&lat[]=<широта_точки_1>&lon[]=<долгота_точки_2>&lat[]=<широта_точки_2>
Описание параметров
- operator_login - логин оператора. Предварительно необходимо создать учетную запись оператора в интерфейсе программы.
- operator_password - пароль оператора.
- unit_id - ID службы такси, информацию которой необходимо использовать при расчете маршрута и стоимости поездки.
- tarif_id - ID тарифа службы такси, информацию которого необходимо использовать при расчете маршрута и стоимости поездки. Чтобы тариф подбирался автоматически с учетом времени укажите значение -1.
- lon[] - географическая долгота точки маршрута. Указывается столько раз сколько точек маршрута (для каждой точки маршрута). Минимум два раза.
- lat[] - географическая широта точки маршрута. Указывается столько раз сколько точек маршрута (для каждой точки маршрута). Минимум два раза.
Ответ
Ответ в формате JSON:
{"result":"1","distance":"0.03","distance_suburb":"0","measure":"km","suburban":"0","is_zonal":"1","zonal_price":"100","transfer_str":"КОНЕЦ -> КОНЕЦ = 100 ","pre_price":"100","fix_price":"100","min_price":"100","tarif_combo1":"0","combo1_distance":"0","combo1_distance_suburb":"0","idle_speed":"0","idle_start_after_seconds":"0","tarif_ratio":"1","increase_defer":"30","tarif_landing":"100","increase_distance_threshold":"0","increase_distance_tarif":"0","increase_distance":"0.03","increase_distance_sum":"0","adaptive_landing_increase":"0","execution_time":"144","execution_time1":"","nodes":[{"id":"0","lon":"74.484703","lat":"63.799877","s":"1","zid":"105"},{"id":"0","lon":"74.484001","lat":"63.799877","s":"1","zid":"105"},{}],"places":[{"id":"1","lon":"74.48474884","lat":"63.79967880"},{"id":"2","lon":"74.48403931","lat":"63.79966736"},{}],"zones_calc":[],"pre_price_raw":"100","fix_price_raw":"100","rounding":"-0.60","error":""}
Параметры result, error всегда присутствуют в ответе. В случае успешного выполнения запроса параметр result имеет значение 1. В случае если произошла ошибка, то параметр result НЕ равен 1, а в параметр error содержит текстовое описание ошибки.
Описание параметров ответа
- distance - длина расчетного маршрута в километрах.
- distance_suburb - длина расчетного маршрута в километрах за городом.
- pre_price - предварительная цена.
- fix_price - окончательная цена, если на настройках тарифа установлен флаг фиксации стоимости поездки.
- nodes - массив с точками пути расчетного маршрута.
- places - массив с точками поездки маршрута.
- rounding - тип округления стоимости поездки согласно настройкам тарифа.
Пример запроса
https://test.taxomet.ru/get_distance?operator_login=test-api&operator_password=*******&unit_id=1&tarif_id=-1&lon[]=74.484749&lat[]=63.799679&lon[]=74.484039&lat[]=63.799667
Нет нужной функции API?
Свяжитесь с нами и мы откроем нужную функцию для API.