DocuSign API: Как аннулировать конверт без отправки уведомлений по электронной почте?

Введение в DocuSign API и управление конвертами

В постоянно развивающемся ландшафте цифрового документооборота API DocuSign выделяется как мощный инструмент, позволяющий разработчикам интегрировать функциональность электронной подписи в бизнес-приложения. Конверты (Envelopes), содержащие документы для подписи, являются центральным элементом этой экосистемы, обеспечивая беспрепятственное управление соглашениями от создания до завершения. Однако в некоторых случаях возникает необходимость в аннулировании конверта — отмене его до или во время процесса подписания — для исправления ошибок или адаптации к меняющимся потребностям бизнеса. Ключевой задачей для пользователей API является контроль уведомлений, особенно избежание нежелательных электронных писем, которые могут сбить с толку получателей. В этой статье рассматриваются механизмы аннулирования конвертов через DocuSign API с минимизацией прерываний, со ссылкой на официальную документацию и практические примеры.

Сравниваете платформы электронной подписи с DocuSign или Adobe Sign?

eSignGlobal предлагает более гибкое и экономичное решение для электронной подписи с глобальным соответствием, прозрачным ценообразованием и более быстрой адаптацией.

👉 Начните бесплатную пробную версию

Аннулирование конверта в DocuSign: основные понятия

Что такое конверт в DocuSign?

Конверт в DocuSign представляет собой полный пакет, содержащий один или несколько документов, получателей и инструкции по подписанию. Через API разработчики могут программно создавать, отправлять и управлять этими конвертами. Аннулирование конверта фактически делает его недействительным, предотвращая дальнейшие действия, такие как подписание. Это полезно в бизнес-процессах, когда, например, сделка срывается или документ требует пересмотра, предотвращая продолжение неполных или ошибочных процессов.

REST API DocuSign (версия 2.1) предоставляет конечные точки для операций с конвертами, включая метод voidEnvelope. По умолчанию аннулирование вызывает уведомления для всех получателей, информируя их по электронной почте об аннулировании. Это обеспечивает прозрачность, но может быть нежелательным в автоматизированных системах или при предварительном уведомлении о внутренних исправлениях.

Процесс аннулирования по умолчанию и поведение уведомлений

Чтобы аннулировать конверт с помощью DocuSign API, обычно отправляется PUT-запрос к конечной точке /envelopes/{envelopeId}/void. Вот базовый пример на Python с использованием DocuSign eSignature SDK:

from docusign_esign import ApiClient, EnvelopesApi

# Инициализация API-клиента
api_client = ApiClient()
api_client.host = 'https://demo.docusign.net/restapi'
api_client.set_default_header('Authorization', 'Bearer YOUR_ACCESS_TOKEN')

envelopes_api = EnvelopesApi(api_client)

# Аннулирование конверта
void_request = {
    'status': 'voided',
    'voidedReason': 'Document needs revision before sending'
}

envelopes_api.update_envelope_status(
    account_id='YOUR_ACCOUNT_ID',
    envelope_id='ENVELOPE_ID',
    envelope=None,  # Не требуется для аннулирования
    void_uri=void_request
)

В этом стандартном процессе DocuSign автоматически отправляет уведомления по электронной почте получателям, указанным в конверте, с подробным описанием статуса аннулирования и причины. Эти электронные письма включают причину аннулирования и могут содержать ссылку на конверт для справки. Согласно руководству разработчика DocuSign, это ожидаемое поведение для поддержания аудиторского следа и осведомленности пользователей, соответствующее стандартам соответствия, таким как ESIGN и eIDAS.

Однако для приложений, управляемых API, таких как интеграция CRM или инструменты пакетной обработки, отправка этих электронных писем может загромождать почтовые ящики или преждевременно раскрывать внутренние изменения. Хорошей новостью является то, что DocuSign позволяет настраивать подавление этих уведомлений, обеспечивая более контролируемый опыт.

Как аннулировать конверт без отправки уведомлений по электронной почте

Подавление уведомлений по электронной почте во время процесса аннулирования требует предварительной настройки на уровне конверта или учетной записи, поскольку сам вызов API аннулирования не имеет прямого флага «no-notify». Эта стратегия включает в себя использование настроек уведомлений DocuSign и ролей получателей для минимизации внешних коммуникаций. Этот подход особенно ценен для корпоративных пользователей с уровнями Business Pro или Advanced API, где объемы конвертов велики, а автоматизация имеет решающее значение.

Шаг 1: Настройка параметров уведомлений конверта

Перед созданием или отправкой конверта настройте правила уведомлений через API. Используйте объект notification в определении конверта, чтобы отключить электронные письма получателям об изменениях статуса, включая аннулирование. Включите в конечную точку createEnvelope Envelopes API:

{
  "notification": {
    "reminders": {
      "reminderDelay": 0,
      "reminderOffset": 0,
      "reminderFrequency": "none"
    },
    "expirations": {
      "expireAfter": 0,
      "expireWarn": 0
    },
    "recipientEmailNotification": {
      "emailSubject": "",
      "emailBlurb": "",
      "emailBody": ""
    }
  }
}

Блок recipientEmailNotification можно оставить пустым или настроить для подавления значений по умолчанию. Для конкретного контроля аннулирования убедитесь, что конверт создан в статусе «черновика» (status: 'sent' = false), что позволяет аннулировать его без первоначальных уведомлений. После аннулирования из черновика, если уведомления отключены, электронные письма не будут отправлены.

Шаг 2: Аннулирование из статуса черновика

Аннулирование конверта в режиме черновика (до отправки) по сути избегает уведомлений, поскольку получатели еще не получили никаких оповещений. Используйте тот же вызов update_envelope_status, но для конверта-черновика:

# Создание конверта как черновика
envelope_definition = {
    'status': 'created',  # Режим черновика
    'emailSubject': 'Internal Review Document',
    'documents': [...],  # Ваши документы
    'recipients': {
        'signers': [...]  # Определены, но пока не уведомлены
    },
    'notification': {  # Подавление всего
        'recipientEmailNotification': {}
    }
}

envelopes_api.create_envelope(account_id='YOUR_ACCOUNT_ID', envelope_definition=envelope_definition)

# Позже, аннулирование без отправки
void_request = {'status': 'voided', 'voidedReason': 'Internal correction'}
envelopes_api.update_envelope_status(account_id='YOUR_ACCOUNT_ID', envelope_id='DRAFT_ENVELOPE_ID', void_uri=void_request)

Этот метод гарантирует, что электронные письма не будут отправлены во время аннулирования. Для конвертов в процессе (уже отправленных) сначала верните их в черновик с помощью API correct, а затем аннулируйте — подавляя уведомления в запросе на исправление с помощью allowReassign: false и пустых полей уведомлений.

Шаг 3: Конфигурация на уровне учетной записи и расширенная конфигурация

Для более широкого контроля интегрируйте функции управления идентификацией и доступом (IAM) DocuSign, доступные в планах Enhanced или Enterprise. IAM позволяет настраивать уведомления о событиях через веб-хуки Connect API, направляя события аннулирования на ваш сервер, а не по электронной почте. Настройте конфигурацию Connect:

• Конечная точка: /accounts/{accountId}/connect
• Включите envelopeEvents для статуса «voided», но исключите доставку электронной почты.

Кроме того, для планов API (Starter за 600 долларов в год или Advanced за 5760 долларов в год) используйте веб-хуки для бесшумной обработки аннулирований. Отслеживайте прослушиватель connect на предмет событий аннулирования и реагируйте внутренне, не вызывая электронные письма DocuSign по умолчанию.

Лучшие практики и ограничения

• Тестирование: Проверяйте процессы в демонстрационной среде DocuSign, поскольку аннулирование в рабочей среде необратимо.
• Соответствие: Подавление уведомлений подходит для внутренних аннулирований, но убедитесь, что журналы аудита фиксируют причины для соответствия нормативным требованиям.
• Квоты: Планы API ограничивают количество конвертов (например, 100 в месяц для Intermediate), поэтому эффективное аннулирование помогает сохранить квоты.
• Пограничные случаи: Если конверт был частично подписан, аннулирование все равно может уведомить этих подписантов, если не настроено предварительно.

Эта техника упрощает интеграцию API, уменьшая операционный шум в сценариях с большим объемом. С точки зрения бизнеса, это повышает эффективность команд, полагающихся на DocuSign API для CRM или ERP-систем, хотя и требует предварительного планирования.

Конкурентная среда: обзор платформ электронной подписи

DocuSign лидирует на рынке электронной подписи благодаря своему комплексному набору API, включая eSignature для основной подписи и CLM (управление жизненным циклом контрактов) для сквозной обработки соглашений. Интеграция CLM включает аналитику на основе искусственного интеллекта, управление шаблонами и аналитику, что идеально подходит для предприятий, управляющих сложными контрактами. Цены начинаются с 10 долларов в месяц для Personal, но расширяются до пользовательских Enterprise для интенсивного использования API, с дополнительными функциями, такими как аутентификация, добавляющая затраты на основе использования.

Adobe Sign (теперь Adobe Acrobat Sign) дополняет экосистему документов Adobe, предлагая надежную интеграцию PDF и мобильную подпись. Он предоставляет доступ к API для автоматизации, поддерживая аннулирование через аналогичные конечные точки REST, но с собственным контролем уведомлений Adobe. Планы варьируются от 10 долларов в месяц на пользователя для Individual до 40 долларов в месяц на пользователя для Enterprise, подчеркивая бесшовные рабочие процессы с инструментами Creative Cloud. Однако для пользователей с большим объемом квоты API могут быть ограничивающими без премиальных обновлений.

eSignGlobal позиционирует себя как глобальный конкурент, соответствующий требованиям в 100 основных странах и регионах, особенно с сильными сторонами в Азиатско-Тихоокеанском регионе (APAC). Ландшафт электронной подписи в APAC характеризуется фрагментацией, высокими стандартами и строгими правилами, что контрастирует со стандартами ESIGN/eIDAS в США/ЕС. В APAC решения требуют подхода «экосистемной интеграции», включая глубокое аппаратное/API-уровневое взаимодействие с цифровыми идентификаторами от правительства к бизнесу (G2B) — техническое препятствие, выходящее далеко за рамки распространенных в западных странах методов на основе электронной почты или самодекларации. eSignGlobal превосходит в этом, бесшовно интегрируясь с iAM Smart в Гонконге и Singpass в Сингапуре для надежной проверки. Его план Essential за 16,6 долларов в месяц, позволяющий отправлять до 100 документов, неограниченное количество пользовательских мест и проверку кода доступа, обеспечивает надежную ценность на основе соответствия, при этом по цене ниже, чем у конкурентов. Платформа активно расширяется на мировых рынках, включая США и ЕС, в качестве жизнеспособной альтернативы DocuSign и Adobe Sign.

Ищете более умную альтернативу DocuSign?

eSignGlobal предлагает более гибкое и экономичное решение для электронной подписи с глобальным соответствием, прозрачным ценообразованием и более быстрой адаптацией.

👉 Начните бесплатную пробную версию

HelloSign (теперь Dropbox Sign) фокусируется на простоте, предлагая интуитивно понятный API для управления конвертами, включая параметры аннулирования, позволяющие подавлять уведомления с помощью пользовательских настроек. Он подходит для SMB, с планами от бесплатных (ограниченных) до 20 долларов в месяц на пользователя (Essentials), но ему не хватает глубины корпоративных функций, таких как расширенный IAM.

Это сравнение подчеркивает компромиссы: DocuSign превосходит по глубине, в то время как альтернативы, такие как eSignGlobal, предлагают региональные преимущества.

Региональные нюансы в реализации электронной подписи

Хотя DocuSign API доступен по всему миру, региональные различия влияют на внедрение. В APAC более строгие правила хранения данных и аутентификации усиливают потребность в локализованных решениях, как упоминалось ранее. Предприятия должны оценивать поведение API в соответствии с местным законодательством, чтобы гарантировать, что процессы аннулирования поддерживают юридическую целостность.

В заключение, освоение API DocuSign для аннулирования без уведомлений обеспечивает эффективные рабочие процессы. Для тех, кто ищет альтернативы, eSignGlobal заслуживает рассмотрения как нейтральный и соответствующий региональным требованиям вариант, особенно для операций, ориентированных на APAC.