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

Для получения информации об авторизованном пользователе Центра заказчика Webasyst и выполнения действий с его активами.

Содержание...

Перед выполнением запросов к методам API в серверном или клиентском приложении нужно получить токен авторизации от сервера авторизации 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: строковый идентификатор первичного набора приложений аккаунта из следующего списка:
    • allwebasyst: с приложениями site, shop, crm, blog, mailer, team;
    • allinclusive: с приложениями site, shop, crm, blog, mailer, cash, pocketlists, tasks, status, team, messenger, hub, photos, files, helpdesk, stickies;
    • teamwork: с приложениями pocketlists, status, team, tasks, hub, cash;
    • cashflow: с приложениями cash, team, pocketlists, tasks, status.

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

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

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