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.
Node 4 or later.
npm install docusign-esign --save
This client has the following external dependencies:
As of version 4.2.0, Promise support has been added.
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)
.then(function (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)
.then(function (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);
})
.catch(function (error) {
if(error)
throw error;
});
})
.catch(function (error) {
if(error)
throw error;
});
});
app.listen(port, host, function (error) {
if (error)
throw error;
console.log('Your server is running on http://' + host + ':' + port + '.');
});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 = '[email protected]'; // 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)
.then(function (res) {
var baseUri,
accountDomain;
apiClient.addDefaultHeader('Authorization', 'Bearer ' + res.body.access_token);
apiClient.getUserInfo(res.body.access_token)
.then(function (userInfo) {
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]);
})
.catch(function(error){
if (error) {
return next(error);
}
});
})
.catch(function(error) {
if (error) {
return next(error);
}
});
},
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})
.then(function(envelopeSummary) {
console.log('EnvelopeSummary: ' + JSON.stringify(envelopeSummary));
return next(null);
})
.catch(function (error){
if (error) {
return next(error);
}
});
}
], function end (error) {
if (error) {
console.log('Error: ', error);
process.exit(1);
}
process.exit();
});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)
.then(function (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);
})
.catch(function (error) {
if (error)
console.log(error)
throw error;
});
});
app.listen(port, host, function(error) {
if (error)
throw error;
console.log('Your server is running on http://' + host + ':' + port + '.');
});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:
-
After obtaining a Bearer token, call the OAuth::userInfo endpoint.
The
getUserInfomethod 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_urifield.Note: The host for the OAuth::userInfo method is
account-d.docusign.comfor the demo/developer environment, andaccount.docusign.comfor the production environments. -
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.
-
Instantiate the SDK using the basePath. Eg
ApiClient apiClient = new ApiClient(basePath); -
Create the
authentication_valueby combining thetoken_typeandaccess_tokenfields you receive from a DocuSign OAuth flow. See the authentication guide. -
Set the SDK's authentication header by using
Configuration.Default.AddDefaultHeader('Authorization', authentication_value)
Unit tests are available in the Test folder.
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.
Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the DocuSignAPI tag.
The DocuSign Node Client is licensed under the MIT License.