API DocuSign: Come cercare buste tramite valori di campi personalizzati?

Gestione efficiente della navigazione delle buste nell'API DocuSign

Nel panorama competitivo delle soluzioni di firma digitale, l'API di DocuSign si distingue come un potente strumento per sviluppatori e aziende per automatizzare i flussi di lavoro. Una sfida comune è recuperare buste specifiche - il termine di DocuSign per i pacchetti di documenti - in base a metadati personalizzati. Questa capacità è fondamentale per le aziende che gestiscono un volume elevato di accordi, consentendo ricerche mirate senza la necessità di vagliare manualmente. Da un punto di vista aziendale, la padronanza di tali funzionalità API può semplificare gli audit di conformità, il monitoraggio delle vendite e l'assistenza clienti, riducendo in definitiva i costi operativi.

Stai confrontando piattaforme di firma elettronica con DocuSign o Adobe Sign?

eSignGlobal offre una soluzione di firma elettronica più flessibile ed economica con conformità globale, prezzi trasparenti e un processo di onboarding più rapido.

👉 Inizia una prova gratuita

Comprensione delle buste e dei campi personalizzati nell'API DocuSign

Una busta DocuSign rappresenta l'unità centrale della firma elettronica, incapsulando documenti, destinatari e campi di firma. I campi personalizzati, noti anche come campi di testo o etichette, consentono agli utenti di incorporare direttamente metadati come ID contratto, nomi di clienti o tag di stato all'interno della busta. Questi campi non sono solo per la visualizzazione; supportano query programmatiche, che sono preziose per l'integrazione con sistemi CRM o dashboard personalizzati.

Da un punto di vista aziendale, l'utilizzo di campi personalizzati per la ricerca può migliorare la governance dei dati. Le aziende in settori regolamentati, come la finanza o l'assistenza sanitaria, possono utilizzarli per filtrare le buste in base ai contrassegni di conformità, garantendo un accesso rapido durante gli audit. L'API di DocuSign, parte della sua piattaforma per sviluppatori, supporta questa funzionalità tramite endpoint RESTful, con livelli di prezzo come il piano Intermediate (3.600 dollari all'anno) che offrono fino a 100 buste al mese per tali operazioni.

Guida passo passo: ricerca di buste in base ai valori dei campi personalizzati

Per cercare buste utilizzando i valori dei campi personalizzati tramite l'API DocuSign, è necessario un account sviluppatore attivo e credenziali API. Questa procedura presuppone che si stia utilizzando l'API REST eSignature v2.1, lo standard attuale nel 2025. Di seguito è riportata una procedura dettagliata neutra e pratica basata sulla documentazione ufficiale.

Prerequisiti e configurazione

1. Ottenere l'accesso all'API: registrati per una sandbox per sviluppatori DocuSign su developer.docusign.com. Genera una chiave di integrazione (ID client) e una chiave segreta per l'autenticazione OAuth. Per gli ambienti di produzione, esegui l'upgrade a un piano a pagamento: il piano Starter (600 dollari all'anno) è adatto per le ricerche di base.

2. Definire campi personalizzati: quando crei una busta, aggiungi campi personalizzati tramite l'API. Utilizza l'oggetto customFields nella definizione della busta. Ad esempio:

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

   Questo incorpora "CLI-12345" come valore ricercabile nel campo "ClientID".

3. Autenticazione: utilizza il flusso JWT o Auth Code Grant. Un esempio di richiesta JWT in Python (utilizzando la libreria requests) è il seguente:

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

   Sostituisci i segnaposto con le tue credenziali. Questo token viene utilizzato per autenticare le successive chiamate API.

Esecuzione della ricerca

L'endpoint chiave è GET /accounts/{accountId}/envelopes/search, ma per il filtraggio dei campi personalizzati, combina i parametri di query o utilizza GET /envelopes più flessibile con criteri di ricerca. L'API di ricerca di DocuSign consente di eseguire query sui campi personalizzati tramite il parametro searchText, che corrisponde ai metadati della busta, inclusi i valori personalizzati.

• Endpoint di ricerca di base: utilizza GET /accounts/{accountId}/envelopes?search_text={value}. Questo esegue la scansione dell'oggetto, dei nomi e dei campi personalizzati della busta.

  Per una corrispondenza esatta dei campi personalizzati, utilizza il parametro query nella ricerca avanzata. Tuttavia, le query dirette sui campi personalizzati richiedono Envelopes: listStatusChanges o autorizzazioni simili.

  Esempio di richiesta 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"
  

  Frammento di risposta:

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

• Filtraggio avanzato con campi personalizzati: per ricerche di buste specifiche, recupera prima le buste all'interno di un intervallo di date o di uno stato e poi filtra sul lato client. DocuSign consiglia di combinare i parametri fromDate e toDate con search_text per una maggiore efficienza. Se i tuoi volumi superano le quote (ad esempio, 100 buste al mese con il piano Intermediate), valuta l'upgrade ad Advanced (5.760 dollari all'anno) per le funzionalità di elaborazione in batch.

  Nel codice, analizza la risposta per trovare la corrispondenza con i valori esatti dei campi personalizzati:

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

Best practice e limitazioni

• Quote e costi: le ricerche rientrano nei limiti dell'API delle buste. Il superamento comporterà costi aggiuntivi o la necessità di una personalizzazione Enterprise.
• Sicurezza: utilizza sempre HTTPS e autorizzazioni basate sui ruoli per impedire query non autorizzate.
• Gestione degli errori: i problemi comuni includono 401 (token non valido) o 400 (query non valida). Registra le risposte per il debug.
• Scalabilità: per le ricerche ad alto volume, integra con i webhook Connect di DocuSign per aggiornamenti push, riducendo la necessità di polling.

Questa funzionalità API posiziona DocuSign come leader nell'automazione della conformità, anche se le aziende dovrebbero valutare i costi totali, inclusi componenti aggiuntivi come l'autenticazione.

DocuSign: leader di mercato nelle soluzioni di firma elettronica

DocuSign è un pioniere della firma elettronica dal 2004, offrendo una suite completa di strumenti di gestione dei documenti. La sua piattaforma eSignature include piani da Personal (120 dollari all'anno) a Business Pro (480 dollari all'anno/utente), con accesso API tramite piani per sviluppatori separati. Le funzionalità chiave includono modelli, invio in blocco e integrazioni con oltre 400 applicazioni. Per esigenze avanzate, Intelligent Agreement Management (IAM) di DocuSign combina CLM (Contract Lifecycle Management) con informazioni basate sull'intelligenza artificiale, automatizzando la revisione e la valutazione del rischio. IAM è adatto alle aziende, anche se i prezzi sono personalizzati e possono aumentare in base ai posti e al volume delle buste.

Adobe Sign: potenti integrazioni per i flussi di lavoro aziendali

Adobe Sign, parte di Adobe Document Cloud, eccelle nell'integrazione perfetta con gli strumenti PDF e le suite creative. I prezzi partono da circa 10 dollari al mese/utente per i singoli, fino a piani aziendali personalizzati. Supporta campi personalizzati e ricerche API simili a DocuSign, utilizzando endpoint come /agreements per interrogare i metadati. I vantaggi includono una forte affinità con l'ecosistema Adobe e la conformità globale, ma le funzionalità API avanzate potrebbero richiedere licenze aggiuntive. Le aziende apprezzano la sua attenzione alla creazione di documenti accanto alla firma.

eSignGlobal: soluzioni su misura per la conformità APAC e globale

eSignGlobal si distingue come un attore specializzato, in particolare nella regione Asia-Pacifico (APAC), dove le normative sulla firma elettronica sono frammentate, elevate e rigorosamente regolamentate. A differenza dei framework di ESIGN/UETA negli Stati Uniti o eIDAS in Europa - che si basano sulla verifica tramite e-mail o sull'autodichiarazione - l'APAC richiede standard di integrazione dell'ecosistema. Ciò comporta un profondo accoppiamento hardware/a livello di API con le identità digitali government-to-business (G2B), aumentando significativamente le barriere tecnologiche al di sopra dei modelli occidentali. eSignGlobal affronta questo problema coprendo la conformità in oltre 100 paesi e regioni globali principali, con una forte presenza in APAC tramite data center locali a Hong Kong e Singapore. Supporta integrazioni perfette con iAM Smart di Hong Kong e Singpass di Singapore per una forte autenticazione. I prezzi sono competitivi, con il piano Essential a 299 dollari all'anno (equivalenti a circa 16,6 dollari al mese annualizzati) che consente fino a 100 documenti firmati, posti utente illimitati e verifica del codice di accesso, il tutto su una base di conformità ed efficienza dei costi inferiore a molti concorrenti pur mantenendo la validità legale.

Stai cercando un'alternativa più intelligente a DocuSign?

eSignGlobal offre una soluzione di firma elettronica più flessibile ed economica con conformità globale, prezzi trasparenti e un processo di onboarding più rapido.

👉 Inizia una prova gratuita

HelloSign (Dropbox Sign): una soluzione semplificata per le PMI

HelloSign, ora Dropbox Sign, dà la priorità a un'interfaccia intuitiva per le piccole e medie imprese. Un livello gratuito consente fino a tre documenti al mese, con piani a pagamento a partire da 15 dollari al mese. La sua API supporta la ricerca di buste tramite campi personalizzati, utilizzando endpoint come /templates e /signatures, anche se non è granulare come DocuSign. Adatto per una rapida integrazione con Dropbox, l'attenzione è rivolta alla facilità d'uso piuttosto che alla personalizzazione di livello aziendale.

Panoramica comparativa delle piattaforme di firma elettronica

Questa tabella evidenzia compromessi neutri; la scelta dipende dalle esigenze regionali e dalla scala.

In sintesi, mentre l'API di DocuSign consente ricerche precise di buste, l'esplorazione di alternative può ottimizzare per mercati specifici. Per la conformità regionale, eSignGlobal offre un'opzione bilanciata come alternativa a DocuSign.