API платформы VK WorkSpace (SaaS) для партнеров

Назначение документа

Документ содержит описание программного интерфейса к SaaS-версии платформы VK WorkSpace (далее — партнерский API). С помощью API приложение партнера VK WorkSpace может автоматизированно:

• создавать запросы на регистрацию клиентов;
• управлять подписками клиентов на тарифы.

Документ предназначен для разработчиков партнеров VK WorkSpace.

Общая информация

Авторизация

Авторизация выполняется при помощи токена. При отправке запросов токен передается в HTTP‑заголовке X-Access-Token.

Формат запроса

Запросы к API передаются по протоколу HTTP. Формат запроса:

<метод> /partner/api/v1/<ресурс> HTTP/1.1

<параметры>

где:

• <метод> ― HTTP‑метод;
• <ресурс> ― идентификатор (URI) ресурса;
• <параметры> ― параметры запроса, которые не входят в URI ресурса.

Данные передаются в формате JSON.

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

Если запрос выполнен успешно, API возвращает в ответе коды 200 (OK) и необходимые данные. Ответы возвращаются в формате JSON.

Ошибки

Если запрос не выполнен, API возвращает в ответе коды 400 и 403. Формат ответа с кодом ошибки:

{
    "error": {
        "code": 0000,
        "message": "Ошибка"
    }
}

Код	Возможные причины
400 Bad Request	Сервер не может обработать запрос: - У вас нет прав на указанный домен - Домен уже зарегистрирован ранее - Указаны неправильные данные (неправильный адрес электронной почты, некорретный ИНН и т.п.) - Произошла техническая ошибка
403 Forbidden	Проблемы с авторизацией, доступом к данным: - Указан невалидный токен авторизации - Отправитель запроса не является действущим партнером VK WorkSpace

Список и описание запросов

• Регистрация клиента и домена
• Получение информации по клиенту
• Получение статуса заявки на регистрацию
• Получение списка тарифов
• Создание подписки на тариф
• Изменение подписки на тариф

Регистрация клиента и домена

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

Входные данные:

POST /partner/api/v1/clients/ HTTP/1.1

X-Access-Token: api.clients.registration
Content-Type: application/json

Параметры запроса с примерами значений:

{
    "email": "client@mail.ru",
    "subpartner": "local_partner",
    "domain_name": "example.ru",
    "partner_client_id": "client-000000",
    "fio": "Иванов Иван Иванович",
    "phone": "79998887755",
    "company": {
        "is_resident": false,
        "inn": "123456789",
        "ogrn": "32165645987651321314",
        "kpp": "55566622",
        "country": "РФ",
        "name": "СтройСервис",
        "registration_number": "321654",
        "zip_code": 630023,
        "address": "Москва ул.Ленина д.5",
        "address_legal": "Москва ул.Ленина д.6",
        "city": "Москва",
        "street": "Ленина",
        "house": "5"
    }
}

Описание параметров:

Параметр	Тип	Обязательный	Описание
email	string	да	Адрес электронной почты клиента, для которого регистрируется домен
subpartner	string		Ваш партнер или подрядчик, обслуживающий клиента (если применимо)
domain_name	string		Имя домена
partner_client_id	string		Идентификатор клиента в вашей системе
fio	string		ФИО клиента
phone	string		Номер телефона клиента
company	object		Данные компании клиента
is_resident	bool	да, если указан company	Налоговый резидент РФ. Возможные значения: true, false
inn	string	да, если указан company	ИНН
country	string	да, если указан company	Страна
name	string	да, если указан company	Наименование организации
ogrn	string	да, если указан company	ОГРН или ОГРНИП
kpp	string	да, если указан company	КПП
address	string		Фактический адрес
address_legal	string		Юридический адрес
zip_code	string		Почтовый индекс
city	string		Город
street	string		Улица
house	string		Дом

Выходные данные:

В случае успешного выполнения запроса возвращает код 200 и данные:

HTTP/1.1 200 OK

{
    "client_uid": "550e8400-e29b-41d4-a716-446655440000",
    "link": "https://link-to-register-client",
    "valid_until": "2024-12-31T23:59:59Z",
    "link_uid": "abc123-456def-789ghi"
}

Описание параметров:

Параметр	Тип	Описание
client_uid	string	Идентификатор вашего клиента, присвоенный системой VK WorkSpace
link	string	Ссылка на прохождение регистрации, в которой зашиты параметры: - uid — уникальный код ссылки; - email — адрес почты клиента, если был передан в запросе; - domain_name — имя домена, если было передан в запросе. Ссылка имеет ограниченный период действия.
valid_until	string	Срок окончания действия ссылки
link_uid	string	Идентификатор ссылки на регистрацию

В слушае ошибки возвращает коды 400, 403.

Получение информации по клиенту

Возвращает информацию по клиенту.

Входные данные:

GET /partner/api/v1/clients/<client_uid>/ HTTP/1.1

X-Access-Token: api.clients.get

Описание параметров:

Path-парметр	Тип	Обязательный	Описание
<client_uid>	int	да	Идентификатор клиента в системе VK WorkSpace, предоставляется в ответе на запрос на регистрацию клиента

Выходные данные:

В случае успешного выполнения запроса возвращает код 200 и данные:

HTTP/1.1 200 OK

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "partner_client_id": "partner-00000",
  "domain_name": "example.com",
  "status": "active",
  "phone": "+7934567890",
  "email": "client@example.com"
}

Описание параметров:

Параметр	Тип	Описание
client_uid	string	Идентификатор клиента в системе VK WorkSpace
partner_client_id	string	Идентификатор клиента в вашей системе
domain_name	string	Имя домена. Возвращается, если домен был передан в запросе на регистрацию либо по созданной ссылке выполнилось создание домена
status	string	Статус (актуальность) ссылки на регистрацию клиента, возможные значения: active (активна), inactive (неактивна)
phone	string	Номер телефона клиента
email	string	Адрес почты клиента

В слушае ошибки возвращает коды 400, 403.

Получение статуса регистрации

Возвращает статус по процессу регистрации клиента и домена.

Входные данные:

GET /partner/api/v1/registrations/<link_uid>/status/ HTTP/1.1

X-Access-Token: api.registrations.status

Описание параметров:

Path-парметр	Тип	Обязательный	Описание
<link_uid>	int	да	Идентификатор ссылки на регистрацию, предоставляется в ответе на запрос на регистрацию клиента

Выходные данные:

В случае успешного выполнения запроса возвращает код 200 и данные:

HTTP/1.1 200 OK

{
    "client_uid": "550e8400-e29b-41d4-a716-446655440000",
    "domain_name": "example.ru",
    "valid_until": "2024-12-31T23:59:59Z",
    "status": "0" 
}

Описание параметров:

Параметр	Тип	Описание
client_uid	string	Идентификатор клиента в VK WorkSpace
domain_name	string	Имя домена. Возвращается, если домен был передан в запросе на регистрацию либо по созданной ссылке выполнилось создание домена
valid_until	string	Срок окончания действия ссылки на регистрацию
status	int	Статус заявки

В слушае ошибки возвращает коды 400, 403.

Получение списка тарифов

Возвращает список тарифов с информацией по ним.

Входные данные:

GET /partner/api/v1/rates/ HTTP/1.1

X-Access-Token: api.rates.get

Выходные данные:

В случае успешного выполнения запроса возвращает код 200 и данные:

HTTP/1.1 200 OK

[
  {
    "uid": "basic-0000",
    "name": "Basic Plan",
    "service_slug": "basic_service",
    "rate_type": "monthly",
    "period": "1 month",
    "users_max": 100,
    "price": "10000.00",
    "options": [
      {
        "option_slug": "priority_support",
        "price": "20000.00",
        "option_limit": null,
        "is_default": true,
        "is_fix": true
      }
    ]
  },
  {
    // данные следующего тарифа
  }
]

Описание параметров:

Параметр	Тип	Описание
uid	string	Идентификатор тарифа
name	string	Название тарифа
service_slug	string
rate_type	sring	Тип подписки (помесячная, годовая)
period	string	Период оплаты подписки на тариф
users_max	int	Максимальное количество пользователей на тарифе
price	int	Стоимость подписки на тариф
options	object	Опции, которые могут быть подключены в рамках тарифа
option_slug	string	Идентификатор опции
price	string	Стоимость опции
option_limit	int	Ограничения по опции
is_default	bool	Условия подключения опции: - true — опция подключается автоматически, не требует действий; - false — для подключения опции требуется выполнить действия
is_fix	bool	Стоимость опции: - фиксированная (не зависит от количества пользователей в подписке) — значение true; - указана за одного пользователя — значение false

В слушае ошибки возвращает коды 400, 403.

Создание подписки на тариф

Создает подписку на тариф и возвращает идентификатор созданной подписки.

Входные данные:

POST /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.create
Content-Type: application/json

Параметры запроса:

{
    "client_uid": "550e8400-e29b-41d4-a716-446655440000",
    "domain_name": "example.ru",
    "order_id": "ORD123456",
    "deal_number": "DEAL78910",
    "rate": "premium",
    "users_count": 100,
    "auto_renew": true
}

Описание параметров:

Параметр	Тип	Обязательный	Описание
client_uid	int	да	Идентификатор клиента в VK WorkSpace
domain_name	string	да	Имя домена
order_id	string		Идентификатор заявки в вашей системе (если применимо)
deal_number	string		Идентификатор сделки в вашей системе (если применимо)
rate	string	да	Название / идентификатор тарифа, который можно узнать с помощью запроса GET /partner/api/v1/rates (Получение списка тарифов); см. uid в rates
users_count	int	да	Количество пользователей на тарифе
auto_renew	bool	да	Автопродление подписки, возможные значения: true (включить), false (не включать)

Выходные данные:

В случае успешного выполнения запроса возвращается код 200 с указанием идентификатора подписки:

HTTP/1.1 200 OK

{
    "id":00000
}

В слушае ошибки возвращает коды 400, 403.

Изменение подписки на тариф

Изменяет подписку на тариф:

• включает или отключает автопродление подписки;
• изменяет количество пользователей (лицензий) на тарифе;
• изменяет тариф.

Входные данные:

PATCH /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.update
Content-Type: application/json

Параметры запроса:

{
    "client_uid": "550e8400-e29b-41d4-a716-446655440000",
    "domain_name": "example.ru",
    "rate": "premuim",
    "users_count": 100,
    "auto_renew": false
}

Описание параметров:

Параметр	Тип	Обязательный	Описание
client_uid	int	да	Идентификатор клиента в VK WorkSpace
domain_name	string	да	Имя домена
deal_number	string	да	Идентификатор сделки
rate	string		Название (идентификатор) нового тарифа, если нужно изменить тариф
users_count	int		Новое количество пользователей на тарифе, если нужно изменить количество лицензий
auto_renew	bool		Включение (true) или отключение (false) автопродления подписки

Выходные данные:

В случае успешного выполнения запроса возвращает код 200 ОК с указанием идентификатора подписки:

HTTP/1.1 200 OK

{
  "id": 0000000
}

В слушае ошибки возвращает коды 400, 403.

Сценарии использования

Зарегистрировать нового клиента и домен и активировать подписку на тариф

Выполняем последовательно запросы и действия:

1. Регистрируем клиента POST /partner/api/v1/clients/, получаем ссылку и выполняем регистрацию.
2. Узнаем статус регистрации GET /partner/api/v1/registrations/<id>/status/, чтобы убедиться, что регистрация прошла успешно (либо можно запросить информацию по клиенту GET /partner/api/v1/clients/<id>/).
3. Запрашиваем список тарифов GET /partner/api/v1/rates/.
4. Создаем подписку на тариф POST /partner/api/v1/subscriptions/.

1. Пример запроса на регистрацию клиента:

POST /partner/api/v1/clients/ HTTP/1.1

X-Access-Token: api.clients.registration
Content-Type: application/json

{
    "email": "hinkali@hinkali.ru",
    "subpartner": "MyPartner",
    "domain_name": "hinkali.ru",
    "fio": "Ivanov Ivan Ivanovich",
    "phone": "+793456789",
    "company": 
      {
        "is_resident": true,
        "inn": "1234567890",
        "country": "Russia",
        "name": "ООО Хинкалёнок",
        "registration_number": "987654321",
        "zip_code": 123456,
        "city": "Москва",
        "street": "Тверская",
        "house": "10"
      }
}

В случае успешной регистрации будет возвращен ответ 200 ОК с указанием ссылки на регистрацию:

HTTP/1.1 200 OK

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://example.com/registration/12345",
  "valid_until": "2024-12-31T23:59:59Z",
  "link_uid": "abc123-456def-789ghi"
}

2а. Пример запроса статуса регистрации:

GET /partner/api/v1/registrations/abc123-456def-789ghi/status/ HTTP/1.1

X-Access-Token: api.registrations.status

В случае успешного выполнения запроса будет возвращен ответ 200 ОК с информацией по клиенту:

HTTP/1.1 200 OK

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "hinkali.ru",
  "valid_until": "2024-12-31T23:59:59Z",
  "status": "0" 
}

2б. Пример запроса информации по клиенту:

GET /partner/api/v1/clients/550e8400-e29b-41d4-a716-446655440000/ HTTP/1.1

X-Access-Token: api.clients.get

В случае успешного выполнения запроса будет возвращен ответ 200 ОК с информацией по клиенту:

HTTP/1.1 200 OK

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "partner_client_id": "MyPartner",
  "domain_name": "hinkali.ru",
  "status": "active",
  "phone": "+7934567890",
  "email": "hinkali@hinkali.ru"
}

3. Пример запроса на получение списка тарифов:

GET /partner/api/v1/rates/ HTTP/1.1

X-Access-Token: api.rates.get

В случае успешного выполнения запроса будет возвращен ответ 200 ОК с информацией по тарифам:

HTTP/1.1 200 OK

[
  {
    "uid": "basic-00000",
    "name": "Basic Plan",
    "service_slug": "basic_service",
    "rate_type": "monthly",
    "period": "1 month",
    "users_max": 100,
    "price": "10000.00",
    "options": [
      {
        "option_slug": "priority_support",
        "price": "20000.00",
        "option_limit": null,
        "is_default": true,
        "is_fix": true
      }
    ]
  }
]

4. Пример запроса на создание подписки:

POST /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.create
Content-Type: application/json

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "example.com",
  "order_id": "ORD123456",
  "deal_number": "DEAL78910",
  "rate": "premium",
  "users_count": 50,
  "auto_renew": true
}

В случае успешного выполнения запроса будет возвращен ответ 200 ОК с идентификатором подписки:

HTTP/1.1 200 OK

{
  "id": 000000
}

Выключить автопродление подписки и прекратить списание оплаты по ней

Чтобы выключить автопродление конкретной подписки и прекратить списание оплаты по ней, выполняем запрос Изменение подписки на тариф и указываем параметр auto_renew со значением false:

PATCH /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.update
Content-Type: application/json

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "example.com",
  "auto_renew": false
}

В случае успешноого выключения автопродления будет возвращен ответ 200 ОК с идентификатором подписки:

HTTP/1.1 200 OK

{
  "id": 000000
}

Возобновить автопродление подписки

Чтобы возобновить автопродление подписки, выполняем запрос Изменение подписки на тариф и указываем параметр auto_renew со значением true:

PATCH /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.update
Content-Type: application/json

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "example.com",
  "auto_renew": true
}

В случае успешного выполнения запроса будет возвращен ответ 200 OK с указанием идентификатора подписки:

HTTP/1.1 200 OK

{
  "id": 000000
}

Изменить количество пользователей (лицензий) на тарифе

Чтобы изменить количество лицензий, выполняем запрос Изменение подписки на тариф и указываем новое количество лицензий в параметре users_count:

PATCH /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.update
Content-Type: application/json

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "example.com",
  "users_count": 25
}

В случае успешного изменения количества лицензий будет возвращен ответ 200 ОК с указанием идентификатора подписки:

HTTP/1.1 200 OK

{
  "id": 000000
}

Изменить тарифный план клиента

Чтобы изменить тариф для адаптации подписки под запросы клиента, выполняем запрос Изменение подписки на тариф и указываем новый тариф rate:

PATCH /partner/api/v1/subscriptions/ HTTP/1.1

X-Access-Token: api.subscriptions.update
Content-Type: application/json

{
  "client_uid": "550e8400-e29b-41d4-a716-446655440000",
  "domain_name": "example.com",
  "rate": "premium"
}

В случае успешного изменения тарифа будет возвращен ответ 200 ОК с указанием идентификатора подписки:

HTTP/1.1 200 OK

{
  "id": 000000
}