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

Для интеграции облачного сервиса eVHC используется программный интерфейс на основе протокола HTTPS. Клиентом (стороной инициирующей соединение) во всех случаях является DMS. Данные передаются в формате JSON (RFC 7159) в кодировке UTF-8. Все даты передаются в формате ISO8601. Поля в объектах могут следовать в произвольном порядке.

Процесс интеграции eVHC с дилерской системой управления предприятием может быть ускорен благодаря готовым интеграционным решениям, представленным в разделе Модули интеграция с ДМС.

Актуальная информация

Последнюю версию документации по API всегда можно получить по ссылке: https://docs.powervhc.com

Адрес для доступа к API (API endpoint)

Все запросы к eVHC API начинаются с «https://api.powervhc.com/v1/». Используется стандартный для HTTPS порт 443.

Безопасность

Для доступа к 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'"
}

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

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

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

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

  • eVHC - прямая приёмка (осмотр машины мастером-консультантом при приёмке АМ)
  • VC - осмотр проводимый в рем.зоне с записью видео и согласованием дополнительных работ через интернет (Video Capture)
  • QC - контроль качества (Quality Check)

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

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

  1. Отсутствие поля в JSON
  2. Наличие поля со значением null

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

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

1cL 1С обработчик 1С инструкция