# Вызов коннектора

Любой коннектор — REST или RPC — вызывается через одни и те же три инструмента. Они доступны как нативные инструменты агента и через [MCP-сервер](/docs/mcp). Флоу всегда один: получить каталог, прочитать паспорт сервиса, выполнить вызов.

### list_services — каталог

Возвращает каталог коннекторов: канонический `key` и однострочное summary на каждый сервис. Размером с рукопожатие (~2–5 КБ), поэтому любая сессия может начинаться отсюда. При подключённых аккаунтах каждая позиция помечается `connected: true/false`.

### describe_service — паспорт

Возвращает структурированный **паспорт** одного сервиса: его модули, типовые рецепты (конкретные примеры `VERB /path` с шаблонами тела), лимиты, подсказки по полям и пагинации, enum'ы, примеры ответов и `version`/`ttl` для клиентского кэширования. Вызовите без `module` для индекса, затем с `module` — для полной спецификации модуля.

```bash
describe_service(service="wildberries")
describe_service(service="wildberries", module="statistics")
```

### connector_execute — вызов

Единый исполнитель для любого коннектора. Аргументы валидируются по схеме сервиса **до** любого исходящего HTTP-запроса.

```bash
connector_execute(
  service="wildberries",
  module="statistics",
  method="GET",
  path="/api/v1/supplier/orders",
  query={"dateFrom": "2026-04-15"}
)
```

## Параметры connector_execute

<ParamTable rows={[
  { name: "service", type: "string", required: true, description: "Ключ коннектора из list_services (например wildberries). Может нести суффикс аккаунта — см. адресацию нескольких аккаунтов ниже." },
  { name: "module", type: "string", description: "Подобласть коннектора (statistics, content, …), как указано в паспорте." },
  { name: "method", type: "string", required: true, description: "REST: HTTP-глагол (GET/POST/…). RPC: имя RPC-метода." },
  { name: "path", type: "string", description: "REST: путь запроса. RPC: оставьте пустым, имя метода передайте в method." },
  { name: "body", type: "object", description: "Тело запроса для записывающих вызовов." },
  { name: "query", type: "object", description: "Параметры строки запроса." },
  { name: "instance_id", type: "string", description: "Нацелиться на конкретный подключённый аккаунт, когда их несколько." },
]} />

## REST vs RPC

Коннекторы бывают двух форм, и `connector_execute` обрабатывает обе:

- **REST** (большинство коннекторов) — передайте `module`, HTTP-`method`, `path` и `body`/`query`.
- **RPC** (например `bitrix24`, семейство `onec`) — оставьте `path` пустым, а имя RPC-метода передайте в `method`.

Рецепты в паспорте показывают точную форму для каждого коннектора, так что угадывать почти не приходится.

## Адресация нескольких аккаунтов

Когда у организации подключено больше одного аккаунта для сервиса (несколько кабинетов Ozon, например), адресуйте конкретный. **Голое имя** сервиса распределяет чтения по всем подключённым аккаунтам; **записи должны указывать один** — через `instance_id` или суффикс к сервису:

```bash
connector_execute(service="ozon:Top Zip", method="POST", path="/v1/product/import", body={ ... })
```

## Подсказки did-you-mean

Вызовы не падают молча при почти-попадании. Рецепты — это примеры, а не белый список, поэтому:

- Неизвестный **module** возвращает жёсткую ошибку с подсказками `did_you_mean` и списком `known_modules`.
- Неизвестный или несовпавший **path** всё равно выполняется, но добавляет мягкую подсказку `path_did_you_mean` и меню `available_paths` в метаданных ответа.
- Неизвестный **аккаунт** возвращает `UNKNOWN_INSTANCE` со списком `candidates`.

## Ошибки

Вызовы коннекторов возвращают стандартный контракт ошибки инструмента — `code`, `message`, `retryable` и опциональный `hint`. Вызовы через MCP не несут HTTP-статуса. См. [таблицу ошибок MCP](/docs/mcp) и [Ошибки и лимиты](/docs/reference).