DocuSign API: Как предварительно заполнить теги данными, но разрешить пользователю редактировать?

Навигация по DocuSign API: предварительное заполнение полей с возможностью редактирования пользователем

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

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

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

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

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

Освоение предварительного заполнения в DocuSign API: техническое руководство

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

Ключевые концепции: вкладки и их атрибуты

Вкладки в DocuSign определяются в массиве tabs объекта signHere или text в полезной нагрузке API. Для предварительного заполнения используйте атрибут value, но для включения редактирования убедитесь, что documentId и pageNumber вкладки правильно выровнены, и избегайте флагов "только для чтения". Важно отметить, что вкладки по умолчанию не блокируются, если это явно не указано через атрибуты locked или required, что обеспечивает естественную возможность редактирования.

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

Пошаговая реализация

1. Аутентификация и подготовка конверта: Начните с получения токена доступа через OAuth 2.0. Создайте конверт, используя конечную точку /envelopes. Загрузите свой документ в виде файла, закодированного в base64, или сошлитесь на существующий шаблон.

   Пример фрагмента полезной нагрузки (JSON):

   {
     "status": "sent",
     "emailSubject": "Review and Sign Agreement",
     "documents": [
       {
         "documentBase64": "<base64-encoded-PDF>",
         "name": "Contract.pdf",
         "fileExtension": "pdf",
         "documentId": "1"
       }
     ],
     "recipients": {
       "signers": [
         {
           "email": "signer@example.com",
           "name": "John Doe",
           "recipientId": "1",
           "tabs": {
             "textTabs": [
               {
                 "tabLabel": "BuyerName",
                 "documentId": "1",
                 "pageNumber": "1",
                 "xPosition": "100",
                 "yPosition": "200",
                 "width": "150",
                 "height": "20",
                 "value": "Pre-filled Name from API",  // Предварительно заполняет поле
                 "locked": "false",  // Обеспечивает возможность редактирования
                 "required": "false"  // Необязательно; установите значение true, если обязательно
               }
             ]
           }
         }
       ]
     }
   }
   

   Здесь атрибут value внедряет данные, а locked: false (по умолчанию) позволяет подписывающему лицу редактировать. Координаты (xPosition, yPosition) точно позиционируют вкладку на PDF.

2. Обработка предварительного заполнения на основе шаблонов: Если вы используете шаблоны (через /templates/{templateId}/envelopes), сначала извлеките вкладки с помощью GET-запроса к /envelopes/{envelopeId}/documents/{documentId}/tabs. Затем измените ответ, чтобы добавить value, не изменяя tabLabel или положение. Отправьте обновленный конверт. Этот метод подходит для многократно используемых форм, сохраняя структуру при внедрении динамических данных.

3. Выполнение API-вызовов: Используйте POST к /accounts/{accountId}/envelopes с полезной нагрузкой. Такие библиотеки, как DocuSign SDK для Node.js или Python, упрощают этот процесс:

   # Пример Python с использованием библиотеки docusign-esign
   from docusign_esign import ApiClient, EnvelopesApi, EnvelopeDefinition
   
   api_client = ApiClient()
   api_client.host = 'https://demo.docusign.net/restapi'  # Используйте production для реальной работы
   envelopes_api = EnvelopesApi(api_client)
   
   envelope_definition = EnvelopeDefinition(
       status='sent',
       email_subject='Please sign',
       documents=[/* ваш документ */],
       recipients=/* с вкладками, как указано выше */
   )
   
   results = envelopes_api.create_envelope(account_id, envelope_definition)
   

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

4. Рекомендации по редактированию:

   • Проверка: используйте конечную точку validateTabs перед отправкой, чтобы проверить размещение вкладок и целостность данных.
   • Условная логика: для сложных случаев интегрируйтесь с функциями Business Pro через API для применения правил (например, отображать редактируемые поля только в том случае, если предварительно заполненные значения соответствуют условиям).
   • Обработка ошибок: если предварительное заполнение не удается (например, несоответствие вкладок), API возвращает ошибку 400 — регистрируйте их для отладки.
   • Тестирование: всегда используйте песочницу разработчика DocuSign. Обратите внимание на квоты конвертов: планы Starter API позволяют отправлять около 40 в месяц, расширяясь по мере повышения уровня до Premium за 5760 долларов в год.

5. Распространенные ошибки и решения:

   • Чрезмерная блокировка: если вкладка отображается как нередактируемая, убедитесь, что не применяется readOnly или пользовательская проверка. Решение: явно установите editable: true в атрибутах вкладки.
   • Перезапись данных: изменения подписывающего лица плавно перезаписывают значения API, но отслеживайте через originalValue, если требуется соответствие требованиям.
   • Сценарии с несколькими подписывающими лицами: назначайте вкладки по recipientId; предварительно заполняйте только для соответствующих подписывающих лиц, чтобы избежать путаницы.
   • Примечания о соответствии требованиям: предварительно заполненные данные должны соответствовать таким правилам, как ESIGN Act (США) или eIDAS (ЕС), обеспечивая захват изменений в журнале аудита.

Этот процесс обычно занимает 10-20 минут для базовой интеграции, а полная настройка увеличивает сложность. Предприятия сообщают об увеличении скорости подписания на 30-40% после реализации, согласно тематическим исследованиям DocuSign.

Преимущества в бизнес-контексте

Предварительное заполнение редактируемых вкладок упрощает адаптацию, заявки на кредиты и соглашения с поставщиками. Например, в сфере недвижимости агенты могут автоматически заполнять информацию о покупателе из данных MLS, позволяя вносить корректировки на месте. Он также хорошо интегрируется с CRM, такими как Salesforce, уменьшая разрозненность данных.

Обзор DocuSign и его экосистемы

DocuSign является лидером в области электронных подписей с 2003 года, предлагая полный набор, включающий eSignature, CLM (управление жизненным циклом контрактов) и API-инструменты. Его API обеспечивает плавную интеграцию, поддерживая более 1000 приложений. Цены начинаются с 10 долларов в месяц для личного использования, расширяясь до 40 долларов в месяц на пользователя для Business Pro, а планы API начинаются с 600 долларов в год. Расширенные функции, такие как Bulk Send и аутентификация, увеличивают стоимость использования, что делает его подходящим для предприятий, которым требуется надежная автоматизация.

IAM (управление идентификацией и доступом) DocuSign повышает безопасность с помощью SSO и журналов аудита, в то время как CLM автоматизирует переговоры по контрактам, извлечение и анализ — идеально подходит для юридических команд, работающих с большими объемами контрактов.

Конкурентная среда: Adobe Sign, eSignGlobal и HelloSign

Adobe Sign: интеграция для предприятий

Adobe Sign, часть Adobe Document Cloud, превосходно работает в рабочих процессах, ориентированных на PDF, с глубокой интеграцией с Acrobat. Он поддерживает предварительное заполнение с редактируемым заполнением с использованием тегов полей через API, аналогичный DocuSign. Цены начинаются с 10 долларов в месяц на пользователя для личного использования, до 40 долларов в месяц на пользователя для команд, с индивидуальными предложениями для предприятий. Преимущества включают заполнение форм на основе искусственного интеллекта и мобильные подписи, но квоты API могут быть ограничены для больших объемов использования. Он соответствует глобальным стандартам, таким как ESIGN и eIDAS, что делает его подходящим для творческих и документоориентированных отраслей.

eSignGlobal: глобальный игрок, ориентированный на Азиатско-Тихоокеанский регион

eSignGlobal позиционирует себя как универсальную альтернативу, соответствующую требованиям в 100 основных странах мира, особенно преуспевая в Азиатско-Тихоокеанском регионе (АТР). Ландшафт электронных подписей в АТР фрагментирован, с высокими стандартами и строгими правилами — в отличие от более основанных на фреймворках моделей ESIGN (США) или eIDAS (ЕС), которые полагаются на проверку электронной почты или самозаявление. АТР требует подхода "интеграции экосистемы", требующего глубокой аппаратной/API интеграции с цифровыми идентификаторами от правительства к бизнесу (G2B), что повышает технологические барьеры намного выше западных стандартов.

eSignGlobal решает эту проблему с помощью встроенной поддержки таких систем, как iAM Smart в Гонконге и Singpass в Сингапуре, обеспечивая плавные и соответствующие требованиям рабочие процессы. Он активно расширяется в Европе и Америке, чтобы конкурировать с DocuSign и Adobe Sign, предлагая конкурентоспособные цены: план Essential за 16,6 долларов в месяц позволяет отправлять до 100 документов, неограниченное количество пользовательских мест и проверку с помощью кодов доступа — обеспечивая высокую ценность соответствия требованиям без взимания платы за место. Эта модель привлекает расширяющиеся команды в регулируемых отраслях, таких как финансы и HR.

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

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

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

HelloSign (теперь Dropbox Sign): простота для малого и среднего бизнеса

HelloSign, приобретенный Dropbox в 2019 году, фокусируется на удобных для пользователя подписях и поддерживает предварительное заполнение редактируемых полей API через шаблоны. Он высоко ценится за быструю настройку и интеграцию с Google Workspace. Цены начинаются с бесплатного уровня (3 документа в месяц), затем Essentials за 15 долларов в месяц, до Premium за 25 долларов в месяц на пользователя. Хотя он соответствует ESIGN/UETA, ему не хватает некоторых функций корпоративного уровня, таких как расширенный IAM, что делает его подходящим для малого бизнеса, но недостаточно надежным для глобальных требований соответствия.

Сравнительная таблица платформ электронных подписей

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

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

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