---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.2
  - property: og:type
    content: article
  - property: article:section
    content: Платформа плагинов
  - property: og:title
    content: Работа с API Форм
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/dev/yandex-360/extensions/ru/tools/api/api-forms.md
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/tools/api/api-forms.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/yandex-360/extensions/ru/llms.txt?revision=r22165285


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

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

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

## Пакеты {#packages}

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

## Установка

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

## Базовое использование {#basic-usage}

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

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

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

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

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

### Path-, query- и body-параметры {#request-params}

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

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

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

```typescript
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);
```

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

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

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

{% note info "ID формы из контекста слота" %}

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

```typescript
const surveyId = Number(slotContext?.entityId);

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

В `surveys-list.bulk-action` поле содержит несколько ID через запятую. Формат контекста для всех точек интеграции описан в разделе [Слоты Форм](https://yandex.ru/dev/yandex-360/extensions/ru/tools/slots/slots-forms.md#context).

{% endnote %}

## Разрешения {#permissions}

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

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

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

```json
{
    "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` | Чтение данных текущего пользователя |

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

## Найти поддержанную операцию {#supported-operations}

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

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

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

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

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

## Загрузка файлов {#file-upload}

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

```typescript
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`:

```typescript
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` в соответствии с операцией.

## Ответы и ошибки {#responses-and-errors}

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

```typescript
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`.

```typescript
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);
    }
}
```
