docusign-esign

The Official DocuSign Node Client

NPM module that wraps the DocuSign API

Documentation about the DocuSign API

Documentation about this package

You can sign up for a free developer sandbox.

Requirements

Node 4 or later.

Installation via the NPM Package Manager

npm install docusign-esign --save

Dependencies

This client has the following external dependencies:

• jsonwebtoken@8.2.0
• passport-oauth2@1.4.0
• superagent@3.8.2

Usage

OAuth Authorization Code Grant

See the Node.JS OAuth Authorization Code Grant flow example for Node.JS 8.10 or later. It also shows how to use the SDK with promises instead of callback functions.

The following example uses callback functions.

uncomment auth code grant section in test/OAuthClientTests.js, run it and then open http://localhost:3000.

const express = require('express');
const docusign = require('docusign-esign');
const apiClient = new docusign.ApiClient();

const app = express();
const port = process.env.PORT || 3000;
const host = process.env.HOST || 'localhost';

const integratorKey = 'ae30ea4e-3959-4d1c-b867-fcb57d2dc4df'; // An IK for a non-mobile docusign account
const clientSecret = 'b4dccdbe-232f-46cc-96c5-b2f0f7448f8f';
const redirectUri = 'http://localhost:3000/auth'; // This needs to be registered with the integrator key in your admin account
const basePath = 'https://demo.docusign.net/restapi';

const responseType = apiClient.OAuth.ResponseType.CODE; // Response type of code, to be used for the Auth code grant
const scopes = [apiClient.OAuth.Scope.EXTENDED];
const randomState = "*^.$DGj*)+}Jk"; // after successful login you should compare the value of URI decoded "state" query param with the one created here. They should match

apiClient.setBasePath(basePath);

app.get('/', function (req, res) {
    const authUri = apiClient.getAuthorizationUri(integratorKey, scopes, redirectUri, responseType, randomState);//get DocuSign OAuth authorization url
     //Open DocuSign OAuth login in a browser, res being your node.js response object.
    res.redirect(authUri);
});

app.get('/auth', function (req, res) {
  // IMPORTANT: after the login, DocuSign will send back a fresh
  // authorization code as a query param of the redirect URI.
  // You should set up a route that handles the redirect call to get
  // that code and pass it to token endpoint as shown in the next
  // lines:
  apiClient.generateAccessToken(integratorKey, clientSecret, req.query.code, function (err, oAuthToken) {
    
    console.log(oAuthToken);
    
    //IMPORTANT: In order to access the other api families, you will need to add this auth header to your apiClient.
    apiClient.addDefaultHeader('Authorization', 'Bearer ' + oAuthToken.accessToken);

    apiClient.getUserInfo(oAuthToken.accessToken, function (err, userInfo) {
      console.log("UserInfo: " + userInfo);
      // parse first account's baseUrl
      // below code required for production, no effect in demo (same
      // domain)
      apiClient.setBasePath(userInfo.accounts[0].baseUri + "/restapi");
      res.send(userInfo);
    });
  });
});

app.listen(port, host, function (err) {
  if (err)
    throw err;

  console.log('Your server is running on http://' + host + ':' + port + '.');
});

OAuth JSON Web Token (JWT) Grant

See the Node.JS Service Integration example for Node 8.10 or later. It uses the OAuth JWT Grant flow. It also demonstrates how to use the SDK with promises.

The following example can be used with an older version of Node.JS.

var docusign = require('docusign-esign');
var oAuth = docusign.ApiClient.OAuth;
var restApi = docusign.ApiClient.RestApi;
var async = require('async');
var path = require('path');

var integratorKey = '***';                    // Integrator Key associated with your DocuSign Integration
var userId = 'YOUR_USER_ID';                  // API Username for your DocuSign Account (use the GUID not the email address)
var fullName = 'Joan Jett';                   // Recipient's Full Name
var recipientEmail = '[e-mail]'; // Recipient's Email
var templateId = '***';                       // ID of the Template you want to create the Envelope with
var templateRoleName = '***';                 // Role name of the Recipient for the Template

var expiresIn = 3600; // Number of seconds until the JWT assertion is invalid
var basePath = restApi.BasePath.DEMO;
var oAuthBasePath = oAuth.BasePath.DEMO;
var redirectURI = 'https://www.docusign.com/api';
var privateKeyFilename = 'keys/docusign_private_key.txt'; //path to the file storing the private key from the RSA Keypair associated to the Integrator Key

var apiClient = new docusign.ApiClient({
    basePath: basePath,
    oAuthBasePath: oAuthBasePath
});
var scopes = [
    oAuth.Scope.IMPERSONATION,
    oAuth.Scope.SIGNATURE
];
  
async.waterfall([
  function initApiClient (next) {
    
    // assign the api client to the Configuration object
    docusign.Configuration.default.setDefaultApiClient(apiClient);

    // IMPORTANT NOTE:
    // the first time you ask for a JWT access token, you should grant access by making the following call
    // get DocuSign OAuth authorization url:
    var oauthLoginUrl = apiClient.getJWTUri(integratorKey, redirectURI, oAuthBasePath);
    // open DocuSign OAuth authorization url in the browser, login and grant access
    console.log(oauthLoginUrl);
    // END OF NOTE

    // configure the ApiClient to asynchronously get an access to token and store it

    var fs = require('fs');
    var privateKeyFile = fs.readFileSync(path.resolve(__dirname, privateKeyFilename));
    apiClient.requestJWTUserToken(integratorKey, userId, scopes, privateKeyFile, expiresIn, function (err, res) {
      var baseUri,
        accountDomain;
      if (err) {
        return next(err);
      }
      apiClient.addDefaultHeader('Authorization', 'Bearer ' + res.body.access_token);

      apiClient.getUserInfo(res.body.access_token, function (err, userInfo) {
        if (err) {
          return next(err);
        }
        accountId = userInfo.accounts[0].accountId;
        baseUri = userInfo.accounts[0].baseUri;
        accountDomain = baseUri.split('/v2');
        apiClient.setBasePath(accountDomain[0] + '/restapi');
        console.log('LoginInformation: ' + JSON.stringify(userInfo));
        return next(null, userInfo.accounts[0]);
      });
    });
  },

  function sendTemplate (loginAccount, next) {
    // create a new envelope object that we will manage the signature request through
    var envDef = new docusign.EnvelopeDefinition();
    envDef.emailSubject = 'Please sign this document sent from Node SDK';
    envDef.templateId = templateId;

    // create a template role with a valid templateId and roleName and assign signer info
    var tRole = new docusign.TemplateRole();
    tRole.roleName = templateRoleName;
    tRole.name = fullName;
    tRole.email = recipientEmail;

    // create a list of template roles and add our newly created role
    var templateRolesList = [];
    templateRolesList.push(tRole);

    // assign template role(s) to the envelope
    envDef.templateRoles = templateRolesList;

    // send the envelope by setting |status| to 'sent'. To save as a draft set to 'created'
    envDef.status = 'sent';

    // use the |accountId| we retrieved through the Login API to create the Envelope
    var accountId = loginAccount.accountId;

    // instantiate a new EnvelopesApi object
    var envelopesApi = new docusign.EnvelopesApi();

    // call the createEnvelope() API
    envelopesApi.createEnvelope(accountId, {'envelopeDefinition': envDef}, function (err, envelopeSummary, response) {
      if (err) {
        return next(err);
      }
      console.log('EnvelopeSummary: ' + JSON.stringify(envelopeSummary));
      next(null);
    });
  }

], function end (error) {
  if (error) {
    console.log('Error: ', error);
    process.exit(1);
  }
  process.exit();
});

OAuth Implicit Grant

uncomment implicit grant section in test/OAuthClientTests.js, run it and then open http://localhost:3000.

const express = require('express');
const docusign = require('docusign-esign');
const apiClient = new docusign.ApiClient();

const app = express();
const port = process.env.PORT || 3000;
const host = process.env.HOST || 'localhost';

const integratorKey = '68c1711f-8b19-47b1-888f-b49b4211d831'; // An IK for a mobile docusign account
const redirectUri = 'http://localhost:3000/auth';
const basePath = 'https://demo.docusign.net/restapi';

const responseType = apiClient.OAuth.ResponseType.TOKEN; // Response type of token, to be used for implicit grant
const scopes = [apiClient.OAuth.Scope.EXTENDED];
const randomState = "*^.$DGj*)+}Jk"; // after successful login you should compare the value of URI decoded "state" query param with the one created here. They should match

apiClient.setBasePath(basePath);

app.get('/', function (req, res) {
    const authUri = apiClient.getAuthorizationUri(integratorKey, scopes, redirectUri, responseType, randomState);//get DocuSign OAuth authorization url
     //Open DocuSign OAuth login in a browser, res being your node.js response object.
    res.redirect(authUri);
});

app.get('/auth', function (req,res) {
  // IMPORTANT: after the login, DocuSign will send back a new
  // access token in the hash fragment of the redirect URI.
  // You should set up a client-side handler that handles window.location change to get
  // that token and pass it to the ApiClient object as shown in the next
  // lines:
  res.send();
});

app.get('/auth/:accessToken', function (req, res) {
  // This a sample endpoint to allow you to pass in the previously recEIved accesstoken to log in via getUserInfo
  // ex: http://localhost:3000/auth#access_token=<token>&expires_in=<expiresIn>&token_type=<tokenType>&state=<randomState>
  // ex: http://localhost:3000/auth/<token>

  const accessToken = req.params.accessToken;
  
  //IMPORTANT: In order to access the other api families, you will need to add this auth header to your apiClient.
  apiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
  
  apiClient.getUserInfo(accessToken, function (err, userInfo) {
    if (err)
      console.log(err)

    console.log("UserInfo: " + userInfo);
    // parse first account's baseUrl
    // below code required for production, no effect in demo (same
    // domain)
    apiClient.setBasePath(userInfo.accounts[0].baseUri + "/restapi");
    res.send(userInfo);
  });
});

app.listen(port, host, function(err) {
  if (err)
    throw err;

  console.log('Your server is running on http://' + host + ':' + port + '.');
});

The basePath

This section applies to applications which use OAuth for authentication with DocuSign.

The SDK must be configured to use the correct basePath for the accredited user's DocuSign account.

To determine the user's basePath:

1. After obtaining a Bearer token, call the OAuth::userInfo endpoint.

   The getUserInfo method can be used to call the OAuth::userInfo endpoint. See the file ApiClient.js, line 713.

   Use the results to choose the account. One of the user's accounts is their default account. The method's results include the selected account's base_uri field.

   Note: The host for the OAuth::userInfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environments.

2. Combine the base_uri with "/restapi" to create the basePath. Use the basePath for your subsequent API calls for the account id.

   You can and should cache the basePath for at least the user's session with your application. It changes very infrequently.

3. Instantiate the SDK using the basePath. Eg ApiClient apiClient = new ApiClient(basePath);

4. Create the authentication_value by combining the token_type and access_token fields you receive from a DocuSign OAuth flow. See the authentication guide.

5. Set the SDK's authentication header by using Configuration.Default.AddDefaultHeader('Authorization', authentication_value)

Testing

Unit tests are available in the Test folder.

Contributing

This SDK is auto-generated from OpenAPI specification file. For that reason, we actually do NOT accept pull requests. If you find a bug or have an idea that you want to see in the SDK, please open a new issue.

Support

Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the DocuSignAPI tag.

License

The DocuSign Node Client is licensed under the MIT License.

Changelog

[v4.1.0] - eSignature API v18.3.00 - 9/13/2018

Changed

• The getOAuthBasePath() method is now an accessor function for the new oAuthBasePath property, rather than being derived from basePath.
• Updated the swagger spec to version 18.3.00.00

Added

• Created a new ApiClient property, oAuthBasePath. This property is retrieved using getOAuthBasePath() and set by setOAuthBasePath(). DCM-2834
• Created a new docusign.ApiClient.OAuth.BasePath collection that holds base path data for the following environments: STAGE, DEMO, PRODUCTION.
• Created a new docusign.ApiClient.RestApi.BasePath collection that holds rest API base paths for the following environments: STAGE, DEMO, PRODUCTION. These recorded path values can be accessed using an instantiated docusign.apiClient object.
• Added an opts parameter that allows you to specify parameter values when instantiating an apiClient. The opts parameter currently supports passing in basePath and oAuthBasePath values. If not set during instantiation of an apiClient, they default to their production values.
• An Organization value has been added to the account model. DCM-2710

Deprecated

• The configureJWTAuthorizationFlow method is now deprecated. Please use requestJWTUserToken instead, which takes the private key as byte array or a Stream. DCM-2765