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": "Ошибка"    }}

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

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

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

 
POST /partner/api/v1/clients/ HTTP/1.1X-Access-Token: api.clients.registrationContent-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"    }}

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

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

В случае успешного выполнения запроса возвращает код 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"}

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

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

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

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

 
GET /partner/api/v1/clients/<client_uid>/ HTTP/1.1X-Access-Token: api.clients.get

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

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

В случае успешного выполнения запроса возвращает код 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"}

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

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

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

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

 
GET /partner/api/v1/registrations/<link_uid>/status/ HTTP/1.1X-Access-Token: api.registrations.status

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

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

В случае успешного выполнения запроса возвращает код 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" }

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

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

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

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

 
GET /partner/api/v1/rates/ HTTP/1.1X-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      }    ]  },  {    // данные следующего тарифа  }]

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

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

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

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

 
POST /partner/api/v1/subscriptions/ HTTP/1.1X-Access-Token: api.subscriptions.createContent-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}

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

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

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

 
HTTP/1.1 200 OK{    "id":00000}

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

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

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

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

 
PATCH /partner/api/v1/subscriptions/ HTTP/1.1X-Access-Token: api.subscriptions.updateContent-Type: application/json

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

 
{    "client_uid": "550e8400-e29b-41d4-a716-446655440000",    "domain_name": "example.ru",    "rate": "premuim",    "users_count": 100,    "auto_renew": 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.1X-Access-Token: api.clients.registrationContent-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.1X-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.1X-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.1X-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.1X-Access-Token: api.subscriptions.createContent-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.1X-Access-Token: api.subscriptions.updateContent-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.1X-Access-Token: api.subscriptions.updateContent-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.1X-Access-Token: api.subscriptions.updateContent-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.1X-Access-Token: api.subscriptions.updateContent-Type: application/json{  "client_uid": "550e8400-e29b-41d4-a716-446655440000",  "domain_name": "example.com",  "rate": "premium"}

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

 
HTTP/1.1 200 OK{  "id": 000000}