Справочник waafir-esign
Сервер waafir-esign предоставляет подключённому ИИ-клиенту собственный
сервис электронной подписи Waafir: создайте конверт по файлу в вашей
организации, дайте его подписантам подписать (или отклонить) его,
отслеживайте статус и скачайте подписанный PDF. Подписи соответствуют eIDAS
AES (PAdES) и создаются собственным механизмом подписания Waafir; каждая
подпись фиксирует согласие подписанта (IP-адрес, user agent, метку времени) в
защищённом от подделки журнале аудита, а подписанный PDF сохраняется как
новейшая версия исходного файла.
Подключение: https://app.waafir.io/api/mcp/waafir или сервер области
https://app.waafir.io/api/mcp/waafir-esign — см.
Настройка. Имена инструментов на обоих одинаковые. Инструментам чтения нужна область доступа
read — в подключении, созданном при входе, или в
PAT; для создания, отправки,
отклонения, изменения подписантов и аннулирования нужна область доступа
write. Для подписания нужна write и разрешение подписывать документы:
одобренное на экране согласия для подключения или включённое при создании
токена (см.
Разрешение токену подписывать документы);
без него esign_sign скрыт из списка инструментов и отклоняется при вызове. Подключение или токен, ограниченные конкретными комнатами данных,
могут работать только с конвертами по файлам в этих комнатах данных — та же
граница, которую соблюдают инструменты комнаты данных.
Ежемесячная квота конвертов
Электронное подписание учитывается по конвертам — один документ / одно задание на подписание считается один раз, сколько бы подписантов в нём ни было. Этот MCP-сервер и подписание внутри приложения расходуют один общий ежемесячный пул:
- Для доступа нужно дополнение E-Signatures или активная подписка Waafir.
Без них каждый запрос к
waafir-esignотклоняется на входе с HTTP 402 ещё до запуска какого-либо инструмента — это отказ уровня 1.ADDON_NOT_PURCHASEDпоявляется внутри текстаmessageэтого ответа; это не отдельное машиночитаемое поле, поэтому ветвитесь по статусу 402, а не по коду. Наwaafirинструментыesign_вместо этого скрыты из списка инструментов, а вызов одного из них отклоняется на уровне 2 сQUOTA_EXCEEDEDи сообщением, называющим инструмент, которое также содержитADDON_NOT_PURCHASED. - Ваш тариф включает ежемесячный пакет конвертов: Starter — 10, Premium — 50, Enterprise — 50 на каждое активное место (календарный месяц).
- Каждая приобретённая единица дополнения E-Signatures добавляет 100 конвертов в месяц сверх пакета вашего тарифа; единицы суммируются на любом тарифе.
- Квота — это жёсткий потолок: если вы отправляете конверт на пределе,
отправка отклоняется с кодом
QUOTA_EXCEEDEDи предложением купить дополнительные единицы или повысить тариф — автоматически за конверт ничего никогда не списывается. Текст сообщения также называет внутренний маркерESIGN_QUOTA_EXCEEDED; это просто текст, поэтому ветвитесь поerror.code, который равенQUOTA_EXCEEDED. Создание сsend: true, упёршееся в потолок, всё равно оставляет черновик — отправьте его, когда появится запас, а не создавайте заново.
Квота расходуется, когда конверт отправляется (открывается для
подписания), а не за каждую подпись, — поэтому подписание и отклонение никогда
не расходуют квоту. Чтение и скачивание тоже. Проверить запас можно в любой
момент с помощью esign_quota_status.
Ваше собственное NDA с электронной подписью
Когда ваша организация загружает собственное NDA (Инвесторы → NDA → Загрузить собственное NDA, см. Настраиваемость), каждый инвестор подписывает его в модуле подписания Waafir: инвестор, выполнивший вход, выбирает Подписать NDA, и документ открывается в новой вкладке; посетитель по ссылке для общего доступа получает ссылку для подписания по электронной почте на указанный им адрес. Эти конверты NDA не учитываются в ежемесячной квоте, а сам шаблон NDA нельзя отправить как обычный конверт.
Инструменты
Ключи аргументов и результатов на этом сервере записываются в
snake_case— то же соглашение, что и на всех остальных MCP-серверах Waafir.file_id,envelope_id,signing_mode,field_layout,consent_affirmed,confirm_send,download_url,has_more.
Несовместимое изменение — раньше
waafir-esignпринимал аргументы вcamelCase.fileId,envelopeId,signingMode,fieldLayoutиconsentAffirmedбольше не принимаются; у каждого теперь есть написание вsnake_case, указанное в таблицах ниже.confirm_sendне изменился — он уже был в snake_case.Если устаревшее написание было обязательным аргументом, оно отклоняется, а не принимается молча: вызов
esign_create_envelope, всё ещё передающийfileId, не проходит валидацию аргументов с указаниемfile_idкак отсутствующего ключа. Если оно было необязательным, оно молча отбрасывается — точно так же, как любой другой нераспознанный ключ, — см. два режима сбоя ниже. Обновите вызовы, используя написания с этой страницы.
Ключ с опечаткой приводит к сбою одним из двух способов, и один из них незаметен. Нераспознанный аргумент отбрасывается, а не отклоняется, поэтому дальнейшее зависит только от того, был ли нужный вам ключ обязательным:
-
Обязательный ключ → вызов отклоняется. Аргумент просто отсутствует. Это явный, безопасный случай, и он касается
esign_create_envelope(file_id),esign_get_envelope,esign_sign(envelope_idиconsent_affirmed),esign_decline,esign_void_envelope,esign_revise_signers(envelope_idиsignatories) иesign_download_signed— включая все устаревшие написания этих ключей в camelCase.У него нет
error.code. Аргументы проверяются по опубликованной схеме инструмента до его запуска, поэтому отсутствующий обязательный ключ — или ключ неверного типа — возвращается как результат-ошибка, который сервер формирует сам: ответ помечен как ошибка, и его текст называет проблемный аргумент, но ни один инструмент не запускался, поэтому полеerror.codeуровня 2 ничем не заполняется. Не ветвитесь поINVALID_ARGUMENTпри сбое формы аргументов — читайте сообщение.INVALID_ARGUMENTпо-прежнему возвращается при отказе, который инструмент выдаёт после запуска, например при неверно сформированномconfirm_token. -
Необязательный ключ → вызов выполняется успешно, но делает другое. Вы получаете
200и корректный результат, который отвечает на другой вопрос:- Фильтры
esign_list_envelopesнеобязательны, поэтому случайныйfileIdотбрасывается, и вы получаете нефильтрованный список всех конвертов, которые видит токен, — надмножество, возвращённое так, будто это отфильтрованный ответ. - В
esign_create_envelopeотброшенныйsigningMode: "sequential"оставляет конверт в режиме по умолчаниюparallel. Тогда при отправке юридически обязывающий запрос подписи уходит всем подписантам одновременно — именно то, чему должен был помешать запросsequential.fieldLayoutотбрасывается так же.
- Фильтры
Поскольку отброшенный необязательный ключ не может о себе сообщить,
проверяйте, что результат повторяет то, что вы запросили: созданный
конверт сообщает свой signing_mode, а esign_list_envelopes отфильтрован,
только если вы правильно написали фильтр.
esign_create_envelope (запись)
Создание конверта по файлу в вашей организации с указанием подписантов. Принимается любой адрес электронной почты — подписанту не нужна учётная запись Waafir. Способ связи с каждым из них определяется при отправке конверта в зависимости от того, есть ли у этого адреса учётная запись Waafir: владелец учётной записи подписывает в сеансе (уведомление в приложении и письмо со ссылкой на экран подписания), а всем остальным по электронной почте отправляется гостевая ссылка для подписания. Критерий — существование учётной записи, а не членство в вашей организации, поэтому подписант из другой организации тоже подписывает в сеансе. Каждый ожидающий подписант получает ровно один из двух вариантов — никогда оба и никогда ни одного.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
file_id | string (UUID) | да | Файл для подписания. Должен принадлежать вашей организации. |
signatories | array | да | От 1 до 50 объектов { "email": string, "name"?: string }. Принимается любой адрес — подписантам не нужно быть пользователями Waafir; внешние адреса получают гостевую ссылку для подписания. |
transaction_id | string (UUID) | нет | Устарел и игнорируется. Принимается, чтобы существующие интеграции продолжали работать; прекратите его передавать. |
send | boolean | нет | Если true, сразу открыть конверт для подписания — в два шага (см. ниже). Нужен токен с разрешением Отправлять людям вне вашей организации. |
confirm_token | string | нет | Только с send: true: токен из вызова предпросмотра. |
confirm_send | boolean | нет | Устарел и игнорируется: send: true теперь принимает confirm_token. |
signing_mode | "parallel" | "sequential" | нет | Порядок подписания. "parallel" — по умолчанию: подписанты могут подписывать в любом порядке, а при отправке письма уходят всем сразу. "sequential" отправляет письмо только первому и допускает каждого следующего подписанта, когда подписали все предыдущие; подписание вне очереди отклоняется с CONFLICT. Отсутствие параметра — или опечатка signingMode — означает "parallel". |
field_layout | array | нет | Переопределение макета размещения полей; не указывайте для макета по умолчанию. |
observers | array | нет | До 20 наблюдателей (копия) в виде { "email": string, "name"?: string }. Наблюдатель получает по электронной почте копию запроса подписи и каждого напоминания со ссылкой только для чтения, чтобы следить за статусом. Наблюдатели никогда не подписывают, и подписанная копия им не отправляется. |
send: true работает в два шага, потому что отправка в момент успеха
рассылает настоящие, юридически обязывающие письма с запросом подписи на
каждый указанный адрес. Первый вызов ничего не создаёт и не отправляет: он
возвращает предпросмотр (подписанты, число наблюдателей и ваша квота) и
confirm_token. Вызовите снова с идентичными аргументами и токеном, чтобы
создать и отправить. Токен действует один раз и истекает через несколько
минут. Без разрешения send: true отклоняется с FORBIDDEN (GRANT_REQUIRED);
создайте конверт без send и отправьте его в Waafir.
esign_revise_signers проходит те же два шага и требует того же разрешения,
когда он отправил бы кому-то письмо: новому подписанту или наблюдателю в уже
отправленном конверте.
Возвращает конверт. Его поля — ровно id, file_id, status,
signing_mode, created_by, signed_output_name,
signed_output_version_count, field_layout, packet_page_count и
expires_at: результат — это список разрешённых полей, сопоставленных
вручную, поэтому больше ничего не передаётся. Метки времени — строки ISO-8601.
Черновик конверта нужно отправить, прежде чем кто-либо сможет подписать.
Отправка расходует один конверт из вашей ежемесячной квоты — на потолке
send возвращает QUOTA_EXCEEDED, и конверт остаётся черновиком, который
можно отправить позже. Ошибочно отправленный конверт можно отозвать с помощью
esign_void_envelope.
Файл, который ещё проверяется. Если файл — новая загрузка или новая версия,
проверку которой Waafir ещё не завершил, вызов отвечает UNAVAILABLE с
error.reason: "ACTIVATION_PENDING" и сообщением
This file is still being checked. Try again shortly. Ничего не создаётся;
вызовите инструмент снова после короткой паузы.
esign_list_envelopes (чтение)
Список конвертов вашей организации, сначала новые, с подписантами и статусами
каждого конверта. Необязательный фильтр: file_id. (transaction_id устарел и игнорируется.)
Поскольку фильтры необязательны, устаревшее написание в camelCase молча
отбрасывается, и вызов возвращает нефильтрованный список, а не ошибку; см.
примечание о ключах выше.
С пагинацией — limit (необязательно, 1–100, по умолчанию 25) и offset
(необязательно, по умолчанию 0) должны быть числами; значение другого типа
не проходит валидацию аргументов, как любое другое несоответствие типа. Число
вне диапазона ограничивается, а не отклоняется — limit: 10000
становится 100, offset: -2 становится 0. Возвращает:
{ envelopes: [...],
pagination: { limit, offset, count, has_more, next_offset, total },
filtered_by_pat_scope: boolean }Используйте has_more, чтобы отличить обрезанный результат от полного, и
следуйте по next_offset, пока он не станет null; никогда не делайте вывод о
наличии следующих страниц из count === limit. total — число конвертов,
которые видит этот токен.
filtered_by_pat_scope равно true, когда токен ограничен конкретными
комнатами данных и этот список разрешённых сузил результат, — окно применяется
после фильтра, поэтому страницы всегда точны. Это намеренно логическое
значение, а не количество скрытых конвертов: сообщение о том, сколько
конвертов скрыто, раскрыло бы существование и объём конвертов, которые токену
видеть не разрешено.
esign_get_envelope (чтение)
Получение одного конверта с подписантами и их статусами
(pending / signed / declined). Входные данные: envelope_id. Помимо
полей инструмента создания, перечисленных выше, конверт содержит created_at,
updated_at и signatories (каждый —
{ id, email, name, status, signed_at }).
esign_sign (запись)
Подписание вашего собственного ожидающего слота подписанта — слота, адрес электронной почты которого совпадает с пользователем, владеющим токеном. Подписание не расходует квоту (конверт уже был учтён при отправке). Нужен токен с включённым параметром Подписывать документы.
Подписание выполняется двумя вызовами, чтобы помощник показал вам, что вы собираетесь подписать, прежде чем что-либо будет подписано:
- Предпросмотр. Вызовите без
confirm_token. Ничего не подписывается. Результат —dry_run: trueс конвертом, документамиdocumentsпо порядку, однимdocument_hash, охватывающим их все, подписантомsigner, переданными вами полямиfields, текстом согласия,confirm_tokenи егоexpires_at. - Подтверждение. Когда человек согласится, вызовите снова с
идентичными аргументами и этим
confirm_token. Этот вызов подписывает.
confirm_token действует один раз, только для этого токена и этих
аргументов, и истекает через пять минут. Если за это время изменились конверт,
его документы, ваше место в порядке подписания или ваши поля, подтверждение
отклоняется, и вы снова получаете предпросмотр.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
envelope_id | string (UUID) | да | Конверт для подписания. |
consent_affirmed | boolean | да | Должно быть буквально true — явное подтверждение текста согласия. Значения по умолчанию нет; если его не передать или передать false, вызов не проходит на границе протокола. |
fields | object | нет | Значения для заполнения с ключами по меткам полей; имя и дата по умолчанию подставляются, если не указаны. |
confirm_token | string | нет | Не указывайте для предпросмотра. Передайте токен, возвращённый предпросмотром, чтобы подписать. |
Подтверждение возвращает { envelope } — конверт в той же форме со списком
разрешённых полей, которую возвращает esign_create_envelope.
Возможные ошибки: FORBIDDEN, если вы не ожидающий подписант этого
конверта, CONFLICT, если конверт не открыт для подписания, — или, для
конверта sequential, если предыдущий подписант ещё не подписал. Это значения
error.code в полезной нагрузке, а не HTTP-статусы, — см.
Настройка.
Двухшаговое подтверждение добавляет следующие отказы, каждый со своим
(code: …) в сообщении:
error.code | code: | Что делать |
|---|---|---|
FORBIDDEN | GRANT_REQUIRED | Токен не может подписывать. Создайте новый с включённым параметром Подписывать документы. |
INVALID_ARGUMENT | CONFIRM_TOKEN_MALFORMED | Вызовите снова без confirm_token, чтобы получить его. |
CONFLICT | CONFIRM_TOKEN_INVALID | Токен истёк, уже использован или принадлежит другому токену. Снова выполните предпросмотр. |
CONFLICT | CONFIRM_ARGS_MISMATCH | Аргументы отличаются от аргументов предпросмотра. Снова выполните предпросмотр. |
CONFLICT | CONFIRM_STATE_CHANGED | Конверт изменился после предпросмотра. Снова выполните предпросмотр и покажите его человеку. |
CONFLICT | DOCUMENT_NOT_PINNED | Конверт был отправлен до появления закрепления документов. Подпишите его в Waafir из письма с запросом подписи. |
UNAVAILABLE | CONFIRM_UNAVAILABLE | Подтверждение временно недоступно. Повторите попытку немного позже. |
Если в макете конверта есть обязательные поля, а fields их не содержит,
вызов отклоняется с INVALID_ARGUMENT и сообщением, содержащим
(code: MISSING_REQUIRED_FIELDS). Сообщение не называет отсутствующие метки;
их показывает экран подписания в приложении. Заполните их и вызовите снова.
esign_decline (запись)
Отклонение вашего собственного ожидающего слота (окончательно — конверт
переходит в declined). Входные данные: envelope_id. Возвращает
{ id, status: "declined" }. Квоту не расходует.
esign_void_envelope (запись)
Отзыв ошибочно отправленного конверта. Это средство на случай, когда ушёл запрос подписи, который не должен был уйти: конверт перестаёт принимать подписи, все действующие гостевые ссылки для подписания немедленно аннулируются, а ожидающие подписанты больше не могут действовать.
Входные данные: envelope_id. Возвращает аннулированный конверт в той же
форме со списком разрешённых полей, которую возвращает esign_create_envelope.
- Окончательно. Аннулированный конверт нельзя отправить повторно — вместо этого создайте новый.
- Уже зафиксированные подписи и полный журнал аудита сохраняются; аннулирование не стирает то, что уже подписано.
- Допустимо, только пока конверт находится в состоянии
draft,sentилиpartially_signed. Любой другой статус возвращаетCONFLICT, а конверт, срок действия которого истёк, сообщает об этом, а не устаревший статус. - Кто может аннулировать: только человек, создавший запрос подписи, или
владелец или администратор организации. Все остальные получают
FORBIDDEN; вызывающий, который вообще не является стороной конверта, получаетNOT_FOUND, поэтому инструмент никогда не подтверждает существование конверта тому, кто не должен о нём знать. - Аннулирование не расходует квоту — и не возвращает её. Квота списывается при отправке конверта.
esign_revise_signers (запись, деструктивно)
Исправление того, кого просят подписать, без аннулирования конверта и расходования второго конверта из квоты: опечатка в адресе электронной почты, пропущенный контрагент, неверный порядок подписания. Конверт сохраняет свой идентификатор, журнал аудита и единицу квоты. Квоту не расходует.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
envelope_id | string (UUID) | да | Конверт для изменения. |
signatories | array | да | Полный список подписантов, который должен получиться в конверте, в порядке подписания: от 1 до 50 объектов { "email": string, "name"?: string }. Он заменяет текущий список. |
signing_mode | "parallel" | "sequential" | нет | Изменить порядок подписания. Если не указан, текущий режим сохраняется; он не сбрасывается на "parallel". |
observers | array | нет | Полный список наблюдателей (копия), до 20. Если не указан, текущие наблюдатели сохраняются; наблюдатель, которого вы не включили, удаляется, и его ссылка только для чтения перестаёт работать. |
Это деструктивная операция. Подписант, которого вы не включили в
signatories, удаляется: его приглашение отзывается, его ссылка для
подписания сразу перестаёт работать, и его об этом не уведомляют. Все поля,
размещённые для него, удаляются. Подписант, который уже есть в конверте,
сохраняет свою ссылку и повторно письмо не получает. Новый подписант
приглашается сразу, если конверт уже отправлен. Инструмент помечен
destructiveHint: true, поэтому клиент, подтверждающий деструктивные вызовы,
спросит перед его запуском.
- Только до первой подписи. Как только кто-либо подписал, список
подписантов и режим подписания замораживаются: вызов отклоняется с
CONFLICT(code: ESIGN_SIGNERS_FROZEN), и решение — аннулировать конверт и создать новый. Конверт с истёкшим сроком действия также отклоняется сCONFLICT. - Изменение только наблюдателей. Передайте неизменённый список подписантов
(и режим) с новым списком
observers. Удалить наблюдателя можно в любое время, даже после подписания или завершения. Добавить — только пока конверт является черновиком или находится на подписании. - Кто может изменять отправленный конверт: только человек, создавший запрос
подписи, или владелец или администратор организации; все остальные получают
FORBIDDEN. Черновик может изменить любой, кто его видит. - Остальные отказы содержат причину в сообщении: повторяющийся адрес
(
ESIGN_DUPLICATE_SIGNATORY) или пустой список (ESIGN_EMPTY_ROSTER) — этоINVALID_ARGUMENT; новый подписант или наблюдатель в отправленном конверте, если вы не можете читать все охватываемые им документы, — этоFORBIDDEN.
Возвращает конверт в той же форме, что и
esign_get_envelope, плюс сводку revision о том,
что изменилось (и observer_revision, если были переданы наблюдатели).
esign_list_my_pending_signatures (чтение)
Список конвертов, ожидающих вашей собственной подписи в этой организации:
все открытые конверты с ожидающим слотом подписанта, совпадающим с адресом
электронной почты владельца токена. Это самый полезный запрос на чтение перед
esign_sign.
Входных данных нет. Возвращает
{ envelopes: [{ id, file_id, document_name, status, created_at }] }.
Ограничен организацией этого токена и, если токен ограничен, его списком разрешённых комнат данных — ожидающие подписи в других организациях никогда не показываются, даже если вы там подписант.
esign_download_signed (чтение)
Получение краткосрочного предподписанного URL для скачивания подписанного PDF.
Входные данные: envelope_id. Возвращает { download_url, expires_in_seconds }.
В конверте должна быть хотя бы одна зафиксированная подпись; подписанный PDF
также доступен в продукте как новейшая версия исходного файла. Нужен токен с
включённым параметром Читать содержимое документа; без него вызов
отклоняется с GRANT_REQUIRED.
esign_quota_status (чтение)
Входных данных нет. Возвращает { quota, used, remaining } за текущий
календарный месяц — общую квоту конвертов (пакет тарифа + приобретённые
единицы), отправленные конверты и запас до потолка.
esign_remind (запись)
Входные данные envelope_id. Повторно отправляет письмо каждому ожидающему
подписанту конверта, находящегося на подписании, и копию каждому наблюдателю —
не чаще одного раза в час на конверт. Нужно разрешение Отправлять людям вне вашей организации, и выполняется в два шага: первый вызов ничего не
отправляет и возвращает, кому будет отправлено письмо (наблюдателей — по
имени), плюс confirm_token; вызовите снова с ним. Если за это время добавлен
наблюдатель, подтверждение не проходит. Только для участников команды сделки.
esign_resend_signatory (запись)
Входные данные envelope_id, signatory_id. Снимает отметку о недоставке или
блокировке адреса и снова отправляет письмо этому подписанту. То же разрешение
и те же два шага, что и у esign_remind.
esign_send_draft (запись)
Входные данные envelope_id. Отправляет сохранённый черновик: каждый подписант
получает юридически обязывающий запрос подписи, каждый наблюдатель — копию, и
расходуется один конверт квоты. То же разрешение и те же два шага;
предпросмотр называет подписантов, наблюдателей и вашу квоту, и отправляются
именно те подписанты и наблюдатели, которых вы видели в предпросмотре.
Результат перечисляет все адреса suppressed, на которые письмо не было
отправлено.
esign_preview (чтение)
Входные данные envelope_id. Возвращает конверт так, как его показывает панель
подписания:
{ envelope_id, status, file_id, document_name, is_creator, signers, placed, fields, shows_signed_output, shows_live_source }. document_name равно null,
если вам не разрешено читать документ. Содержимое документа не возвращается.
Только для участников команды сделки.
esign_verify (чтение)
Входные данные envelope_id. Возвращает сводку о сертификате и целостности,
которую показывает страница проверки Waafir. Только для участников команды
сделки.
Юридическая сила
Подписи являются усиленными электронными подписями (Advanced Electronic Signatures, PAdES) по eIDAS и действительны для NDA и договоров в соответствии с US ESIGN/UETA и EU eIDAS. Согласие подписанта (IP, user agent, метка времени) фиксируется в момент подписания в журнале аудита Waafir, который допускает только добавление записей и связан цепочкой хешей. Конверты, созданные или отправленные через этот MCP-сервер, фиксируются в этом журнале как действия, инициированные токеном, поэтому отправку, инициированную агентом, всегда можно отличить от отправки, выполненной человеком в приложении. Квалифицированные подписи (QES) в этот выпуск не входят.