PortaSigma integration API

The purpose of this document is to describe the API that allows integration of applications with PortaSigma.

API Goals

The purpose of the API is that all issuer functions can be performed by an application via an API. This includes creation and follow-up of signature requests, as well as receiving notifications.

Resources and Available Functions

For all the operation descriptions, we include a relative URL. The root URL may vary for the PortaSigma SaaS service or for an inhouse install. For PortaSigma.com the API root URL for the API version described in this document is:

https://api.portasigma.com/v1

E.g. where the documents refer to issuing a request as GET /docs/23/, the full request URL should be:

GET https://api.portasigma.com/v1/docs/23/

Operations on Authentication widget

In order to use authentication widget, you will need an access key that you can get from:

GET https://api.portasigma.com/v1/widget/

Operations on Signature Transactions

A signature transaction in PortaSigma consists of a document (a PDF file) with some metadata (title and comments) and a status. A transaction may have an undetermined number of signature requests, each corresponding to a signer. A signer is defined by name, e-mail address (for notifications) and a citizen identifier (for security checks) that consists of a country code and a national identity number (e.g. in Spain, the DNI).

There are three kinds of signature transactions and each one has its mandatory fields and its appropriate signature request/s, this three kinds are:

  • With digital certificate
  • With registered user
  • With no registered user

For simplicity, we will refer to the signature transactions as documents, and to individual signature requests as signers.

From version 1.7.6 onwards, a signature transaction can also have oncopy requests. Those define persons who will receive a copy via e-mail of the signed document. These requests require a name and an e-mail.

This is a list of operations available on these resources:

Operation Command Notes
Get the document list GET /docs/ Return a list with all the documents
Add a document POST /docs/ Data included in the POST are the file and its metadata (title, comments...). It returns a redirection to the created document
Document detail GET /docs/{id}/ Returns an X(HT)ML representation of the uploaded document and its metadata
Delete a document DELETE /docs/{id}/ Delete a document and all the associated information
Download a PDF file GET /docs/{id}.pdf Returns an attachment with the file (mime-type application/pdf)
List of signers GET /docs/{id}/signers/ List of individual signer requests for a document
Add a signer to a document POST /docs/{id}/signers/ Data included in the POST are name, email, and identification. Returns a redirection to the created signer
Add oncopy user to the doc POST /docs/{id}/oncopy/ Data included in the POST are name and email. Returns a redirection to the created oncopy request.
Download attached documents GET /docs/{id}/signers/{rId}/ Returns a zip with all the documents that
from a signature request attacheds/ the signer has attached at the moment of signing.
Download evidence report GET /evr/{id}/ Create and download the evidence report. Only with no registered users.
Upload a P12 file POST /keyfiles/ Upload a P12 or PFX file for cloud signature.
Change password PUT /users/{username}/ Change password account.
Sign a document POST /docs/{id}/signers/{rId}/ Signs the request, using information from the Access Token information provided in the POST. Data included in the POST are username, token, password and comment.

Resource Representation

Read Resource (GET) in XHTML Format

PortaSigma web services use XHTML so that it may be read both by a human in a browser, as well as parsed by an application as well-formed XML, by using XPath expressions.

As a general criterion, resources are represented with semantic XHTML, by using the standard attribute class to identify the type of object contained in the HTML tag. E.g.:

<dd class="description">User Manual</dd>

This allows locating the objects or their attributes with XPath expressions such as:

//dd[@class='description']

Or, using XML namespaces, assuming we mapped x to the namespace http://www.w3.org/1999/xhtml:

//x:dd[@class='description']

In general, you may safely ignore the tag, since the class conveys the real semantics:

//*[@class='description']

(use ‘*’, meaning any tag, instead).

The usual representation of a simple object is done with the dl tag (definition list), using dt (definition term) for the attribute name and dd (definition data) for the attribute value itself.

Example document encoding for a document with no designated signers:

<dl class="document">
  <dt>id</dt> <dd class="id">987</dd>
  <dt>owner</dt> <dd class="owner">carles</dd>
  <dt>description</dt> <dd class="description">Lease Contract</dd>
  <dt>comments</dt> <dd class="comments">Please sign before next week</dd>
  <dt>status</dt> <dd class="status"> <span class="status.code">0</span>
      (<span class="status.text">No Requests</span>)
  </dd>
  <dt>date</dt> <dd class="date">2011-01-27T12:18:00+0100</dd>
  <dt>file</dt> <dd><a class="file" href="../987.pdf">Contract.pdf</a></dd>
  <dt>due date</dt> <dd class="dueDate">2011-02-20T12:00:00+0100</dd>
  <dt>visible</dt> <dd class="visible">false</dd>
  <dt>requests</dt>
  <dd class="requests">
      <span class="num-requests">0</span>
      <ul class="requests list">
      </ul>
  </dd>
</dl>

Object lists are represented as unsorted lists (ul), each element is contained within a li tag, and the attribute data is typically in span tags:

<ul class="documents list">
  <li class="document">
      <h3><a href="952/">Signature transaction [952]</a></h3>
      <p>id: <span class="id">952</span></p>
      <p>description: <span class="description">One File</span></p>
      <p>comments: <span class="comments">Please sign before next week</span></p>
      <p>reference: <span class="reference">FF-222-URL</span></p>
      <p>status: <span class="status">3</span></p>
      <p>date: <span class="date">2011-01-25T15:40:03+0100</span></p>
      <p>file: <span class="filename">OneFile.pdf</span></p>
      <p>download: <a class="download" href="952.pdf">pummer.pdf</a></p>
  </li>

  <li class="document">
      <h3><a href="955/">Signature transaction [955]</a></h3>
      <p>id: <span class="id">955</span></p>
      <p>description: <span class="description">Another file</span></p>
      <p>comments: <span class="comments">See if you agree to this</span></p>
      <p>reference: <span class="reference">FF-223-URL</span></p>
      <p>status: <span class="status">3</span></p>
      <p>date: <span class="date">2011-01-25T15:53:04+0100</span></p>
      <p>file: <span class="filename">AnotherFile.pdf</span></p>
      <p>download: <a class="download" href="955.pdf">pummer.pdf</a></p>
  </li>
  <!-- etc... -->
</ul>

Example XPath for obtaining all document id:

//x:li[@class='document']/x:p/x:span[@class='id']

Status codes for document:

Value Code Description
0 NO_REQUESTS Document was uploaded with no designated signers
2 SENT All requests have been sent
3 SIGNED All designated signers have signed the document
4 REJECTED At least one signer rejected the document
5 PARTIALLY_SIGNED Some have signed the document, but others not yet

For individual requests:

Value Code Description
20 SENT Sent
30 SIGNED Signed
40 REJECTED Rejected

Object Creation (POST)

In order to create resources in Portasigma, there is the HTTP POST method. The behavior for a correct POST is to return a redirection to the newly created resource. The HTTP response will include:

  • Status: 303 (See Other)
  • Location header: the URL to the created resource

The defined behavior for a browser is to issue a GET request to the URL defined in Location. The web service client may do away with this request, unless it needs some of the generated data. The id of the generated resource can be parsed from the location, hence no need to issue the request for that case.

Signature Transaction

In order to allow for file upload, data is encoded as multipart/form-data. The included form fields are:

Name Type Size M/O Description
description text 120 M Descriptive title for the document
comments text 255 O Comments to be included in the e-mail notification sent to the signer. They may be used to notify the purpose of the signature
reference text 255 O A unique reference to the document used by the client application to identify this request
dueDate text 25 O Due date (in ISO 8601 format)
visible text 5 O Apply visible signature (true or false)
visiblePattern text 10 O Visible signature pattern name
file file   M The PDF file that must be signed
sorted checkbox   O Indicates if this is a sorted transaction (default:false)
allowPublicAccess text 5 O Retrieve a public validation code of the document (true or false)
disableAutoSign text   O Indicates if automatic signature will be applied (true or false)
  • M/O: mandatory/optional
  • Input type: the equivalence for HTML input attribute type
  • Size: maximum size for this field

Sample form equivalent for a document upload (and creation of a signature transaction):

<form enctype="multipart/form-data" method="post">
   <p>
      <label for="id_description">Description:</label>
      <input maxlength="120" id="id_description" type="text" name="description" />
   </p>
   <p>
      <label for="id_comments">Comments:</label>
      <input maxlength="255" id="id_comments" type="text" name="comments" />
   </p>
   <p>
      <label for="id_reference">Reference:</label>
      <input maxlength="255" id="id_reference" type="text" name="reference" />
   </p>
   <p>
      <label for="id_file">File:</label>
      <input id="id_file" type="file" name="file" />
   </p>
   <p>
      <label for="id_sorted">Sorted:</label>
      <input id="id_sorted" type="checkbox" name="sorted" value="true" />
   </p>
   <p><input type="submit" value="OK" /></p>
</form>

Sample form equivalent for a document upload with visible signature active and visible signature pattern selected. Pattern must be configured previously through PortaSigma front-end (Visible signature patterns option of My Account section):

<form enctype="multipart/form-data" method="post">
   <p>
      <label for="id_description">Description:</label>
      <input maxlength="120" id="id_description" type="text" name="description" />
   </p>
   <p>
      <label for="id_comments">Comments:</label>
      <input maxlength="255" id="id_comments" type="text" name="comments" />
   </p>
   <p>
      <label for="id_reference">Reference:</label>
      <input maxlength="255" id="id_reference" type="text" name="reference" />
   </p>
       <p>
      <label for="id_visible">Visible:</label>
      <input id="id_visible" type="checkbox" name="visible" value="true" />
   </p>
       <p>
      <label for="id_visiblePattern">Visible pattern:</label>
      <input maxlength="255" id="id_visiblePattern" type="text" name="visiblePattern" />
   </p>
   <p>
      <label for="id_file">File:</label>
      <input id="id_file" type="file" name="file" />
   </p>
   <p>
      <label for="id_sorted">Sorted:</label>
      <input id="id_sorted" type="checkbox" name="sorted" value="true" />
   </p>

   <p><input type="submit" value="OK" /></p>
</form>

As an alternative, a signature transaction may be created from a URL. In this case data is encoded as application/x-www-form-urlencoded. Included fields are:

Name Type Size M/O Description
description text 120 M Descriptive title
comments text 255 O Comments to be included in the e-mail
reference text 255 O Unique reference to the document
dueDate text 25 O Due date (in ISO 8601 format)
visible text   O Apply visible signature (true or false)
visiblePattern text 10 O Visible signature pattern name
url text   M Link to the PDF file that must be signed
sorted text   O Whether the signature is sorted (true or false)
allowPublicAccess text   O Retrieve a public validation code of the document (true or false)

In this case, the PDF file URL must be openly accessible (no authentication required).

Signature Request (add a Signer to a Document)

There are three kinds of requests.
  • Signing with digital certificate
  • Signing with registered user
  • Signing with no registered user

Fields for signing with digital certificate and registered user:

Name Type Size M/O Description
name text 80 M Signer full name (is used in e-mail headings)
email text 320 M Signer e-mail (for notification)
id-country text 2 M Abridged country code (ISO 3166)
id-number text 12 M Depending on the country, national identifier code (e.g. Spanish DNI)
order text 12 M The order of the request in the transaction (if the transaction is sorted, it will be ignored if not)
type text 1 O Type of request (0 for human, 1 for approval. If this parameter is omitted, it will get zero value

In case of signing with registered user, if id-country and id-number are not sent, the signature request will be received by the email’s user.

Fields for signing with no registered user:

Name Type Size M/O Description
name text 80 M Signer full name (is used in e-mail headings)
email text 320 M Signer e-mail (for notification)
id-country text 2 M Abridged country code (ISO 3166)
id-number text 12 M Depending on the country, national identifier code (e.g. Spanish DNI)
type text 1 M Type of request. Must be 2
phone-number text 9 O Indicates phone number where signer will receive a SMS code

In case of signing with a no registered user with SMS, phone-number field is mandatory, if, instead, signature with SMS is not desired phone-number must be omitted.

Sample form to add a signer to a document:

<form enctype="application/x-www-form-urlencoded" method="post">
   <p>
      <label for="id_name">Name:</label>
      <input maxlength="80" id="id_name" type="text" name="name" />
   </p>
   <p>
      <label for="id_email">Email:</label>
      <input maxlength="320" id="id_email" type="text" name="email" />
   </p>
   <p>
       <label for="id_idcountry">ID (Country):</label>
       <input maxlength="2" id="id_idcountry" type="text" name="id-country" />
   </p>
   <p>
       <label for="id_idnumber">ID (Number):</label>
       <input maxlength="12" id="id_idnumber" type="text" name="id-number" />
   </p>
   <p>
       <label for="id_order">Order:</label>
       <input maxlength="12" id="id_order" type="text" name="order" />
   </p>
   <p><input type="submit" value="OK" /></p>
</form>

Oncopy Request (add an oncopy request to a Document)

Included fields are:

Name Type Size M/O Description
name text 80 M User full name (is used in e-mail headings)
email text 320 M User e-mail (for notification)

Sample form to add an oncopy request to a document:

<form enctype="application/x-www-form-urlencoded" method="post">
   <p>
      <label for="id_name">Name:</label>
      <input maxlength="80" id="id_name" type="text" name="name" />
   </p>
   <p>
      <label for="id_email">Email:</label>
      <input maxlength="320" id="id_email" type="text" name="email" />
   </p>
   <p><input type="submit" value="OK" /></p>
</form>

Signature Request (sign a Document)

An Access Token will need to be generated by the signer and provided to the WebService client before access to the signer’s certificate is provided. Included fields are:

Name Type Size M/O Description
username text 80 M The signer Portasigma username
token text 320 M The token label provided for remote signature access
password text 320 O The password for accessing the Token (if specified)
id-country text 2 M Abridged country code (ISO 3166)
id-number text 12 M Depending on the country, national identifier code
name text 80 O Signer user full name (is used in e-mail headings)
comment text 500 O The comment for the signature

Sample form to add a signer to a document:

<form enctype="application/x-www-form-urlencoded" method="post">
   <p>
      <label for="id_username">Username:</label> <input maxlength="80" id="id_username" type="text" name="username" />
   </p>
   <p>
      <label for="id_token">Token:</label> <input maxlength="320" id="id_token" type="password" name="token" />
   </p>
   <p>
      <label for="id_password">Password:</label> <input maxlength="320" id="id_password" type="password" name="password" />
   </p>
   <p>
      <label for="id_comment">Comment:</label> <input maxlength="500" id="id_comment" type="text" name="comment" />
   </p>
   <p>
      <input type="submit" value="OK" />
   </p>
</form>

Add P12 file

In order to allow for file upload, data is encoded as multipart/form-data. The included form fields are:

Name Type Size M/O Description
file file   M The p12 data
filename text 80 M The filename of p12
password text 320 M The password for accessing the p12
name text 80 M The name of p12 for showing in Portasigma
usemanual text 4 M true/false. For signing manual requests must be true

Change password account

Fields for changing password account:

Name Type Size M/O Description
oldPassword text 80 M The old password
newPassword text 80 M The new password

Notifications (Callbacks)

When used as a web application, PortaSigma sends e-mail notifications whenever the state of a signature transaction changes (e.g. every time the document is signed or rejected).

When used as a web service (where the issuer role is played by an application), it is much more convenient to send these notifications via a callback, which is an invocation to the client application (via HTTP POST). This notification can be used additionally to the e-mail notification, or as a replacement for it.

This POST will contain the following fields, encoded as application/x-www-form-urlencoded:

Name Type Size M/O Description
id text 80 M Internal identifier of the signature transaction in PortaSigma
reference text 320 M External reference (as provided by the client application when invoking the web service
status text 2 M Transaction status code (as described above)

Should the application wish a more detailed information, it may issue a regular read request to the appropriate transaction (GET /docs/{id}/).

Setting up the Callback Address

You can set up the address of the web service callback notifications address for a user account via the PortaSigma web application:

  1. Login to PortaSigma with the account you will use to access the API,
  2. Select the “My Account” menu,
  3. Click on the submenu option “Signature Notifications”
  4. Activate the Configuration for Web Service notifications, and set up the proper URL and authentication credentials, if needed.

If you want to integrate more than one application with PortaSigma, and each application requires a different callback notification address, you will have to create a separate account for each application.