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

Эффективное управление навигацией по конвертам в DocuSign API

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

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

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

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

Понимание конвертов и пользовательских полей в DocuSign API

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

С коммерческой точки зрения, использование пользовательских полей для поиска может улучшить управление данными. Предприятия в регулируемых отраслях, таких как финансы или здравоохранение, могут использовать их для фильтрации конвертов на основе меток соответствия, обеспечивая быстрый доступ во время аудита. API DocuSign, являющийся частью его платформы для разработчиков, поддерживает эту функциональность через RESTful endpoints, а уровни цен, такие как план Intermediate (3600 долларов США в год), предоставляют до 100 конвертов в месяц для таких операций.

Пошаговое руководство: поиск конвертов по значениям пользовательских полей

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

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

1. Получите доступ к API: зарегистрируйтесь в песочнице разработчика DocuSign на developer.docusign.com. Сгенерируйте ключ интеграции (идентификатор клиента) и секретный ключ для аутентификации OAuth. Для производственной среды перейдите на платный план — план Starter (600 долларов США в год) подходит для базового поиска.

2. Определите пользовательские поля: при создании конверта добавьте пользовательские поля через API. Используйте объект customFields в определении конверта. Например:

   {
     "status": "sent",
     "emailSubject": "Agreement for Review",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   Это встраивает "CLI-12345" в качестве значения, доступного для поиска, в поле "ClientID".

3. Аутентификация: используйте JWT или процесс предоставления кода авторизации. Пример запроса JWT на Python (с использованием библиотеки requests):

   import requests
   import jwt
   import time
   
   def get_jwt_token(integration_key, user_id, rsa_key, account_id):
       claim = {
           "iss": integration_key,
           "sub": user_id,
           "aud": "account-docusigncom",
           "iat": int(time.time()),
           "exp": int(time.time()) + 3600,
           "scope": "signature impersonation"
       }
       token = jwt.encode(claim, rsa_key, algorithm='RS256')
       response = requests.post(
           "https://account-docusign.com/oauth/token",
           headers={"Authorization": f"Bearer {token}"},
           data={
               "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
               "assertion": token
           }
       )
       return response.json()["access_token"]
   

   Замените заполнители своими учетными данными. Этот токен используется для аутентификации последующих вызовов API.

Выполнение поиска

Ключевой endpoint — GET /accounts/{accountId}/envelopes/search, но для фильтрации по пользовательским полям объедините параметры запроса или используйте более гибкий GET /envelopes с критериями поиска. API поиска DocuSign позволяет выполнять запросы по пользовательским полям с помощью параметра searchText, который сопоставляет метаданные конверта, включая пользовательские значения.

• Базовый endpoint поиска: используйте GET /accounts/{accountId}/envelopes?search_text={value}. Это сканирует темы, имена и пользовательские поля конвертов.

  Для точного соответствия пользовательским полям используйте параметр query в расширенном поиске. Однако для прямых запросов по пользовательским полям требуются разрешения Envelopes: listStatusChanges или аналогичные.

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

  curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes?search_text=CLI-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
  

  Фрагмент ответа:

  {
    "envelopes": [
      {
        "envelopeId": "abc-123-def",
        "status": "completed",
        "customFields": {
          "textCustomFields": [
            {
              "name": "ClientID",
              "value": "CLI-12345"
            }
          ]
        }
      }
    ]
  }
  

• Расширенная фильтрация с использованием пользовательских полей: для конкретного поиска конвертов сначала извлеките конверты в диапазоне дат или статусе, а затем отфильтруйте на стороне клиента. DocuSign рекомендует объединять параметры fromDate и toDate с search_text для повышения эффективности. Если ваш объем превышает квоты (например, 100 конвертов в месяц для плана Intermediate), рассмотрите возможность обновления до Advanced (5760 долларов США в год) для получения функций пакетной обработки.

  В коде проанализируйте ответ, чтобы сопоставить точные значения пользовательских полей:

  import json
  
  response = requests.get(
      f"https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json"
      },
      params={"search_text": "CLI-12345", "from_date": "2025-01-01T00:00:00Z"}
  )
  envelopes = response.json()["envelopeSummary"]["envelopes"]
  matching_envelopes = [
      env for env in envelopes
      if any(cf["name"] == "ClientID" and cf["value"] == "CLI-12345" for cf in env.get("customFields", {}).get("textCustomFields", []))
  ]
  print(json.dumps(matching_envelopes, indent=2))
  

Лучшие практики и ограничения

• Квоты и затраты: поиск учитывается в лимитах API конвертов. Превышение приведет к дополнительным сборам или потребует индивидуальной настройки Enterprise.
• Безопасность: всегда используйте HTTPS и контроль доступа на основе ролей, чтобы предотвратить несанкционированные запросы.
• Обработка ошибок: распространенные проблемы включают 401 (недействительный токен) или 400 (недействительный запрос). Регистрируйте ответы для отладки.
• Масштабируемость: для поиска больших объемов интегрируйтесь с веб-хуками DocuSign Connect для отправки обновлений, уменьшая потребность в опросе.

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

DocuSign: лидер рынка решений для электронной подписи

DocuSign является пионером в области электронной подписи с 2004 года, предлагая комплексные инструменты управления документами. Его платформа электронной подписи включает планы от Personal (120 долларов США в год) до Business Pro (480 долларов США в год на пользователя), а доступ к API предоставляется через отдельные планы для разработчиков. Ключевые функции включают шаблоны, массовую отправку и интеграцию с более чем 400 приложениями. Для расширенных потребностей Intelligent Agreement Management (IAM) от DocuSign объединяет CLM (управление жизненным циклом контрактов) с аналитикой на основе искусственного интеллекта, автоматизируя пересмотр и оценку рисков. IAM подходит для предприятий, хотя цены являются индивидуальными и могут увеличиваться в зависимости от количества мест и конвертов.

Adobe Sign: мощная интеграция для корпоративных рабочих процессов

Adobe Sign, являющийся частью Adobe Document Cloud, превосходно интегрируется с инструментами PDF и креативными пакетами. Цены начинаются примерно с 10 долларов США в месяц на пользователя для отдельных лиц и расширяются до индивидуальных планов для предприятий. Он поддерживает пользовательские поля и поиск API, аналогичные DocuSign, с использованием таких endpoints, как /agreements, для запроса метаданных. Преимущества включают сильную связь с экосистемой Adobe и глобальное соответствие, но расширенные функции API могут потребовать дополнительного лицензирования. Предприятия ценят его акцент на создании документов наряду с подписью.

eSignGlobal: индивидуальные решения для APAC и глобального соответствия

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

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

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

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

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

HelloSign, теперь Dropbox Sign, отдает приоритет удобному интерфейсу для малого и среднего бизнеса. Бесплатная версия позволяет использовать до трех документов в месяц, а платные планы начинаются от 15 долларов США в месяц. Его API поддерживает поиск конвертов по пользовательским полям, используя такие endpoints, как /templates и /signatures, хотя и не так детализирован, как DocuSign. Подходит для быстрой интеграции с Dropbox, с акцентом на простоту использования, а не на корпоративную настройку.

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

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

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