Принципы работы *************** Для интеграции облачного сервиса PowerVHC используется программный интерфейс на основе протокола HTTPS. Клиентом (стороной инициирующей соединение) во всех случаях является DMS. Данные передаются в формате JSON (`RFC 7159`_) в кодировке UTF-8. Все даты передаются в формате ISO8601_. Поля в объектах могут следовать в произвольном порядке. Процесс интеграции PowerVHC с дилерской системой управления предприятием может быть ускорен благодаря готовым интеграционным решениям, представленным в разделе `Модули интеграция с ДМС`_. Актуальная информация ===================== Последнюю версию документации по API всегда можно получить по ссылке: https://docs.powervhc.com Адрес для доступа к API (API endpoint) ====================================== Все запросы к PowerVHC API начинаются с «https://api.powervhc.com/v1/». Используется стандартный для HTTPS порт 443. .. attention:: До недавнего времени поддерживалась возможность работы с системой через устаревшие точки доступа: "https://evhc-test-api.untwined-solutions.co.uk/v1/", "https://evhc-api.untwined-solutions.co.uk/v1/". Поддержка данных точек доступа в любой момент может быть прекращена. Убедительная просьба в дальнейшей работе использовать только основную точку доступа «https://api.powervhc.com/v1/». 12 апреля 2022 Безопасность ============ Для доступа к API используется только протокол HTTPS с современными алгоритмами шифрования. Доступ к хосту API по протоколу HTTP и порту 80 закрыт, это необходимо для обеспечения безопасности и не является признаком недоступности системы. Примеры в документации ====================== В описанных ниже примерах, для отправки запросов на сервер используется утилита curl_ и дополнение к браузеру Chrome Postman. Использование данных инструментов не обязательно, доступ к API может производится с использованием любого HTTP клиента. Авторизация =========== Имя пользователя и пароль ~~~~~~~~~~~~~~~~~~~~~~~~~ Для доступа к веб-интерфейсу системы используется традиционная авторизация с использованием имени пользователя и пароля. В целях обеспечения безопасности проверка имени пользователя и пароля занимает примерно 1 секунду. Во избежание лишних задержек не используйте авторизацию с использованием имени пользователя и пароля в реализации программных интерфейсов (API). Ключ доступа к API ~~~~~~~~~~~~~~~~~~ Ключи доступа к API представляет собой строку длиной до 50 символов состоящую из букв латинского алфавита, цифр, ``-`` и подчёркиваний. Ключ API чувствителен к регистру. Пример ключа доступа к API: ``70QVm7hf8owpaM-0kYQLyzwiXLIO_1yVHYn3GiVD7L8`` Ключи доступа к API не хранятся на сервере в явном виде. Напоминание утраченного ключа доступа к API невозможно, вместо этого возможна только блокировка утраченного ключа и выпуск нового. Серьёзно относитесь к обеспечению конфиденциальности своих ключей для доступа к API. Помните, что по предоставляемым полномочиям ключ доступа к API эквивалентен логину и паролю, для которых он сгенерирован. Если у вас есть подозрение, что ваш ключ доступа к API стал известен посторонним, незамедлительно сообщите об этом в службу технической поддержки для блокировки старого и выпуска нового ключа. Авторизация запроса к API ~~~~~~~~~~~~~~~~~~~~~~~~~ Для авторизации запроса к API он должен содержать в заголовке поле :code:`X-API-KEY` со значением ключа доступа к API. Пример авторизации запроса: 1. CURL .. code-block:: none :emphasize-lines: 6,8 $ curl -v -H "X-API-KEY: 70QVm7hf8owpaM-0kYQLyzwiXLIO_1yVHYn3GiVD7L8" https://api.powervhc.com/v1/system-clients/1/surveys/aCwETtusxRY5GaVN > GET /v1/system-clients/1/surveys/aCwETtusxRY5GaVN HTTP/1.1 > User-Agent: curl/7.29.0 > Accept: */* > X-API-KEY: 70QVm7hf8owpaM-0kYQLyzwiXLIO_1yVHYn3GiVD7L8 > < HTTP/1.1 200 OK < server: Cowboy < date: Fri, 28 Aug 2015 08:04:12 GMT < content-length: 33047 < content-type: application/json; charset=utf-8 2. Postman (расширение Chrome) .. figure:: _static/auth-postman-request.png :align: center *Пример запроса.* .. figure:: _static/auth-postman-response.png :align: center *Ответ от сервера.* Обработка ошибок ================ Коды статуса HTTP ~~~~~~~~~~~~~~~~~ Для возвращения результата запроса используются стандартные коды статуса HTTP (RFC7231_). Коды начинающиеся с 2 обозначают успешные операции, с 4 - ошибки клиента, с 5 - ошибки сервера. Наиболее часто используемые коды статуса HTTP: .. tabularcolumns:: |l|l| +----+----------------------------------------------------------------------------------------------------------------------------+ |Код |Описание | +====+============================================================================================================================+ |200 |OK. Операция успешна. | +----+----------------------------------------------------------------------------------------------------------------------------+ |201 |Created. | | |Объект создан.Используется совместно с HTTP методом POST. Заголовок Location содержит URL созданного объекта. | +----+----------------------------------------------------------------------------------------------------------------------------+ |204 |No content. | | |Операция успешна, но не возвращает данных. Используется вместо кода 200 когда HTTP метод не возвращает ничего в теле ответа.| +----+----------------------------------------------------------------------------------------------------------------------------+ |400 |Bad request. | | |Некорректный запрос. Тело ответа может содержать более подробное описание ошибки. | +----+----------------------------------------------------------------------------------------------------------------------------+ |401 |Unauthorized. | | |Пользователь не авторизован. Проверьте заголовок запроса X-API-KEY. | +----+----------------------------------------------------------------------------------------------------------------------------+ |403 |Forbidden. | | |Доступ к запрашиваемому ресурсу закрыт для авторизованного пользователя. | +----+----------------------------------------------------------------------------------------------------------------------------+ |404 |Not Found. | | |Запрашиваемый ресурс не найден на сервере. | +----+----------------------------------------------------------------------------------------------------------------------------+ |405 |Method Not Allowed. | | |Запрошенный метод не допустим для данного ресурса. | +----+----------------------------------------------------------------------------------------------------------------------------+ |406 |Not Acceptable. | | |Согласование типа содержимого не удачно. Проверьте заголовок запроса Content-Type. | +----+----------------------------------------------------------------------------------------------------------------------------+ |500 |Internal Server Error. | | |Внутренняя ошибка на сервере. Обратитесь в службу поддержки. | +----+----------------------------------------------------------------------------------------------------------------------------+ |503 |Service Unavailable. | | |Используется при недоступности сервиса. Свяжитесь со службой поддержки. | +----+----------------------------------------------------------------------------------------------------------------------------+ Подробная информация об ошибке ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ При возникновении проблем при обработке запроса, сервер может включить дополнительную информацию об ошибке в тело ответа. HTTP код при этом будет начинаться с 4 или 5 указывая на наличие ошибки. Наиболее часто этот механизм применяется совместно с кодом 400 Bad request и указывает на проблему с запросом к серверу. Дополнительная информация содержит следующие поля: +----------+--------------------------------------------+ |Имя поля |Описание | +==========+============================================+ |errorCode |Код ошибки (отличается от кода статуса HTTP)| +----------+--------------------------------------------+ |error |Краткое описание ошибки | +----------+--------------------------------------------+ |errorInfo |Подробная информация об ошибке | +----------+--------------------------------------------+ Пример: .. code-block:: json { "errorCode": 1, "error": "Unable to convert JSON. Unknown value.", "errorInfo": "Invalid value 'false1' in field 'orderClosed'" } Идентификатор системного клиента ================================ Системным клиентом в рамках сервиса PowerVHC называется одно предприятие/холдинг имеющее доступ к сервису. Данный объект предназначен для сбора статистики, разграничения полномочий и обеспечения не пересекающегося пространства идентификаторов (заказов, пакетов, клиентов, листов проверок итд) для каждого предприятия. Идентификатор системного клиента является постоянным и используется в пути(URL) ко многим ресурсам. .. _survey-types: Доступные типы листов проверок (survey types) ============================================= В приложении PowerVHC используются следующие типы листов проверок: - ``eVHC`` - прямая приёмка (осмотр машины мастером-консультантом при приёмке АМ) - ``VC`` - осмотр проводимый в рем.зоне с записью видео и согласованием дополнительных работ через интернет (Video Capture) - ``QC`` - контроль качества (Quality Check) - ``VR`` - видеообзор (Video Review) - ``CVR`` - видеообзор для клиента (Customer Video Review) Отсутствующие поля и значение null в JSON ========================================= При передаче данных иногда требуется отличить отсутствия значения от пустой строки или значения 0. Для обозначения отсутствия значения применяются 2 механизма: 1. Отсутствие поля в JSON 2. Наличие поля со значением :code:`null` Оба эти механизма по большей части эквивалентны. Допустимо использование любого из них. При отправке данных сервер PowerVHC не передает поля с не заданными значениями (поля со значением :code:`null` отсутствуют). Например, если объём двигателя у АМ имеет значение :code:`null` или отсутствует, то это поле не будет использоваться для выбора пакетов. Указание другого значения приведет к фильтрации списка доступных пакетов по объёму двигателя. Модули интеграция с ДМС ======================= +-----+------------------+------------------+ ||1cL|| `1С обработчик`_ | `1С инструкция`_ | +-----+------------------+------------------+ .. _RFC 7159: https://tools.ietf.org/html/rfc7159 .. _ISO8601: https://en.wikipedia.org/wiki/ISO_8601 .. _curl: https://curl.haxx.se .. _RFC7231: https://tools.ietf.org/html/rfc7231 .. _`1С обработчик`: https://portal.powervhc.com/assets/integration/1c/1Cv8_ОбменEVHCv2_1.dt .. _`1С инструкция`: https://portal.powervhc.com/assets/integration/1c/eVHC_для_1С_8.X.pdf .. |1cL| image:: _static/1c-logo.png :width: 50pt