Article : GETTING STARTED WITH OUR ELECTRONIC SIGNATURE API
GETTING STARTED WITH OUR ELECTRONIC SIGNATURE API
INTRODUCTION
This guide for developpers and integrators describes the procedure to integrate Universign's contract signature service to a client web site.
While great care has been taken to make integration as simple as possible, the reader is assumed to be familiar with programming concepts in the language used for integration.
PREREQUISITE
The online contract signature service is based on the notion of collection of signatures. A collection of signatures is composed of documents to sign and a list of signatories who will afflix their signature on the documents.
Each signatory is defined by its first name and last name, a mobile phone number or an email address in order to receive his secret code.
Each document - in the PDF format - is defined by its name and content.
Each collection creation request must contain the URL where to redirect the signatory after the signing process took place. It is possible to define different URLs in case of success, failure or cancelation.
DESCRIPTION OF THE WORKFLOW
scheme of digital signature collection
The workflow of a basic collection is as follows:
When your client clicks on the 'sign' button of your web page, you emit a collection creation request towards Universign. It must contain all the information about the signatory (first name, last name, mobile phone number), but also the redirect addresses at the end of the process.
Universign responds sending you the signing URL and the id of the collection. You must keep this id (in a database or a user session) in order to subsequently retrieve the signed document.
Redirect your client to the URL Universign sent you (using a HTTP code 302).
Once the signing process has been completed (a success or a failure), the signatory is redirected to the URL you specified during the collection creation. With the id of the collection, you can retrieve the signed document and present it to your client.
CODE EXAMPLES
Our code examples use the library "XML-RPC for PHP" available at the address http://phpxmlrpc.sourceforge.net.
This code example creates a simple signature collection with a unique document for one signatory with SMS authentication.
include("path/to/xmlrpc.inc");
//used variables
$uni_url = "https://login:password@ws.universign.eu/sign/rpc/"; // address of the universign server with basic authentication
$firstname = "John"; // the signatory first name
$lastname = "Doe"; // the signatory last name
$phoneNumber = "0123456789"; // the signatory mobile phone number
$doc_name ="documentToSign.pdf"; // the name of the PDF document to sign
$doc_content = file_get_contents($doc_name); // the binary content of the PDF file
$returnPage = array (
"success" => "https://www.google.com/#q=success",
"fail" => "https://www.google.com/#q=fail",
"cancel" => "https://www.google.com/#q=cancel"
);
//create the request
$c = new xmlrpc_client($uni_url);
$signer = array(
"firstname" => new xmlrpcval($firstname, "string"),
"lastname" => new xmlrpcval($lastname, "string"),
"phoneNum"=> new xmlrpcval($phoneNumber, "string")
);
$doc = array(
"content" => new xmlrpcval($doc_content, "base64"),
"name" => new xmlrpcval($doc_name, "string")
);
$language = "en";
$signers = array(new xmlrpcval($signer, "struct"));
$request = array(
"documents" => new xmlrpcval(array(new xmlrpcval($doc, "struct")), "array"),
"signers" => new xmlrpcval($signers, "array"),
// the return urls
"successURL" => new xmlrpcval($returnPage["success"], "string"),
"failURL" => new xmlrpcval($returnPage["fail"], "string"),
"cancelURL" => new xmlrpcval($returnPage["cancel"], "string"),
//the types of accepted certificate : timestamp for simple signature
"certificateTypes" => new xmlrpcval(array(new xmlrpcval("timestamp", "string")), "array"),
"language" => new xmlrpcval($language, "string"),
//The OTP will be sent by SMS
"identificationType" => new xmlrpcval("sms", "string")
);
$f = new xmlrpcmsg('requester.requestTransaction', array(new xmlrpcval($request, "struct")));
//send request and stores response values
$r = &$c->send($f);
if (!$r->faultCode()) {
//if the request succeeded
$url = $r->value()->structMem('url')->scalarVal(); //you should redirect the signatory to this url
$id = $r->value()->structMem('id')->scalarVal(); //you should store this id
} else {
//displays the error code and the fault message
print "An error occurred: ";
print "Code: " . $r->faultCode(). " Reason: '" . $r->faultString();
}
This code example uses an id from a collection created previously to retrieve the signed document. It is executed after the redirection of the signatory to the success URL.
include("path/to/xmlrpc.inc");
//used variables
$uni_url = "https://login:password@ws.universign.eu/sign/rpc/"; // address of the universign server with basic authentication
$uni_id = "99999999-9999-9999-9999-999999999999"; // a collection id
//create the request
$c = new xmlrpc_client($uni_url);
$f = new xmlrpcmsg('requester.getDocumentsByTransactionId', array(new xmlrpcval($uni_id, "string")));
//Send request and analyse response
$r = &$c->send($f);
if (!$r->faultCode()) {
//if the request succeeded
$doc['name'] = $r->value()->arrayMem(0)->structMem('name')->scalarVal();
$doc['content'] = $r->value()->arrayMem(0)->structMem('content')->scalarVal();
} else {
//displays the error code and the fault message
print "An error occurred: ";
print "Code: " . $r->faultCode(). " Reason: '" . $r->faultString();
}
Any doubt or question? Don't hesitate to contact us.
TROUBLESHOOTINGS
Your Universign account will not be debited if an error occurs during the signature process.
When a request fails, Universign returns an error code that will enable you to understand and to solve the problem.
73002 - an error occurred during the signature process.
73003 - an error occurred when managing your certificate.
73010 - your authentication failed.
73011 - no available account.
73024 - unreadable file.
