DocuSign API: Как получить список всех шаблонов в определенной папке?

Введение в шаблоны DocuSign и API

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

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

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

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

Понимание шаблонов DocuSign

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

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

Начало работы с API DocuSign

Чтобы использовать API DocuSign, разработчикам необходима активная учетная запись DocuSign и учетные данные API. DocuSign предоставляет бесплатную среду-песочницу для тестирования, которая отражает производственные возможности. Аутентификация обычно включает OAuth 2.0, и вы можете сгенерировать ключ интеграции (идентификатор клиента) и секретный ключ из центра разработчиков DocuSign.

Ключевые конечные точки для шаблонов находятся в API eSignature, в частности, ресурс /accounts/{accountId}/templates. Вам потребуется идентификатор учетной записи, который можно получить через конечную точку /accounts. Папки в DocuSign идентифицируются уникальными идентификаторами папок, которые можно получить с помощью конечной точки /folders. Такая настройка обеспечивает безопасный и масштабируемый доступ к данным шаблонов.

Документация API DocuSign является всеобъемлющей и поддерживает SDK для таких языков, как Java, .NET, PHP и Python, что упрощает интеграцию. Для предприятий это означает, что электронные подписи могут быть встроены в CRM-системы (например, Salesforce) или пользовательские приложения, повышая операционную эффективность без необходимости переключения между инструментами.

Как использовать API DocuSign для получения шаблонов из определенной папки

Получение списка шаблонов из определенной папки с помощью DocuSign REST API — это простой процесс. Эта функциональность особенно полезна для приложений, которым необходимо динамически заполнять параметры шаблонов или проверять содержимое папок. Основной конечной точкой является GET /accounts/{accountId}/folders/{folderId}/templates, которая возвращает постраничный список шаблонов в указанной папке.

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

Прежде чем углубляться в код, убедитесь, что:

• У вас есть токен доступа OAuth 2.0.
• Известны идентификатор учетной записи и идентификатор папки. Чтобы получить идентификатор папки, сначала вызовите GET /accounts/{accountId}/folders, чтобы перечислить все папки и определить нужную (например, по имени или статусу общего доступа).
• Разрешения: API-пользователь должен иметь доступ на чтение шаблонов.

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

1. Аутентификация и получение токена: Используйте поток OAuth для получения токена доступа. Например, с помощью DocuSign eSignature SDK в Python:

   import docusign_esign as ds_esign
   
   # Настройка API-клиента
   api_client = ds_esign.ApiClient()
   api_client.host = 'https://demo.docusign.net/restapi'  # Используйте demo для тестирования
   api_client.set_default_header('Authorization', 'Bearer ' + access_token)
   

2. Получение идентификатора папки: Если идентификатор папки неизвестен, перечислите папки:

   envelopes_api = ds_esign.EnvelopesApi(api_client)
   folders = envelopes_api.list_folders(account_id)
   # Итерация для поиска папки по имени, например folder_id = next(f['folderId'] for f in folders if f['folderName'] == 'My Templates Folder')
   

3. Перечисление шаблонов в папке: Используйте Templates API для получения шаблонов:

   templates_api = ds_esign.TemplatesApi(api_client)
   template_list = templates_api.list_templates(account_id, folder=folder_id, count=100)  # Настройте count для разбиения на страницы
   for template in template_list.envelopes:
       print(f"Template Name: {template.name}, ID: {template.template_id}")
   

   Это вернет такие сведения, как имя шаблона, идентификатор, статус общего доступа и дата последнего изменения. Ответ имеет формат JSON, содержащий массив envelopes с кратким описанием шаблонов.

4. Обработка разбиения на страницы и ошибок: Если в папке больше шаблонов, чем указано в количестве (по умолчанию 20, максимум 100), используйте параметр запроса start_position для получения последующих страниц. Распространенные ошибки включают 401 (не авторизован) или 404 (папка не найдена) — всегда включайте обработку ошибок:

   try:
       template_list = templates_api.list_templates(account_id, folder=folder_id)
   except ds_esign.ApiException as e:
       print(f"Error: {e.body}")
   

5. Расширенная фильтрация: Добавьте параметры запроса, такие как search_text для фильтрации по имени или include для включения общих шаблонов. Для корпоративных пользователей это хорошо сочетается с интеграцией веб-хуков для обновлений в режиме реального времени при изменении шаблонов.

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

Пример использования

Представьте себе юридическую фирму, интегрирующую DocuSign со своей системой управления делами. API извлекает шаблоны из папки «Contracts», автоматически заполняя их в зависимости от типа дела, обеспечивая тем самым соответствие требованиям и скорость.

Лучшие практики управления шаблонами с помощью API

При реализации этой функциональности API приоритетом является безопасность, использование JWT или кода авторизации для получения токенов и их регулярная ротация. Используйте кэширование для ограничения вызовов API, чтобы избежать ограничений скорости (например, 1000 вызовов в час в производственной среде). Для масштабируемости используйте веб-хуки DocuSign Connect для уведомления вашего приложения о новых шаблонах без необходимости опроса.

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

Сравнение DocuSign с конкурентами

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

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

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

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

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

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

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

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

Заключение

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