API DocuSign: Come aggiungere un destinatario "Copia Carbone" dopo l'invio?

Comprendere i destinatari in copia conoscenza in DocuSign

Nel regno delle firme elettroniche, l'API di DocuSign offre potenti strumenti per automatizzare i flussi di lavoro dei documenti, ma aggiungere destinatari dopo la creazione di una busta può essere complicato. I destinatari in "copia conoscenza" (CC) sono un ruolo non firmatario che riceve una copia del documento firmato per visualizzazione o conservazione dei registri, senza la necessità di firmare o approvare. Dal punto di vista aziendale, questa funzionalità è preziosa per i team di conformità, i dipartimenti legali o i responsabili delle vendite che devono essere informati senza alterare la catena di firme. Tuttavia, l'API di DocuSign ha limitazioni sulle modifiche una volta inviata una busta, che esploreremo in dettaglio.

Questo articolo approfondisce i passaggi pratici per aggiungere destinatari CC tramite l'API eSignature di DocuSign dopo l'invio di una busta. Tratteremo i prerequisiti, le chiamate API, le potenziali insidie e le migliori pratiche, facendo riferimento alla documentazione ufficiale e alle informazioni sull'implementazione pratica. Comprendere queste sfumature può prevenire interruzioni del flusso di lavoro e garantire processi pronti per l'audit per le aziende che integrano DocuSign.

Nozioni di base sulla gestione dei destinatari dell'API DocuSign

Prima di aggiungere destinatari CC dopo l'invio, è fondamentale comprendere il ciclo di vita della busta di DocuSign. Le buste rappresentano pacchetti di documenti e, una volta "inviate", sono attive, momento in cui le modifiche sono limitate per proteggere l'esperienza del firmatario e l'integrità legale. L'API REST eSignature (v2.1) gestisce queste interazioni, richiedendo l'autenticazione tramite JWT o OAuth per un accesso sicuro.

Concetti chiave:

• Destinatari: include firmatari, approvatori e CC. I CC vengono aggiunti tramite l'array carbonCopies nell'oggetto destinatario.
• Stato della busta: dopo l'invio, le buste sono nello stato "inviato" o "consegnato". Le modifiche sono limitate; non è possibile aggiungere firmatari che richiedono un'azione, ma i CC sono consentiti perché non alterano l'ordine di firma.
• Endpoint API: utilizzare /envelopes/{envelopeId}/recipients per gli aggiornamenti.

Dal punto di vista commerciale, i prezzi dell'API di DocuSign partono da $ 600 all'anno per il piano Starter, supportando fino a 40 buste al mese, adatte per piccole integrazioni, ma i requisiti di volume elevato aumentano i costi.

Guida passo passo: aggiunta di destinatari CC dopo l'invio

L'aggiunta di CC dopo l'invio richiede l'utilizzo della modalità correct o di una soluzione alternativa void-and-resend, poiché l'aggiunta diretta post-invio non è sempre semplice. DocuSign consiglia di pianificare i destinatari in anticipo, ma per scenari dinamici (ad esempio, aggiungere un manager in base alla logica aziendale condizionale), seguire questi passaggi. Questa procedura presuppone che tu disponga di un account sviluppatore e di un token di accesso API.

Prerequisiti

1. Configurazione API: integrare l'SDK DocuSign (per Java, .NET, PHP, ecc.) o utilizzare chiamate REST grezze. Autenticarsi con la chiave di integrazione e l'ID utente.
2. ID busta: recuperare l'ID dalla risposta di invio iniziale (ad esempio, tramite POST su /envelopes).
3. Autorizzazioni: assicurarsi che il proprio account consenta la correzione della busta (abilitata in "Funzionalità" nelle impostazioni di amministrazione).
4. Controllo dello stato della busta: interrogare /envelopes/{envelopeId} per confermare che sia nello stato "inviato" e che nessun firmatario abbia completato un'azione che blocca le modifiche.

Suggerimento aziendale: per le aziende, il piano API Advanced ($ 5.760 all'anno) sblocca funzionalità come l'invio in blocco e i webhook, che possono notificare automaticamente i CC al completamento.

Metodo 1: utilizzo della correzione della busta (consigliato per piccole modifiche)

La funzionalità "Correzione" di DocuSign consente modifiche in corso senza invalidare la busta, adatta per l'aggiunta di CC.

1. Avviare la correzione:

   • PUT su /envelopes/{envelopeId}/correct con un corpo di:

     {
       "clientUserId": "optional_client_id",
       "correctInProgress": true
     }
     

     Questo sospende temporaneamente la busta.

2. Aggiungere destinatari CC:

   • POST su /envelopes/{envelopeId}/recipients con i dettagli del CC:

     {
       "carbonCopies": [
         {
           "email": "cc@example.com",
           "name": "John Doe",
           "recipientId": "unique_id_for_cc",  // Ad esempio, "CC1"
           "routingOrder": 0  // I CC non influiscono sull'ordine
         }
       ],
       "resendEnvelope": false  // Non inviare nuovamente le notifiche per ora
     }
     

     • recipientId deve essere univoco; evitare conflitti con i destinatari esistenti.
     • Facoltativo: aggiungere accessControl per l'accesso CC protetto da password.

3. Inviare nuovamente o notificare:

   • PUT di nuovo su /envelopes/{envelopeId}/correct per riprendere:

     {
       "resendEnvelope": true  // Attiva le e-mail per i nuovi CC
     }
     

     Il CC riceverà una copia una volta che la busta è stata completata o su richiesta.

Potenziale insidia: se la busta è "completata", non è possibile correggerla: utilizzare i webhook tramite la funzionalità Connect (piano Advanced) per monitorare lo stato.

Metodo 2: invalidare e inviare nuovamente (per scenari complessi)

Se la correzione non è fattibile (ad esempio, a causa dell'azione del firmatario), invalidare la busta e ricrearla con il nuovo CC.

1. Invalidare la busta:

   • PUT su /envelopes/{envelopeId}:

     {
       "status": "voided",
       "voidedReason": "Adding CC recipient"
     }
     

2. Ricreare con CC:

   • POST su /envelopes con il payload originale, più il CC nell'oggetto recipients:

     {
       "emailSubject": "Updated Document",
       "documents": [/* documenti originali */],
       "recipients": {
         "signers": [/* firmatari originali */],
         "carbonCopies": [
           {
             "email": "cc@example.com",
             "name": "John Doe",
             "recipientId": "CC1"
           }
         ]
       },
       "status": "sent"
     }
     

3. Notificare ai firmatari originali: utilizzare /envelopes/{newEnvelopeId}/recipients/{recipientId}/resend per ogni firmatario per riprendere.

Osservazione aziendale: questo metodo comporta costi aggiuntivi per l'utilizzo della busta (ad esempio, Business Pro ~100 buste/utente/anno, $ 480/utente/anno), quindi è adatto per correzioni a basso volume. Tracciare le quote tramite la dashboard utilizzando l'API per la gestione.

Migliori pratiche e limitazioni

• Gestione degli errori: gli errori comuni includono 400 (destinatario non valido) o 403 (autorizzazioni insufficienti). Convalidare sempre prima con un GET su /envelopes/{envelopeId}/recipients.
• Test: utilizzare la Developer Sandbox di DocuSign (gratuita) per simulare senza consumare buste di produzione.
• Conformità: l'aggiunta di CC mantiene le tracce di controllo, in linea con gli standard ESIGN/UETA, ma registra i motivi per evitare controversie.
• Alternative di automazione: per frequenti esigenze post-invio, integrare i webhook (piano Advanced) per attivare notifiche esterne anziché modifiche API.

In pratica, le aziende segnalano un aumento dell'efficienza del 20-30% nell'esecuzione di queste operazioni tramite script SDK, ma per operazioni su larga scala, considerare i piani personalizzati Enterprise per una regolazione illimitata.

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

eSignGlobal offre soluzioni di firma elettronica più flessibili ed economiche con conformità globale, prezzi trasparenti e onboarding più rapido.

👉 Inizia una prova gratuita

Confronto di DocuSign con i principali concorrenti

Per fornire una prospettiva equilibrata, confrontiamo le funzionalità API di DocuSign con alternative come Adobe Sign, eSignGlobal e HelloSign (ora Dropbox Sign). Questa tabella si basa sui dati pubblici del 2025, evidenziando i prezzi, la gestione dei destinatari e i punti di forza regionali per aiutare le aziende a prendere decisioni nella selezione dei fornitori.

Questo confronto mostra che DocuSign eccelle nella profondità dell'API matura, ma a un costo più elevato, mentre i concorrenti offrono flessibilità per segmenti specifici.

Focus su Adobe Sign

Adobe Sign, parte di Adobe Document Cloud, offre un'API senza interruzioni per la gestione dei destinatari, inclusa l'aggiunta di CC post-invio più semplice tramite il suo endpoint API "Amend". I prezzi sono competitivi, a partire da $ 10/utente/mese per la versione base, che si estende alla personalizzazione Enterprise. È adatto per le aziende già all'interno della suite Adobe, offrendo una solida gestione dei PDF e conformità globale, anche se la latenza APAC potrebbe essere un problema.

Focus su eSignGlobal

eSignGlobal si posiziona come un attore globale, conforme in oltre 100 paesi principali, con una forte presenza nella regione Asia-Pacifico (APAC). Il panorama delle firme elettroniche in APAC è frammentato, con standard elevati e normative rigorose: a differenza dei quadri ESIGN/eIDAS degli Stati Uniti/UE, APAC richiede soluzioni di "integrazione dell'ecosistema". Ciò significa un accoppiamento hardware/API profondo con le identità digitali governative (G2B), un ostacolo tecnologico che va ben oltre la verifica e-mail o i modelli di auto-dichiarazione comunemente visti in Occidente. eSignGlobal affronta questo problema con integrazioni native come iAM Smart a Hong Kong e Singpass a Singapore, garantendo la validità legale senza costi aggiuntivi.

I prezzi sono convenienti, con il suo piano Essential a $ 16,6 al mese all'anno, consentendo fino a 100 firme di documenti, posti utente illimitati e verifica tramite codici di accesso. Questo valore guidato dalla conformità lo rende competitivo rispetto a DocuSign e Adobe Sign, in particolare per i team transfrontalieri che cercano un TCO inferiore.

Cerchi un'alternativa più intelligente a DocuSign?

eSignGlobal offre soluzioni di firma elettronica più flessibili ed economiche con conformità globale, prezzi trasparenti e onboarding più rapido.

👉 Inizia una prova gratuita

Considerazioni finali sulla selezione della firma elettronica

Per le aziende che navigano nei flussi di lavoro basati su API, DocuSign rimane una scelta solida, anche se le modifiche post-invio richiedono un'attenta pianificazione. Con l'aumento delle alternative, considerare le esigenze regionali: eSignGlobal si distingue come un'opzione neutrale e guidata dalla conformità per le operazioni orientate all'APAC. Valutare in base alla capacità, all'integrazione e alla posizione geografica per una corrispondenza ottimale.