Waafir
Эта страница переведена машинным способом и ожидает проверки человеком. Возможны неточности.

Справочник 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_idstring (UUID)даФайл для подписания. Должен принадлежать вашей организации.
signatoriesarrayдаОт 1 до 50 объектов { "email": string, "name"?: string }. Принимается любой адрес — подписантам не нужно быть пользователями Waafir; внешние адреса получают гостевую ссылку для подписания.
transaction_idstring (UUID)нетУстарел и игнорируется. Принимается, чтобы существующие интеграции продолжали работать; прекратите его передавать.
sendbooleanнетЕсли true, сразу открыть конверт для подписания — в два шага (см. ниже). Нужен токен с разрешением Отправлять людям вне вашей организации.
confirm_tokenstringнетТолько с send: true: токен из вызова предпросмотра.
confirm_sendbooleanнетУстарел и игнорируется: send: true теперь принимает confirm_token.
signing_mode"parallel" | "sequential"нетПорядок подписания. "parallel" — по умолчанию: подписанты могут подписывать в любом порядке, а при отправке письма уходят всем сразу. "sequential" отправляет письмо только первому и допускает каждого следующего подписанта, когда подписали все предыдущие; подписание вне очереди отклоняется с CONFLICT. Отсутствие параметра — или опечатка signingMode — означает "parallel".
field_layoutarrayнетПереопределение макета размещения полей; не указывайте для макета по умолчанию.
observersarrayнетДо 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 (запись)

Подписание вашего собственного ожидающего слота подписанта — слота, адрес электронной почты которого совпадает с пользователем, владеющим токеном. Подписание не расходует квоту (конверт уже был учтён при отправке). Нужен токен с включённым параметром Подписывать документы.

Подписание выполняется двумя вызовами, чтобы помощник показал вам, что вы собираетесь подписать, прежде чем что-либо будет подписано:

  1. Предпросмотр. Вызовите без confirm_token. Ничего не подписывается. Результат — dry_run: true с конвертом, документами documents по порядку, одним document_hash, охватывающим их все, подписантом signer, переданными вами полями fields, текстом согласия, confirm_token и его expires_at.
  2. Подтверждение. Когда человек согласится, вызовите снова с идентичными аргументами и этим confirm_token. Этот вызов подписывает.

confirm_token действует один раз, только для этого токена и этих аргументов, и истекает через пять минут. Если за это время изменились конверт, его документы, ваше место в порядке подписания или ваши поля, подтверждение отклоняется, и вы снова получаете предпросмотр.

ПолеТипОбязательноОписание
envelope_idstring (UUID)даКонверт для подписания.
consent_affirmedbooleanдаДолжно быть буквально true — явное подтверждение текста согласия. Значения по умолчанию нет; если его не передать или передать false, вызов не проходит на границе протокола.
fieldsobjectнетЗначения для заполнения с ключами по меткам полей; имя и дата по умолчанию подставляются, если не указаны.
confirm_tokenstringнетНе указывайте для предпросмотра. Передайте токен, возвращённый предпросмотром, чтобы подписать.

Подтверждение возвращает { envelope } — конверт в той же форме со списком разрешённых полей, которую возвращает esign_create_envelope.

Возможные ошибки: FORBIDDEN, если вы не ожидающий подписант этого конверта, CONFLICT, если конверт не открыт для подписания, — или, для конверта sequential, если предыдущий подписант ещё не подписал. Это значения error.code в полезной нагрузке, а не HTTP-статусы, — см. Настройка.

Двухшаговое подтверждение добавляет следующие отказы, каждый со своим (code: …) в сообщении:

error.codecode:Что делать
FORBIDDENGRANT_REQUIREDТокен не может подписывать. Создайте новый с включённым параметром Подписывать документы.
INVALID_ARGUMENTCONFIRM_TOKEN_MALFORMEDВызовите снова без confirm_token, чтобы получить его.
CONFLICTCONFIRM_TOKEN_INVALIDТокен истёк, уже использован или принадлежит другому токену. Снова выполните предпросмотр.
CONFLICTCONFIRM_ARGS_MISMATCHАргументы отличаются от аргументов предпросмотра. Снова выполните предпросмотр.
CONFLICTCONFIRM_STATE_CHANGEDКонверт изменился после предпросмотра. Снова выполните предпросмотр и покажите его человеку.
CONFLICTDOCUMENT_NOT_PINNEDКонверт был отправлен до появления закрепления документов. Подпишите его в Waafir из письма с запросом подписи.
UNAVAILABLECONFIRM_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_idstring (UUID)даКонверт для изменения.
signatoriesarrayдаПолный список подписантов, который должен получиться в конверте, в порядке подписания: от 1 до 50 объектов { "email": string, "name"?: string }. Он заменяет текущий список.
signing_mode"parallel" | "sequential"нетИзменить порядок подписания. Если не указан, текущий режим сохраняется; он не сбрасывается на "parallel".
observersarrayнетПолный список наблюдателей (копия), до 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) в этот выпуск не входят.