# Вручай — API массового выпуска именных документов

> Сервис принимает таблицу участников и макет листа, а возвращает готовые
> документы: по одному PDF или JPEG на человека, с подстановкой имени,
> склонением по падежам, номером и ссылкой на проверку подлинности.
> Почти всё, что делает кабинет, доступно по токену API — кроме действий только для человека: сотрудники, пароль и вход, токены, оплата картой.

Агенту начинать отсюда: https://vruchay.ru/docs/AGENTS.md — порядок работы, сценарии и подводные камни.
Готовые способы выдачи — прежде чем писать свой код: форма на сайте (Тильда, WordPress, Битрикс, закрытые страницы личного кабинета), форма по ссылке, выдача по API из CRM и LMS, рассылка писем. Свой сервер между сайтом и «Вручай» не нужен: https://vruchay.ru/docs/integrations.md
Подключиться к MCP самому: https://vruchay.ru/docs/connect.md — команда для твоего клиента, вход через OAuth без токена.
MCP-сервер: https://vruchay.ru/mcp (вход через OAuth или Authorization: Bearer vru_…). Все клиенты: https://vruchay.ru/docs/mcp.md
REST API: https://vruchay.ru/api, заголовок Authorization: Bearer vru_… . Вёрстка листа: https://vruchay.ru/docs/layout-guide.md
Каждая ссылка ниже — markdown-файл страницы. Полная выжимка одним файлом (большая): https://vruchay.ru/llms-full.txt

## Начало работы

- [API сервиса «Вручай»](https://vruchay.ru/docs/README.md): «Вручай» выпускает именные документы: сертификаты, грамоты, дипломы и благодарности.
- [AGENTS.md — «Вручай» для ИИ-агента](https://vruchay.ru/docs/AGENTS.md): Для агента, которому человек поручил работу с «Вручай»: как устроена предметная область, в каком порядке действовать и обо что спотыкаются.
- [Готовые тексты для агента](https://vruchay.ru/docs/agent-prompt.md): Скопируйте подходящий текст, вставьте своему агенту — Claude, ChatGPT, Claude Code, Cursor или любому другому — и замените то, что в квадратных скобках.
- [Подключись к «Вручай» сам](https://vruchay.ru/docs/connect.md): Инструкция для ИИ-агента, которому человек написал «подключи Вручай».
- [Подключение агента по MCP](https://vruchay.ru/docs/mcp.md): На сайте «Вручай» работает сервер MCP (Model Context Protocol).
- [Как свёрстать лист: руководство для агента](https://vruchay.ru/docs/layout-guide.md): Это руководство для программы, которая верстает сертификат, грамоту или диплом сама, без человека у экрана: где стоит каждый блок, каким шрифтом и кеглем он набран, как подставляются ФИО и падежи и как до выпуска убедиться, что всё влезло.
- [Способы выдачи](https://vruchay.ru/docs/integrations.md): Свёрстанный документ попадает к людям одним из четырёх путей: пакетом по списку, через форму по ссылке, через форму на сайте организации или по одному через API.
- [Сценарии целиком](https://vruchay.ru/docs/recipes.md): Шесть типовых задач от начала до конца: какие инструменты MCP вызывать, в каком порядке и с какими аргументами, и то же самое запросами REST.
- [Аутентификация](https://vruchay.ru/docs/authentication.md): API опознаёт вызывающего по заголовку
- [Ограничения частоты](https://vruchay.ru/docs/rate-limits.md): Лимит стоит не на всём API, а точечно — на маршрутах, где он действительно нужен: вход, публичные формы, страница проверки подлинности, тяжёлая проверка таблицы, письма наружу.
- [Ошибки](https://vruchay.ru/docs/errors.md): Ошибка — это всегда JSON.

## Эндпоинты: analytics

- [GET /api/analytics/summary — Сводка за период](https://vruchay.ru/docs/endpoints/analytics/get-analytics-summary.md): Сводка за период одним запросом — экран «Аналитика» в кабинете: выпуск и проверки по QR по дням, сравнение с прошлым таким же периодом, письма, состояние выданных документов и разбивка по материалам.
- [GET /api/analytics — Показатели организации за всё время](https://vruchay.ru/docs/endpoints/analytics/get-analytics.md): Цифры организации за всё время — те, с которыми идут на продление: сколько документов выдано и разослано, сколько раз их проверяли по QR, насколько чисто проходят пакеты выпуска, какие шаги работы с сервисом уже пройдены, плюс итоги текущего и прошлого календарного месяца.
- [POST /api/analytics/digest/preview — Прислать себе месячную сводку](https://vruchay.ru/docs/endpoints/analytics/post-analytics-digest-preview.md): Отправляет на свою почту месячную сводку — то самое письмо, что первого числа в 9:00 по Москве уходит владельцам организации, если за прошлый месяц у неё что-то происходило.

## Эндпоинты: audit

- [GET /api/audit/facets — Значения для отбора журнала](https://vruchay.ru/docs/endpoints/audit/get-audit-facets.md): Чем можно отобрать журнал действий: виды действий и авторы, которые в журнале организации встречаются.
- [GET /api/audit — Журнал действий](https://vruchay.ru/docs/endpoints/audit/get-audit.md): Журнал действий организации, новые сверху, страницами.

## Эндпоинты: auth

- [GET /api/auth/me — Кто я](https://vruchay.ru/docs/endpoints/auth/get-auth-me.md): Возвращает, от чьего имени выполняются запросы: имя, роль в организации и признак, что это организация самого сервиса.

## Эндпоинты: awards

- [DELETE /api/award-rules/{id} — Удалить набор правил](https://vruchay.ru/docs/endpoints/awards/delete-award-rules-id.md): Убирает набор из списка.
- [GET /api/award-rules/{id} — Набор правил целиком](https://vruchay.ru/docs/endpoints/awards/get-award-rules-id.md): Набор правил со всеми правилами, условиями и выходами — то, что показывает конструктор и применяет движок раскладки.
- [GET /api/award-rules/templates — Документы, годные в шаблоны правил](https://vruchay.ru/docs/endpoints/awards/get-award-rules-templates.md): Список документов организации, из которых выбирают шаблон для выхода правила (outputs[].templateDocumentId).
- [GET /api/award-rules — Список наборов правил награждения](https://vruchay.ru/docs/endpoints/awards/get-award-rules.md): Наборы правил награждения организации.
- [PATCH /api/award-rules/{id} — Изменить набор правил](https://vruchay.ru/docs/endpoints/awards/patch-award-rules-id.md): Меняет набор правил.
- [POST /api/award-rules/{id}/duplicate — Скопировать набор правил](https://vruchay.ru/docs/endpoints/awards/post-award-rules-id-duplicate.md): Делает копию набора — «взять как на прошлом мероприятии и поправить».
- [POST /api/award-rules — Создать набор правил награждения](https://vruchay.ru/docs/endpoints/awards/post-award-rules.md): Заводит набор правил награждения у организации.
- [POST /api/documents/{id}/awards/preview — Раскладка награждения — что выйдет, если выпустить сейчас](https://vruchay.ru/docs/endpoints/awards/post-documents-id-awards-preview.md): Прогоняет правила по таблице получателей документа и возвращает раскладку: кому какой шаблон полагается, сколько документов выйдет после дедупликации и какие строки остались без документа и почему.
- [POST /api/documents/{id}/awards/rule-set — Привязать набор правил к мероприятию](https://vruchay.ru/docs/endpoints/awards/post-documents-id-awards-rule-set.md): Выбирает, по какому набору правил награждается это мероприятие.
- [POST /api/documents/{id}/awards/suggest — Заготовка правил по колонкам таблицы](https://vruchay.ru/docs/endpoints/awards/post-documents-id-awards-suggest.md): Собирает черновик набора правил по колонкам уже загруженной таблицы получателей.

## Эндпоинты: billing

- [GET /api/billing/card-payments/{id} — Состояние оплаты картой](https://vruchay.ru/docs/endpoints/billing/get-billing-card-payments-id.md): Состояние платежа, созданного POST /api/billing/checkout.
- [GET /api/billing/card — Подключена ли оплата картой](https://vruchay.ru/docs/endpoints/billing/get-billing-card.md): Отвечает, можно ли сейчас оплатить документы картой.
- [GET /api/org/billing — Реквизиты плательщика](https://vruchay.ru/docs/endpoints/billing/get-org-billing.md): Реквизиты, по которым организации выставляют счета и закрывающие документы.
- [GET /api/org/invoices/available — Можно ли получить счёт по тарифу](https://vruchay.ru/docs/endpoints/billing/get-org-invoices-available.md): Отвечает, выставляет ли сервис сейчас счета по тарифу — POST /api/org/invoices.
- [GET /api/org/invoices/{id}/pdf — Счёт в PDF](https://vruchay.ru/docs/endpoints/billing/get-org-invoices-id-pdf.md): Отдаёт счёт своей организации в PDF — байтами прямо в ответе, а не ссылкой.
- [GET /api/org/invoices — Счета организации](https://vruchay.ru/docs/endpoints/billing/get-org-invoices.md): Счета, выставленные своей организации, новые первыми, не больше 100.
- [PATCH /api/org/billing — Изменить реквизиты плательщика](https://vruchay.ru/docs/endpoints/billing/patch-org-billing.md): Сохраняет реквизиты, по которым организации выставляют счета.
- [POST /api/billing/checkout — Оплатить документы картой](https://vruchay.ru/docs/endpoints/billing/post-billing-checkout.md): Создаёт платёж в ЮKassa и возвращает ссылку, по которой человек оплачивает покупку картой.
- [POST /api/org/invoices — Получить счёт по тарифу](https://vruchay.ru/docs/endpoints/billing/post-org-invoices.md): Выставляет своей организации счёт на оплату по тарифу из каталога — без разговора и без ожидания.

## Эндпоинты: documents

- [DELETE /api/documents/{id}/purge — Удалить документ из корзины навсегда](https://vruchay.ru/docs/endpoints/documents/delete-documents-id-purge.md): Окончательное удаление документа, который уже лежит в корзине.
- [DELETE /api/documents/{id}/sheets/{sheetId}/background — Убрать фон листа](https://vruchay.ru/docs/endpoints/documents/delete-documents-id-sheets-sheetId-background.md): Убирает фон листа: backgroundFileId становится null, лист печатается белым, блоки остаются на месте.
- [DELETE /api/documents/{id}/sheets/{sheetId} — Удалить лист](https://vruchay.ru/docs/endpoints/documents/delete-documents-id-sheets-sheetId.md): Удаляет лист документа и перенумеровывает оставшиеся (position без дыр).
- [DELETE /api/documents/{id} — Отправить документ в корзину](https://vruchay.ru/docs/endpoints/documents/delete-documents-id.md): Мягкое удаление: документ помечается deletedAt и пропадает из списка, но остаётся в корзине (GET /api/documents?trashed=true).
- [GET /api/documents/files/{fileId}/raw — Файл по постоянному адресу](https://vruchay.ru/docs/endpoints/documents/get-documents-files-fileId-raw.md): Постоянный адрес файла организации — для <img src> и всего, что хранит ссылку дольше пятнадцати минут.
- [GET /api/documents/files/{fileId}/url — Подписанная ссылка на файл](https://vruchay.ru/docs/endpoints/documents/get-documents-files-fileId-url.md): Возвращает временную подписанную ссылку на файл организации в хранилище — в первую очередь на фон листа (backgroundFileId), чтобы показать его в превью.
- [GET /api/documents/{id}/registry.csv — Реестр выданных документов в CSV](https://vruchay.ru/docs/endpoints/documents/get-documents-id-registry-csv.md): Тот же реестр, что GET /api/documents/{id}/registry, но таблицей под русский Excel: разделитель — точка с запятой, кодировка UTF-8 с меткой порядка байтов, строки разделены \r\n, каждая ячейка в кавычках.
- [GET /api/documents/{id}/registry — Реестр выданных документов](https://vruchay.ru/docs/endpoints/documents/get-documents-id-registry.md): Реестр выдач по документу: по одной строке на каждого получателя, у которого есть выпущенный файл (lastFileId), в порядке строк таблицы.
- [GET /api/documents/{id} — Карточка документа](https://vruchay.ru/docs/endpoints/documents/get-documents-id.md): Документ целиком с листами (и их макетами) в порядке position.
- [GET /api/documents — Список документов организации](https://vruchay.ru/docs/endpoints/documents/get-documents.md): Библиотека материалов организации: страница списка с итоговым числом.
- [PATCH /api/documents/{id}/sheets/{sheetId} — Сохранить макет листа](https://vruchay.ru/docs/endpoints/documents/patch-documents-id-sheets-sheetId.md): Заменяет макет листа целиком: в layout передаётся весь массив элементов, а не разница.
- [PATCH /api/documents/{id} — Изменить свойства документа](https://vruchay.ru/docs/endpoints/documents/patch-documents-id.md): Частичное обновление карточки: название, размер листа, настройки проверки подлинности, мероприятие, дата выдачи, срок действия, раздел.
- [POST /api/documents/{id}/assets/from-url — Картинка для блока по ссылке](https://vruchay.ru/docs/endpoints/documents/post-documents-id-assets-from-url.md): То же, что загрузка картинки для блока файлом, но картинку скачивает сервер по ссылке: логотип с сайта организации, подпись или печать, выложенные в облако.
- [POST /api/documents/{id}/assets — Загрузить картинку для блока](https://vruchay.ru/docs/endpoints/documents/post-documents-id-assets.md): Загружает картинку для блока на листе — логотип, подпись, печать.
- [POST /api/documents/{id}/duplicate — Копия документа под новое мероприятие](https://vruchay.ru/docs/endpoints/documents/post-documents-id-duplicate.md): Создаёт новый документ на основе существующего: копируются размер листа, настройки проверки, проект, все листы с макетами и колонки таблицы получателей.
- [POST /api/documents/{id}/registry/{fileId}/revoke — Отозвать или вернуть проверку экземпляра](https://vruchay.ru/docs/endpoints/documents/post-documents-id-registry-fileId-revoke.md): Отзывает проверку подлинности конкретного выданного файла (revoked: true) или возвращает её (revoked: false).
- [POST /api/documents/{id}/restore — Вернуть документ из корзины](https://vruchay.ru/docs/endpoints/documents/post-documents-id-restore.md): Снимает пометку удаления с документа в корзине.
- [POST /api/documents/{id}/sheets/{sheetId}/background/from-url — Фон листа по ссылке](https://vruchay.ru/docs/endpoints/documents/post-documents-id-sheets-sheetId-background-from-url.md): То же, что загрузка фона файлом, но картинку скачивает сервер по ссылке.
- [POST /api/documents/{id}/sheets/{sheetId}/background — Загрузить фон листа](https://vruchay.ru/docs/endpoints/documents/post-documents-id-sheets-sheetId-background.md): Загружает картинку фона листа (бланк) и ставит её листу в backgroundFileId.
- [POST /api/documents/{id}/sheets — Добавить лист](https://vruchay.ru/docs/endpoints/documents/post-documents-id-sheets.md): Добавляет в конец документа пустой лист (layout: [], schemaVersion: 3).
- [POST /api/documents/{id}/template — Сохранить документ как шаблон](https://vruchay.ru/docs/endpoints/documents/post-documents-id-template.md): Сохраняет документ шаблоном — **копией**, а не пометкой на самом документе.
- [POST /api/documents — Создать документ](https://vruchay.ru/docs/endpoints/documents/post-documents.md): Создаёт материал сразу с одним листом и двумя колонками таблицы получателей — name и email.
- [POST /api/uploads — Ссылка на загрузку файла с диска](https://vruchay.ru/docs/endpoints/documents/post-uploads.md): Выдаёт одноразовую ссылку, по которой файл с диска загружается без токена в команде: фон листа, картинка для блока или таблица получателей.

## Эндпоинты: folders

- [DELETE /api/folders/{id} — Удалить папку (устаревшее)](https://vruchay.ru/docs/endpoints/folders/delete-folders-id.md): Устаревший синоним DELETE /api/projects/{id}.
- [GET /api/folders — Папки библиотеки (устаревшее)](https://vruchay.ru/docs/endpoints/folders/get-folders.md): Устаревший синоним GET /api/projects.
- [PATCH /api/folders/{id} — Переименовать папку (устаревшее)](https://vruchay.ru/docs/endpoints/folders/patch-folders-id.md): Устаревший синоним PATCH /api/projects/{id}.
- [PATCH /api/folders/order — Переставить папки (устаревшее)](https://vruchay.ru/docs/endpoints/folders/patch-folders-order.md): Устаревший синоним PATCH /api/projects/order.
- [POST /api/folders — Завести папку (устаревшее)](https://vruchay.ru/docs/endpoints/folders/post-folders.md): Устаревший синоним POST /api/projects.

## Эндпоинты: generation

- [GET /api/documents/{id}/issue/{jobId} — Состояние документа, выданного по API](https://vruchay.ru/docs/endpoints/generation/get-documents-id-issue-jobId.md): Состояние документа, заказанного POST /api/documents/{id}/issue.
- [GET /api/documents/{id}/jobs — Выпуски по материалу](https://vruchay.ru/docs/endpoints/generation/get-documents-id-jobs.md): Последние выпуски по материалу — новые первыми.
- [GET /api/jobs/{jobId}/archive — Скачать готовые документы](https://vruchay.ru/docs/endpoints/generation/get-jobs-jobId-archive.md): Отдаёт готовый пакет файлом: ZIP со всеми документами задания или один PDF на всю пачку для печати.
- [GET /api/jobs/{jobId}/download-options — Что можно скачать по заданию](https://vruchay.ru/docs/endpoints/generation/get-jobs-jobId-download-options.md): Что сейчас можно сделать с готовым пакетом: сколько в нём файлов, сколько они весят и поместится ли пачка в один PDF на печать.
- [GET /api/jobs/{jobId}/failures — Кого выпуск не осилил](https://vruchay.ru/docs/endpoints/generation/get-jobs-jobId-failures.md): Поимённый разбор неудач задания: по каким строкам документ не создался и почему.
- [GET /api/jobs/{jobId} — Состояние выпуска](https://vruchay.ru/docs/endpoints/generation/get-jobs-jobId.md): Текущее состояние задания.
- [POST /api/documents/{id}/generate — Запустить выпуск документов](https://vruchay.ru/docs/endpoints/generation/post-documents-id-generate.md): Заводит задание на выпуск и ставит его в очередь.
- [POST /api/documents/{id}/issue — Выдать один документ одному человеку](https://vruchay.ru/docs/endpoints/generation/post-documents-id-issue.md): Выпускает один документ по данным из запроса — без таблицы и без пакета.
- [POST /api/jobs/{jobId}/archive-link — Ссылка на готовые документы](https://vruchay.ru/docs/endpoints/generation/post-jobs-jobId-archive-link.md): Выдаёт подписанную ссылку на скачивание пакета — ту, что можно отдать человеку.
- [POST /api/jobs/{jobId}/cancel — Отменить выпуск](https://vruchay.ru/docs/endpoints/generation/post-jobs-jobId-cancel.md): Отменяет остаток начатого выпуска.
- [POST /api/jobs/{jobId}/resume — Продолжить прерванный выпуск](https://vruchay.ru/docs/endpoints/generation/post-jobs-jobId-resume.md): Доделывает то же самое задание с того места, где оно встало.

## Эндпоинты: integrations

- [DELETE /api/integrations/tilda/{id} — Удалить интеграцию с формой](https://vruchay.ru/docs/endpoints/integrations/delete-integrations-tilda-id.md): Удаляет интеграцию насовсем.
- [GET /api/integrations/tilda/{id} — Настройки одной интеграции](https://vruchay.ru/docs/endpoints/integrations/get-integrations-tilda-id.md): Одна интеграция организации целиком.
- [GET /api/integrations/tilda/requests — Заявки с форм на сайте](https://vruchay.ru/docs/endpoints/integrations/get-integrations-tilda-requests.md): Последние 200 заявок организации, новые первыми, — журнал выдачи документов посторонним людям через формы на сайте.
- [GET /api/integrations/tilda — Интеграции с формами на сайте](https://vruchay.ru/docs/endpoints/integrations/get-integrations-tilda.md): Все интеграции организации, новые первыми, вместе со счётчиком принятых заявок.
- [PATCH /api/integrations/tilda/{id} — Изменить интеграцию с формой](https://vruchay.ru/docs/endpoints/integrations/patch-integrations-tilda-id.md): Меняет настройки интеграции.
- [POST /api/integrations/tilda — Создать интеграцию с формой](https://vruchay.ru/docs/endpoints/integrations/post-integrations-tilda.md): Заводит форму выдачи — интеграцию одного из двух видов (kind)

## Эндпоинты: layout

- [GET /api/documents/{id}/fields — Поля документа](https://vruchay.ru/docs/endpoints/layout/get-documents-id-fields.md): Какие поля есть у документа и где они стоят: чем можно заполнить %поле на листе, какие поля уже стоят на каждом листе, какие из них ничем не заполнятся и что принимает выдача по одному.
- [GET /api/layout/catalog — Справочник вёрстки](https://vruchay.ru/docs/endpoints/layout/get-layout-catalog.md): Всё, что программе нужно знать до первого блока, одним ответом: единицы, форматы листа, пределы, значения по умолчанию у каждого вида блока, шрифты, готовые раскладки и служебные поля для подстановки.
- [PATCH /api/documents/{id}/sheets/{sheetId}/elements — Правка блоков листа по частям](https://vruchay.ru/docs/endpoints/layout/patch-documents-id-sheets-sheetId-elements.md): Добавляет, меняет и убирает блоки листа одним запросом — без пересылки всего макета.
- [POST /api/documents/{id}/sheets/{sheetId}/check — Проверить вёрстку листа](https://vruchay.ru/docs/endpoints/layout/post-documents-id-sheets-sheetId-check.md): Проверка листа глазами вёрстки — для программы, которая верстает вслепую.
- [POST /api/documents/{id}/sheets/{sheetId}/preset — Свёрстать лист готовой раскладкой](https://vruchay.ru/docs/endpoints/layout/post-documents-id-sheets-sheetId-preset.md): Верстает лист по готовой раскладке: вид документа задаёт слова и порядок строк, стиль — шрифты и цвета.
- [POST /api/documents/{id}/sheets/{sheetId}/preview — Превью листа картинкой](https://vruchay.ru/docs/endpoints/layout/post-documents-id-sheets-sheetId-preview.md): Отрисовывает один лист так, как он напечатается, и отдаёт картинкой JPEG: с фоном, шрифтами, QR и данными получателя.

## Эндпоинты: mail

- [DELETE /api/mail/domains/{id} — Удалить почтовый домен](https://vruchay.ru/docs/endpoints/mail/delete-mail-domains-id.md): Удаляет домен вместе со всеми отправителями на нём (каскадно).
- [DELETE /api/mail/senders/{id} — Удалить отправителя](https://vruchay.ru/docs/endpoints/mail/delete-mail-senders-id.md): Удаляет одного отправителя; домен и остальные отправители на нём остаются.
- [GET /api/mail/domains — Список почтовых доменов организации](https://vruchay.ru/docs/endpoints/mail/get-mail-domains.md): Возвращает все домены, которые организация заявила для отправки писем от своего имени, вместе с отправителями на каждом из них.
- [GET /api/mail/emails — Письма организации](https://vruchay.ru/docs/endpoints/mail/get-mail-emails.md): Последние 200 писем организации, новые первыми, — сырые записи журнала без перевода причин отказа.
- [GET /api/mail/templates/{documentId} — Письмо о выдаче документа для материала](https://vruchay.ru/docs/endpoints/mail/get-mail-templates-documentId.md): Возвращает транзакционный шаблон письма (поток transactional — «выдача документа») для материала, вместе с выбранным отправителем.
- [PATCH /api/mail/senders/{id} — Изменить отправителя](https://vruchay.ru/docs/endpoints/mail/patch-mail-senders-id.md): Меняет то, что организация пишет о себе сама: отображаемое имя, адрес для ответов, подпись и пометку «основной».
- [POST /api/mail/domains/{id}/check — Проверить DNS-записи домена](https://vruchay.ru/docs/endpoints/mail/post-mail-domains-id-check.md): Запрашивает DNS домена и сверяет записи из dnsRecords с тем, что реально опубликовано.
- [POST /api/mail/domains — Добавить почтовый домен](https://vruchay.ru/docs/endpoints/mail/post-mail-domains.md): Заявляет домен организации для отправки писем от его имени.
- [POST /api/mail/send/{documentId} — Разослать документ отмеченным получателям](https://vruchay.ru/docs/endpoints/mail/post-mail-send-documentId.md): Ставит в очередь письма о выдаче документа всем отмеченным (checked) строкам таблицы получателей материала.
- [POST /api/mail/senders/{id}/test — Проверить отправителя письмом себе](https://vruchay.ru/docs/endpoints/mail/post-mail-senders-id-test.md): Отправляет проверочное письмо от имени этого отправителя — чтобы увидеть, что письмо доходит, в поле «от кого» стоит ожидаемое имя, а ответ уходит на заданный адрес для ответов.
- [POST /api/mail/senders — Добавить отправителя на подтверждённом домене](https://vruchay.ru/docs/endpoints/mail/post-mail-senders.md): Создаёт отправителя — адрес и отображаемое имя, от которых уходят письма.
- [POST /api/mail/templates/{documentId}/test-send — Проверить черновик письма о выдаче](https://vruchay.ru/docs/endpoints/mail/post-mail-templates-documentId-test-send.md): Отправляет черновик письма о выдаче документа на свою почту — до сохранения.
- [POST /api/mail/templates/{documentId} — Сохранить письмо о выдаче документа](https://vruchay.ru/docs/endpoints/mail/post-mail-templates-documentId.md): Создаёт или обновляет транзакционный шаблон письма для материала — у материала он один, повторный вызов перезаписывает его.

## Эндпоинты: mailing

- [GET /api/mailing/log — Журнал доставки писем](https://vruchay.ru/docs/endpoints/mailing/get-mailing-log.md): Последние 200 писем организации, новые первыми, с переведённой на человеческий язык причиной недоставки и сводкой по состояниям.
- [GET /api/mailing/stats — Сводка по письмам за период](https://vruchay.ru/docs/endpoints/mailing/get-mailing-stats.md): Сколько писем организации ушло, дошло, прочитано и не дошло за отрезок дней — итогом, по дням и с разбивкой по материалам и рассылкам без документа.
- [GET /api/mailing/templates/{documentId} — Шаблон письма выбранного потока](https://vruchay.ru/docs/endpoints/mailing/get-mailing-templates-documentId.md): Возвращает шаблон письма для материала в указанном потоке — вместе с отправителем.
- [GET /api/mailing/text/{id} — Рассылка без документа](https://vruchay.ru/docs/endpoints/mailing/get-mailing-text-id.md): Одна рассылка без документа: текст, поток, отправитель, проект — и сколько писем по ней уже поставлено.
- [PATCH /api/mailing/text/{id} — Изменить черновик рассылки без документа](https://vruchay.ru/docs/endpoints/mailing/patch-mailing-text-id.md): Переписывает черновик рассылки без документа.
- [POST /api/mailing/audience — Проверить, кому уйдёт рассылка](https://vruchay.ru/docs/endpoints/mailing/post-mailing-audience.md): Показывает до отправки, кому письмо уйдёт и кому не уйдёт, — тем же расчётом, что и POST /api/mailing/send.
- [POST /api/mailing/problems/seen — Отметить недоставки посмотренными](https://vruchay.ru/docs/endpoints/mailing/post-mailing-problems-seen.md): Отмечает все недошедшие письма организации (bounced и failed) посмотренными.
- [POST /api/mailing/resend — Повторить недоставленные письма](https://vruchay.ru/docs/endpoints/mailing/post-mailing-resend.md): Ставит новые письма вместо недоставленных по одному материалу: берутся все письма в состояниях bounced и failed, по каждому адресу — последняя попытка.
- [POST /api/mailing/send — Разослать письма по материалам](https://vruchay.ru/docs/endpoints/mailing/post-mailing-send.md): Ставит письма в очередь по каждому из выбранных материалов — до двадцати за вызов, по письму на материал каждому получателю.
- [POST /api/mailing/templates/{documentId} — Сохранить письмо рассылки](https://vruchay.ru/docs/endpoints/mailing/post-mailing-templates-documentId.md): Создаёт или обновляет шаблон письма для материала в указанном потоке.
- [POST /api/mailing/test — Отправить проверочное письмо себе](https://vruchay.ru/docs/endpoints/mailing/post-mailing-test.md): Отправляет письмо по сохранённому шаблону материала на свою почту — чтобы посмотреть на него своими глазами.
- [POST /api/mailing/text/{id}/audience — Проверить, кому уйдёт рассылка без документа](https://vruchay.ru/docs/endpoints/mailing/post-mailing-text-id-audience.md): Показывает до отправки, кому письмо рассылки без документа уйдёт и кому не уйдёт, — тем же расчётом, что и POST /api/mailing/text/{id}/send, по тому же списку адресов.
- [POST /api/mailing/text/{id}/send — Отправить рассылку без документа](https://vruchay.ru/docs/endpoints/mailing/post-mailing-text-id-send.md): Ставит в очередь письма рассылки без документа — по письму на каждый адрес из списка.
- [POST /api/mailing/text/{id}/test — Проверить рассылку без документа письмом себе](https://vruchay.ru/docs/endpoints/mailing/post-mailing-text-id-test.md): Отправляет письмо рассылки без документа на свою почту — по сохранённому черновику, чтобы посмотреть на него своими глазами.
- [POST /api/mailing/text — Создать рассылку без документа](https://vruchay.ru/docs/endpoints/mailing/post-mailing-text.md): Заводит черновик рассылки без документа — письма, к которому прикладывать нечего: приглашение на следующее мероприятие, перенос церемонии, напоминание забрать грамоту.

## Эндпоинты: mcp

- [POST /mcp — Сервер MCP](https://vruchay.ru/docs/endpoints/mcp/post-mcp.md): Сервер Model Context Protocol на сайте: https://vruchay.ru/mcp — без /api, его вписывают в настройки агента руками.

## Эндпоинты: oauth

- [GET /api/oauth/authorize/preview — Что показать на странице согласия OAuth](https://vruchay.ru/docs/endpoints/oauth/get-oauth-authorize-preview.md): Проверяет запрос разрешения OAuth и отдаёт то, что страница согласия показывает человеку: какое приложение просит доступ, куда уйдёт разрешение, к какой организации и может ли этот человек его дать.
- [GET /.well-known/oauth-authorization-server — Описание входа через OAuth](https://vruchay.ru/docs/endpoints/oauth/get-well-known-oauth.md): Описание входа через OAuth 2.1 для клиентов MCP — Claude.ai, Claude Desktop, ChatGPT, Cursor.
- [POST /api/oauth/authorize — Разрешить агенту доступ (OAuth)](https://vruchay.ru/docs/endpoints/oauth/post-oauth-authorize.md): Кнопка «Разрешить» на странице согласия https://vruchay.ru/oauth/authorize: человек разрешает клиенту MCP (Claude.ai, ChatGPT, Cursor…) доступ к своей организации и выбирает права.
- [POST /api/oauth/deny — Отказать агенту в доступе (OAuth)](https://vruchay.ru/docs/endpoints/oauth/post-oauth-deny.md): Кнопка «Отказать» на странице согласия https://vruchay.ru/oauth/authorize: человек не пускает клиента MCP в организацию.
- [POST /api/oauth/register — Регистрация клиента OAuth](https://vruchay.ru/docs/endpoints/oauth/post-oauth-register.md): Динамическая регистрация клиента OAuth (RFC 7591): Claude.ai, ChatGPT, Cursor и другие клиенты MCP регистрируются сами, без человека, перед тем как попросить у него разрешение.
- [POST /api/oauth/token — Обмен кода OAuth на токен](https://vruchay.ru/docs/endpoints/oauth/post-oauth-token.md): Последний шаг входа через OAuth 2.1: клиент меняет одноразовый код, полученный на свой адрес возврата после согласия человека, на токен доступа.

## Эндпоинты: org

- [DELETE /api/org/domain — Отключить свой домен](https://vruchay.ru/docs/endpoints/org/delete-org-domain.md): Отключает свой домен: формы по ссылке на нём перестают открываться, ссылки на vruchay.ru работают как прежде.
- [GET /api/org/domain — Свой домен для форм по ссылке](https://vruchay.ru/docs/endpoints/org/get-org-domain.md): Свой домен организации, на котором открываются её формы по ссылке: https://forms.school.ru/f/{token} вместо https://vruchay.ru/f/{token}.
- [GET /api/org/preferences — Настройки интерфейса сотрудника](https://vruchay.ru/docs/endpoints/org/get-org-preferences.md): Тема, формат дат и плотность интерфейса текущего сотрудника.
- [GET /api/org/public-profile — Публичный профиль организации](https://vruchay.ru/docs/endpoints/org/get-org-public-profile.md): Что организация показывает о себе снаружи: на публичной странице /org/<slug> и на странице проверки документа.
- [GET /api/org/usage — Условия и остаток документов](https://vruchay.ru/docs/endpoints/org/get-org-usage.md): Сколько документов организация уже выпустила, сколько ещё может выпустить и на каких условиях: бесплатная проба, назначенный план или оплаченный тариф старого образца.
- [GET /api/org — Организация и свой профиль](https://vruchay.ru/docs/endpoints/org/get-org.md): Название организации, отметка о тарифе и данные текущего сотрудника.
- [PATCH /api/org/domain — Подключить свой домен для форм](https://vruchay.ru/docs/endpoints/org/patch-org-domain.md): Подключает или меняет свой домен организации для форм по ссылке.
- [PATCH /api/org/me — Изменить своё имя](https://vruchay.ru/docs/endpoints/org/patch-org-me.md): Меняет имя текущего сотрудника — то, что отвечает GET /api/org в userName и GET /api/auth/me в name.
- [PATCH /api/org/preferences — Изменить настройки интерфейса](https://vruchay.ru/docs/endpoints/org/patch-org-preferences.md): Меняет тему, формат дат или плотность интерфейса текущего сотрудника.
- [PATCH /api/org/public-profile — Изменить публичный профиль](https://vruchay.ru/docs/endpoints/org/patch-org-public-profile.md): Правит публичное лицо организации.
- [PATCH /api/org/verify-domain — Домен страницы проверки](https://vruchay.ru/docs/endpoints/org/patch-org-verify-domain.md): Сохраняет домен, на котором организация хочет показывать страницу проверки документов, например sertifikaty.vruchay.ru.
- [PATCH /api/org — Переименовать организацию](https://vruchay.ru/docs/endpoints/org/patch-org.md): Меняет название организации.
- [POST /api/org/domain/check — Проверить записи своего домена](https://vruchay.ru/docs/endpoints/org/post-org-domain-check.md): Проверяет обе записи: хост ведёт на сервис (CNAME или A с теми же адресами, что у vruchay.ru) и TXT _vruchay.{host} содержит секрет организации.
- [POST /api/org/public-profile/logo — Загрузить логотип](https://vruchay.ru/docs/endpoints/org/post-org-public-profile-logo.md): Загружает логотип для публичной страницы организации.

## Эндпоинты: overview

- [GET /api/overview — Сводка по организации](https://vruchay.ru/docs/endpoints/overview/get-overview.md): Сводка для рабочего стола кабинета одним запросом: условия и остаток документов, счётчики выпуска, рассылки и проверок по QR, пять последних материалов и пять последних заданий выпуска.

## Эндпоинты: projects

- [DELETE /api/projects/{id} — Удалить проект](https://vruchay.ru/docs/endpoints/projects/delete-projects-id.md): Удаляет проект.
- [GET /api/projects — Проекты организации](https://vruchay.ru/docs/endpoints/projects/get-projects.md): Проекты организации в том порядке, в каком они стоят в кабинете.
- [PATCH /api/projects/{id} — Переименовать проект](https://vruchay.ru/docs/endpoints/projects/patch-projects-id.md): Меняет название проекта.
- [PATCH /api/projects/order — Переставить проекты](https://vruchay.ru/docs/endpoints/projects/patch-projects-order.md): Задаёт порядок проектов в кабинете.
- [POST /api/projects — Завести проект](https://vruchay.ru/docs/endpoints/projects/post-projects.md): Заводит проект в конце списка.

## Эндпоинты: public

- [GET /api/referral-offer — Что обещано по коду приглашения](https://vruchay.ru/docs/endpoints/public/get-referral-offer.md): Что получит тот, кто регистрируется по коду приглашения.
- [GET /api/v1/archive/{token} — Скачать готовые документы по ссылке](https://vruchay.ru/docs/endpoints/public/get-v1-archive-token.md): Скачивание пакета по подписанной ссылке — без входа и без заголовка Authorization.
- [GET /api/v1/forms/{token} — Настройки формы по ссылке](https://vruchay.ru/docs/endpoints/public/get-v1-forms-token.md): Что показывает страница формы по ссылке — https://vruchay.ru/f/{token}: чья форма, какой документ, какие поля спросить у участника, текст согласия.
- [GET /api/v1/public/org/{slug}/search — Поиск документа в публичном реестре организации](https://vruchay.ru/docs/endpoints/public/get-v1-public-org-slug-search.md): Поиск в публичном реестре эмитента — без входа.
- [GET /api/v1/public/org/{slug} — Публичная страница организации](https://vruchay.ru/docs/endpoints/public/get-v1-public-org-slug.md): Публичная страница эмитента: кто это, чем подтверждена его личность и что он выдаёт.
- [GET /api/v1/reviews — Опубликованные отзывы](https://vruchay.ru/docs/endpoints/public/get-v1-reviews.md): Отзывы заказчиков для посадочной страницы сервиса.
- [GET /api/v1/verify/{id} — Проверка подлинности документа](https://vruchay.ru/docs/endpoints/public/get-v1-verify-id.md): Страница проверки выданного документа.
- [POST /api/v1/leads — Заявка на разговор об условиях](https://vruchay.ru/docs/endpoints/public/post-v1-leads.md): Заявка с посадочной страницы: организация просит связаться и обсудить условия.
- [POST /api/v1/uploads/{link} — Загрузить файл по ссылке](https://vruchay.ru/docs/endpoints/public/post-v1-uploads-link.md): Принимает файл по одноразовой ссылке из POST /api/uploads (в MCP — get_upload_link).

## Эндпоинты: recipients

- [DELETE /api/documents/{id}/recipients/columns/{columnId} — Удалить колонку](https://vruchay.ru/docs/endpoints/recipients/delete-documents-id-recipients-columns-columnId.md): Удаляет колонку и пересчитывает position у оставшихся, чтобы нумерация шла подряд.
- [DELETE /api/documents/{id}/recipients/rows/{rowId} — Удалить строку](https://vruchay.ru/docs/endpoints/recipients/delete-documents-id-recipients-rows-rowId.md): Удаляет строку из таблицы получателей.
- [GET /api/documents/{id}/recipients — Получить таблицу получателей](https://vruchay.ru/docs/endpoints/recipients/get-documents-id-recipients.md): Возвращает таблицу получателей документа целиком: колонки по порядку, строки по порядку (не больше 10 000) и число отмеченных строк.
- [PATCH /api/documents/{id}/recipients/columns/{columnId} — Переименовать колонку](https://vruchay.ru/docs/endpoints/recipients/patch-documents-id-recipients-columns-columnId.md): Переименовывает колонку и одной транзакцией переносит значения во всех строках под новый ключ (значения хранятся по имени, а не по идентификатору колонки), а также переписывает макеты листов документа: поля, ссылавшиеся на прежнее имя, начинают ссылаться на новое.
- [PATCH /api/documents/{id}/recipients/rows/{rowId} — Изменить строку](https://vruchay.ru/docs/endpoints/recipients/patch-documents-id-recipients-rows-rowId.md): Правит одну строку: значения ячеек и/или отметку к выпуску.
- [POST /api/documents/{id}/recipients/checked — Отметить строки к выпуску](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-checked.md): Ставит или снимает отметку к выпуску сразу у многих строк.
- [POST /api/documents/{id}/recipients/columns/order — Переставить колонки таблицы](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-columns-order.md): Задаёт порядок колонок в таблице получателей материала.
- [POST /api/documents/{id}/recipients/columns — Добавить колонку](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-columns.md): Добавляет колонку в конец таблицы получателей.
- [POST /api/documents/{id}/recipients/import — Импортировать таблицу получателей](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-import.md): Записывает таблицу получателей в документ: заводит недостающие колонки и добавляет строки.
- [POST /api/documents/{id}/recipients/parse — Разобрать файл со списком получателей](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-parse.md): Читает загруженный файл (Excel .xlsx или CSV) и возвращает, что в нём распознано: имя листа, строку с шапкой, колонки с подобранными латинскими именами переменных и сами строки.
- [POST /api/documents/{id}/recipients/rows — Добавить строку](https://vruchay.ru/docs/endpoints/recipients/post-documents-id-recipients-rows.md): Добавляет одну строку в конец таблицы получателей.

## Эндпоинты: referral

- [GET /api/referral — Приглашение друга](https://vruchay.ru/docs/endpoints/referral/get-referral.md): Всё, что показывает раздел «Пригласить друга»: код приглашения организации, готовая ссылка, готовый текст для мессенджера, список приглашённых и сколько бонусных документов уже заработано.

## Эндпоинты: registry

- [GET /api/registry/analytics — Сводка по выданным документам](https://vruchay.ru/docs/endpoints/registry/get-registry-analytics.md): Цифры под таблицей реестра: сколько выдано, отозвано, заменено, истекло, как дошли письма, сколько раз документы проверяли и скачивали, и разбивка по материалам.
- [GET /api/registry/archive — Скачать документы архивом](https://vruchay.ru/docs/endpoints/registry/get-registry-archive.md): Скачать пачку выданных документов одним ZIP-архивом: либо отмеченные по идентификаторам, либо всё, что нашлось по отбору.
- [GET /api/registry/export.csv — Выгрузить реестр в CSV](https://vruchay.ru/docs/endpoints/registry/get-registry-export-csv.md): Тот же реестр таблицей для Excel — по тому же отбору, что и GET /api/registry.
- [GET /api/registry/facets — Значения для фильтров реестра](https://vruchay.ru/docs/endpoints/registry/get-registry-facets.md): Что подставлять в отбор реестра: материалы и мероприятия, по которым что-то выдано.
- [GET /api/registry/files/{fileId}/download — Скачать один документ](https://vruchay.ru/docs/endpoints/registry/get-registry-files-fileId-download.md): Отдать файл одного выданного документа — посмотреть или переслать вручную.
- [GET /api/registry/files/{fileId} — Карточка выданного документа](https://vruchay.ru/docs/endpoints/registry/get-registry-files-fileId.md): Что с документом было и что с ним стало: строка реестра, письма с ним и лента событий, сведённая из трёх источников — выпуска, событий писем и журнала действий организации (по самому файлу и по его материалу).
- [GET /api/registry — Реестр выданных документов](https://vruchay.ru/docs/endpoints/registry/get-registry.md): Страница реестра выданного по всей организации: каждый выпущенный документ одной строкой — кому, по какому материалу, когда, в каком состоянии, что с письмом и сколько раз проверяли.
- [POST /api/registry/reissue — Перевыпустить документы](https://vruchay.ru/docs/endpoints/registry/post-registry-reissue.md): Выдать новый документ вместо выбранного — по текущим данным той же строки таблицы получателей и текущему макету материала.
- [POST /api/registry/resend — Переотправить письма с документами](https://vruchay.ru/docs/endpoints/registry/post-registry-resend.md): Ещё раз отправить письмо с уже выпущенным документом — на адрес из текущей строки получателя.
- [POST /api/registry/revoke/preview — Предпросмотр отзыва](https://vruchay.ru/docs/endpoints/registry/post-registry-revoke-preview.md): Что будет отозвано, до того как это станет необратимым: число документов по цели, сколько из них уже отозваны и первые двадцать имён.
- [POST /api/registry/revoke — Отозвать или вернуть проверку документов](https://vruchay.ru/docs/endpoints/registry/post-registry-revoke.md): Отозвать проверку у пачки документов или вернуть её.

## Эндпоинты: reviews

- [DELETE /api/reviews/{id} — Убрать свой отзыв](https://vruchay.ru/docs/endpoints/reviews/delete-reviews-id.md): Убрать отзыв своей организации.
- [GET /api/reviews/mine — Отзыв своей организации](https://vruchay.ru/docs/endpoints/reviews/get-reviews-mine.md): Отзыв, который оставила ваша организация: текст, состояние проверки и замечание модератора, если отзыв отклонили.
- [PATCH /api/reviews/mine — Оставить или переписать отзыв](https://vruchay.ru/docs/endpoints/reviews/patch-reviews-mine.md): Оставить отзыв о сервисе или переписать уже оставленный.

## Эндпоинты: tokens

- [DELETE /api/tokens/{id} — Отозвать токен API](https://vruchay.ru/docs/endpoints/tokens/delete-tokens-id.md): Отзывает токен: с этого момента запросы с ним получают 401.
- [GET /api/tokens — Список действующих токенов API](https://vruchay.ru/docs/endpoints/tokens/get-tokens.md): Список действующих (не отозванных) токенов API организации, новые сверху.
- [POST /api/tokens — Выдать токен API](https://vruchay.ru/docs/endpoints/tokens/post-tokens.md): Выдаёт новый токен API организации.

## Эндпоинты: validation

- [POST /api/documents/{id}/validation/exclude — Снять отметку с проблемных строк](https://vruchay.ru/docs/endpoints/validation/post-documents-id-validation-exclude.md): Снимает отметку к выпуску (checked: false) с перечисленных строк — «выпустить только чистые».
- [POST /api/documents/{id}/validation/fix — Исправить ячейки по результатам проверки](https://vruchay.ru/docs/endpoints/validation/post-documents-id-validation-fix.md): Записывает новые значения в отдельные ячейки — по одной или сразу во многих строках (например, «ФИО прописными» во всех трёхстах строках протокола).
- [POST /api/documents/{id}/validation — Проверить список получателей перед выпуском](https://vruchay.ru/docs/endpoints/validation/post-documents-id-validation.md): Проверяет строки таблицы получателей против макетов документа и возвращает отчёт: сколько строк чистых, сколько выпускать нельзя, поимённый список строк с проблемами и остаток квоты.

## Справочники

- [Набор правил награждения](https://vruchay.ru/docs/reference/award-rules.md): Контракт живёт в packages/shared/src/awards/rules.ts (схемы awardRuleSet, awardRule, awardCondition, awardOutput) и plan.ts (форма раскладки AwardPlan).
- [Задание на выпуск](https://vruchay.ru/docs/reference/generation-job.md): Форма записи о выпуске, которую возвращают POST /api/documents/{id}/generate, POST /api/jobs/{jobId}/resume, POST /api/jobs/{jobId}/cancel, GET /api/jobs/{jobId} и GET /api/documents/{id}/jobs (массивом).
- [Макет листа](https://vruchay.ru/docs/reference/layout.md): Контракт живёт в packages/shared/src/schema/layout.ts и rich-text.ts; им же пользуются редактор, превью и серверный PDF-рендер.
- [Отбор в реестре выданного](https://vruchay.ru/docs/reference/registry-filter.md): Один и тот же набор параметров принимают GET /api/registry, GET /api/registry/analytics, GET /api/registry/export.csv, GET /api/registry/archive (строкой запроса) и POST /api/registry/revoke, POST /api/registry/revoke/preview (объектом filter в теле).
- [Строка реестра выданного](https://vruchay.ru/docs/reference/registry-row.md): Форма одной строки, которую возвращают GET /api/registry (в items[]) и GET /api/registry/files/{fileId} (в row).
- [Коды проблем проверки списка](https://vruchay.ru/docs/reference/validation-problem-codes.md): Возвращаются в rows[].problems[].code ответа POST /api/documents/{id}/validation.