Spice up Your Website with a DocuSign Electronic Signature Embedded Tool

To make it easier, let’s create a DocuSign class with all necessary methods. This will let us keep the same valid token during the whole process and renew it if needed.

import jwt
from docusign_esign import *

class DocuSignClient:
     token = None

Now, to communicate with the DocuSign API, what we first need is a way to get a valid EnvelopesApi object, i.e that has a valid token and correct parameters (pathname and headers), so let’s add these two methods:

     def get_client(self):
         api_client = ApiClient()
         api_client.host = <MY_DOCUSIGN_API_BASE_PATH>
         api_client.set_default_header("Authorization", f"Bearer {self.token}")

         return api_client

     def get_envelope_api(self):
         api_client = self.get_client()
         envelope_api = EnvelopesApi(api_client)

         return envelope_api

However, because we want the token to be valid and to automatically renew if not, I added the following pre-check:

     def get_client(self):
         if not self.is_token_valid():
             self.token = self.renew_token()

        # ...

As you will see below, this check is essentially a call to the DocuSign API using the current token to verify whether it is valid. If it is expired or invalid (401 status code), we renew it. We use a single login for all users in the platform. Therefore, we use the JWT Grant authentication as suggested in the documentation.

     def is_token_valid(self, method="GET"):
         headers = {"Authorization": f"Bearer {self.token}"}
         response = requests.request(
             method, f"{<MY_DOCUSIGN_API_BASE_PATH>}/v2.1/accounts/", headers=headers
         )

         if response.status_code != 401:
             return True

         return False

     def renew_token(self):
         current_datetime = datetime.datetime.now()
         jwt_token = jwt.encode(
             {
                 "iss": <MY_DOCUSIGN_INTEGRATION_KEY>,
                 "sub": <MY_DOCUSIGN_API_USERNAME>,
                 "name": <NAME>,
                 "aud": "account-d.docusign.com",
                 "iat": current_datetime,
                 "exp": current_datetime + datetime.timedelta(minutes=30), # validity duration of 30 minutes
                 "scope": "signature impersonation",
             },
             key=<MY_DOCUSIGN_PRIVATE_KEY>.encode(),
             algorithm="RS256",
         )

         headers = {"Content-Type": "application/x-www-form-urlencoded"}
         url = f"{<MY_DOCUSIGN_BASE_URL>}/oauth/token"
         payload = {
             "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
             "assertion": jwt_token,
         }
         response = requests.request("POST", url, headers=headers, data=payload)

        return response.json()["access_token"]

Believe me, all these methods will simplify your life. You’ll only have to call get_envelope_api() to get a functional EnvelopeApi with a valid token.

Once done, we can then add methods to create a DocuSign envelope, which is roughly a container for documents that you send to a recipient for signing.

     def make_docusign_envelope(
         self,
         signer_full_name,
         signer_email,
         contact_id,
         document_path,
         document_name,
         anchor_y_offset="0",
         anchor_x_offset="0",
     ):
         with open(document_path, "rb") as file:
             content_bytes = file.read()
             base64_file_content = base64.b64encode(content_bytes).decode("ascii")

         document = Document(
             document_base64=base64_file_content,
             name=document_name,
             file_extension="pdf",
             document_id=1,
         )

         signer = Signer(
             email=signer_email,
             name=signer_full_name,
             recipient_id="1",
             routing_order="1",
             client_user_id=contact_id,
         )

         sign_here = SignHere(
             anchor_string="/sn1/", # the anchor string to indicate where to sign on the PDF
             anchor_units="pixels",
             anchor_y_offset=anchor_y_offset,
             anchor_x_offset=anchor_x_offset,
         )

         signer.tabs = Tabs(sign_here_tabs=[sign_here])

         envelope_definition = EnvelopeDefinition(
             email_subject="Please sign this document",
             documents=[document],
             recipients=Recipients(signers=[signer]),
             status="sent",
         )

         return envelope_definition

The make_docusign_envelope() method allows you to design a fully customizable envelope, by defining all components such as the document content, signers, locations where a signature has to be attached… You can then use it as a template like so:

     def call_docusign_create_envelope(
         self, full_name, email, contact_crm_id, document_path, document_name,
     ):
         envelope_api = self.get_envelope_api()
         envelope_definition = self.make_docusign_envelope(
             full_name, email, contact_crm_id, document_path, document_name
         )

         results = envelope_api.create_envelope(
             <MY_DOCUSIGN_API_ACCOUNT_ID>, envelope_definition=envelope_definition,
         )

         envelope_id = results.envelope_id

         return envelope_id

Indeed, call_docusign_create_envelope will make use of the previous method to create an envelope based on this template and returns an envelope ID that can be used to start the signing process (a.k.a ceremony).

    def build_docusign_redirection_url(self, redirection_route, options):
         return <MY_FRONTEND_URL> + redirection_route + options

     def start_signing_ceremony(
         self,
         envelope_id,
         full_name,
         email,
         contact_crm_id,
         redirection_route,
         authentication_method="none",
     ):
         envelope_api = self.get_envelope_api()
         return_url = self.build_docusign_redirection_url(redirection_route, envelope_id)
         recipient_view_request = RecipientViewRequest(
             authentication_method=authentication_method,
             client_user_id=contact_crm_id,
             recipient_id="1",
             return_url=return_url,
             user_name=full_name,
             email=email,
         )

         results = envelope_api.create_recipient_view(
             <MY_DOCUSIGN_API_ACCOUNT_ID>,
             envelope_id,
             recipient_view_request=recipient_view_request,
         )

         return results.url

Note that the custom redirection url built by build_docusign_redirection_url is the one that will be used frontend-wise once the signing ceremony is completed, i.e when the user clicks on the “Finish” button. Completing the ceremony will also update the envelope status in DocuSign to completed.