DocuSign API: Как получить статус конкретного получателя в конверте?

Понимание статуса получателя в конверте DocuSign

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

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

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

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

Зачем отслеживать статус получателя через DocuSign API?

Предприятия интегрируют API DocuSign для оптимизации операций, но распространенной проблемой является мониторинг действий отдельных получателей в режиме реального времени. В DocuSign "конверт" относится к контейнеру, используемому для отправки одного или нескольких документов на подпись, который может включать нескольких получателей с последовательной или параллельной маршрутизацией. Статус получателя - например, "Отправлено", "Доставлено", "Подписано", "Отклонено" или "Аннулировано" - дает представление о состоянии рабочего процесса. Например, в многостороннем контракте, если ключевой утверждающий не отвечает, можно запустить автоматические уведомления, чтобы подтолкнуть его к продвижению.

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

Пошаговое руководство: получение статуса получателя с помощью DocuSign API

Чтобы получить статус конкретного получателя в конверте, вы будете использовать DocuSign eSignature REST API (версия 2.1 или выше). Этот процесс требует аутентификации через OAuth 2.0 и базового понимания конечных точек API. Ниже приведено практическое руководство, предполагающее, что у вас есть учетная запись разработчика и токен доступа к API.

Предварительные условия

• Учетные данные API: Получите свой ключ интеграции (Client ID), секретный ключ и идентификатор пользователя из центра разработчиков DocuSign. Настройте аутентификацию JWT или Auth Code Grant.
• Инструменты: Используйте Postman, cURL или язык программирования, такой как Python/Node.js, в сочетании с DocuSign SDK.
• ID конверта: Вам потребуется уникальный ID конверта (генерируется при создании через API или веб-приложение).
• ID получателя или электронная почта: Определите конкретного получателя по его роли (например, "signer1") или электронной почте.

Шаг 1: Аутентификация и получение токена доступа

Сначала получите токен доступа. Для аутентификации JWT (рекомендуется для приложений типа "сервер-сервер"):

curl -X POST "https://account-d.docusign.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=YOUR_JWT_TOKEN"

Замените YOUR_JWT_TOKEN на base64-закодированную полезную нагрузку JWT. Ответ включает access_token со сроком действия около часа.

Шаг 2: Вызов конечной точки Envelopes:Recipients

Используйте конечную точку GET /envelopes/{envelopeId}/recipients для получения подробной информации обо всех получателях, включая статус.

• URL конечной точки: https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
  • Замените {accountId} на ID вашей учетной записи DocuSign.
  • Замените {envelopeId} на ID целевого конверта.
• Заголовки:
  • Authorization: Bearer {access_token}
  • Accept: application/json

Пример запроса cURL:

curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients" \
  -H "Authorization: Bearer {access_token}"

Шаг 3: Разбор ответа для получения конкретного получателя

JSON-ответ возвращает массив получателей в recipients.signers или recipients.carbonCopies и т.д. Найдите соответствующего получателя по email или recipientId.

Пример фрагмента ответа:

{
  "recipients": {
    "signers": [
      {
        "email": "recipient@example.com",
        "recipientId": "1",
        "status": "signed",
        "signedDateTime": "2025-01-15T10:30:00Z",
        "deliveryStatus": "delivered"
      }
    ]
  },
  "envelopeId": "{envelopeId}"
}

Обратите внимание на ключевые поля:

• status: Основной индикатор (например, "sent", "viewed", "signed", "declined", "faxpending").
• declineReason: Если отклонено, то объяснение причины.
• signedDateTime: Временная метка операции.
• errorDetails: Любые возникшие проблемы.

Для конкретного получателя отфильтруйте массив на стороне клиента. Если вы знаете recipientId, используйте целевую конечную точку: GET /envelopes/{envelopeId}/recipients/{recipientId} для получения более точной информации.

Шаг 4: Обработка крайних случаев и лучшие практики

• Обработка ошибок: Обратите внимание на HTTP 401 (сбой аутентификации) или 404 (недействительный ID). Реализуйте повторные попытки для ограничения скорости (100 вызовов/минуту для демонстрационных учетных записей).
• Опрос для обновления в реальном времени: Статус не обновляется мгновенно; опрашивайте конечную точку каждые 30-60 секунд или используйте DocuSign Connect (Webhook) для уведомлений, управляемых событиями.
• Безопасность: Всегда используйте HTTPS и ограничьте область действия токена до signature.
• Тестирование: Начните в демонстрационной среде (demo.docusign.net), чтобы избежать реальных затрат. Для производственной среды используйте na3.docusign.net или URL-адрес конкретного региона.

В коде библиотеки, такие как Python SDK, упрощают этот процесс:

from docusign_esign import ApiClient, EnvelopesApi

api_client = ApiClient()
api_client.host = "https://demo.docusign.net/restapi"
api_client.set_default_header("Authorization", f"Bearer {access_token}")

envelopes_api = EnvelopesApi(api_client)
recipients = envelopes_api.get_recipients(account_id, envelope_id)
specific_recipient = next(r for r in recipients.signers if r.email == "recipient@example.com")
print(specific_recipient.status)

Этот подход очень эффективен для интеграции с CRM-системами, такими как Salesforce, или пользовательскими приложениями, позволяя предприятиям автоматизировать оповещения или панели отчетов.

Коммерческие сведения: использование API в экосистеме электронных подписей

Цены на API DocuSign начинаются с 600 долларов в год для плана Starter (40 конвертов в месяц) и расширяются до пользовательских корпоративных вариантов для больших объемов. Хотя он и мощный, он требует тщательного управления квотами - автоматизированная отправка, такая как пакетные операции, ограничена примерно 100 в год на пользователя. Для предприятий Азиатско-Тихоокеанского региона задержки при трансграничной передаче данных могут повлиять на скорость реагирования API, что побуждает к оценке региональных альтернатив.

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

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

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

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

Изучение альтернатив: Adobe Sign, eSignGlobal и HelloSign

Adobe Sign предлагает надежный API, аналогичный DocuSign, для отслеживания статуса, используя такие конечные точки, как /agreements/{agreementId}/participants для запроса статуса подписывающего. Он высоко ценится в отраслях с интенсивным использованием документов, но может показаться менее гибким для сложной маршрутизации.

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

HelloSign предлагает простой вызов API для статуса получателя через /agreement/recipients, хорошо интегрированный с Dropbox для управления файлами. Он удобен для небольших команд, но ему не хватает глубины автоматизации корпоративного уровня по сравнению с DocuSign.

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

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

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

Заключительные мысли о выборе электронной подписи

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