IntegrationDocuments.ru.markdown

Руководство по интеграции с системой RCS

Введение

Используемые термины и сокращения

Общие положения

Аутентификация
Разграничение прав доступа
Идентификация сервера
Версионирование протокола
Форматы данных
Общие форматы ответа
Типы данных
Синхронизация идентификаторов

Third-Party API

Получение информации об автомобилях с телематикой
Диагностика автомобилей с телематикой
Предложения и уведомления
Получение данных телеметрии
- Чтение “холодных” данных
- Получение данных в режиме real-time
Выполнение команд на устройствах Remoto
Автомобили для тест-драйва и кредита (Third-Party API)
Пользователи (Third-Party API)
Автомобили без телематики
Программа лояльности (Third-Party API)
Время посещения
Заявки (Third-Party API)
Чат с дилером

DMS API

Дилеры
Заявки (DMS API)
Автомобили для тест-драйва и кредита (DMS API)
Пользователи (DMS API)
Автомобили пользователей
Программа лояльности (DMS API)
История техобслуживания и ремонта

Введение

Документация по интеграции с системой RCS состоит из двух частей: руководство пользователя (настоящий документ) и ссылочная документация.

Знакомство с механизмами интеграции с системой RCS рекомендуется начинать с прочтения руководства пользователя и только потом переходить к ссылочной документации.

В настоящем документе описаны механизмы обмена данными между системой RSC и информационными системами подписчиков (дилеров). Документ описывает как использовать API в целом, рассказывает о принципах, заложенных в API и о моделях поведения.

Ссылочная документация построена с помощью набора инструментов Swagger на базе OpenAPI Specification (OAS) и доступна по следующим ссылкам:

Ссылка	Описание
Third-Party API endpoints	Ссылочная документация по точкам входа Third-Party API.
DMS - Dealers	Ссылочная документация по точкам входа DMS API Дилеры.
DMS - Car catalogue	Ссылочная документация по точкам входа DMS API Автомобили для тест-драйва и кредита.
DMS - Requests	Ссылочная документация по точкам входа DMS API Заявки.
DMS - Users & vehicles	Ссылочная документация по точкам входа DMS API Пользователи и автомобили пользователей.
DMS - Loyalty programme	Ссылочная документация по точкам входа DMS API Программа лояльности.
DMS - Service maintenance	Ссылочная документация по точкам входа DMS API История техобслуживания и ремонта.

Важно: во всем, что касается сигнатур точек входа, передаваемых и возвращаемых параметров, ссылочная документация является приоритетной.

Используемые термины и сокращения

В настоящем разделе приведены аббревиатуры и термины, используемые в документе.

API (Application Program Interface) – интерфейс прикладных программ.

RCS (Remoto Cloud Services) – экземпляр облачного сервиса Bright Box, предназначенный для:

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

Third-Party API – интеграционные веб-службы, развёртываемые на стороне RCS.

DMS (Dealer Mobility Service) – веб-служба со стандартизованным API, предоставляемым дилером для обмена данными по инициативе RCS.

Подписка – сущность в системе RCS, набор параметров, представляющий B2B клиента Bright Box и его настройки для корректного функционирования порталов и мобильного приложения клиента.

Подписчик – сторона (клиент) в договоре с Bright Box на использование RCS. В системе RCS представлен подпиской.

Клиент – подписчик, дилер, использующий службы Third-Party API RCS и/или предоставляющий службы DMS API для обмена данными с RCS.

NSC (National Sales Company) – национальная торговая компания. Это субъект в организационной иерархии подписчика, который определяет контент, чувствительный к локализации, и задаёт локализацию контента для нижестоящих (субординированных) субъектов (дилерских сетей и дилеров). В системе RCS является подобъектом подписки.

Дилерская сеть – субъект в организационной иерархии подписчика. В системе RCS является подобъектом NSC.

Дилер – дилер в составе организационной структуры подписчика, дилерский центр в составе организационной структуры подписчика. В системе RCS является подобъектом дилерской сети.

МП (Remoto) – мобильное приложение клиента (подписчика), предоставляющее услуги Connected Car и услуги дилеров с помощью RCS (включая устройство Remoto).

Пользователь – пользователь мобильного приложения Remoto, выступающий потребителем услуг Connected Car и услуг дилера.

DTO (Data Transfer Object) – это лишённый всякого поведения тип объекта (класс), служащий контейнером для данных при их передаче (включая сериализацию и десериализацию) из одной системы в другую.

Оперативные данные/real-time данные от устройств – сообщения и данные телеметрии, получаемые в режиме реального времени с помощью средств телематики от устройств Remoto, установленных в транспортных средствах.

ПУ (Панель управления) – один из порталов RCS. Предназначен для управления данными подписки, включающей в себя всю организационную структуру: NSC, дилерские сети и дилерские центры.

Устройство Remoto – физическое устройство, устанавливаемое на автомобиль. Предназначено для удаленного управления автомобилем и/или для отслеживания состояния автомобиля и передачи телеметрической информации через систему RCS.

Автомобиль с телематикой (connected car) – автомобиль с установленным устройством Remoto и подключенный к системе RCS.

Автомобиль без телематики (unconnected car) – автомобиль без установленного устройства Remoto, но зарегистрированный в системе RCS с целью получения услуг от дилера, таких как, получений новостей, специальных предложений, услуг по обслуживанию автомобиля, его ремонту и т. д.

RCC (Remoto Car Control) – это набор функций и сервисов Remoto, которые отвечают за удаленное управление автомобилем путем отправки ему команд.

OAS (OpenAPI Specification) – стандартный, не зависящий от языка интерфейс для построения RESTful API. Может использоваться для генерации ссылочной документации по API, клиентского и серверного кода для реализации API, тестирования и другими вариантами использования.

Swagger – набор инструментов для разработки и документирования API, базирующийся на OAS.

Общие положения

RCS использует два механизма интеграции с информационными системами подписчиков (дилеров):

Third-Party API – это интеграционные веб-службы, развёртываемые на стороне RCS. Приложение подписчика (дилера) обращается к методам Third-Party API, чтобы получить данные для синхронизации справочников, оперативные данные телеметрии, удаленно управлять автомобилем, выполняя команды на устройствах Remoto, или сообщить об изменении статуса информационных объектов, таких, например, как заявки пользователей на приобретение автозапчастей или прохождение тест-драйва.
Dealership Mobility Service (DMS) – это интеграционная веб-служба, развёрнутая на стороне подписчика (дилера) для обмена данными по инициативе системы RCS. RCS обращается к методам DMS API для синхронизации справочников, получения информации об оперативной деятельности подписчика (дилера), требуемой для удовлетворения потребностей пользователей.

Вся информация, приведенная в этом разделе, относится к обоим механизмам интеграции. Специфичные для одного из механизмов сведения будут отмечены явным образом: (Third-Party API) или (DMS API).

Оба API предназначены для взаимодействия «сервер-сервер», что обуславливает ряд архитектурных особенностей. В частности, основные API систем представлены в стиле REST: функции системы выставляются для клиента в виде набора ресурсов, над которыми можно выполнять операции посредством отправки запросов по протоколу HTTPS.

(Third-Party API) Оперативные данные от устройств предоставляются по протоколу AMQP 0-9-1 поверх TLS.

Для защиты трафика на транспортном уровне используются протоколы TLS 1.3. Не допускается использование незащищенного соединения.

Аутентификация

Для защиты от несанкционированного доступа используется двусторонняя аутентификация с помощью сертификатов:

серверный сертификат соответствует доменному имени сервера и подписывается общеизвестным доверенным центром сертификации (например, COMODO CA);
(Third-Party API) клиентский сертификат для доступа к Third-Party API выпускается и подписывается собственным центром сертификации продукта Remoto;
(DMS API) клиентский сертификат для доступа к DMS API выпускается, подписывается и предоставляется подписчиком (дилером);
при выпуске сертификатов должен быть использован алгоритм шифрования семейства SHA-2. Алгоритмы MD5 и SHA-1 являются устаревшими и корректная работа с сертификатами на базе этих алгоритмов не гарантируется.

Аутентификация и авторизация клиента осуществляется по сертификату, использованному им при установлении соединения.

Практически все запросы к API являются авторизованными и требуют предоставления корректного клиентского сертификата. Лишь несколько запросов могут быть анонимными. Такая возможность явно обозначается в их спецификации. Следует иметь ввиду, что обращение к таким ресурсам в любом случае защищается протоколом TLS 1.3, но аутентификация в этом случае является односторонней, сервер не требует наличия клиентского сертификата. Тем не менее, в таких запросах может присутствовать сертификат.

Сертификат, указанный в запросе, должен быть корректным, действительным и соответствовать зарегистрированному клиенту.

Разграничение прав доступа

(Third-Party API)

Сервер осуществляет разграничение прав доступа клиента к автомобилям на трех уровнях:

Предоставления доступа ко всем устройствам подписки. Клиент получает доступ ко всем автомобилям подписки. Эта возможность является свойством подписки и должна быть явно включена для клиента.
Список привязок автомобилей к клиентам. Клиент имеет доступ к автомобилю только при условии наличия такой привязки. С точки зрения клиента отсутствие привязки полностью аналогично отсутствию данных об автомобиле в БД сервера. При попытке выполнить запрос, оперирующий непривязанным к клиенту или отсутствующим в БД автомобилем, запрос не будет выполнен, и сервер вернет код ответа 404 Not Found или 400 Bad Request в зависимости от контекста (см. Общие форматы ответа).
Права, выданные клиенту, на операции, выполняемые с конкретным автомобилем. Привязка автомобиля к клиенту или предоставление доступа ко всем автомобилям подписки еще не означает, что клиент может выполнять с этим автомобилем любые операции. Сервер поддерживает гибкую настройку предоставляемых прав. При попытке выполнить операцию, на которую у клиента нет прав, с автомобилем, для которого есть привязка, запрос не будет выполнен, и сервер вернет код ответа 403 Forbidden.

Идентификация сервера

(Third-Party API)

Ссылочная документация по точкам входа: Third-Party API endpoints.

Swagger tag: Root

Клиент может определить, что он имеет дело именно с сервером RCS, отправив следующий анонимный запрос:

GET /

Запрос не требует указания поддерживаемой клиентом версии протокола (заголовок X-API-Version может отсутствовать).

Получение ответа на запрос в ожидаемом формате, во-первых, подтверждает, что подключение выполнено к нужному серверу, а во-вторых, снабжает клиента информацией об используемой версии протокола.

Гарантируется, что для всех будущих версий протокола (включая обновление мажорной версии) формат ответа сервера при обращении к данному ресурсу будет обратно совместим с текущим форматом.

Выполнив запрос:

GET /parameters

клиент может запросить используемые сервером значения параметров протокола. Этот запрос уже требует авторизации и является версионируемым.

Версионирование протокола

(Third-Party API)

Версии протокола нумеруются в формате X.Y. Изменение минорного компонента (Y) версии гарантирует обратную совместимость, мажорного (X) – не гарантирует. В случае мажорной версии 0 обратная совместимость не гарантируется даже при изменении минорного компонента.

Поддерживаемые сервером версии протокола клиент может определить по ответу на запрос GET /. Отсутствие в списке записи для мажорной версии означает, что все семейство этих версий сервером не поддерживается, даже если поддерживается более старшая мажорная версия. Наличие записи для версии X.Y означает, что сервер поддерживает все версии протокола X.Z, где Z <= Y. Для мажорной версии 0 совместимость минорных версий не гарантируется. Это означает, что версия 0.Z поддерживается сервером только если явно присутствует в списке поддерживаемых протоколов.

При обращении к ресурсам REST клиент обязан явно указывать поддерживаемую им версию протокола в заголовке X-API-Version. Заголовок поддерживается при обращении к любому ресурсу REST. Если версия протокола поддерживается, ответ сервера может быть представлен в формате более новой минорной версии в рамках той же мажорной, что не должно представлять проблем для клиента с учетом обратной совместимости (клиент должен просто игнорировать неизвестные ему поля). Если сервер не поддерживает указанную версию, он не выполнит запрос и вернет код 400 Bad Request. Содержимое ответа при этом будет представлено в формате, соответствующем коду ошибки UNSUPPORTED_VERSION (см. Общие форматы ответа). Гарантируется, что для всех будущих версий протокола (включая обновление мажорной версии) формат ответа сервера в этой ситуации будет обратно совместим с текущим форматом.

Исключением является запрос к ресурсу для чтения информации о сервере (GET /), при обращении к которому указание поддерживаемой клиентом версии протокола (заголовка X-API-Version) не требуется. Однако, если версия все же указана, то ресурс будет обрабатывать ее также, как и любой другой: проверять совместимость и поддерживаемость версии с возможным возвратом кода ошибки.

Форматы данных

REST API поддерживает обмен данными в формате JSON. Соответственно, ответы сервера имеют заголовок Content-Type, установленный в значение application/json. Запросы клиента, подразумевающие передачу содержимого, также должны иметь такое значение заголовка Content-Type. Если клиент не передает заголовок Content-Type в запросе с содержимым, значение application/json подразумевается. Передача заголовка Content-Type с другим значением приведет к отказу в выполнении запроса с кодом ответа 415 Unsupported Media Type.

В случае ожидания ответа на запрос, клиент может передать заголовок Accept со значением application/json, что не является обязательным. Если передан заголовок Accept, не допускающий формат application/json, сервер не будет выполнять запрос, вернув код ответа 406 Not Acceptable.

Общие форматы ответа

Перечисленные здесь коды и форматы ответа являются общими для всех запросов к API. Они допускаются для всех запросов, помимо тех, что явно описаны в спецификациях конкретных запросов.

В данном разделе приводятся типовые ответы, явно генерируемые прикладным уровнем сервера API. Естественно, веб-инфраструктура (веб-сервер, прокси-серверы, шлюзы и т. д.) может выполнять генерацию других, допустимых HTTP протоколом, ответов, не описанных здесь. Кроме того, инфраструктурные модули могут генерировать ответы с теми же кодами, что описаны здесь, но с отличающимся содержимым. Подобные ситуации не отражены в данной спецификации.

400 Bad Request

Запрос сформирован неверно и не прошел валидацию на сервере.

Сервер не выполнил каких-либо операций, связанных с запросом.

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

{
    // Информация об ошибке.
    "error": {

        // Технический код ошибки.
        "code": "<string>",

        // Человекочитаемое описание ошибки.
        "message": "<string>",

        // Техническое имя поля запроса, вызвавшего ошибку.
        // Может не передаваться.
        "source": "<string>"
    }
}

Если конкретный запрос подразумевает какие-то особые правила валидации запроса, то эти случаи (с их техническими кодами) оговариваются отдельно в спецификации таких запросов. Следующие коды применимы к любым запросам, предполагающим отправку данных от клиента на сервер (в строке запроса, теле запроса или HTTP заголовке):

Клиент в заголовке X-API-Version запросил версию протокола, которую сервер не поддерживает. Гарантируется, что для всех будущих версий протокола (включая обновление мажорной версии) формат ответа сервера в этой ситуации будет обратно совместим с текущим форматом.

{
    // Информация об ошибке.
    "error": {

        // Технический код ошибки.
        "code": "UNSUPPORTED_VERSION",

        // Человекочитаемое описание ошибки.
        "message": "<string>",

        // Техническое имя поля запроса, вызвавшего ошибку.
        // Может не передаваться.
        "source": "X-API-Version"
    }
}

Отсутствует обязательное поле. Код возврата также используется, если передается значение null, когда оно не допустимо, или пустая строка ("") для типов данных, представляемых в виде строки, но требующих значения.
```
{
    "error": {

        "code": "VALUE_REQUIRED",
        ...
    }
}
```
Неверный формат данных поля (например, строка вместо числа и т. п.).
```
{
    "error": {

        "code": "INVALID_FORMAT",
        ...
    }
}
```
Значение поля выходит за пределы допустимого диапазона. Следует иметь ввиду, что данный код не используется в тех случаях, когда ожидается положительное число, а передается 0 или отрицательное, или ожидается неотрицательное, а передается отрицательное. В указанных случаях используется предыдущий код (InvalidFormat).
```
{
    "error": {

        "code": "OUT_OF_RANGE",
        ...
    }
}
```
Размер значения поля (для строк и бинарных данных) выходит за пределы допустимого диапазона.
```
{
    "error": {

        "code": "INVALID_LENGTH",
        ...
    }
}
```

В запросе указан идентификатор автомобиля, не существующий или не относящийся к текущему клиенту. Данный код подразумевает, что все идентификаторы автомобилей указаны в правильном формате. Иначе будет выдан ответ 400 Bad Request с общим кодом “invalid_format”.

{
    // Информация об ошибке.
    "error": {

        // Технический код ошибки.
        "code": "ILLEGAL_VEHICLE_ID",

        // Человекочитаемое описание ошибки.
        "message": "<string>",

        // Техническое имя поля запроса, вызвавшего ошибку.
        "source": "device_ids"
    }
}