Вызов по ключу

Ключ агента вызывает подключённые сервисы организации без агента: по REST на https://api.samreshuuu.ru/v1 или через MCP-сервер. Двери различаются транспортом, а не смыслом: каталог, паспорт и вызов принимают одни аргументы и отказывают одними кодами с одними details, у REST к ним добавляется HTTP-статус. Агент в приложении зовёт те же операции своими инструментами по другим правилам, они собраны в разделе Агент в приложении.

ШагRESTMCPПраво ключа
КаталогGET /v1/connectorslist_servicestools:read
Паспорт сервисаGET /v1/connectors/{service}, модуль в ?module=describe_servicetools:read
Подключённые кабинетыGET /v1/connectionsнетtools:read
ВызовPOST /v1/connectors/{service}/executeconnector_executetools:read, запись tools:write
Статус согласияGET /v1/connectors/approvals/{approval_id}нетtools:read

Первый вызов

Сначала узнайте, какие кабинеты видит ключ. Ответ data перечисляет {service, connection, label} по кабинетам, открытым всей организации; connection это готовый адрес для service:

bash
curl https://api.samreshuuu.ru/v1/connections \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY"

Затем вызовите сервис. Тело вызова это аргументы connector_execute без service: method, path, module, body, query. Ответ и отказы те же, что у MCP:

bash
curl https://api.samreshuuu.ru/v1/connectors/moysklad/execute \ -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"GET","path":"/api/remap/1.2/report/stock/all","query":{"limit":100}}'

Каталог и паспорт

Каталог отдаёт services: [{name, summary, transport}] без признака подключённости: имя в каталоге значит «сервис существует», а не «подключён». Подключённые кабинеты называет GET /v1/connections.

Паспорт одного сервиса без module это индекс: модули, call_template, critical_hints и заголовки рецептов. С module паспорт отдаёт методы модуля, шаблоны запросов, лимиты, пагинацию и примеры ответов. Неизвестный модуль возвращает индекс и _module_filter_warning со списком допустимых. Переиспользуйте полный паспорт при совпадении сервиса, модуля, версии содержимого и области доступа; version обозначает версию схемы ответа. Аргументы вызова проверяются по схеме сервиса до любого исходящего запроса.

Параметры вызова

FieldTypeDescription
servicerequiredstringКлюч коннектора из каталога (например moysklad). Кабинет называется суффиксом в этой же строке (`ozon:2`), отдельного поля для него нет; см. «Кабинеты» ниже. В REST это часть пути, а не поле тела.
modulestringREST: обычно не нужен, модуль выводится из path; укажите, только если пути нет среди рецептов. RPC: обязателен (пространство методов, например crm).
methodrequiredstringREST: HTTP-глагол (GET/POST/…). RPC: имя метода (crm.deal.list). Глагол и путь всегда в разных полях.
pathstringREST: путь с подставленными значениями (/api/v3/stocks/12); адрес объекта из ответа (meta.href) принимается как есть. RPC: пустая строка.
bodyobject | arrayТело POST/PUT/PATCH или именованные аргументы RPC-метода.
queryobjectПараметры строки запроса; массивы сериализуются автоматически.

REST и RPC

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

  • REST (большинство коннекторов): HTTP-method, path и body/query; module выводится из пути.
  • RPC (например bitrix24): module (пространство методов, например crm), имя метода в method (crm.deal.list), аргументы в body, path пустой.

Точную форму показывают call_template и рецепты паспорта. HTTP-глагол с путём у RPC-сервиса отклоняется с TOOL_VALIDATION_FAILED и меню available_recipes.

Кабинеты

Ключ видит только кабинеты, открытые всей организации; личные кабинеты того, кто выпустил ключ, ему недоступны. Когда у сервиса один такой кабинет, голое имя сервиса адресует его. Когда подключено несколько, голое имя по ключу не читает их все: вызов отказывает с UNKNOWN_INSTANCE и списком details.candidates (connection, label). Тот же код со списком приходит, если названного кабинета нет или его метка стоит у нескольких. Возьмите connection из candidates или из GET /v1/connections и передайте в service целиком: в REST это путь /v1/connectors/ozon:2/execute, в MCP аргумент service:

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

Какой из случаев произошёл, называет details.connector_code (INSTANCE_AMBIGUOUS или INSTANCE_NOT_FOUND); ветвитесь по code.

Сервис не подключён

Ключ не подключает сервисы: пароли и токены кабинетов через API не передаются. Если нужного кабинета нет или его вход истёк, вызов отказывает, а details несут ссылку для человека connect_url и причину auth_reason:

auth_reasonКодЧто случилосьЧто делает человек
missing_linkINTEGRATION_REQUIREDКабинета, открытого организации, нетПодключает кабинет и открывает его организации
not_sharedINTEGRATION_REQUIREDКабинет есть у того, кто выпустил ключ, но он личныйОткрывает этот кабинет организации
reauthentication_requiredAUTH_RECONNECT_REQUIREDВход в кабинет истёкПодключает кабинет заново
json
{ "code": "INTEGRATION_REQUIRED", "message": "…", "retryable": false, "details": { "connect_url": "https://samreshuuu.ru/connectors?connect=moysklad&mode=connect&org=5b2e9d7a-1c4f-4e8b-a6d3-7f0c2b9e4a18", "auth_reason": "missing_link" } }

Отдайте connect_url человеку из организации. Ссылка ведёт в приложение и токена не несёт: страница сама попросит войти. Параметр org называет организацию ключа, поэтому человек из нескольких организаций подключит кабинет туда, где работает ключ. После его действия повторите тот же вызов; повтор до этого получит тот же отказ.

Согласие на запись

Запись, которую режим доверия организации без человека не пропускает, по ключу не выполняется сразу. Вызов отказывает 409 с кодом APPROVAL_PENDING, а карточка согласия с этим вызовом встаёт в основном чате того, кто выпустил ключ, в приложении Сам Решу. Одобряет человек в приложении, а не ваш клиент, поэтому у заявки есть ручка статуса. Чтение согласия не спрашивает.

details отказа:

ПолеЧто значит
approval_idid заявки
approval_statuspending, пока человек не ответил
approval_status_pathпуть ручки статуса, /v1/connectors/approvals/{approval_id}
approval_expires_atдо какого момента заявка ждёт ответа и повтора

GET /v1/connectors/approvals/{approval_id} отвечает объектом заявки: id, status, created_at, expires_at (у ждущей и одобренной заявки) и decided_at (после ответа человека). status принимает значения pending, approved, rejected, expired, executed. Ручка видит только заявки своего ключа: чужой и неизвестный id отвечают 404 с кодом DATA_NOT_FOUND.

  1. Получив APPROVAL_PENDING, опрашивайте ручку статуса с паузой. Повтор того же вызова, пока заявка ждёт, отвечает той же заявкой без второй карточки.
  2. Когда status стал approved, повторите тот же вызов с теми же аргументами: одобрение исполнит его один раз, и status станет executed. Вызов с другими аргументами поднимет новую карточку. Одобряется этот вызов, а не правило для ключа.
  3. Заявка ждёт ответа и повтора сутки, срок называет approval_expires_at. Потом она снимается (expired), и повтор спросит заново.

Отказы, после которых повторять вслепую нельзя:

  • TOOL_USER_DECLINED (403): человек отклонил вызов. До конца срока заявки тот же вызов отказывает так же. Не повторяйте его и не обходите другим вызовом.
  • APPROVAL_RETIRED (409): одобрение уже использовано или снято, details.reason называет причину. При claim_lost одобренный вызов мог уже выполниться: проверьте состояние в сервисе, прежде чем решать, повторять ли.
  • APPROVAL_QUEUE_PENDING (409): у человека уже ждут ответа другие одобрения; повторите после них.
  • APPROVAL_NO_APPROVER (409): карточку показать не удалось, вызов не выполнен.

Тариф, лимит и журнал

Вызовы по ключу работают, пока у организации действует тариф, и отдельно не оплачиваются; без тарифа запрос получает 402 с кодом SUBSCRIPTION_REQUIRED. Каждый REST-запрос и каждый connector_execute через MCP тратят минутный лимит ключа, превышение отвечает 429 с кодом RATE_LIMIT_EXCEEDED и паузой в Retry-After и в details.retry_after_s. Таблица лимитов описана в разделе Ошибки и лимиты API агентов.

Журнал вызовов коннекторов по ключу (ключ, сервис, действие, кабинет, исход, длительность) показывает консоль разработчика.

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

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

  • Неизвестный service возвращает отказ с похожими ключами в details.suggestions.
  • Неизвестный module возвращает TOOL_VALIDATION_FAILED со списками known_modules и suggestions, и то же даёт пропущенный там, где он нужен (RPC), с тем же списком. У REST-вызова модуль выводится из пути, и неверная метка вызов не ломает.
  • Path, которого нет среди рецептов, всё равно выполняется, а в метаданные ответа (и в ошибку, например 404) ложится меню available_paths. Глагол, которого нет у рецептов этого пути, не отказывает и подсказки не добавляет: какие глаголы принимает путь, решает таблица глаголов коннектора, а где она не закрыта, отвечает сам сервис.
  • Неизвестный или неназванный кабинет возвращает UNKNOWN_INSTANCE со списком candidates, см. Кабинеты.

Ошибки

Через MCP отказ приходит результатом с isError: true и объектом {code, message, retryable, hint?, details?}, по REST тем же кодом в объекте ошибки с HTTP-статусом. Ветвитесь по code; details несут данные отказа (кандидаты, подсказки, ссылку), а не инструкции. Кроме случаев выше, стоит различать:

  • Нет прав у кабинета на путь (403). AUTH_SCOPE_MISSING: ключу или токену кабинета не хватает прав, их можно выдать новым подключением. AUTH_SCOPE_NOT_GRANTABLE: права приложения фиксированы, повтор не поможет. details.required_scopes называют права, которых не хватило.
  • Автопроверка запретила запись. TOOL_AUTO_REVIEW_BLOCKED: секрет уходит не тому сервису, который его выдал; согласие этот запрет не снимает.
  • Метод снят вендором. Если Wildberries или Ozon сами объявили метод выключенным (заголовок Sunset с прошедшей датой или «this method is deprecated» в теле), подсказка велит больше не звать этот путь и искать преемника в describe_service.

Агент в приложении

Агент в чате и задаче зовёт те же три шага своими инструментами list_services, describe_service и connector_execute, но правила у него свои:

  • list_services агента отдаёт items (подключённые сервисы с кабинетами и статусом на момент as_of) и available (имена всего каталога).
  • Голое имя сервиса у агента распределяет чтения по всем подключённым кабинетам, кроме сервисов, где свод по кабинетам не складывается (например onec и moysklad); запись называет один кабинет. Вызов по ключу так не делает и отказывает со списком candidates.
  • У connector_execute агента есть параметр files: файлы для загрузки по имени поля вендора (id вложения или артефакта, путь в песочнице), кодирует их платформа.
  • В песочнице агента cw.connect() читает страницы, фильтрует их и считает итог в одной ячейке Python; в повторяющемся сценарии агент зовёт готовую функцию навыка.
  • Нет кабинета или его вход истёк: ход встаёт на паузу с карточкой подключения и продолжается, когда кабинет подключат.

Какие коннекторы и кабинеты выданы агенту, описано в разделе Агенты.

Была ли страница полезна?