pleasesign-api v1.0.2
nodejs-sdk
NodeJS SDK for interacting with the PleaseSign API
The NodeJS SDK for PleaseSign is straightforward and simple to use. We provide an interface for the common document actions that you'll need to perform from an integrated system.
Installation
Get the package into your $GOPATH/src with go get github.com/PleaseSign/golang-sdk
npm
You can install the library via npm with:
npm install pleasesign-api --savegit
You can install the library straight from the github repository with:
npm install PleaseSign/nodejs-sdk --saveAuthentication
The first step is to setup the authentication when initialising the package.
// Require the sdk and setup the default client for your authentication.
var PleasesignApi = require('pleasesign-api');
var defaultClient = PleasesignApi.ApiClient.instance;
// This will be your X-PLEASESIGN-KEY id.
var key = defaultClient.authentications['key'];
key.apiKey = "PLSAPPxxx"
// This will be your X-PLEASESIGN-APP secret key.
var value = defaultClient.authentications['value'];
value.apiKey = ""
// Make a client api to begin making calls. This will be authenticated with the
// token you have just set up.
var api = new PleasesignApi.ClientApi()Create a file
All documents sent through the API must first have file/s created for sending. All files
must be uploaded with the createFile function. This will process the file through PleaseSign, and allow
the file to be assigned to a document. Note: Files may be reused between documents, however we only
guarantee that a file will be available for up to 1 week after being created.
var apiInstance = new PleasesignApi.ClientApi();
// Require the fs module, and read the file into a stream. This could also
// be a Blob or Buffer.
var fs = require('fs');
var file = fs.createReadStream("/path/to/myfile.pdf");
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful call made, access the response accordingly.
console.log(data.id);
console.log(data.page_count);
// $ e64d894c-a15d-4b61-877a-ea83533062db
// $ 1
}
};
apiInstance.createFile(file, callback);Send a document
If you want to send a document, you can do so by using the sendDocument function.
This function requires a full document object constructed with recipients, their tabs, and valid files.
See the api documentation for more info on what is required for a valid document request.
The document will be sent shortly after making this request.
var apiInstance = new PleasesignApi.ClientApi();
// Create the document input.
var documentInput = {
title: "Sent from NodeJS SDK",
message: "Sign this document, please.",
demo: true,
files: [
{
id: "e64d894c-a15d-4b61-877a-ea83533062db", // This is a valid file_id, returned by the File POST.
order: 1
}
],
recipients: [
{
first_name: "Michael",
last_name: "Fitz-Payne",
email: "mfp@pleasesign.com.au",
order: 1,
tabs: [
{
x: 43,
y: 102,
text_height: 16,
type: "full_name",
page: 1
},
{
x: 292,
y: 98,
height: 24,
type: "signature",
page: 1
}
]
}
]
}
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful call made, access the response accordingly.
console.log(data.id);
// $ PLSDOCY1JFwiMU2lF0fbZYGsHfMhwx
}
};
apiInstance.sendDocument(documentInput, callback);Get a document's information
You can retrieve document information either by id, or by listing the documents sent from your account.
To get a document by id, use the getDocument function.
var apiInstance = new PleasesignApi.ClientApi();
// Make the call with the desired documentId.
var documentId = "PLSDOCY1JFwiMU2lF0fbZYGsHfMhwx";
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful request, handle the response accordingly.
for (var key in data) {
if (data.hasOwnProperty(key)) {
console.log(key + ": " + data[key]);
}
}
/* $
id: PLSDOCY1JFwiMU2lF0fbZYGsHfMhwx
title: Sent from NodeJS SDK
message: Sign this document, please.
void_reason: null
status: complete
demo: true
pages: 1
sender_name: Michael Fitz-Payne
sender_email: mfitzpayne@gmail.com
created_date: 1468558152
recipients: [object Object] // This is an array of recipients.
*/
}
};
apiInstance.getDocument(documentId, callback);List my documents
To list the documents sent from your account, you can use the getDocuments function, and pass in the parameters to filter out unwanted results. The result set is paginated. See the api documentation
for more information on the filters and working with our pagination.
var apiInstance = new PleasesignApi.ClientApi();
// Setup the optional parameters. See the api documentation for more information
// on the optional params for this function.
var opts = {
'page': 1,
'perPage': 1,
'status': "complete"
};
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful response, handle the data accordingly.
console.log(data._metadata);
results = data.records;
console.log(results);
/*
{
current_page: 1,
results_per_page: 1,
total_pages: 15,
total_results: 15
}
[
{
id: 'PLSDOCil9gg4V1xs1CyiW6CZ48wpKg',
title: 'Sent from Nodejs Sdk',
message: 'Sign this, please.',
void_reason: 'null',
status: 'complete',
demo: true,
pages: 1,
sender_name: 'Michael Fitz-Payne',
sender_email: 'mfp@pleasesign.com.au',
created_date: 1466664971,
recipients: [ [Object] ]
}
]
*/
}
};
apiInstance.getDocuments(opts, callback);Retrieve a link
If you want to retrieve a link to the document PDF file, you can use the getDocumentFile function.
This returns a URL to the document file. The URL expires after a short period of time. The expiry time is returned with the response.
var apiInstance = new PleasesignApi.ClientApi();
// Call the function with the document you want to retrieve a link for.
var documentId = "PLSDOCil9gg4V1xs1CyiW6CZ48wpKg";
var type = "original";
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful response, handle the data accordingly.
console.log("link: ", data.link);
console.log("expiry: ", data.expiry);
/*
link: https://...(truncated)...
expiry: 1468561028
*/
}
};
apiInstance.getDocumentFile(documentId, type, callback);Correct a recipient
If you have the information wrong for a recipient, or you want to change who you're sending a document to,
you can use the correctRecipient function. This will update the recipient given as the recipientID (you can find the recipientID from the GetDocument function) with the new information provided.
var apiInstance = new PleasesignApi.ClientApi();
// Call the function with the recipientID of the recipient you want to update.
// The options passed in will be the new recipients information.
var recipientId = "jNflKZvWYjdHC1FT";
var opts = {
'firstName': "Michael",
'lastName': "Fitz-Payne",
'email': "mfp@pleasesign.com.au",
'order': 1
};
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful request, handle the data accordingly.
for (var key in data) {
if (data.hasOwnProperty(key)) {
console.log(key + ": " + data[key]);
}
}
/*
id: Ld3tWRra8oQN06Ld
first_name: Michael
last_name: Fitz-Payne
status: sent
email: mfp@pleasesign.com.au
next_reminder_date: 1468732468
order: 1
authentication: [object Object]
last_contacted_date: 1468559667
last_viewed_date: NaN
bounce_message: null
*/
}
};
apiInstance.correctRecipient(recipientId, opts, callback);Void a document
If you no longer wish for anyone to be able to sign a document, use the voidDocument function. This will prevent
any more changes to the document, and notify anyone that has signed the document that a void has occurred. This is not
reversable.
var apiInstance = new PleasesignApi.ClientApi();
// Call the function with the documentID to void, and the reason. This will
// be saved against the document for future reference.
var documentId = "PLSDOCf8mc7AE8qpFRAOHKMXt0nqJK";
var opts = {
'reason': "This is no longer relevant"
};
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful calls to voidDocument return 204 No Content.
}
};
apiInstance.voidDocument(documentId, opts, callback);Send a reminder
Sometimes people aren't able to sign a document straight away. PleaseSign automatically sends out reminders, however you
may wish to send another one outside of the normal timeframe. You can do this by using the remindRecipient function. The
recipient provided in the recipientID will be sent a signing link (if they are eligible to sign the document).
The recipientID can be retrieved by calling the getDocument function.
var apiInstance = new PleasesignApi.ClientApi();
// Call the function with the recipientId of the recipient you want to remind.
var recipientId = "Ld3tWRra8oQN06Ld";
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
// Successful calls to remindRecipient return 204 No Content.
}
};
apiInstance.remindRecipient(recipientId, callback);For more information, visit our api documentation or drop us a line at api-support@pleasesign.com.au.
8 years ago