Юздеск через API и MCP: почему у поддержки нет спецификации, а токен ошибок не спорит с HTTP-статусом

Обзор

Юздеск — российский хелпдеск: тикеты, чат с клиентами, база знаний, отчётность по агентам. Подключиться к API можно самому — в настройках компании есть готовый api_token API-канала, без заявок и одобрений.

Mira подключает этот API — 27 действий из 47 статей документации — и отдаёт его в Claude через MCP. Ниже — что там есть на самом деле и что расходится с интуицией.

Что доступно

У хелпдеска нет спецификации

В отличие от банков волны финансовых коннекторов — у Модульбанка и Т-Банка есть боевой Swagger, у ЮKassa расписан каждый путь, — Юздеск не публикует ни OpenAPI, ни Swagger вовсе. Документация — обычные текстовые статьи, разложенные по 13 категориям и 47 страницам. Пришлось собрать снимок контракта руками: пройти каждую статью, выписать метод, путь и обязательные поля, сохранить как отдельный JSON-файл и сверять с ним таблицу вызовов тем же тестом, каким сверяются с настоящим Swagger остальные коннекторы. Разница не в строгости проверки — она осталась той же самой, — а в том, откуда взялись исходные данные.

HTTP 200 — это ещё не успех

Самое неочевидное место API. Юздеск не использует HTTP-статус для логических отказов: неверный токен, отсутствующий обязательный параметр, превышенный лимит запросов — всё это приходит с HTTP 200 и телом вида {"code": 112, "error": "invalid token"}. Запрос без единого параметра и запрос с заведомо неверным токеном отвечают ОДИНАКОВО по статусу — отличие видно только внутри тела.

Это переворачивает обычный порядок разбора. У большинства API сначала смотрят на статус (200 — читай тело как данные, 4xx/5xx — читай как отказ), а Юздеску нужен третий шаг: статус 200 у Юздеска ничего не гарантирует, пока не заглянешь в поле code. При этом настоящий отказ инфраструктуры — например, обратный прокси, ответивший 502 без единого байта JSON, — всё ещё остаётся настоящим HTTP-статусом, и его нужно ловить раньше попытки разобрать тело как конверт Юздеска. Разбор идёт в таком порядке: сначала честный HTTP 429/5xx (если он есть), и только потом — код внутри тела.

Комментарий и ответ в чате — разного рода «видно снаружи»

У большинства коннекторов барьер записи делит действия на «просто меняет свои данные» и «ещё и тратит деньги». У Юздеска денег нет вовсе — хелпдеск не банк, — но есть третье измерение: кому видно результат.

Комментарий к тикету можно оставить публичным (уходит клиенту письмом или в канал тикета) или приватным (виден только команде) — одним и тем же действием, разным значением поля type. А вот ответ в чате устроен иначе: у него нет приватного варианта вообще — chat_send_message всегда доставляет сообщение клиенту, единственный способ ответить в чате от лица агента. Барьер записи это не различает — оба действия одинаково требуют разрешения на запись у источника, — но при выборе действия имеет смысл понимать разницу.

Два хоста на 47 статей

Почти весь API живёт на одном адресе — api.usedesk.ru. Ровно один метод (обновление AI-описания статьи базы знаний, нужного для ИИ-поиска) ходит на другой хост, secure.usedesk.ru. Мелочь, которая легко потерялась бы при переносе кода по шаблону «один базовый адрес на всех» — и не потерялась, потому что таблица вызовов хранит хост как явное поле у каждого действия, а не константу модуля.

Что не вошло — и почему

20 из 47 статей документации не стали действиями коннектора, и у каждой группы — своя причина, не общее «не успели»:

• Общая информация (2 статьи) — введение в API и получение api_token: вводные страницы, а не методы, которые можно вызвать.
• Виджет (7 статей) — браузерный JavaScript SDK для установки чата на сайт клиента. Это код, который встраивают тегом <script>, а не HTTP-эндпоинт, который можно вызвать с сервера.
• Webhooks (4 статьи) — Юздеск сам присылает их НАМ при новом тикете или сообщении. Направление входящее: не то, что вызывает агент.
• Правила (4 статьи) — настройка внутри Юздеска, чтобы он сам слал запросы в другую систему по триггеру. Мы не вызываем этот API — максимум могли бы его принимать.
• Дополнительные блоки (1 статья) — тот же класс, что «Правила»: динамический блок — это Юздеск, который сам делает запрос на URL из своих настроек и ждёт HTML в ответ, а не вызов, который делает агент.
• Коды ошибок и справочник статусов (2 статьи) — статичные таблицы в документации, не методы.