Документация по использованию XML протокола RBTaxi

Вводная часть

XML протокол не является заменой APIv3 и используется для отправки горящих заказов из системы RBTaxi в систему Службы Такси для передачи Исполнителю на выполнение. API реализовано на HTTP протоколе, метод указывается непосредственно для каждого запроса.
POST запросы содержат в теле XML документ.

Адрес интерфейса: https://api.rbtaxi.ru/ya/.

Ответ всегда в UTF-8.

Термин Описание
Служба такси Сторонее ПО для работы с заказами
Исполнитель Таксопарк, клиент RBTaxi и Службы такси
apikey API-ключ для инфообмена между RBTaxi и Службой такси
Передается во всех запросах
executorId Уникальный ID исполнителя, для идентификации компании, совершающей действия по заказу
Передается в запросах от Службы такси
requestcar Ссылка Службы такси для получения Предложений заказов
setcar Ссылка Службы такси для получения Закреплений заказов
cancelrequest Ссылка Службы такси для получения Отмены заказов
Здесь и далее жирным выделены обязательные для передачи параметры

Описание

Данный протокол изначально создан для связи Исполнителей работающих в RBTaxi и в Службе такси.

Интеграция начинается с передачи Службой такси своих ссылок requestcar, setcar, cancelrequest в техническую поддержку RBTaxi.

В ответ RBTaxi предоставляет API-ключ инфообмена, два доступа к песочнице и, соответственно, два ключа executorId для добавления и исполнения заказа (один доступ является Автором заказа, другой Исполнителем). К Службе такси может быть подключено не ограниченное количество Исполнителей.

На указанные ссылки начинают поступать Предложения заказов с указанием каким именно Исполнителям следует показать данный заказ.

По готовности Исполнителя выполнить заказ Служба такси отправляет RBTaxi запрос на Взятие заказа, RBTaxi выполняет проверку доступности заказа и отправляет встречный запрос Закрепления заказа, на основании полученного ответа от Службы такси, RBTaxi отвечает соответстующим кодом на поступивший ранее запрос Взятие заказа; в случае недоступности заказа или некорректного ответа на запрос Закрепления заказа, RBTaxi выполняет запрос Отмены заказа и отвечает кодом 404 на поступивший ранее запрос Взятие заказа.

В случае закрепления заказа Служба такси уведомляет RBTaxi об изменении Статуса заказа Исполнителем посредством запроса Простановки статуса к RBTaxi.

История изменений

Ниже описываются изменения в протоколе.

Дата Описание
24.06.2016 Изменена схема получения информации о клиенте,
теперь данные необходимо дополнительно запрашивать (см. Информация о клиенте).
27.06.2016 В секцию CompanyInfo добавлен узел ApiKey
25.04.2017 (Важное!) Подготовка к строгой проверке марки/модели т.с. на соответствие нашей базе,
в противном случае заказ не будет закреплён за исполнителем.
20.07.2017 Добавлены поля "BlockNumber" и "BuildNumber - номера корпуса и строения соотвественно.
19.10.2017 Изменено описпание атрибута type у тега BookingTime в XML Предложения заказа.
Добавлены поля Require в XML Предложения заказа для опций: Багаж, Лыжи/Сноуборд, Встреча с табличкой,
Машина без рекламы, Водитель со знанием иностранного языка, Радио, Курьерская доставка, Подъем на этаж.
Изменено описание протокола.
Исправлены ошибки и опечатки.

Заголовки ответов

Успешность GET или POST запроса определяет HTTP статус код

Статус Описание
200 Ok Запрос выполнен без ошибок
404 Not Found Заказ, указанный в запросе не найден
400 Bad Request В запросе нехватает параметров или значение параметров указано неверно
403 Forbidden Передан некорректный API-ключ
500 Internal Server Error Возникла внутреняя ошибка сервера

Запросы от RBTaxi

Предложение заказа

POST

служба_такси/requestcar

RBTaxi отправляет запрос в Службу такси с предложением заказа

Пример XML предложения заказа
<xml version="1.0" encoding="UTF-8">
<Request>
	<Orderid>9932425</Orderid>
	<ApiKeys>
		<Key>eccbc87e4b5ce2fe28308fd4f2a7baf3</Key>
	</ApiKeys>
	<Recipient blacklisted="no" loyal="yes"></Recipient>
	<CompanyInfo>
		<Id>4</Id>
		<Name>2Товарища</Name>
		<ApiKey>dc09c97fd73d7a324bdbfe7c79525f64</ApiKey>
		<Phones>
			<Phone>+71111111111</Phone>
		</Phones>
	</CompanyInfo>
	<Source>
		<FullName>Россия, Москва, проезд 2-й Рощинский, 12</FullName>
		<ShortName>проезд 2-й Рощинский, 12</ShortName>
		<Point>
			<Lon>37.6053100000</Lon>
			<Lat>55.7045700000</Lat>
		</Point>
		<Country>
			<CountryName>Россия</CountryName>
			<Locality>
				<LocalityName>Москва</LocalityName>
				<Thoroughfare>
					<ThoroughfareName>проезд 2-й Рощинский</ThoroughfareName>
					<Premise>
						<PremiseNumber>12</PremiseNumber>
					</Premise>
				</Thoroughfare>
			</Locality>
		</Country>
	</Source>
	<Destinations>
		<Destination order="1">
			<FullName>Россия, Москва, аэропорт Шереметьево, 21</FullName>
			<ShortName>аэропорт Шереметьево, 21</ShortName>
			<Point>
				<Lon>37.413673</Lon>
				<Lat>55.971204</Lat>
			</Point>
			<Country>
				<CountryName>Россия</CountryName>
				<Locality>
					<LocalityName>Москва</LocalityName>
					<Thoroughfare>
						<ThoroughfareName>аэропорт Шереметьево</ThoroughfareName>
						<Premise>
							<PremiseNumber>21</PremiseNumber>
						</Premise>
					</Thoroughfare>
				</Locality>
			</Country>
		</Destination>
	</Destinations>
	<BookingTime type="exact">2016-04-05T11:40</BookingTime>
	<RbtTariff>
		<Autoclass>econom</Autoclass>
		<UType>min</UType>
		<MinPrice>320</MinPrice>
		<IncTime>20</IncTime>
		<TimeCost>10</TimeCost>
		<TimeCostUnit>1</TimeCostUnit>
		<Waiting>
			<TimeFree>10</TimeFree>
			<TimeCostWait>10</TimeCostWait>
		</Waiting>
		<Outcity>
			<Cost>100</Cost>
			<CostUnit>1</CostUnit>
		</Outcity>
		<OutcityGiving>
			<Cost>100</Cost>
			<CostUnit>1</CostUnit>
		</OutcityGiving>
	</RbtTariff>
	<Tariffs>
		<Tariff>e/m/320/20/10/10/10/100</Tariff>
	</Tariffs>
	<OwnerCharge>0.1</OwnerCharge>
	<FixMarkup>0</FixMarkup>
	<Requirements>
		<Require name="nameplate" value="Александр">yes</Require>
		<Require name="child_chair">no</Require>
		<Require name="animal_transport">no</Require>
		<Require name="universal">no</Require>
	</Requirements>
	<RouteInfo>
		<Time unit="second">0</Time>
		<Distance unit="meter">0</Distance>
	</RouteInfo>
	<Comments>Произвольный заказ с весьма зауреадным комментарием.</Comments>
</Request>

Теги из "XML предложения заказа" описаны ниже

Тег Описание Атрибуты
Orderid ID заказа в РБТ
ApiKeys Содержит идентификаторы компаний
Key Уникальный идентификатор компании
Recipient Характеристика клиента
  • blacklisted - признак недобросовестности клиента, определяется по черному списку
    • yes - клиент внесен в черный список
    • no - клиента нет в черном списке
  • loyal — признак постоянного клиента
    • yes - постоянный клиент
    • no - пользователь не считается постоянным клиентом
CompanyInfo Содержит информацию о компании авторе заказа
Id ID компании
Name Название компании
ApiKey Уникальный идентификатор компании
Phones Содержит телефоны компании
Phone Телефон компании
Source Содержит описание места подачи машины
Destinations Содержит описание адресов всех промежуточных остановок и пункта назначения
Destination Описание одного места назначения
  • order - порядковый номер остановки в маршруте
FullName Полный адрес места подачи, от страны до номера дома
ShortName Короткий адрес места подачи машины (улица и номер дома)
Point Содержит географические координаты места подачи машины
Lon Долгота
Lat Широта
Airport Содержит информацию о встерече клиента в аэропорту
Flight Номер рейса
Country Содержит адрес места подачи, разбитый на элементы
CountryName Название страны
Locality Содержит описание населенного пункта
LocalityName Название населенного пункта
Thoroughfare Содержит адрес, улицу (бульвар, проезд и т. п.)
ThoroughfareName Название улицы
Premise Содержит номер дома (строения, корпуса и т. п.)
PremiseNumber Номер дома
BlockNumber Номер корпуса
BuildNumber Номер строения
PorchNumber Номер подъезда
BookingTime Время подачи такси
  • type - указывает на вид заказа, срочный или несрочный
    • notlater - срочный заказ (до подачи машины меньше 10 минут)
    • exact - несрочный заказ (до подачи машины больше 10 минут)
RbtTariff Описывает тариф заказа в полном формате
Autoclass Требуемый класс машины
  • econom - Эконом
  • comfort - Комфорт
  • business - Бизнес
  • universal - Универсал
  • minivan - Минивэн
  • minibus - Микроавтобус
UType Требуемый класс авто Описывает тариф заказа в коротком формате
  • min - минутный
  • km - километражный
  • fix - фикс цена
MinPrice Минимальная стоимость заказа
IncTime Количество минут, включенных в заказ
TimeCost Стоимость минуты (или интервала см. TimeCostUnit)
TimeCostUnit Интервал к которому приводится стоимость по времени
IncDist Количество километров, включенных в заказ
DistCost Стоимость километра (или интервала см. DistCostUnit)
DistCostUnit Интервал к которому приводится стоимость по расстоянию
FixPrice Фиксированная стоимость заказа
Waiting Содержит стоимости ожидания
TimeFree Бесплатное ожидание (минуты)
TimeCostWait Платное ожидание (рубли в минуту)
Outcity Содержит стоимости поездки за город
OutcityGiving Содержит стоимость подачи за город
Cost Стоимость
CostUnit Интервал к которому приводится стоимость по расстоянию
Tariffs Описывает тариф заказа в коротком формате, который формируется следущим образом:
c/m/p1/p2/p3/p4/p5/p6

  • c - класс машины
  • m - тарификация (m - по минутам, k - по километрам, f - фикс)
  • p1 - минимальная стоимость заказа (в целых рублях)
  • p2 - количество километров (минут), включенных в заказ
  • p3 - стоимость в целых рублях дополнительного километра (минуты)
  • p4 - бесплатное ожидание (минуты)
  • p5 - платное ожидание (рубли в минуту)
  • p6 - стоимость километра за городом в рублях

Варианты классов машин:
  • e - Эконом
  • c - Комфорт
  • b - Бизнес
  • u - Универсал
  • v - Минивэн
  • a - Микроавтобус
Requirements Содержит дополнительные требования к машине
OwnerCharge Процент по заказу
FixMarkup Фиксированная наценка
Require Требование к машине
  • name - название опции
    • no_smoking - разрешено ли курение
      • yes - в машине должно быть запрещено курение
      • no - курение в машине должно быть разрешено
    • beznal - оплата безналично
      • yes - заказ оплачивается безналично
    • child_chair - детское кресло есть, предназначено для детей указанного возраста
      • <возраст ребенка>
      • no - детского кресла нет
      • (Возможно наличие нескольких кресел)
    • animal_transport - перевозка животных
      • yes - в машине должно быть разрешено перевозить животных
    • card - терминал для оплаты
      • yes - в машине должен быть терминал для оплаты банковскими картами
    • universal - кузов универсал
      • yes - машина должна быть в кузове универсал
    • baggage - клиент с багажом
      • yes - в машине должно быть место для багажа
      • value - описание багажа
    • ski - клиент с лыжами/сноубордом
      • yes - в машине должно быть место для лыж/сноубора
    • nameplate - кстреча с табличкой
      • yes - водитель должен встретить клиента с табличкой
      • value - текст таблички
    • noadv - без рекламы
      • yes - в машине не должно быть рекламы
    • english - знание английского языка
      • yes - водитель должен быть со знанием английского языка
    • radio - желаемая радиостанция
      • yes - выбранная радиостанция
      • value - название радиостанции
    • delivery - курьерская доставка
      • yes - необходима курьерская доставка
      • phone - телефон для связи
    • delivery-lift - подъем на этаж
      • yes - необходим подъем на этаж
      • floor - этаж
      • flat - квартира
    • car_license - авто с лицензией
      • yes - необходимо наличие лицензии
      • no - наличие лицензии не обязательно
RouteInfo Информация о маршруте клиента
Time Время в пути
  • unit - единица измерения
    • second - секунды
Distance Длина маршрута от места подачи до места назначения
  • unit - единица измерения
    • meter - метры
Comments Комментарии к заказу, может содержать дополнительные требования

Закрепление заказа

POST

служба_такси/setcar

RBTaxi отправляет запрос в Службу такси с закреплением заказа за водителем

Пример XML закрепления заказа
<?xml version="1.0" encoding="UTF-8"?>
<Request>
    <Orderid>9932425</Orderid>
    <ApiKeys>
        <Key>eccbc87e4b5ce2fe28308fd4f2a7baf3</Key>
    </ApiKeys>
    <Recipient blacklisted="no" loyal="yes"></Recipient>
    <CompanyInfo>
        <Id>4</Id>
        <Name>2Товарища</Name>
        <Phones>
            <Phone>+71111111111</Phone>
        </Phones>
    </CompanyInfo>
    <Source>
        <FullName>Россия, Москва, проезд 2-й Рощинский, 12</FullName>
        <ShortName>проезд 2-й Рощинский, 12</ShortName>
        <Point>
            <Lon>37.6053100000</Lon>
            <Lat>55.7045700000</Lat>
        </Point>
        <Country>
            <CountryName>Россия</CountryName>
            <Locality>
                <LocalityName>Москва</LocalityName>
                <Thoroughfare>
                    <ThoroughfareName>проезд 2-й Рощинский</ThoroughfareName>
                    <Premise>
                        <PremiseNumber>12</PremiseNumber>
                    </Premise>
                </Thoroughfare>
            </Locality>
        </Country>
    </Source>
    <Destinations>
        <Destination order="1">
            <FullName>Россия, Москва, аэропорт Шереметьево, 21</FullName>
            <ShortName>аэропорт Шереметьево, 21</ShortName>
            <Point>
                <Lon>37.413673</Lon>
                <Lat>55.971204</Lat>
            </Point>
            <Country>
                <CountryName>Россия</CountryName>
                <Locality>
                    <LocalityName>Москва</LocalityName>
                    <Thoroughfare>
                        <ThoroughfareName>аэропорт Шереметьево</ThoroughfareName>
                        <Premise>
                            <PremiseNumber>21</PremiseNumber>
                        </Premise>
                    </Thoroughfare>
                </Locality>
            </Country>
        </Destination>
    </Destinations>
    <BookingTime type="exact">2016-04-05T11:40</BookingTime>
    <RbtTariff>
        <Autoclass>econom</Autoclass>
        <UType>min</UType>
        <MinPrice>320</MinPrice>
        <IncTime>20</IncTime>
        <TimeCost>10</TimeCost>
        <TimeCostUnit>1</TimeCostUnit>
        <Waiting>
            <TimeFree>10</TimeFree>
            <TimeCostWait>10</TimeCostWait>
        </Waiting>
        <Outcity>
            <Cost>100</Cost>
            <CostUnit>1</CostUnit>
        </Outcity>
        <OutcityGiving>
            <Cost>100</Cost>
            <CostUnit>1</CostUnit>
        </OutcityGiving>
    </RbtTariff>
    <Tariffs>
        <Tariff>e/m/320/20/10/10/10/100</Tariff>
    </Tariffs>
    <Cars>
        <Car>
            <Uuid>6921</Uuid>
            <Tariff>e/m/320/20/10/10/10/100</Tariff>
        </Car>
    </Cars>
    <OwnerCharge>0.1</OwnerCharge>
    <FixMarkup>0</FixMarkup>
    <Requirements>
        <Require name="child_chair">no</Require>
        <Require name="animal_transport">no</Require>
        <Require name="universal">no</Require>
    </Requirements>
    <RouteInfo>
        <Time unit="second">0</Time>
        <Distance unit="meter">0</Distance>
    </RouteInfo>
    <Comments>Произвольный заказ с весьма зауреадным комментарием.</Comments>
</Request>

Основные теги из "XML закрепления заказа" описаны выше, дополнительные ниже

Тег Описание Атрибуты
Name Имя клиента
Cars Содержит список водителей
Car Содержит описание водителя
Uuid Уникальный идентификатор водителя в системе Службы Такси
Tariff Тариф по которому данный водитель будет выполнять заказ

Отмена заказа

GET

служба_такси/cancelrequest

RBTaxi отправляет запрос в Службу такси на отмену предложенного заказа

Параметр Тип Описание
orderid int ID заказа
reason string Причина отмены

Запросы от Службы такси

Взятие заказа

GET

/ya/update/carack

Служба такси отправляет RBTaxi запрос на взятие предложенного ранее заказа

Параметр Тип Описание
uuid int Уникальный идентификатор водителя в системе Службы такси
orderid int ID заказа
phones string Телефон водителя
carNumber string Гос. номер машины
carColor string Цвет машины
carModel string Модель и марка машины
driverName string Имя водителя

Информация о клиенте

GET

/ya/update/getorderdata

Служба такси отправляет RBTaxi запрос на уточнение контактов клиента

Параметр Тип Описание
orderid int ID заказа
Пример XML с информацией о клиенте
<xml version="1.0" encoding="UTF-8">
<OrderData>
	<ContactInfo>
		<Phones>
			<Phone>+79091002030</Phone>
		</Phones>
		<Name>Александра</Name>
	</ContactInfo>
</OrderData>

Простановка статусов

GET

/ya/update/requestconfirm

Служба такси отправляет RBTaxi запрос на изменение статуса по заказу

Параметр Тип Описание
orderid int ID заказа
extra string При завершении заказа в этом поле передается итоговая стоимость
commentDone string При завершении заказа в этом поле передается коммантарий
Например: если закрывается фикс заказ на большую стоимость, необходимо обязательно указать комментарий
status string статус заказа из списка

Возможные статусы

Параметр Описание
driving Водитель выехал к клиенту
waiting Водитель прибыл на место назначения, ожидает клиента
transporting Водитель везет клиента к месту назначения
complete Заказ выполнен
cancelled Заказ отменен клиентом
failed Водитель не смог выполнить заказ

Редактирование автомобиля

GET

/ya/update/renewdriver

Служба такси отправляет RBTaxi запрос на изменение информации об автомобиле

Параметр Тип Описание
uuid int Уникальный идентификатор водителя в системе Службы такси
orderid int ID заказа
phones string Телефон водителя
carNumber string Гос. номер машины
carColor string Цвет машины
carModel string Модель и марка машины
driverName string Имя водителя

Отказ от заказа

GET

/ya/update/refuseorder

Служба такси отправляет RBTaxi запрос на отказ от заказа

Параметр Тип Описание
orderid int ID заказа
reason string Причина отмены