DocuSign

Communication with DocuSign assumes the existence of a user in DocuSign who grants TAS (the application) authorization (grant), based on which TAS can act on their behalf and issue documents for signature.

The authorization process is not yet finalized due to technical limitations of TAS. However, it can be done through another channel and unless the user revokes it in the DocuSign interface, the authorization should remain valid.

To communicate with DocuSign from calculations, you need to define an endpoint for authorization and for the API. This allows you to switch between production or test DocuSign environments.

The authorization endpoint for the test environment is: https://account-d.docusign.com/oauth/ The API endpoint for the test environment is: https://demo.docusign.net/restapi

For testing, you can create an account https://developers.docusign.com/platform/account/

It is also necessary to know:

  • user ID (userId) under which TAS should appear
  • integration key (integrationKey) unique for each connected application
  • own a private key used to sign JWT during API login (created together with integrationKey when adding an application to DocuSign)

All API operations require:

  • access token - created when the application logs in to the authorization portal. It is valid for an hour, but I would suggest creating a new one for each case rather than sharing the value.
  • API account ID - a DocuSign user can have multiple “accounts”. This account will probably only be one in our case and the ID will not change, but again I would download its value at the beginning of each case.

DocuSign settings

Creating a DEMO account in DocuSign is possible https://developers.docusign.com/platform/account/

  1. When editing the application in DS, you need to add a Redirect URL: https://neworigin.teamassistant.cz/docusign/authorization-code/callback
  2. Open in private window URL:
    TEST:
    https://account-d.docusign.com/oauth/auth?redirect_uri=https%3A%2F%2Fneworigin.teamassistant.cz%2Fdocusign%2Fauthorization-code%2Fcallback&scope=signature impersonation&client_id=INTEGRATION-ID&state=d733c43856&response_type=code
    PRODUCT:
    https://account.docusign.com/oauth/auth?redirect_uri=https%3A%2F%2Fneworigin.teamassistant.cz%2Fdocusign%2Fauthorization-code%2Fcallback&scope=signature impersonation&client_id=INTEGRATION-ID&state=d733c43856&response_type=code
  3. In the URL, you need to replace INTEGRATION-ID with the Integration Key of the application you are connecting to in DS.
  4. The DocuSign interface will open where you log in and confirm that this application (TAS) has the right to impersonate you so that TAS can generate signature requests.
  5. If everything goes well, you should be taken to the address https://neworigin.teamassistant.cz/docusign/authorization-code/callback , where it will say "DocuSign authorization completed"

//Ideally, implement it from the beginning with secured = true and feel free to add somewhere that the error Secret 'XYZ123' not found. It means that you need to add the appropriate integration private key to local.js under the name XYZ123

Use the email template to request TAS access to a client's DocuSign

EMLPT or EML

API - Login and find Account ID

https://developers.docusign.com/platform/auth/jwt/jwt-get-token/

DSCreateAuthJWT(endpoint, integrationKey, userId, secureKey, algorithm, secured = false)

The function generates a JWT token, required for logging in to DocuSign.

  • endpoint – endpoint definition, account-d.docusign.com = test, account.docusign.com = production
  • integrationKey - application integration key
  • userId – user ID under which to issue the document for signature
  • secureKey – password or private key for signing, or identifier from sails.config.secrets if secured = true
    true - the name of the key that is written in security in local.js
    false - the actual content of the key that you have generated in the DS interface for the given integration
  • algorithm – signature algorithm. For the private key it will be RS256
  • secured - toggles the meaning of the secureKey parameter

DSGetAccessToken(authorizationEndpoint, JwtData)

The function obtains the access token needed to call API operations.

DSGetDefaultApiAccountId(authorizationEndpoint, accessToken)

The function finds the default account Id of the selected user.

DSListSignatureProviders (DSEndpoint, accessToken, apiAccountId)

The function detects the list of signature providers available for the account used.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function

Sending documents for signature via email

DSCreateEnvelope(DSEndpoint, accessToken, apiAccountId, subject = '', documents = [], signers = [], copies = [], comment 'null)

Creates an envelope containing documents for signature and sends an email to the signers. Multiple documents can be placed in the envelope, but only the envelope is signed, not each document individually.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • subject - subject of the sent email
  • documents – array of objects defining documents to be signed. Object structure:
  • filename - name of the document being signed, including the extension
  • payload – content of the signed document as base64
  • signers – an array of objects defining the people who must sign the documents in the envelope.

Object structure:

[{
 "documentId": "1",
 "name": "SignHereTab",
 "pageNumber": "1",
 "recipientId": "1", #This value represents your {RECIPIENT_ID}
 "tabLabel": "SignHereTab",
 "xPosition": "75",
 "yPosition": "572"
 }]
  • routingOrder - optional parameter defining the order of signers. If not filled in, the order in which recipients are listed is used. If the parameter is null, the recipient can sign at any time (or several of them can be invited to sign at the same time).
  • signatureProvider - optional provider selection (TSP) for Standards-based Signing using a personal certificate. It can contain a field of multiple objects. The structure of the provider object is as follows and the values ​​must match the documentation https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/standards-based-signatures/ . The list of available providers is given in the Signature provider options section.
{
 "signatureProviderName": "UniversalSignaturePen_OpenTrust_Hash_TSP",
 "signatureProviderOptions": {
 "sms": "+AAAXXYYZZ"
 }
 }
  • signatureProviderName - select the signature provider. UniversalSignaturePen_OpenTrust_Hash_TSP is an authority managed by DocuSign
  • signatureProviderOptions – an object with the parameters of the given provider. The aforementioned UniversalSignaturePen_OpenTrust_Hash_TSP has as a mandatory parameter one of the attributes sms or oneTimePassword for entering the signer's phone number, for its authentication, or directly for entering a one-time password, which must be passed to the signer via another channel.
  • emailSubject - the subject of the notification email, specific to the recipient
  • emailComment - text contained in the body of the notification email, specific to the recipient

ATTENTION - the emailSubject and emailComment parameters must both be filled in for the given recipient, or neither of them must be filled in

Invalidation of the envelope

DSVoidEnvelope(DSEndpoint, accessToken, apiAccountId, envelopeId, message = '')

Marks the envelope as invalid. Further actions and signing with this envelope will not be possible.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • envelopeId – envelope ID obtained by the DSCreateEnvelope() function
  • message - a message explaining the reason for canceling the envelope

DSQueueForPurgeEnvelopeDocuments (DSEndpoint, accessToken, apiAccountId, envelopeId, includeMetadata = false)

Queues documents from the envelope for deletion from DocuSign.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • envelopeId – envelope ID obtained by the DSCreateEnvelope() function
  • includeMetadata – false = delete only documents, true = delete also attachments and signatures

Information about existing envelopes in DocuSign

DSListEnvelopeStatusChanges (DSEndpoint, accessToken, apiAccountId, fromDate = null, toDate = null, fromToStatus = '', statuses = ['any'], envelopeIds = null, additionalOptions = {})

Returns a list of envelopes that have undergone a monitored change at a given time, or are in a defined state. For a list of states, see the documentation https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • fromDate – time from (ideally in ISO 8601 format including time zone
  • toDate – time to, if omitted, defaults to current time
  • fromToStatus – the state the envelope was supposed to reach in the time period
  • statuses – array of statuses in which the envelopes should be at this moment
  • envelopeIds – array of tracked envelope identifiers
  • additionalOptions – an object in which additional filters can be defined according to the documentation https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/

DSGetEnvelope(DSEndpoint, accessToken, apiAccountId, envelopeId, includeAttributes = [])

Downloads information about the selected envelope.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • envelopeId – envelope ID obtained by the DSCreateEnvelope() function
  • includeAttributes - field with selection of extended attributes to include in the response, see documentation

Working with documents in an envelope

DSListEnvelopeDocuments(DSEndpoint, accessToken, apiAccountId, envelopeId)

Returns a list of documents inserted into the envelope, plus a “certificate” of the envelope activity (signing).

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • envelopeId – envelope ID obtained by the DSCreateEnvelope() function

DSGetEnvelopeDocument(DSEndpoint, accessToken, apiAccountId, envelopeId, documentId)

Downloads the selected document from the envelope. The data is passed as base64.

  • DSEndpoint - DocuSign API endpoint, https://demo.docusign.net/restapi = test
  • accessToken – access token obtained with the DSGetAccessToken() function
  • apiAccountId – account Id obtained by the DSGetDefaultApiAccountId() function
  • envelopeId – envelope ID obtained by the DSCreateEnvelope() function
  • documentId – document ID from the list returned by the DSListEnvelopeDocuments() function, or the string “certificate” to download the activity summary, or the string “archive” to download all documents together with the summary in one ZIP file

Anna Gernát Updated by Anna Gernát

ISDOC.PDF

Contact

Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)