Принципы работы

Для интеграции облачного сервиса 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.

Внимание

До недавнего времени поддерживалась возможность работы с системой через устаревшие точки доступа: «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 он должен содержать в заголовке поле X-API-KEY со значением ключа доступа к API. Пример авторизации запроса:

  1. CURL

$ 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

  1. Postman (расширение Chrome)

../_images/auth-postman-request.png

Пример запроса.

../_images/auth-postman-response.png

Ответ от сервера.

Обработка ошибок

Коды статуса HTTP

Для возвращения результата запроса используются стандартные коды статуса HTTP (RFC7231). Коды начинающиеся с 2 обозначают успешные операции, с 4 - ошибки клиента, с 5 - ошибки сервера.

Наиболее часто используемые коды статуса HTTP:

Код

Описание

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

Подробная информация об ошибке

Пример:

{
  "errorCode": 1,
  "error": "Unable to convert JSON. Unknown value.",
  "errorInfo": "Invalid value 'false1' in field 'orderClosed'"
}

Идентификатор системного клиента

Системным клиентом в рамках сервиса PowerVHC называется одно предприятие/холдинг имеющее доступ к сервису. Данный объект предназначен для сбора статистики, разграничения полномочий и обеспечения не пересекающегося пространства идентификаторов (заказов, пакетов, клиентов, листов проверок итд) для каждого предприятия. Идентификатор системного клиента является постоянным и используется в пути(URL) ко многим ресурсам.

Доступные типы листов проверок (survey types)

В приложении PowerVHC используются следующие типы листов проверок:

  • eVHC - прямая приёмка (осмотр машины мастером-консультантом при приёмке АМ)

  • VC - осмотр проводимый в рем.зоне с записью видео и согласованием дополнительных работ через интернет (Video Capture)

  • QC - контроль качества (Quality Check)

  • VR - видеообзор (Video Review)

  • CVR - видеообзор для клиента (Customer Video Review)

Отсутствующие поля и значение null в JSON

При передаче данных иногда требуется отличить отсутствия значения от пустой строки или значения 0. Для обозначения отсутствия значения применяются 2 механизма:

  1. Отсутствие поля в JSON

  2. Наличие поля со значением null

Оба эти механизма по большей части эквивалентны. Допустимо использование любого из них. При отправке данных сервер PowerVHC не передает поля с не заданными значениями (поля со значением null отсутствуют). Например, если объём двигателя у АМ имеет значение null или отсутствует, то это поле не будет использоваться для выбора пакетов. Указание другого значения приведет к фильтрации списка доступных пакетов по объёму двигателя.

Модули интеграция с ДМС

1cL

1С обработчик

1С инструкция