API de DocuSign: ¿Cómo buscar sobres por valores de campos personalizados?

Gestión eficiente de la navegación de sobres en la API de DocuSign

En el competitivo panorama de las soluciones de firma digital, la API de DocuSign destaca como una poderosa herramienta para que los desarrolladores y las empresas automaticen los flujos de trabajo. Un desafío común es recuperar sobres específicos (el término de DocuSign para los paquetes de documentos) en función de metadatos personalizados. Esta capacidad es crucial para las empresas que manejan grandes volúmenes de acuerdos, ya que permite búsquedas específicas sin necesidad de una selección manual. Desde una perspectiva empresarial, dominar tales capacidades de la API puede agilizar las auditorías de cumplimiento, el seguimiento de ventas y la atención al cliente, lo que en última instancia reduce los costos operativos.

¿Está comparando plataformas de firma electrónica con DocuSign o Adobe Sign?

eSignGlobal ofrece una solución de firma electrónica más flexible y rentable con cumplimiento global, precios transparentes y un proceso de incorporación más rápido.

👉 Comience una prueba gratuita

Comprensión de los sobres y los campos personalizados en la API de DocuSign

Un sobre de DocuSign representa la unidad central de la firma electrónica, que encapsula documentos, destinatarios y campos de firma. Los campos personalizados, también conocidos como campos de texto o etiqueta, permiten a los usuarios incrustar metadatos directamente en el sobre, como ID de contrato, nombres de clientes o etiquetas de estado. Estos campos no son meramente para mostrar; admiten consultas programáticas, lo cual es invaluable para la integración con sistemas CRM o paneles personalizados.

Desde una perspectiva empresarial, el uso de campos personalizados para la búsqueda puede mejorar la gobernanza de los datos. Las empresas en industrias reguladas, como las finanzas o la atención médica, pueden usarlos para filtrar sobres según las etiquetas de cumplimiento, lo que garantiza un acceso rápido durante las auditorías. La API de DocuSign, parte de su plataforma para desarrolladores, admite esta funcionalidad a través de puntos finales RESTful, con niveles de precios como el plan Intermedio (USD 3600 por año) que ofrecen hasta 100 sobres por mes para tales operaciones.

Guía paso a paso: búsqueda de sobres por valores de campos personalizados

Para buscar sobres por valores de campos personalizados a través de la API de DocuSign, necesita una cuenta de desarrollador activa y credenciales de API. Este proceso asume que está utilizando la API REST de firma electrónica v2.1, el estándar actual en 2025. Aquí hay un tutorial neutral y práctico basado en la documentación oficial.

Requisitos previos y configuración

1. Obtenga acceso a la API: regístrese para obtener una zona de pruebas de desarrollador de DocuSign en developer.docusign.com. Genere una clave de integración (ID de cliente) y una clave secreta para la autenticación OAuth. Para entornos de producción, actualice a un plan pago: el plan Starter (USD 600 por año) es adecuado para búsquedas básicas.

2. Defina campos personalizados: al crear un sobre, agregue campos personalizados a través de la API. Utilice el objeto customFields en la definición del sobre. Por ejemplo:

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

   Esto incrusta “CLI-12345” como un valor de búsqueda bajo el campo “ClientID”.

3. Autenticación: utilice el flujo JWT o Auth Code Grant. Una solicitud JWT de ejemplo en Python (usando la biblioteca requests) se ve así:

   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"]
   

   Reemplace los marcadores de posición con sus credenciales. Este token se utiliza para autenticar llamadas API posteriores.

Realización de la búsqueda

El punto final clave es GET /accounts/{accountId}/envelopes/search, pero para el filtrado de campos personalizados, combine los parámetros de consulta o utilice el más flexible GET /envelopes con criterios de búsqueda. La API de búsqueda de DocuSign permite consultar por campos personalizados a través del parámetro searchText, que coincide con los metadatos del sobre, incluidos los valores personalizados.

• Punto final de búsqueda básica: utilice GET /accounts/{accountId}/envelopes?search_text={value}. Esto escanea los asuntos, nombres y campos personalizados del sobre.

  Para coincidencias exactas de campos personalizados, aproveche el parámetro query en la búsqueda avanzada. Sin embargo, las consultas directas de campos personalizados requieren Envelopes: listStatusChanges o permisos similares.

  Solicitud cURL de ejemplo:

  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"
  

  Fragmento de respuesta:

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

• Filtrado avanzado con campos personalizados: para búsquedas de sobres específicos, primero recupere los sobres dentro de un rango de fechas o estado y luego filtre en el lado del cliente. DocuSign recomienda combinar los parámetros fromDate y toDate con search_text para mejorar la eficiencia. Si sus volúmenes superan las cuotas (por ejemplo, 100 sobres por mes en el plan Intermedio), considere actualizar a Advanced (USD 5760 por año) para obtener capacidades masivas.

  En el código, analice la respuesta para que coincida con los valores exactos de los campos personalizados:

  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))
  

Mejores prácticas y limitaciones

• Cuotas y costos: las búsquedas cuentan para los límites de la API de sobres. Excederlos incurre en cargos por exceso o requiere una personalización empresarial.
• Seguridad: utilice siempre HTTPS y permisos basados en roles para evitar consultas no autorizadas.
• Manejo de errores: los problemas comunes incluyen 401 (token no válido) o 400 (consulta no válida). Registre las respuestas para la depuración.
• Escalabilidad: para búsquedas de alto volumen, intégrese con los webhooks de Connect de DocuSign para enviar actualizaciones, lo que reduce las necesidades de sondeo.

Esta capacidad de la API posiciona a DocuSign como líder en el cumplimiento automatizado, aunque las empresas deben evaluar los costos totales, incluidos los complementos como la autenticación.

DocuSign: líder del mercado en soluciones de firma electrónica

DocuSign ha sido pionero en la firma electrónica desde 2004 y ofrece un conjunto completo de herramientas de gestión de documentos. Su plataforma de firma electrónica incluye planes desde Personal (USD 120 por año) hasta Business Pro (USD 480 por usuario por año), con acceso a la API a través de planes de desarrollador separados. Las características clave incluyen plantillas, envío masivo e integraciones con más de 400 aplicaciones. Para necesidades avanzadas, la gestión inteligente de acuerdos (IAM) de DocuSign combina CLM (gestión del ciclo de vida del contrato) con información basada en IA, automatizando las revisiones y la evaluación de riesgos. IAM es adecuado para empresas, aunque los precios son personalizados y pueden aumentar con los asientos y los volúmenes de sobres.

Adobe Sign: integraciones sólidas para flujos de trabajo empresariales

Adobe Sign, parte de Adobe Document Cloud, destaca por su perfecta integración con las herramientas de PDF y los conjuntos creativos. Los precios comienzan en alrededor de USD 10/usuario por mes para individuos, escalando a planes personalizados para empresas. Admite campos personalizados y búsquedas de API similares a DocuSign, utilizando puntos finales como /agreements para consultar metadatos. Las ventajas incluyen fuertes vínculos con el ecosistema de Adobe y el cumplimiento global, pero las capacidades avanzadas de la API pueden requerir licencias adicionales. Las empresas valoran su enfoque en la creación de documentos junto con la firma.

eSignGlobal: soluciones personalizadas para APAC y cumplimiento global

eSignGlobal se distingue como un actor especializado, particularmente en la región de Asia-Pacífico (APAC), donde las regulaciones de firma electrónica son fragmentadas, de alto estándar y estrictamente reguladas. A diferencia de los marcos de ESIGN/UETA de EE. UU. o eIDAS de Europa, que se basan en la verificación por correo electrónico o la autodeclaración, APAC exige estándares de integración del ecosistema. Esto implica una conexión profunda a nivel de hardware/API con las identidades digitales de gobierno a empresa (G2B), lo que eleva significativamente las barreras técnicas por encima de los modelos occidentales. eSignGlobal aborda esto con cobertura de cumplimiento en más de 100 países y territorios globales convencionales, con una ventaja en APAC a través de centros de datos locales en Hong Kong y Singapur. Admite integraciones perfectas con iAM Smart de Hong Kong y Singpass de Singapur para una autenticación sólida. Los precios son competitivos, con un plan Essential a USD 299 por año (equivalente anualizado a alrededor de USD 16.6 por mes), lo que permite hasta 100 documentos firmados, asientos de usuario ilimitados y verificación de código de acceso, todo basado en una base de cumplimiento y rentabilidad por debajo de muchos competidores, manteniendo al mismo tiempo la validez legal.

¿Está buscando una alternativa más inteligente a DocuSign?

eSignGlobal ofrece una solución de firma electrónica más flexible y rentable con cumplimiento global, precios transparentes y un proceso de incorporación más rápido.

👉 Comience una prueba gratuita

HelloSign (Dropbox Sign): simplicidad para las PYMES

HelloSign, ahora Dropbox Sign, prioriza una interfaz fácil de usar para las pequeñas y medianas empresas. Una versión gratuita permite hasta tres documentos por mes, con planes pagos a partir de USD 15 por mes. Su API admite la búsqueda de sobres por campos personalizados, utilizando puntos finales como /templates y /signatures, aunque no tan granular como DocuSign. Adecuado para una rápida integración con Dropbox, el enfoque está en la facilidad de uso en lugar de la personalización de nivel empresarial.

Resumen comparativo de plataformas de firma electrónica

Esta tabla destaca las compensaciones neutrales; la elección depende de las necesidades regionales y la escala.

En conclusión, si bien la API de DocuSign permite una búsqueda precisa de sobres, explorar alternativas puede optimizar para mercados específicos. Para el cumplimiento regional, eSignGlobal ofrece una opción equilibrada como alternativa a DocuSign.