Способы выдачи

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

Прежде чем писать свою интеграцию, найдите свой случай в таблице ниже. Форма и API сами принимают заявку, выпускают документ, списывают квоту, не выдают второй документ тому же человеку и шлют письмо — свой сервер между сайтом и «Вручай» для этого не нужен.

Какой способ выбрать

Пути совмещаются: одна грамота может уйти пакетом по списку, а опоздавшие получат её через форму по ссылке. Всё выданное любым путём попадает в один реестр с кодом проверки и QR.

По списку

В выпуск попадают отмеченные строки. Ссылка на архив открывается в браузере без входа и живёт час; format: "pdf" склеивает все документы в один файл для печати, name задаёт имена файлов в архиве ("%name", "%number %name"). Дальше документы раздают сами или рассылают письмами (ниже).

Проверка остатка — до постановки задания: к выпущенному прибавляется бронь незаконченных заданий. Не хватает документов или вышел срок плана — выпуск не начнётся, ответ 400.

Форма по ссылке

Страница на адресе «Вручай» для тех, у кого нет своего сайта или нет времени его трогать. Нужны права «Полный доступ» и возможность tilda в плане.

MCP:

{
  "kind": "link",
  "name": "Конференция, сертификат участника",
  "documentIds": ["9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"],
  "formFields": ["name"],
  "singleFilePerEmail": true
}

— аргументы setup_form. REST — тот же объект в `POST /api/integrations/tilda`.

В ответе connect.formUrl — ссылка вида https://vruchay.ru/f/{token}, а если у организации подключён и подтверждён свой домен для форм (`PATCH /api/org/domain`) — на нём: https://forms.school.ru/f/{token}. Её и отдают людям.

• Документ у формы по ссылке ровно один.
• formFields — что спросить, кроме почты: имена полей документа, по умолчанию ["name"]. Служебные и постоянные поля спросить нельзя — участник не должен напечатать на листе своё.
• authMode у формы по ссылке по умолчанию none: человек открывает ссылку и сразу получает документ, от перебора её держат dailyLimit и singleFilePerEmail. email_code — почту подтверждают шестизначным кодом из письма.
• Документ отдаётся сразу двумя путями — кнопкой скачивания и письмом: showDownload и sendEmail у формы по ссылке всегда true.
• singleFilePerEmail: true (по умолчанию) — повторная заявка с того же адреса получает уже выданный документ, второй не выпускается. Открывается он только после кода, который приходит на адрес выдачи, — даже при authMode: "none".
• dailyLimit — предел заявок за последние 24 часа, по умолчанию 500.

Что видит участник: страницу с названием организации и документа, поля из formFields, почту и согласие на обработку данных; затем код из письма (если он нужен) и документ — кнопкой скачивания и письмом. В таблице получателей появляется неотмеченная строка с source: "link", документ — в реестре.

Форма на сайте

Кнопка «Получить документ» на странице организации. Нужны права «Полный доступ» и возможность tilda в плане.

MCP — setup_form:

{
  "kind": "site",
  "name": "Сайт школы",
  "documentIds": ["9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"],
  "allowedDomains": ["example.ru"]
}

REST — тот же объект в POST /api/integrations/tilda.

• allowedDomains — домены страниц с формой, до 20. Адреса приводятся к домену сами (https://www.example.ru/events → example.ru), поддомены разрешённого домена тоже считаются своими. С других адресов форма заявки не примет — поэтому открытая с диска страница или чужой тестовый стенд работать не будут.
• documentIds — до 50 документов; на странице может стоять кнопка любого из них.

В ответе connect.embedHtml — готовый HTML для каждого документа: блок с кнопкой и подключение стилей и скрипта формы. Куда вставлять:

• Тильда — блок «HTML-код» (T123) на нужной странице;
• WordPress — блок «Произвольный HTML» в редакторе страницы;
• Битрикс — визуальный редактор в режиме HTML или включаемая область;
• обычная страница — в любое место внутри <body>.

Скрипт защищён от повторной загрузки: две кнопки на одной странице подключают его один раз. Готовые варианты для Тильды, WordPress и Битрикса показывает кабинет: документ → «Выпуск» → «Форма на сайте».

Что видит участник: кнопку на странице, по нажатию — окно с полями, почтой, согласием и кодом из письма; затем документ кнопкой скачивания и письмом.

Закрытая страница и личный кабинет

Форма работает и внутри личного кабинета сайта — например, на закрытой странице Tilda Members, куда пускают только участников мероприятия. Свой сервер для этого не нужен. Кто может открыть страницу, решает сайт: группы и права Тильды «Вручай» не читает.

• Имя и почта подставляются сами. Скрипт формы ищет их по порядку: атрибуты блока data-name и data-email (их заполняет своим шаблоном сайт с собственным кабинетом — WordPress, Битрикс), поля личного кабинета Тильды ma_name и ma_email, объект window.tildamembers. На Тильде ничего дописывать не нужно. Не нашёл — человек введёт сам.
• ФИО можно поправить. По кнопке открывается окно «Проверьте данные»: имя и почта уже вписаны, человек исправляет опечатку, отмечает согласие и получает документ. allowEdit: false делает поля окна только для чтения, а prefillFromAccount: false выключает подстановку. Запрет правки — удобство, не защита: заявку шлёт браузер посетителя.
• showVerifyLink: true — ссылка на проверку подлинности в окне успеха и кнопки «поделиться» ею (showShare, по умолчанию включены, но без ссылки не видны).
• requireAccount: true — заявка принимается, только если страница передала почту учётной записи, то есть человек вошёл в кабинет. Копия кнопки на открытой странице документ не выдаст.
• checkList: true — выдавать только тем, чья почта есть в таблице получателей документа.
• Документ по кнопке, без писем — authMode: "none", sendEmail: false, showDownload: true. Без authMode: "none" форма на сайте сначала пришлёт код на почту: по умолчанию у неё email_code. Текст после выдачи без письма сам становится «Спасибо! Документ готов»; свой — в successMessage. Почта в окне всё равно обязательна, но из кабинета она подставится сама; повторная заявка того же человека получит уже выданный документ (singleFilePerEmail) — после кода на адрес, куда его выдали.

{
  "kind": "site",
  "name": "Конференция, закрытая страница",
  "documentIds": ["9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b"],
  "allowedDomains": ["academy.example.ru"],
  "requireAccount": true,
  "authMode": "none",
  "sendEmail": false,
  "showDownload": true
}

— аргументы setup_form; REST — тот же объект в POST /api/integrations/tilda. Код вставки из connect.embedHtml — в блок «HTML-код» (T123) закрытой страницы.

Форма Тильды без нашего скрипта

У Тильды есть второй путь — без кода на странице: обычная форма Тильды отправляет данные прямо на адрес https://vruchay.ru/api/v1/tilda-create («Свой скрипт для приёма данных»), со скрытыми полями secure (токен формы) и doc_id (id документа), полями mask_name, mask_email и галочкой consent. Пошаговая инструкция — в кабинете там же.

Управление формами

Вид формы (kind) после создания не меняется. Выключенная форма перестаёт принимать заявки сразу, код на странице править не нужно.

Один документ по API

Ваша программа присылает имя — в ответе готовый документ.

• MCP: issue_document с documentId, data, email, send и idempotencyKey.
• REST: `POST /api/documents/{id}/issue` с заголовком Idempotency-Key; состояние — `GET /api/documents/{id}/issue/{jobId}`.

curl -X POST "https://vruchay.ru/api/documents/$DOCUMENT_ID/issue" \
  -H "Authorization: Bearer $VRUCHAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lms-completion-48213" \
  -d '{"data":{"name":"Иванова Анна Сергеевна","hours":"72"},"email":"ivanova@example.com","send":true}'

• Idempotency-Key — ваш идентификатор события, 8–100 знаков. Повтор с тем же ключом отдаёт первый документ, а не выпускает второй.
• 201 — документ готов: код проверки, номер, ссылка на страницу проверки и ссылка получателя на PDF (recipientUrl, 30 дней). 202 — опрашивайте statusUrl раз в 1–2 секунды.
• Поля data — колонки и поля листа документа; их список отдаёт GET /api/documents/{id}/fields (раздел issue). name обязательно.
• Письмо (send: true) уходит по шаблону документа и требует возможности mailing.
• Предел — 120 документов в минуту на организацию.

Что видит получатель: письмо с документом (если send: true) или то, что покажет ваша программа, — ссылку recipientUrl или код проверки.

Письма

Рассылка уже выпущенных документов по строкам таблицы. Нужна возможность mailing в плане.

• В теме и тексте — подстановки %name и другие поля строки. attachGeneratedFile (по умолчанию true) прикладывает PDF.
• PDF тяжелее, чем принимает почта, письмо не останавливает: оно уходит без файла, с пометкой и кнопкой «Открыть документ», в журнале — sent. Чтобы файл прикладывался, держите фон и картинки листа лёгкими — check_sheet предупредит (heavy_images).
• Письма ставятся отмеченным строкам с выпущенным документом; кому не поставлено — в skipped с причиной.
• Без своего отправителя письма идут с общего адреса сервиса: не больше 300 за раз и 500 за сутки на организацию. Со своего подтверждённого домена предела нет — домен подключает управляющий в кабинете.
• Пробное письмо по токену приходит тому, кто выдал токен, а не на адрес из запроса.
• Рассылка необратима: перед send_mail покажите человеку, кому и сколько писем уйдёт.

Форма и API шлют письмо сами (sendEmail у формы, send у API) по тому же шаблону документа.

Какой домен где

Слово «домен» в API встречается в четырёх разных настройках, и они друг от друга не зависят:

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

Когда выдача останавливается

Квота у формы бронируется в момент заявки (при подтверждении кодом — в момент ввода кода), поэтому участник узнаёт об отказе сразу. Отказы видны организатору в журнале заявок и в журнале действий (issue.refused). Уже выданные документы при любом из этих условий остаются действительными и проверяются по QR.

Остаток и срок заранее показывает get_account или `GET /api/org/usage`.