Работа с 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);
}
}