Вручай/База знаний

API

API «Вручай»

«Вручай» выпускает именные документы: сертификаты, грамоты, дипломы и благодарности. Вы приносите макет листа и людей — таблицей, по одному или через форму, — сервис возвращает готовые PDF: по одному на человека, с именем в нужном падеже, номером и ссылкой на проверку подлинности.

Подключить ИИ-агента

Claude, ChatGPT, Cursor и другие агенты создают и верстают документы, загружают получателей и выпускают документы сами — через MCP. Подробная инструкция · Готовые промпты · Инструкция для агента

Проще всего — отдать агенту этот текст. Он сам добавит сервер и попросит вас один раз войти в кабинет. Впишите задачу в скобки.

Промпт для агента
Подключи себе сервис «Вручай» по инструкции https://vruchay.ru/docs/connect.md и проверь подключение вызовом get_account.

Задача: [опиши, что нужно: какой документ, для какого мероприятия, кому выдать и как — по таблице, формой на сайте, по ссылке или через API].

Как работать — https://vruchay.ru/docs/AGENTS.md. Перед тем, что тратит квоту или необратимо (выпуск, выдача, рассылка, отзыв, удаление), покажи мне план и дождись согласия.
Или подключите сами. Адрес MCPhttps://vruchay.ru/mcp
  1. Claude.ai или Claude Desktop: Customize → Connectors → Add custom connector.
  2. Название — «Вручай», адрес — https://vruchay.ru/mcp. Если спросит про OAuth client — «Register automatically». Нажмите Add, затем Connect.
  3. Войдите в кабинет «Вручай» и нажмите «Разрешить». В чате: «+» → Connectors → включите «Вручай».
Для агента без MCP:AGENTS.mdllms.txtllms-full.txt
  1. 1 · Токен

    Настройки → Интеграции → Токены API. Показывается один раз.

    export VRUCHAY_TOKEN=vru_…
  2. 2 · Первый запрос

    Проверьте, что токен живой.

    curl -H "Authorization: Bearer $VRUCHAY_TOKEN" \
  https://vruchay.ru/api/auth/me
  3. 3 · Выпуск

    Документ → получатели → задание → архив. По шагам в AGENTS.md.

    POST /api/documents/{id}/generate
GET  /api/jobs/{jobId}

Справочник

Базовый адрес

https://vruchay.ru/api

Все адреса REST приводятся вместе с префиксом /api. Вне префикса лежат три вещи: сервер MCP https://vruchay.ru/mcp, описание входа через OAuth (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server) и проверка живости /health — она токена не требует.

Косая черта в конце адреса ничего не меняет: /api/documents и /api/documents/ — один и тот же маршрут.

Формат обмена

  • Тело запроса и ответа — JSON в UTF-8, заголовок Content-Type: application/json. Исключения: загрузка файлов (multipart/form-data), выгрузки CSV, PDF и ZIP и превью листа — картинка JPEG.
  • Идентификаторы объектов — UUID.
  • Даты — строки ISO 8601 в UTC, например 2026-09-03T10:15:00.000Z.
  • Размеры и координаты на листе — в миллиметрах, кегль — в пунктах.
  • Тексты сообщений об ошибках — русские: они написаны для человека, который будет читать их в интерфейсе или в журнале.
  • Предел размера тела запроса — 1 МБ. Исключения: подтверждение импорта получателей (16 МБ) и запросы к /mcp (2 МБ).

Что API не делает

Честнее сказать сразу, чем заставлять искать:

  • Нет вебхуков о выпуске. О завершении задания узнают опросом GET /api/jobs/{jobId}; инструмент MCP get_job умеет ждать сам до минуты, а выдача одного документа ждёт готовности прямо в запросе. Входящие адреса платёжного сервиса (POST /api/v1/payments/yookassa) и банка (POST /api/v1/payments/tochka) — наши служебные: они отмечают оплату, начатую человеком в кабинете, и вызывать их самим незачем.
  • Нет вечных ссылок на архив. Архив по адресу задания отдаётся только с заголовком Authorization. Ссылку, которую можно открыть в браузере, выдаёт POST /api/jobs/{jobId}/archive-link — она живёт час. Получателю его документ доступен по своей ссылке 30 дней.
  • Нет пакетного эндпоинта. Строки получателей добавляются по одной либо целиком через импорт таблицы. Отдельного «создать сто строк одним запросом» нет.
  • Нет постраничной навигации по курсору. Списки отдаются целиком либо с ограничением, указанным на странице конкретного эндпоинта.
  • Нет действий за человека. Приглашения, роли, пароли, токены, разрешение доступа агенту и оплата — только в кабинете. Такие запросы отвечают 403.
Вручай