DocuSign API: Как скачать "Объединенный" PDF и отдельные PDF-файлы?

Понимание API загрузки PDF в DocuSign

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

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

API eSignature от DocuSign является частью их более широкой экосистемы, включающей такие инструменты, как Intelligent Agreement Management (IAM) и Contract Lifecycle Management (CLM). IAM повышает безопасность благодаря таким функциям, как единый вход (SSO), расширенный аудит и аутентификация, что делает его идеальным для регулируемых отраслей, таких как финансы и здравоохранение. С другой стороны, CLM упрощает весь процесс заключения контрактов от создания до продления, интегрируясь с CRM-системами для обеспечения сквозной видимости. Эти продукты подчеркивают внимание DocuSign к соответствию требованиям и эффективности, но для разработчиков API является основой пользовательских интеграций.

Что касается загрузки PDF, API предоставляет конечные точки, позволяющие программно получать доступ к подписанным документам. Это имеет решающее значение для предприятий, автоматизирующих рабочие процессы, такие как адаптация персонала в HR или выполнение договоров купли-продажи, где быстрое получение документов может уменьшить количество ручных ошибок и ускорить процессы. Ключевое различие заключается в «Combined» PDF — который объединяет исходный документ, вложения подписантов и сертификат о завершении в один файл — по сравнению с отдельными PDF, которые разбивают конверт на отдельные компоненты, такие как подписанные формы или журналы аудита.

Методы загрузки «Combined» PDF с использованием API DocuSign

Загрузка Combined PDF через DocuSign eSignature REST API довольно проста, особенно при использовании Envelopes API. Этот метод предпочтителен в сценариях, где требуется унифицированный файл для упрощения архивирования или обмена, например, для юридической экспертизы или доставки клиенту. Ниже приведено пошаговое руководство, основанное на официальной документации API v2.1 от DocuSign:

1. Аутентификация и получение токена доступа: Начните с создания токена OAuth 2.0 JWT или используйте Authorization Code Grant. Это обеспечивает безопасные вызовы API. Для производственной среды интегрируйте это в серверную часть вашего приложения для автоматической обработки обновления токенов.

2. Получение сведений о конверте: Используйте конечную точку GET /envelopes/{envelopeId}, чтобы получить статус конверта. Убедитесь, что он находится в состоянии «completed», прежде чем продолжить. Ответ включает идентификаторы документов и сведения о получателе.

3. Запрос Combined PDF: Вызовите конечную точку GET /envelopes/{envelopeId}/documents/combined. Это вернет один PDF-файл, включающий:

   • Исходный документ с примененными подписями и полями.
   • Вложения подписантов (если есть).
   • Сертификат о завершении, суммирующий аудит подписей.

   Пример запроса cURL (замените заполнители):

   curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/combined" \
   -H "Authorization: Bearer {accessToken}" \
   -o combined.pdf
   

   Ответ представляет собой двоичный поток PDF, который можно сохранить напрямую. В коде (например, с использованием Node.js SDK от DocuSign) используйте метод EnvelopesApi.getDocument, установив для параметра combined значение true.

4. Обработка больших файлов и ошибок: Для конвертов, содержащих несколько документов, Combined PDF может превышать 25 МБ — следите за квотами API (например, стартовый план позволяет около 40 конвертов в месяц). Реализуйте обработку ошибок для ответов 404 (не найдено) или 429 (ограничение скорости).

С точки зрения бизнеса, этот метод упрощает отчетность о соответствии требованиям. Предприятия, использующие планы DocuSign Advanced или Enterprise, получают выгоду от расширенных функций, таких как интеграция Bulk Send, где Combined PDF можно использовать в массовом порядке для масштабного распространения. Однако обратите внимание, что автоматизированная отправка имеет ограничения (например, около 10 на пользователя в месяц), поэтому пользователям с большими объемами может потребоваться индивидуальное ценообразование Enterprise.

Загрузка отдельных PDF: когда и как

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

1. Перечисление документов в конверте: Запросите GET /envelopes/{envelopeId}/documents, чтобы получить список идентификаторов документов. Каждый идентификатор соответствует определенному файлу, например, основному документу (ID 1), вложению или сертификату о завершении (обычно ID -1 для сводки).

2. Загрузка отдельных PDF: Для каждого документа используйте GET /envelopes/{envelopeId}/documents/{documentId}. Укажите формат как PDF в запросе (например, ?format=pdf).

   Пример:

   curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}" \
   -H "Authorization: Bearer {accessToken}" \
   -o document_{documentId}.pdf
   

   В SDK, таком как docusign-esign для Python, переберите документы в цикле:

   api_instance = EnvelopesApi()
   results = api_instance.get_document(account_id, envelope_id, document_id, token)
   with open(f'doc_{document_id}.pdf', 'wb') as f:
       f.write(results)
   

3. Варианты использования и ограничения: Отдельные загрузки отлично подходят для модульных систем, таких как интеграция с CLM для контроля версий. Однако они требуют больше вызовов API, увеличивая задержку и стоимость (планы API начинаются с 600 долларов в год для Starter). Для конвертов с условной логикой или веб-формами (функция Business Pro) убедитесь, что вы получаете все соответствующие идентификаторы, чтобы избежать неполных наборов.

Бизнес-наблюдатели отмечают, что, хотя Combined PDF снижает накладные расходы на хранение (один файл против нескольких), отдельные PDF-файлы повышают гибкость для аналитических инструментов, анализирующих определенные разделы. В Азиатско-Тихоокеанском регионе (АТР), где правила хранения данных различаются, раздельная обработка помогает соблюдать местные требования к хранению.

Ключевые различия: Combined vs. Отдельные PDF

Это сравнение подчеркивает, почему предприятия взвешивают эффективность и потребности — Combined для скорости, отдельные для точности.

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

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

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

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

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

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

В центре внимания Adobe Sign

Adobe Sign, как часть Adobe Document Cloud, превосходно подходит для творческих и документоориентированных отраслей. Его API поддерживает загрузку Combined и отдельных PDF, аналогично DocuSign, с использованием таких конечных точек, как /agreements/{agreementId}/combinedDocument. Цены начинаются с более низкой базовой версии, но масштабируются с пользователями, что подходит для маркетинговых команд, которым требуются подписи, встроенные в PDF. Однако для достижения полной функциональности, подобной CLM, могут потребоваться дополнительные лицензии Adobe.

В центре внимания eSignGlobal

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

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

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

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

Влияние на бизнес и заключительные мысли

Для разработчиков и ИТ-руководителей освоение API загрузки PDF от DocuSign может оптимизировать рабочие процессы, но требует внимания к квотам и затратам — особенно в планах API, таких как Intermediate (3600 долларов США в год) для расширенных функций. Хотя DocuSign доминирует в корпоративном пространстве, альтернативы предлагают жизнеспособные пути для операций, чувствительных к стоимости или ориентированных на регион. В качестве нейтральной рекомендации eSignGlobal выделяется как надежная альтернатива DocuSign, особенно для региональных потребностей в соответствии с требованиями в АТР.