docusign / code-examples-python

Docusign Python code examples and launcher

Python Launcher Code Examples

GitHub repo: code-examples-python

This GitHub repo includes code examples for the DocuSign Admin API, Click API, eSignature REST API, Monitor API, and Rooms API. By default, the launcher will display the eSignature examples. To switch between API code examples, select "Choose API" in the top menu.

Introduction

This repo is a Python 3 application that supports the following authentication workflows:

• Authentication with Docusign via Authorization Code Grant. When the token expires, the user is asked to re-authenticate. The refresh token is not used.

• Authentication with Docusign via JSON Web Token (JWT) Grant. When the token expires, it updates automatically.

eSignature API

For more information about the scopes used for obtaining authorization to use the eSignature API, see Required scopes.

For a list of code examples that use the eSignature API, see the How-to guides overview on the Docusign Developer Center.

Rooms API

Note: To use the Rooms API, you must also create your Rooms developer account. Examples 4 and 6 require that you have the Docusign Forms feature enabled in your Rooms for Real Estate account.
For more information about the scopes used for obtaining authorization to use the Rooms API, see Required scopes.

For a list of code examples that use the Rooms API, see the How-to guides overview on the Docusign Developer Center.

Click API

For more information about the scopes used for obtaining authorization to use the Click API, see Required scopes

For a list of code examples that use the Click API, see the How-to guides overview on the Docusign Developer Center.

Monitor API

Note: To use the Monitor API, you must also enable Docusign Monitor for your organization.

For information about the scopes used for obtaining authorization to use the Monitor API, see the scopes section.

For a list of code examples that use the Monitor API, see the How-to guides overview on the Docusign Developer Center.

Admin API

Note: To use the Admin API, you must create an organization in your Docusign developer account. Also, to run the Docusign CLM code example, CLM must be enabled for your organization.

For information about the scopes used for obtaining authorization to use the Admin API, see the scopes section.

For a list of code examples that use the Admin API, see the How-to guides overview on the Docusign Developer Center.

Web Forms API

The Web Forms API is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether the Web Forms API is available for your production account plan.

For more information about the scopes used for obtaining authorization to use the Rooms API, see Required scopes.

For a list of code examples that use the Web Forms API, see the How-to guides overview on the Docusign Developer Center.

Installation

Prerequisites

Note: If you downloaded this code using Quickstart from the Docusign Developer Center, skip items 1 and 2 as they were automatically performed for you.

1. A free Docusign developer account; create one if you don't already have one.

2. A Docusign app and integration key that is configured to use either Authorization Code Grant or JWT Grant authentication.

   This video demonstrates how to obtain an integration key.

   To use Authorization Code Grant, you will need an integration key and a secret key. See Installation steps for details.

   To use JWT Grant, you will need an integration key, an RSA key pair, and the User ID GUID of the impersonated user. See Installation steps for JWT Grant authentication for details.

   For both authentication flows:

   If you use this launcher on your own workstation, the integration key must include a redirect URI of http://localhost:3000/ds/callback

   If you host this launcher on a remote web server, set your redirect URI as

   {base_url}/ds/callback

   where {base_url} is the URL for the web app.

3. Python 3.

4. If you are working on a Windows with a Python version after 3.10 you will also need to install Microsoft C++ Build Tools. After installing that run pip install --upgrade setuptools.

Installation steps

Note: If you downloaded this code using Quickstart from the Docusign Developer Center, skip step 4 as it was automatically performed for you.

1. Extract the Quickstart ZIP file or download or clone the code-examples-python repository.
2. In your command-line environment, switch to the folder:
   cd <Quickstart folder> or cd code-examples-python
3. To install dependencies, run: pip3 install -r requirements.txt (or pipenv can be used)
4. To configure the launcher for Authorization Code Grant authentication, create a copy of the file app/ds_config_sample.py and save the copy as app/ds_config.py.
   1. Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in ds_config.py as your ds_client_id.
   2. Generate a secret key, if you don’t already have one. Under Authentication, select + ADD SECRET KEY. Copy the secret key and save it in ds_config.py as your ds_client_secret.
   3. Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:3000/ds/callback. Select SAVE.
   4. Set a name and email address for the signer. In ds_config.py, save an email address as signer_email and a name as signer_name.
      Note: Protect your personal information. Please make sure that ds_config.py will not be stored in your source code repository.
5. Run the launcher:python run.py
   Note: You will need to alias the python command to run Python 3 or use python3 run.py
6. Open a browser to http://localhost:3000

Installation steps for JWT Grant authentication

Note: If you downloaded this code using Quickstart from the Docusign Developer Center, skip step 4 as it was automatically performed for you.
Also, in order to select JSON Web Token authentication in the launcher, in app/ds_config.py, change the quickstart setting to "false".

1. Extract the Quickstart ZIP file or download or clone the code-examples-python repository.
2. In your command-line environment, switch to the folder: cd <Quickstart folder> or cd code-examples-python
3. To install dependencies, run: pip3 install -r requirements.txt (or pipenv can be used)
4. To configure the launcher for JWT Grant authentication, create a copy of the file app/ds_config_sample.py and save the copy as app/ds_config.py.
   1. Add your User ID. On the Apps and Keys page, under My Account Information, copy the User ID GUID and save it in ds_config.py as your ds_impersonated_user_id.
   2. Add your integration key. On the Apps and Keys page, under Apps and Integration Keys, choose the app to use, then select Actions > Edit. Under General Info, copy the Integration Key GUID and save it in ds_config.py as your ds_client_id.
   3. Generate an RSA key pair, if you don’t already have one. Under Authentication, select + GENERATE RSA. Copy the private key, and save it in a new file named app/private.key.
   4. Add the launcher’s redirect URI. Under Additional settings, select + ADD URI, and set a redirect URI of http://localhost:3000/ds/callback. Select SAVE.
   5. Set a name and email address for the signer. In ds_config.py, save an email address as signer_email and a name as signer_name.
      Note: Protect your personal information. Please make sure that your ds_config.py and private.key files will not be stored in your source code repository.
5. Run the launcher:python run.py
   Note: You will need to alias the python command to run Python 3 or use python3 run.py
6. Open a browser to http://localhost:3000
7. On the black navigation bar, select Login.
8. From the picklist, select JSON Web Token > Authenticate with Docusign.
9. When prompted, log in to your Docusign developer account. If this is your first time using the app, select ACCEPT at the consent window.
10. Select your desired code example.

JWT grant remote signing and Authorization Code Grant embedded signing projects

See Docusign Quickstart overview on the Docusign Developer Center for more information on how to run the JWT grant remote signing project and the Authorization Code Grant embedded signing project.

Installation steps for JWT grant remote signing example

Follow the instructions below if you downloaded the JWT grant remote signing example.

1. Extract the Quickstart ZIP file or download or clone the code-examples-python repository.
2. Run the JWT console project: python jwt_console.py. If you do not already have the docusign-esign package, it will be installed for you when you start the project. Note: You will need to alias the python command to run Python 3 or use python3 run.py
3. Follow the prompts from the command line to grant consent in your browser.
4. Return to the command line and follow the prompts to enter the names and email addresses of your recipients.
5. Check your email to sign the example document.

Payments code example

To use the payments code example, create a test payment gateway on the Payments page in your developer account. See Configure a payment gateway for details.

Once you've created a payment gateway, save the Gateway Account ID GUID to ds_config.py.

License and additional information

License

This repository uses the MIT License. See LICENSE for details.

Pull Requests

Pull requests are welcomed. Pull requests will only be considered if their content uses the MIT License.

code-examples-python's Issues

Trying to run the code

Clean checkout. I believe I've got the credentials correct. Click on "Use embedded signing" and it sends me to DocuSign login, this then tells me "There are no redirect URIs registered with DocuSign":

Run example "eg008_create_template.py"

Error in "Use embedded signing" using JWT

Exploring first example ("Use embedded signing") with JWT option i came across an error with redirect after return from https://account-d.docusign.com/ domain:

127.0.0.1 - - [27/Nov/2020 13:55:36] "GET /ds/callback?code=eyJ0eXXXXXXXNVCIsImFsZyI6IlJTMjU-------exemplary_access_token------------9MYriQVAAEAAAAYAAImtjA HTTP/1.1" 500 -
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/flask/app.py", line 2463, in __call__
    return self.wsgi_app(environ, start_response)
  File "/usr/lib/python3/dist-packages/flask/app.py", line 2449, in wsgi_app
    response = self.handle_exception(e)
  File "/usr/lib/python3/dist-packages/flask/app.py", line 1866, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/usr/lib/python3/dist-packages/flask/_compat.py", line 39, in reraise
    raise value
  File "/usr/lib/python3/dist-packages/flask/app.py", line 2446, in wsgi_app
    response = self.full_dispatch_request()
  File "/usr/lib/python3/dist-packages/flask/app.py", line 1951, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/usr/lib/python3/dist-packages/flask/app.py", line 1820, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/usr/lib/python3/dist-packages/flask/_compat.py", line 39, in reraise
    raise value
  File "/usr/lib/python3/dist-packages/flask/app.py", line 1949, in full_dispatch_request
    rv = self.dispatch_request()
  File "/usr/lib/python3/dist-packages/flask/app.py", line 1935, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "/home/rafal/code/Testapp-python/app/docusign/views.py", line 40, in ds_callback
    resp = DSClient.get_token(session["auth_type"])
  File "/home/rafal/code/Testapp-python/app/docusign/ds_client.py", line 143, in get_token
    resp = cls.get(auth_type).to_dict()
AttributeError: 'NoneType' object has no attribute 'to_dict'

.... and consent grant process cannot be finished

ubuntu 20.04
python 3.8.5
flask 1.1.1
docusign-esign 3.6.0

docusign_maestro not found

When I try to run the examples the run.py does not work as it tries to import docusign_maestro which is not part of the requirements (and nowhere to be found).

unable to get local issuer certificate

Hi,
After download the demo, and config the ds_config.py, run the app.
I got this error during process. Anyone can help? Thanks in advance!

127.0.0.1 - - [04/Mar/2023 22:31:59] "GET /ds/callback?code=eyJ0eXAiOiJNVCIsImFsZyI6IlJTMjU2Iiwia2lkIjoiNjgxODVmZjEtNGU1MS00Y2U5LWFmMWMtNjg5ODEyMjAzMzE3In0.AQsAAAABAAYABwCALDM1vRzbSAgAgLi5fL0c20gCALbi4SrnI_RDshOSksbxKEAVAAEAAAAYAAEAAAAFAAAADQAkAAAAMTMyZjEyZDUtZWZhNi00ZmFmLWI4NmEtMGViMjRmNDg2MmNiIgAkAAAAMTMyZjEyZDUtZWZhNi00ZmFmLWI4NmEtMGViMjRmNDg2MmNiNwCcIV56zLFJR6pJzC8gDNlHMAAA__QMuBzbSBIAAQAAAAMAAAB0c3Y.VVjJFOAeRdluqfLBVvAwHYsOpQA2PNuEMM1kFPnSvdyoazKSAhyvOYhd-CcmWdzYY7WUJxOL4b2UnYWv4Z8yZcWjc8gTuTQ_1TrlF1ZHqgwmhAfQ6jH4Rdanw11RaMv1K-rW0lXFmBczlUaEKezAAS9_hTtiPqfZGs5yDDCvy19JdWnt6lasala8v2MRZKaSGPkAYXaHR6pIDzQOkDHTZ8XWpAfjF4BJbIyt935j0MQaVt5fiCRJf8RIMS1uOBtbGwWinY2Cy15xW6Ksh6UA9S_QxVpJmicrkYuFzsX_qCA1bFfvfka2lpbslZvhpqs2Ztt2kkmvX_H4JYEyD6Lz2Q&state=C880DA7425224C36AB2283F49A3C3397 HTTP/1.1" 500 -

ModuleNotFoundError: No module named 'app'

Hi,

Trying to test bulk user export script, but get following error trying to import. Can you advise what module is required?

ModuleNotFoundError: No module named 'app'

Thx

"private.key" file in wrong folder

When I try to run first example (Use embedded signing), on route /ds/must_authenticate, when I choose option JSON Web Token from the list "Please choose OAuth2.0 grant type", I get error: ValueError: Could not deserialize key data.

In my opinion this error stem from wrong location of "private.key" file. Originally file is located in ./app/private.key. After I moved it to ./private.key that error doesn't appeare anymore.

ubuntu 20.04

python 3.8.5
flask 1.1.1
docusign-esign 3.6.0

Disable redirect after document signing

Is it possible to disable the return_url in the createRecipient endpoint? Or maybe there is another way to get the link to the Envelope?

Pipfile not aligned with requirements

I got fooled when try to install dependencies with pipenv when I saw the project is containing a Pipfile, but it lacks all dependencies defined in requirements.txt

How to assign SignHere Tabs in Bulk Send Envelope

I have set up every other thing for bulk send and it's working pretty nicely. Following is the placeholder snippet which is being replaced by the original recipients in the bulk list:

        signer = Signer(name='Multi Bulk Recipient::signer', email='[email protected]',
                        role_name='signer', note='', routing_order='1', status='created', delivery_method='email',
                        recipient_id='13', recipient_type='signer')
        sign_here = SignHere(anchor_string='**Employee Signature**', anchor_units='pixels',
                             anchor_y_offset='10', anchor_x_offset='20')
        signer.tabs = Tabs(sign_here_tabs=[sign_here])

       envelope_api.create_recipient(ACCOUNT_ID, envelope_id, recipients=Recipients(signers=[signer]))

But it is not creating the SignHere tab in the document. This same code was working in case of single envelope but that's not the case here. Can anyone help?

question on app_url

I do not know what to put in the config file ds_config.py for this fields:

"app_url": "http://localhost:3000", # The URL of the application. Eg http://localhost:5000
# NOTE: You must add a Redirect URI of appUrl/ds/callback to your Integration Key.
# Example: http://localhost:5000/ds/callback

Where to find the application url? And why and how to add ds/callback to integration Key?
Thank you for your answers.
regards