Описание API

Базовые сведения

API представляет собой HTTP REST API с запросами и ответами в формате JSON (кроме загрузки медиафайлов и кроме запросов без тела и ответов без тела).

Путь запроса обычно устроен следующим образом: /<ver>/<entity>/<external_id>/<opts>, где:

• ver - версия вызываемого API, например, v1, (подробности ниже).
• entity - тип сущности, например, contract или creative.
• external_id - внешний идентификатор, выбранный вами для этого объекта.
• opts - опциональные элементы пути, которые могут предоставлять еще какое-либо API (в зависимости от типа сущности).

Сущности создаются и обновляются методом PUT (он идемпотентен) (реже используется POST) и получаются методом GET (реже POST). Удаляются (где поддержано) методом DELETE (реже POST).

API является регистрозависимым. Все параметры, поля и возможные значения должны передаваться как указано в документации, включая регистры.

Если поля или параметры необязательные, не передавайте их или задайте значение null. Для массивов также можно указать пустой массив.

Передача в запросе полей, незнакомых API, не возбраняется, такие поля будут просто проигнорированы.

Используемые MIME types тела запроса и тела ответа:

• application/json (в подавляющем большинстве случаев).
• multipart/form-data (только для загрузки медиаданных).

Адреса для похода в API:

Base URL	Описание
	Тестирование интеграции. Вы можете использовать тестовые данные, которые не передаются в ЕРИР.
https://api.ord.vk.com	Production-интеграция. Используйте только те данные, которые необходимо передать в ЕРИР. Помните, что вы несёте ответственность за передачу недостоверных сведений.

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

Ответ API содержит общепринятые коды ответов HTTP, чтобы указать на успех или ошибку запроса.

Ответ API может содержать тело ответа в формате JSON.

Успешный ответ

Если запрос выполнился успешно, API вернёт код из класса 2xx:

• 200 OK.
• 201 Created.

Пример ответа:

{
  "marker": "LgsiTCSaD"
}

Ошибочный ответ

Если запрос выполнился с ошибкой, API вернёт код из классов 4xx и 5xx:

• 400 Bad Request.
• 401 Unathorized. Подробнее читайте в разделе Авторизация.
• 403 Forbidden.
• 404 Not found.
• 409 Conflict.
• 500 Internal Server Error. Если вы получили эту ошибку, повторите вызов метода позже или обратитесь в техническую поддержку.

Дополнительно API вернёт в теле ответа объект с полем описания ошибки error.

Пример ответа:

{
  "error": "Wrong INN field"
}

Версионирование

Каждый отдельный метод (а не все API разом) снабжается версией вида vN, где N - это какое-то число, например, v1.

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

• Изменение формата запроса.
• Изменение формата или сути ответа.

Версия не изменяется, если:

• В запрос или ответ добавляются новые опциональные поля.
• Изменяются правила валидации значений полей или добавляются какие-то требования, обязательные для всех, и старый вариант нет возможности оставить в старой версии API.

Документация Swagger

Детальная документация по методом находится в Swagger. Методы документации содержат специальные пометки:

• Параметр или поле обязательные, если у его названия находится красная звёздочка.
• Параметр или поле необязательные, если красная звёздочка отсутствует.

Описания параметров или полей могут иметь текст с условиями их применения. Swagger-документация содержит примеры всех параметров и полей: с пометками обязательных и необязательных, а также с условиями в тексте описаний. Если вы хотите выполнить запрос с таким примером, запрос может быть неправильным. Правильные примеры запросов смотрите в разделе API cookbook.

Авторизация

Доступ к API может получить любой зарегистрированный пользователь ОРД.

Для всех запросов к API используются ключи доступа API.

Получение ключа доступа API

Получить ключ доступа API вы можете в личном кабинете ОРД:

• sandbox.ord.vk.com — для dev-окружения (песочницы).
• ord.vk.com — для prod-окружения.

Получение ключа доступа API. Ключ доступа API бессрочен. Вы можете создать максимально 5 ключей доступа API.

Внимание!

Личный кабинет показывает ключ доступа API только один раз. Если ключ доступа API утерян, необходимо создать новый.

Отправка запросов

Чтобы отправить запрос, передайте полученный ключ доступа API в заголовке Authorization: Bearer <TOKEN>.

Внимание!

Вы можете получить ответ от сервера с кодом ошибки 401 Unauthorized, если:

• Не передан ключ доступа API.
• Передан неправильный ключ доступа API.

Использование

Веб-интерфейс

Вы можете использовать API через веб-интерфейс Swagger:

1. В разделе Servers выберите сервер.
2. Нажмите на кнопку Authorize.
3. В диалоговом окне Available authorizations:
   1. В поле Value введите полученный ключ доступа API.
   2. Нажмите на кнопку Authorize.
4. Выберите метод API и нажмите на его название.
5. Нажмите на кнопку Try it out.
6. Введите значения параметров и тела запроса.
7. Нажмите на кнопку Execute.

Программные средства

Вы можете использовать API любыми программными средствами, которые позволяют отправлять HTTPS-запросы.

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

curl -XGET -i -H 'Authorization: Bearer 948d799671533a2eb98e575aa96718e6' https://api-sandbox.ord.vk.com/v1/person/my

Статусы объектов

После успешной загрузки объекта в ОРД он через некоторое время отправляется в ЕРИР, после чего через некоторое время проверяется его статус в ЕРИР. Этот статус можно проверить через API статусов обработки.

Внимание!

Всегда убедитесь, что статус вашего объекта стал через некоторое время (обычно не меньше пары часов) verified.