# Интеграции

> Кабинеты внешних сервисов организации: кто подключает, как функции получают ключи и кто интеграцией распоряжается.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Интеграция это кабинет внешнего сервиса в организации: Wildberries, Ozon, amoCRM, Яндекс
Метрика, Яндекс Директ, Google Таблицы, Telegram и другие. Человек подключает кабинет один
раз, а [функции](https://docs.getxflow.com/platform/functions.md) проектов получают его ключи через переменные окружения.

## Подключение и ключи

Подключает человек в интерфейсе, пункт «Интеграции» в боковом меню (видят Админы и
Редакторы): вход через браузер (OAuth) или ключ в форме. Заводит, выключает интеграцию и
выдаёт к ней доступ только человек. Агенту доступны привязка к проекту, список, состояние
доступа и разовый вызов API.

- Секретные поля хранятся зашифрованными, после сохранения их не видит никто. Название и
  несекретные поля (например, логин) видят Админы и Редакторы. Значение существует только
  внутри запущенной функции.
- Токены OAuth платформа обновляет сама при выкатке функций, когда до истечения меньше 90 дней.
  За 30 дней до конца интерфейс и `xflow status` предлагают выкатить функции.
- Если доступ отозвал сам сервис (сменили пароль, убрали разрешение), выкатка не поможет:
  кабинет переподключает человек. `xflow status` говорит, какой из двух случаев.

## Привязка к проекту

```bash
xflow connections
xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA
xflow deploy functions
xflow connections unlink YANDEX_METRIKA
```

`xflow connections` показывает привязанные кабинеты (с псевдонимом и состоянием доступа) и
доступные, но не привязанные (`available, not linked`). Интеграцию называют именем из первой
колонки или идентификатором, при одинаковых именах команда попросит выбрать по
идентификатору. Значения доезжают до функций на следующей выкатке. В интерфейсе привязать
можно и на экране проекта.

Пока функции проекта читают переменные интеграции, `unlink` отказывает и называет их, `--yes`
отвязывает всё равно. Выкаченные функции держат значения до своей следующей выкатки.

| Переменная в функции | Что в ней |
|---|---|
| `<ПСЕВДОНИМ>_TOKEN` | токен OAuth |
| `<ПСЕВДОНИМ>_<ПОЛЕ>` | остальные поля, например `YANDEX_DIRECT_CLIENT_LOGIN` |

Читают как обычные переменные: `process.env.YANDEX_METRIKA_TOKEN`. В `xflow env` они только для
чтения: `env set` под таким именем отказывает, `env check` считает их имеющимися. У выключенной
интеграции привязка остаётся, но значения в функции не уезжают. Остальное о переменных:
[Переменные и секреты](https://docs.getxflow.com/platform/secrets.md).

## Разовый вызов API без деплоя

```bash
xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
xflow connections call "Яндекс Метрика" /management/v1/counters
xflow connections call OZON /v1/product/list --method POST --data '{}' --header '{"Client-Id":"{CLIENT_ID}"}'
```

Ключи подставляет платформа и запрос делает сама, агенту ключ не достаётся. Привязанный
кабинет зовут псевдонимом, непривязанный именем из списка.

| Флаг | Что делает |
|---|---|
| `--method` | метод запроса. По умолчанию `GET`, с телом `POST` |
| `--data` | тело запроса, JSON |
| `--header` | заголовки, объект JSON |
| `--json` | весь ответ одним JSON |

- `{ИМЯ}` в пути и заголовках заменяется несекретным полем интеграции. Имена печатает
  `xflow connections` в фигурных скобках, неизвестное имя остаётся как набрано.
- Звать можно только адреса этого сервиса из каталога xflow.
- CLI печатает начало ответа: для формы хватает `limit=1`, весь массив обрабатывает функция.
- Статус чужого API приходит внутри ответа, отдельно от ошибок платформы.
- `POST` и `DELETE` меняют данные в живом кабинете безвозвратно: если метод не только читает,
  агенту стоит спросить человека.
- В Git Bash под Windows путь с ведущим `/` портится оболочкой: пишите полный адрес `https://…`
  или ставьте перед командой `MSYS_NO_PATHCONV=1`.

## Кто видит и кто распоряжается

| Режим при заведении | Кто может пустить кабинет в дело |
|---|---|
| только себе | тот, кто завёл |
| выбранным | тот, кто завёл, и названные люди или группы |
| всей организации | все в организации |

- **Владелец организации** ([Участники и доступ](https://docs.getxflow.com/platform/access.md)) использует любую интеграцию.
- **Привязать** к проекту можно только кабинет, доступный тому, кто привязывает.
- **Привязанный** кабинет видит каждый с доступом к проекту. Его ключи читает всякий, кто
  выкатывает код в этот проект: он пишет код функции.
- **Править, переподключать и удалять** может только тот, кто завёл, и Владелец. Режим «всей
  организации» этого права не даёт.
- **Отвязать** от проекта можно без проверки режима.

Агенту для привязки и вызова непривязанного кабинета нужно право «Пользоваться интеграциями
организации» (включено по умолчанию, выключает человек в разделе «AI агент»). Вызов
привязанного кабинета требует того же права, что и выкатка функций.

Число активных интеграций ограничено [тарифом](https://docs.getxflow.com/platform/billing.md) по всей организации.
Выключенная интеграция место не занимает и не удаляется.