---
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-external.md
  - href: https://yandex.ru/dev/yandex-360/extensions/ru/tools/api/api-external.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

Плагин работает в iframe с политикой безопасности контента (Content Security Policy, CSP). Чтобы обратиться к внешнему домену, объявите его в манифесте и выберите канал доступа:

- `proxy` — плагин вызывает `hostApi.externalApiCall()`, а платформа отправляет запрос со своего бэкенда;
- `direct` — плагин отправляет запрос напрямую из браузера с помощью `fetch` или `XMLHttpRequest`. Этот способ не рекомендуется для запросов, требующих авторизации.

Для одного домена можно разрешить оба канала.

## Разрешение в манифесте {#manifest}

Добавьте в `manifest.json` секцию `permissions.external` с перечнем разрешенных доменов и каналов доступа:

```json
{
    "permissions": {
        "external": [
            {
                "domain": "api.example.com",
                "access": ["proxy"],
                "authorization": {
                    "type": "oauth",
                    "scopes": ["read", "write"],
                    "contextTypes": ["user"]
                }
            },
            {
                "domain": "api-direct.example.com",
                "access": ["direct"]
            },
            {
                "domain": "api-both.example.com",
                "access": ["direct", "proxy"]
            }
        ]
    }
}
```

В поле `domain` укажите hostname строчными буквами, без протокола, пути и порта. Для доменов с национальными символами используйте Punycode. Wildcard-домены не поддерживаются.

Обязательное поле `access` — непустой массив без повторов. Используйте одно или оба значения:

- `direct` добавляет `https://<domain>` в директиву `connect-src` политики CSP;
- `proxy` разрешает обращаться к домену через `hostApi.externalApiCall()`.

Поле `authorization` опционально и допустимо только для домена с каналом `proxy`: токен подставляет бэкенд платформы, в iframe он не передается.

## Прямые запросы {#direct-access}

{% note warning "Используйте прямой доступ, только если уверены в условиях" %}

Выбирайте `direct` только для запросов без авторизации или если вы уверены, что у пользователя уже установлены необходимые cookie и браузер сможет передать их внешнему сервису. Для запросов с cookie укажите `credentials: "include"`, а на стороне внешнего сервиса разрешите CORS-запросы с источника плагина и передачу учетных данных. Учитывайте, что браузер может заблокировать сторонние cookie.

Платформа только добавляет домен в директиву `connect-src`: она не авторизует пользователя, не подставляет cookie или токены и не настраивает CORS. Если эти условия нельзя гарантировать, используйте канал `proxy`.

{% endnote %}

Для домена с `access: ["direct"]` или `access: ["direct", "proxy"]` можно использовать браузерные сетевые API:

```tsx
const response = await fetch("https://api-direct.example.com/data.json");
const data = await response.json();
```

Внешний сервис должен поддерживать [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) для источника (origin) плагина. Точное значение источника можно посмотреть в заголовке `Origin` исходящего запроса в инструментах разработчика браузера. Платформа не участвует в прямом запросе: не подставляет токен, не применяет аудит и rate limit прокси.

Канал `direct` расширяет только директиву `connect-src` и не изменяет `img-src`, `script-src`, `style-src` и другие директивы CSP.

Домен с `access: ["proxy"]` не добавляется в `connect-src`, поэтому прямой запрос к нему будет заблокирован CSP.

## CSP, зависящая от разрешений {#scope-csp}

Некоторые разрешения на работу с данными требуют прямых запросов к техническим доменам сервиса. Для таких разрешений платформа автоматически добавляет связанные источники в CSP. Перечислять эти домены в `permissions.external` не нужно: набором управляет сервис, и он может различаться между контурами.

Если для разрешения настроены дополнительные источники, его объявление расширяет CSP, но само по себе не дает доступ к данным. Права пользователя и проверка токена продолжают действовать.

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

**Типичный сценарий** — проверить авторизацию, при необходимости запросить ее у пользователя, затем вызвать API:

```tsx
import {
    hostApi,
    PluginActionError,
} from "@weavix/tracker-plugin-sdk-react";

async function fetchItems() {
    // Проверить авторизацию и показать диалог, если нужно
    const { success } = await hostApi.externalApiAuthCheckAndRequest({
        domains: ["api.example.com"],
        contextType: "user",
    });
    if (!success) {
        // Пользователь закрыл диалог или истек таймаут
        return;
    }

    // Вызвать внешний API через прокси хоста
    const { status, body } = await hostApi.externalApiCall({
        url: "https://api.example.com/v1/items",
        method: "GET",
        contextType: "user",
    });
    // status — HTTP-статус ответа
    // body   — тело ответа (Record<string, unknown>)
}
```

**POST с телом и таймаутом:**

```tsx
const { status, body } = await hostApi.externalApiCall({
    url: "https://api.example.com/v1/items",
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: { name: "New item", value: 42 },
    contextType: "organization",
    timeoutMs: 10000,
});
```

## Обработка ошибок прокси {#errors}

При сетевой ошибке прокси или ответе с ошибочным статусом хост бросает `PluginActionError` с кодом `EXTERNAL_API_CALL_ERROR` (`1013`). Детали — в `e.errorData`:

```tsx
import { EXTERNAL_API_CALL_ERROR } from '@weavix/sdk-core';

try {
    await hostApi.externalApiCall({
        url: "https://api.example.com/data",
        method: "GET",
    });
} catch (e) {
    if (e instanceof PluginActionError && e.code === EXTERNAL_API_CALL_ERROR) {
        console.error("Proxy error:", e.errorData);
    }
}
```

Ошибки прямых запросов обрабатывайте средствами выбранного браузерного API. Например, для `fetch` отдельно проверяйте сетевые ошибки и HTTP-статус ответа.

## Управление авторизацией прокси {#auth}

**Быстрый путь** — `externalApiAuthCheckAndRequest` проверяет авторизацию и при необходимости показывает диалог в одном вызове, см. пример выше.

**Ручное управление.** Если нужен более тонкий контроль — используйте отдельные методы:

```tsx
// Проверить статус по доменам
const { domains } = await hostApi.externalApiAuthGetStatus({
    domains: ["api.example.com"],
    contextType: "user",
});
const isAuthed = domains.every((d) => d.authenticated);

// Показать диалог авторизации с подсказкой
if (!isAuthed) {
    await hostApi.externalApiAuthRequest({
        domains: [
            {
                domain: "api.example.com",
                instructions: {
                    ru: "Войдите в Example",
                    en: "Sign in to Example",
                },
            },
        ],
    });
}

// Отозвать сохраненные учетные данные
await hostApi.externalApiAuthRevoke({
    domains: ["api.example.com"],
    contextType: "user",
});
```

Подробнее о методах — в разделе [hostApi.externalApi\*](https://yandex.ru/dev/yandex-360/extensions/ru/tools/sdk-core.md#externalApi).
