Методы API сервера ресурсов Webasyst

Перед выполнением запросов к методам API в серверном или клиентском приложении нужно получить токен авторизации от сервера авторизации Webasyst.

Методы

• Получение личных данных пользователя
• Редактирование личных данных пользователя
• Загрузка новой фотографии в профиль пользователя
• Удаление фотографии из профиля пользователя
• Получение списка аккаунтов Webasyst, в которых пользователь активировал вход в бекенд с использованием Webasyst ID
• Получение списка лицензий, которыми владеет пользователь
• Создание аккаунта в облаке Webasyst
• Добавление собственного технического поддомена аккаунта в облаке Webasyst
• Активирование лицензии продукта для указанного аккаунта Webasyst
• Получение кода для объединения профилей
• Получение информации о результатах объединения профилей
• Аннулирование выданных ранее разрешений для выполнения запросов о пользователе

Получение личных данных пользователя

HTTP-запросы

• GET: https://www.webasyst.com/id/api/v1/profile/

Необходимые разрешения

• profile

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

{
    "name":"Имя Отчество Фамилия",
    "firstname":"Имя",
    "lastname":"Фамилия",
    "middlename":"Отчество",
    "userpic":"https://{абсолютный URL загруженного изображения пользователя размером 96х96 пикселей}",
    "userpic_original_crop":"https://{абсолютный URL загруженного изображения пользователя исходного размера}",
    "userpic_uploaded":{true или false},    //есть ли у пользователя загруженное изображение
    "email":[    //массив email-адресов
        {
            "value":"name@domain.ru",               //email-адрес
            "ext":"work",                           //необязательное обозначение типа адреса
            "status":{"confirmed" или "unknown"}    //статус адреса
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ],
    "phone":[    //массив номеров телефона
        {
            "value":"79001234567",               //номер телефона
            "ext":"work",                           //необязательное обозначение типа номера
            "status":{"confirmed" или "unknown"}    //статус номера
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ]
}

Редактирование личных данных пользователя

HTTP-запросы

• POST/PUT/PATCH: https://www.webasyst.com/id/api/v1/profile/

Запросы POST и PUT выполняются одинаково и приводят к полной перезаписи всех данных профиля. Если какие-то из перечисленных выше данных не будут переданы в запросе, то вместо них в профиль будут сохранены пустые строки.

При отправке запросов методом PATCH в профиле обновляются только переданные поля, а отсутствующие в теле запроса поля остаются без изменений.

Необходимые разрешения

• profile:write

Формат данных (JSON)

{
    "firstname": "...", // имя
    "lastname": "...", // фамилия
    "middlename": "...", // отчество
    "email": ["...", "..."], // email-адреса
    "phone": ["...","..."] // номера телефона
}

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

В случае успешной обработки запроса сервер ресурсов отдаёт ответ с кодом 200 и тем же форматом, который используется при отправке GET-запросов на этот URL.

Получение списка аккаунтов Webasyst, в которых пользователь активировал вход в бекенд с использованием Webasyst ID

HTTP-запросы

• GET: https://www.webasyst.com/id/api/v1/installations/

Необходимые разрешения

• profile

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

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

[
    {
        //основные поля
        "id":"{client_id аккаунта Webasyst}",
        "domain":"{доменное имя аккаунта}",
        "url":"{абсолютный URL аккаунта}",

        //дополнительные поля, доступные только в облаке Webasyst:
        "cloud_plan_id":"...", //идентификатор тарифа
        "cloud_expire_date":"...", //дата истечения оплаченного срока аккаунта
        "cloud_trial":"...", //является ли аккаунт бесплатным — если ещё не был оплачен
        "cloud_name":"...", //техническое имя аккаунта — передаётся только владельцу аккаунта
        "cloud_data":{...} //необязательные дополнительные данные аккаунта
    },
    {
        ...
    }
]

Загрузка новой фотографии в профиль пользователя

HTTP-запросы

• POST: https://www.webasyst.com/id/api/v1/profile/userpic/

Необходимые разрешения

• profile:write

Формат данных

В теле запроса нужно передать бинарные данные загружаемого файла фотографии. Допустимые форматы изображений, для которых нужно указать обозначение формата в заголовке Content-type:

• JPEG (обозначение формата: image/jpeg);
• PNG (обозначение формата: image/png).

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

В случае успешной загрузки сервер ресурсов отдаёт ответ с кодом 201 и следующим форматом данных:

{
    "userpic": "....", //URL уменьшенного эскиза загруженной фотографии размером 96х96 пикселей
    "userpic_original_crop": "...." //URL оригинальной обрезанной версии загруженной фотографии
}

Удаление фотографии из профиля пользователя

HTTP-запросы

• DELETE: https://www.webasyst.com/id/api/v1/profile/userpic/

Необходимые разрешения

• profile:write

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

В случае успешного удаления фотографии сервер ресурсов отдаёт пустой ответ с кодом 204.

Получение списка лицензий, которыми владеет пользователь

HTTP-запросы

• GET: https://www.webasyst.com/id/api/v1/licenses/

Необходимые разрешения

• license:read

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

[
    {
        "license_id":"{идентификатор лицензии}",
        "slug":"{строковый идентификатор программного продукта}",
        "product_id":"{числовой идентификатор программного продукта}",
        "order_id":"{номер заказа покупки лицензии}",
        "app_id":"{строковый идентификатор приложения, к которому относится программный продукт}",
        "ext_id":"{дополнительный идентификатор плагина, темы дизайна или виджета}",
        "type":"{тип программного продукта:  APP, PLUGIN, THEME или WIDGET}",
        "name":"{название программного продукт}",
        "expire_date":{дата истечения аренды продукта, если он используется на условиях аренды},
        "bound_to":"{доменное имя аккаунта Webasyst, к которому прикреплена лицензия}",
        "bind_available_date":{дата, когда лицензию можно будет прикрепить к другому аккаунту, если эта возможность в данный момент заблокирована}
    },
    ...
 ]

Создание аккаунта в облаке Webasyst

Созданный аккаунт начнёт работать на пробном тарифе с ограниченным бесплатным периодом.

HTTP-запросы

• POST: https://www.webasyst.com/id/api/v1/cloud/signup/

Необходимые разрешения

• Не требуются.

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

JSON или обычный form-data.

Параметры

• bundle (необязательно): идентификатор набора приложений, которые будут изначально доступны в аккаунте:
  • allinclusive (применяется по умолчанию): стандартный набор включает в себя приложения site (Сайт), shop (Shop-Script), crm (CRM), blog (Блог), mailer (Рассылки), cash (Деньги), pocketlists (Pocket Lists), tasks (Задачи), status (Удаленка), team (Команда), hub (Хаб), photos (Фото), files (Файлы), helpdesk (Поддержка);
  • [ваш набор] (пока в тестовом режиме): обратитесь в службу поддержки Webasyst, чтобы получить идентификатор собственного набора, включающего в себя разработанные вами приложения.
• userdomain (необязательно): указанное пользователем начало домена аккаунта, заканчивающегося на .webasyst.cloud. Если значение не указано, то оно будет сформировано автоматически.
• account_name (необязательно): указанное пользователем название компании, которое может использоваться в настройках аккаунта и отображаться на страницах сайта.

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

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

{
    "id":"...", // client_id аккаунта Webasyst
    "domain":"...", // домен аккаунта
    "url":"...", // полный URL аккаунта
    "auth_endpoint": "...", // одноразовый URL для входа в бекенд без авторизации
    "cloud_plan_id":"...", // идентификатор тарифа
    "cloud_expire_date":"2030-01-01", // дата истечения срока действия аккаунта
    "cloud_trial":true, // является ли аккаунт пробным, т. е. ещё не оплачивался
    "cloud_name":"w123456-7890" // техническое название аккаунта
}

При попытке создать второй аккаунт для этого же пользователя сервер ресурсов возвращает ответ следующего формата с кодом 409:

{
    "error":"already_exists", // флаг, обозначающий, что у пользователя уже есть бесплатный аккаунт
    "error_description":"…" // текстовое сообщение об ошибке
}

Добавление собственного технического поддомена аккаунта в облаке Webasyst

Метод добавляет дополнительный поддомен вида хххххх.webasyst.cloud, по которому должен быть доступен данный аккаунт в дополнение к его стандартному техническому адресу.

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

Метод доступен только владельцу аккаунта. Доступность этого метода можно определить по наличию поля cloud_name в данных аккаунта, полученных при выполнении метода получения списка аккаунтов Webasyst, в которых пользователь активировал вход в бекенд с использованием Webasyst ID.

HTTP-запросы

• POST: https://www.webasyst.com/id/api/v1/cloud/rename/

Необходимые разрешения

• Не требуются.

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

JSON или обычный form-data.

Параметры

• client_id: client_id аккаунта;
• domain: название собственного поддомена до символа точки в адресе аккаунта вида хххххх.webasyst.cloud.

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

В случае успешного добавления поддомена сервер ресурсов возвращает пустой ответ с кодом 204.

Активирование лицензии продукта для указанного аккаунта Webasyst

Метод доступен только в том случае, когда разработчик клиентского приложения совпадает с разработчиком программного продукта Webasyst.

HTTP-запросы

• POST: https://www.webasyst.com/id/api/v1/licenses/force/

Необходимые разрешения

• Не требуются.

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

JSON или обычный form-data.

Параметры

• client_id: client_id аккаунта Webasyst,
• slug: полный строковый идентификатор программного продукта.

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

• Если в указанном аккаунте уже активирован указанный продукт, то сервер ресурсов возвращает пустой ответ с кодом 204.
• Если продукт в указанном аккаунте не активирован, то сервер ресурсов активирует для этого аккаунта первую попавшуюся неактивированную лицензию указанного продукта и возвращает пустой ответ с кодом 204.
• Если свободной — неактивированной — у разработчика нет лицензии, то сервер ресурсов создаёт временную пробную лицензию, активирует её для указанного аккаунта и возвращает пустой ответ с кодом 204. Срок действия такой лицензии — 1 месяц.

В случае ошибки сервер ресурсов отдаёт сообщение ошибки в следующем формате:

{
    "error": "...", //числовой код ошибки
    "error_description": "...", //текстовое сообщение об ошибке
}

Возможные коды ответа сервера при возникновении ошибок:

• 400: передан существующий client_id, который не является client_id аккаунта Webasyst, а является client_id другого ресурса, например, сайта или мобильного приложения;
• 403: причина ошибки указывается в поле "error" тела ответа:
  • product_not_allowed: разработчик клиентского приложения не является разработчиком программного продукта Webasyst;
  • invalid_token_client: запрос отправляется не из клиентского приложения.
• 404: причина ошибки указывается в поле "error" тела ответа:
  • installation_not_found: указан несуществующий client_id;
  • product_not_found: продукт с указанным идентификатором slug не существует.

Получение кода для объединения профилей

HTTP-запросы

• GET: https://www.webasyst.com/id/api/v1/profile/mergecode/

Необходимые разрешения

• Не требуются.

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

Сервер возвращает ответ следующего формата с кодом 200:

{
    "code":"...", // код для объединения профилей
    "expires":... // метка времени UNIX, соответствующая моменту, до которого допускается завершить объединение профилей
}

Формат ответа в случае ошибки:

• 409 (пустое тело ответа): контакт недоступен для объединения — для объединения доступны только профили пользователей, созданные не более 1 суток назад.

Получение информации о результатах объединения профилей

HTTP-запросы

• GET: https://www.webasyst.com/id/api/v1/profile/mergeresult/

Необходимые разрешения

• Не требуются.

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

Сервер возвращает ответ следующего формата с кодом 200:

• Если объединение выполнено успешно

  {
      "status":"success",
      "description":"..." // текстовое сообщение
  }

• Если объединение не выполнялось:

  {
      "status":"not_attempted",
      "description":"..." // текстовое сообщение
  }

{
    "code":"...", // код для объединения профилей
    "expires":... // метка времени UNIX, соответствующая моменту, до которого допускается завершить объединение профилей
}

Формат ответа в случае ошибки:

• 409 (пустое тело ответа): контакт недоступен для объединения — для объединения доступны только профили пользователей, созданные не более 1 суток назад.

Аннулирование выданных ранее разрешений для выполнения запросов о пользователе

HTTP-запросы

• DELETE: https://www.webasyst.com/id/api/v1/delete/

Необходимые разрешения

• Не требуются.

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

{
    "delete":true
}