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.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"
    }
}

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

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

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

X-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.1

X-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.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
      }
    ]
  },
  {
    // данные следующего тарифа
  }
]

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

В слушае ошибки возвращает коды 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
}

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

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

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

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

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

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