DocuSign API: Генерация URL-адреса встроенной подписи с определенным сроком действия

Навигация по API DocuSign для безопасных встроенных подписей

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

Роль встроенных подписей в современных бизнес-процессах

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

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

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

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

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

Реализация URL-адресов встроенных подписей с помощью API DocuSign

Чтобы сгенерировать URL-адрес встроенной подписи с определенным сроком действия, разработчики должны пройти аутентификацию через OAuth 2.0 и взаимодействовать с Envelopes API DocuSign. Этот процесс включает в себя создание конверта, подготовку подписи и последующее получение временного URL-адреса для встраивания. С коммерческой точки зрения, освоение этой функции может снизить операционные издержки за счет автоматизации ручных действий и интеграции с инструментами CRM, такими как Salesforce.

Шаг 1: Аутентификация и создание конверта

Начните с получения токена доступа, используя JWT DocuSign или процесс авторизации кода авторизации. Этот токен предоставляет доступ к API на срок до 8 часов, после чего его необходимо обновить.

Создайте конверт, используя конечную точку /accounts/{accountId}/envelopes. Ниже приведен пример запроса в формате JSON через POST:

{
  "emailSubject": "Please sign this document",
  "documents": [
    {
      "documentBase64": "base64-encoded-document-content",
      "name": "Agreement.pdf",
      "fileExtension": "pdf",
      "documentId": "1"
    }
  ],
  "recipients": {
    "signers": [
      {
        "email": "signer@example.com",
        "name": "John Doe",
        "recipientId": "1",
        "routingOrder": "1"
      }
    ]
  },
  "status": "sent"
}

Это создаст базовый конверт с одним подписывающим лицом. status: "sent" немедленно запускает рабочий процесс.

Шаг 2: Добавление полей подписи и встроенных получателей

Для встроенных подписей укажите получателя как встроенного, включив clientUserId и детали аутентификации. Обновите получателей:

"signers": [
  {
    "email": "signer@example.com",
    "name": "John Doe",
    "recipientId": "1",
    "routingOrder": "1",
    "clientUserId": "unique-client-id-123",
    "userId": "signer-user-id",
    "authenticationMethod": "none",  // Или "email" для повышения безопасности
    "embedUrlEvents": {
      "url": "https://your-app.com/return-url"
    }
  }
]

clientUserId связывает сеанс с вашим приложением, гарантируя, что подписывающее лицо проходит аутентификацию в вашей среде.

Затем определите поля подписи, используя конечную точку /envelopes/{envelopeId}/recipients/{recipientId}/tabs. Для простого поля подписи:

{
  "signHereTabs": [
    {
      "documentId": "1",
      "pageNumber": "1",
      "xPosition": "100",
      "yPosition": "200",
      "width": "200",
      "height": "50",
      "recipientId": "1"
    }
  ]
}

Это поместит метку подписи на документ.

Шаг 3: Генерация URL-адреса встроенной подписи с истечением срока действия

Основным шагом является вызов конечной точки /accounts/{accountId}/envelopes/{envelopeId}/views/recipient для получения URL-адреса подписи. Укажите returnUrl для перенаправления после подписания и установите срок действия либо через параметры запроса, либо через настройки конверта.

Пример GET-запроса:

GET /accounts/{accountId}/envelopes/{envelopeId}/views/recipient?email=signer@example.com&userName=John%20Doe&returnUrl=https://your-app.com/complete

Ответ включает поле url со ссылкой на встроенную подпись, срок действия которой по умолчанию составляет 5 минут. Чтобы настроить срок действия, используйте свойство expireAfter конверта (в днях) при создании или используйте expireEnabled и expireAfterDays API в расширенных конфигурациях. Для детального контроля интегрируйтесь с Event Notifications DocuSign для мониторинга и отзыва доступа после истечения срока действия.

В коде (пример Python с использованием библиотеки requests):

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}

# Create envelope (as above)
envelope_response = requests.post(f'{base_url}/envelopes', json=envelope_data, headers=headers)
envelope_id = envelope_response.json()['envelopeId']

# Get embedded URL
url_params = {
    'email': 'signer@example.com',
    'userName': 'John Doe',
    'returnUrl': 'https://your-app.com/complete'
}
url_response = requests.get(f'{base_url}/envelopes/{envelope_id}/views/recipient', params=url_params, headers=headers)
signing_url = url_response.json()['url']

Этот URL-адрес теперь можно встроить во фрейм: <iframe src="{signing_url}" width="100%" height="600px"></iframe>. Срок действия гарантирует, что ссылка станет недействительной после установленного времени, обычно обеспечиваемого на стороне сервера для предотвращения несанкционированного доступа.

Лучшие практики и коммерческие соображения

С коммерческой точки зрения, реализация сроков действия может снизить ответственность в регулируемых отраслях. Отслеживайте использование API через панель управления DocuSign, чтобы избежать ограничений квоты — стартовый план ограничивает 40 конвертами в месяц, в то время как расширенный план за 5760 долларов в год предлагает больше. Протестируйте в режиме песочницы, чтобы обеспечить соответствие ESIGN/UETA в США или eIDAS в ЕС. Распространенные ошибки включают несоответствие clientUserId, приводящее к сбоям аутентификации, или игнорирование returnUrl, влияющее на непрерывность пользовательского потока.

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

Сравнение ведущих платформ электронных подписей

При выборе решения для электронных подписей такие факторы, как гибкость API, ценообразование и региональное соответствие требованиям, играют решающую роль. Ниже приведено нейтральное сравнение DocuSign, Adobe Sign, eSignGlobal и HelloSign (теперь Dropbox Sign) на основе общедоступных данных за 2025 год. В таблице выделены ключевые различия для поддержки принятия обоснованных решений.

Это сравнение показывает, что DocuSign превосходит в корпоративных интеграциях, но по более высокой цене, в то время как другие платформы предлагают ценность в определенных областях.

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

Adobe Sign, глубоко интегрированный с творческими и документальными рабочими процессами, предлагает встроенные подписи через свой API, а параметры истечения срока действия связаны с жизненным циклом конверта. Ценообразование начинается выше, но связка с Acrobat подходит для пользователей, интенсивно работающих с PDF.

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

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

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

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

HelloSign (теперь Dropbox Sign) отдает приоритет простоте в своем API встроенных URL-адресов, а истечение срока действия обрабатывается через настройки документа. Он экономически выгоден для небольших команд, но ему не хватает глубины автоматизации DocuSign.

Заключение: Выбор правильного решения для вашего бизнеса

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