docusign-esign
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/docusign-esign package

    4.3.0 • Public • Published

    The Official DocuSign Node Client

    NPM version NPM downloads Build status Coverage Status

    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

    As of version 4.2.0, Promise support has been added.

    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)
      .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 + '.');
    });

    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 = 'joan.jett@example.com'; // 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();
    });

    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)
      .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 + '.');
    });

    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.

    Install

    npm i docusign-esign@4.3.0

    Version

    4.3.0

    License

    MIT

    Unpacked Size

    3.24 MB

    Total Files

    416

    Last publish

    Collaborators

    • dsdevcenter