Работа с API Форм

Плагин может работать с формами, вопросами, ответами, интеграциями и другими сущностями Форм через типизированный объект formsApi. Запрос отправляется из iframe по bridge-методу api.forms.call, а HTTP-вызов выполняет хост Форм. Прямой запрос к защищенному API из iframe не используется.

Доступ к каждой операции одновременно зависит от разрешений в манифесте и прав текущего пользователя.

Пакеты

Пакет Назначение
@weavix/tracker-api-plugin Типизированный клиент для плагинов
@weavix/tracker-api-types Сгенерированные из OpenAPI типы операций, параметров и ответов; runtime-кода нет

Установка

npm install @weavix/forms-api-plugin @weavix/forms-api-types

Если плагин создан через CLI, пакет @weavix/sdk-react и общий bridge уже подключены шаблоном.

Базовое использование

Импортируйте formsApi:

import {formsApi} from '@weavix/forms-api-plugin';

Версия API выбирается через namespace .v1. В ключе метода не нужно повторять серверный префикс /public/v1:

const {data: survey, headers} =
    await formsApi.v1.get['/surveys/{survey_id}/']({
        pathParams: {survey_id: 42},
    });

Пути операций Форм оканчиваются символом /. Выбирайте путь из автодополнения, чтобы сохранить точную сигнатуру операции.

Path-, query- и body-параметры

Параметры запроса передаются в одном объекте:

  • pathParams — значения плейсхолдеров в пути;
  • queryParams — параметры query string;
  • bodyParams — JSON-тело запроса;
  • image — изображение типа File для загрузки в форму;
  • file — файл типа File для вложения в интеграцию.

Пример списка доступных форм с пагинацией и поиском:

const {data} = await formsApi.v1.get['/surveys/']({
    queryParams: {
        limit: 20,
        offset: 0,
        orderby: '-modified',
        name: 'Опрос',
    },
});

const surveys = data.result;
const hasNextPage = Boolean(data.links.next);

Пример создания вопроса:

const {data: question} =
    await formsApi.v1.post['/surveys/{survey_id}/questions/']({
        pathParams: {survey_id: 42},
        bodyParams: {
            type: 'string',
            label: 'Как вас зовут?',
        },
    });

TypeScript выводит обязательность и типы параметров из установленного пакета @weavix/forms-api-types.

ID формы из контекста слота

В слотах survey.tab, survey.action и surveys-list.item-action значение slotContext.entityId приходит строкой. Проверьте его и преобразуйте в число перед передачей во внутренний API Форм:

const surveyId = Number(slotContext?.entityId);

if (!Number.isSafeInteger(surveyId) || surveyId <= 0) {
    throw new Error('Некорректный ID формы');
}

В surveys-list.bulk-action поле содержит несколько ID через запятую. Формат контекста для всех точек интеграции описан в разделе Слоты Форм.

Разрешения

Разрешения на данные имеют формат forms:<домен>:read|write. Домен — первый сегмент пути API:

  • для GET требуется действие read;
  • для POST, PUT, PATCH и DELETE требуется действие write.

Например, для чтения и изменения форм:

{
    "permissions": {
        "data": [
            "forms:surveys:read",
            "forms:surveys:write"
        ]
    }
}

Поддерживаемые разрешения Форм:

Разрешение Назначение
forms:answers:read Чтение ответа и запущенных для него интеграций
forms:files:read Скачивание файлов
forms:files:write Удаление файлов
forms:surveys:read Чтение форм, вопросов, доступов, ответов, интеграций и связанных данных
forms:surveys:write Создание и изменение форм, вопросов, условий, доступов, интеграций и связанных данных
forms:operations:read Чтение результата асинхронной операции
forms:notifications:read Чтение событий интеграций и их статусов
forms:notifications:write Перезапуск и отмена событий интеграций
forms:users:read Чтение данных текущего пользователя

Запрашивайте только те разрешения, которые нужны сценарию плагина.

Найти поддержанную операцию

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

formsApi.v1.get
formsApi.v1.post
formsApi.v1.put
formsApi.v1.patch
formsApi.v1.delete

Основные домены API:

  • /surveys — формы, вопросы, условия, доступы, ответы, наборы ключей и интеграции;
  • /answers — отдельные ответы и запущенные для них интеграции;
  • /files — скачивание и удаление файлов;
  • /operations — результаты асинхронных операций;
  • /notifications — события интеграций и их статусы;
  • /users — текущий пользователь.

Наличие операции в TypeScript-типах означает, что клиент умеет сформировать запрос. Успех вызова также зависит от версии хоста, разрешений и прав пользователя.

Загрузка файлов

Для загрузки изображения в форму передайте File в поле image:

const image = new File(['image'], 'image.png', {type: 'image/png'});

const {data} = await formsApi.v1.post['/surveys/{survey_id}/images/']({
    pathParams: {survey_id: 42},
    image,
});

Для загрузки вложения в интеграцию используйте поле file:

await formsApi.v1.post[
    '/surveys/{survey_id}/hooks/{hook_id}/subscriptions/{subscription_id}/attachment/'
]({
    pathParams: {
        survey_id: 42,
        hook_id: 7,
        subscription_id: 3,
    },
    file: new File(['report'], 'report.txt'),
});

Для этих двух multipart-операций нельзя одновременно передавать bodyParams. Хост сам создает FormData и использует имя поля image или file в соответствии с операцией.

Ответы и ошибки

Успешный вызов возвращает:

type ApiResponse<T> = {
    data: T;
    headers: Record<string, string>;
};

Бинарный ответ возвращается как ArrayBuffer.

Ошибки приходят как PluginActionError:

  • VALIDATION_ERROR — некорректны версия, метод, путь, параметры, тело или multipart-поле;
  • MISSING_REQUIRED_SCOPE — в манифесте нет необходимого разрешения;
  • числовой HTTP-статус — API Форм вернул non-2xx ответ; детали находятся в errorData;
  • UNKNOWN_ERROR — сетевая ошибка или ошибка чтения/разбора ответа;
  • METHOD_NOT_SUPPORTED — хост не зарегистрировал api.forms.call.
import {
    MISSING_REQUIRED_SCOPE,
    PluginActionError,
    VALIDATION_ERROR,
} from '"@weavix/sdk-core';

try {
    await formsApi.v1.get['/surveys/{survey_id}/']({
        pathParams: {survey_id: 42},
    });
} catch (error) {
    if (error instanceof PluginActionError) {
        console.error(error.code, error.message, error.errorData);
    }
}
Предыдущая
Следующая