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.
Add a form to a signer	POST /signatures/{rid}/form/	Data included in the POST is a json with specific format.
Get the answers of a form	GET /signatures/{rid}/form/	Answers the signer submited.
Download attachments from a signature request	GET /docs/{id}/signers/{rId}/attacheds	Returns a zip with all the documents that 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.
Signup a new user	POST /signup/	Signup a new user with json data.
Change password	PUT /users/{username}/	Change password account.
Sign a document with access token	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.
Signature request detail	GET /signatures/{reqId}/	Returns signature request details.
Sign a no registered user request	POST /signatures/{reqId}/sign/	Sign the request.
Reject a no registered user request	POST /signatures/{reqId}/reject/	Reject the request.

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
6	ERRONEOUS	There is a problem with the document
7	EXPIRED	The time to complete the document has expired
8	PENDING_APPROVAL	The document has a pending approval request
9	APPROVED	The document has been approved.
10	ONCOPY_SENT	The notification of the document is sent to its oncopies

For individual requests:

Value	Code	Description
00	NEW	Newly created, not yet public
10	PUBLISHED	Public and visible to the signer, only if notification fails
20	NOTIFIED	The request has been notified to the signer
30	SIGNED	The request is signed
40	REJECTED	The request is rejected
50	ERROR	An error was detected in the signature
60	PRESIGNED	A signature that was already present in the document
61	SELFSIGNED	Signature made directly by the issuer
62	APPROVED	Signature was approved by the user

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.

The client will receive the response with JSON format if Accept application/json header is added.

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)
disableAutoSign	text		O	Indicates if automatic signature will be applied (true or false)
allowPublicAccess	text	5	O	Retrieve a public validation code of the document (true or false)
publicAccessCodeInDocument	text	5	O	Shows public validation code in the document (true or false)
isQR	text	1	O	Shows a QR which encodes the public URL in the document (true or false)
qrMargin	text	3	O	Distance between QR limits and the document text (mm)
qrPage	text	1	O	0 for first page, -1 for last page, -2 for all pages
qrPos	text	1	O	0 for left, 1 for right
qrSize	text	1	O	Size of the QR Square(mm)

• 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)

This method responds with JSON format if Accept application/json header is added.

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
notif-time	text	3	O	Number of days between recurring notification.
notification-type	text	1	O	2 for sending access URL by SMS

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
notif-time	text	3	O	Number of days between recurring notification.
phone-number	text	9	O	Indicates phone number where signer will receive a SMS code
notification-type	text	1	O	2 for sending access URL by SMS

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)

This method responds with JSON format if Accept application/json header is added.

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 (add a form to the request)

Calling this method it is possible to add a form to a previously created signature request. This creation method only supports checkbox elements for the moment.

It’s important to know that for the correct positioning of the checkbox element in the file you need to include in the original pdf uploaded to portasigma the nexts tags {X:1},{X:2},… in the place you finally want them.

There is an example in cURL in the next block:

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/form' \
--header 'Authorization: Basic {auth_token}' \
--data-raw '{"checkboxList" : {["tags": ["X:1"],"headerName": "sampleHeader", "texts: ["sampleTexts"]}]'

You can add multiple checkbox elements in the same headerName building the json like below and they will be linked by the array position:

--data-raw '{"checkboxList" : [{"tags": ["X:1","X:2"],"headerName": "sampleHeader", "texts: ["sampleText1","sampleText2"]}]'

Signature request details

This method responds with JSON format if Accept application/json header is added.

If signature request type is ‘5’ then it has two differents responses: When HTTP request has authId field in query string, it returns a full signature request description.

curl --location --request GET 'https://api.portasigma.com/v1/signatures/{reqId}?authId={reqId.identifier}' \
--header 'Accept: application/json' \
--header 'Authorization: Token {auth_token}'

When HTTP request has not AuthId field in querystring, it returns a limited signature request description.

curl --location --request GET 'https://api.portasigma.com/v1/signatures/{reqId}/' \
--header 'Accept: application/json' \
--header 'Authorization: Token {auth_token}'

Signature Request (get form elements)

This resource provides the necessary elements to visually construct the form prior to signing.

curl -L -X GET 'https://api.portasigma.com/v1/signatures/{reqId}/signerform/' \
-H 'Accept: application/json' \
-H 'Authorization: Token {auth_token}'

There are three type of elements:

Types of elements	Description
INPUT	element designed for user text input
CHECKBOX	if they are exclusive, both cannot be marked
GROUP	for grouping elements of CHECKBOX or INPUT type

Description of the response:

Param	Description
id	it will be used for answer the form
signerFormElementType	GROUP,INPUT,CHECKBOX
headerName	header of a group
excludingElements	elements that are mutually exclusive
mandatory	true or false
excluding	true or false
text	text to show
answer	if form is not answered this value always will be null
size	field used for INPUT type

[
        {
                "signerFormElement": {
                        "id": 2241,
                        "signerFormElementType": "GROUP",
                        "headerName": "Do you consent to the medical examination?",
                        "excludingElements": [
                                {
                                        "id": 2239,
                                        "signerFormElementType": "CHECKBOX",
                                        "excluding": true,
                                        "mandatory": false,
                                        "text": "I do consent.",
                                        "answer": null,
                                        "size": 120
                                },
                                {
                                        "id": 2240,
                                        "signerFormElementType": "CHECKBOX",
                                        "excluding": true,
                                        "mandatory": false,
                                        "text": "I do not consent.",
                                        "answer": null,
                                        "size": 120
                                }
                        ],
                        "nonExcludingElements": []
                }
        },
        {
                "signerFormElement": {
                        "id": 2244,
                        "signerFormElementType": "GROUP",
                        "headerName": "Do you consent to receiving communications outside of your working hours?",
                        "excludingElements": [
                                {
                                        "id": 2242,
                                        "signerFormElementType": "CHECKBOX",
                                        "excluding": true,
                                        "mandatory": false,
                                        "text": "I do consent.",
                                        "answer": null,
                                        "size": 120
                                },
                                {
                                        "id": 2243,
                                        "signerFormElementType": "CHECKBOX",
                                        "excluding": true,
                                        "mandatory": false,
                                        "text": "I do not consent.",
                                        "answer": null,
                                        "size": 120
                                }
                        ],
                        "nonExcludingElements": []
                }
        }
]

Signature Request (answer form)

To respond to a form, you should send a POST in the following manner:

curl -L -X POST 'https://api.portasigma.com/v1/signatures/{reqId}/signerform/' \
-H 'Accept: application/json' \
-H 'Authorization: Token {auth_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
  "signerFormAnswerElements": [
        {
          "id": 2239,
          "signerFormGroup": {
                "id": 2241
          },
          "answer": true
        },
        {
          "id": 2240,
          "signerFormGroup": {
                "id": 2241
          },
          "answer": false
        },
        {
          "id": 2242,
          "signerFormGroup": {
                "id": 2244
          },
          "answer": true
        },
        {
          "id": 2243,
          "signerFormGroup": {
                "id": 2244
          },
          "answer": false
        }
  ]
}'

Signature Request (add an attachment)

Each signature request can have one or more documents attached to it. To do this, follow the example shown:

curl -L -X POST 'https://api.portasigma.com/v1/signatures/{reqId}/attachments/' \
-H 'Authorization: Token {auth_token}' \
-F 'file=@"path_to_file"'

In response, you will receive the created object in JSON format.

{
        "id":16,
        "title":"id-image-front.jpg",
        "filename":"id-image-front.jpg",
        "signatureRequest":292,
        "sizeKb":15,
        "sizeMb":0.0146484375
}

Signature Request (download an attachment)

Each attached document has an id; this identifier is used to download the document.

curl -L -X GET 'https://api.portasigma.com/v1/signatures/{reqId}/attachment/{attachmentId}/' \
-H 'Accept: application/json' \
-H 'Authorization: Token {auth_token}'

Signature Request (delete an attachment)

Each attached document has an id; this identifier is used to delete the document.

curl -L -X DELETE 'https://api.portasigma.com/v1/signatures/{reqId}/attachment/{attachmentId}/' \
-H 'Authorization: Token {auth_token}'

Signature Request (get form answers)

Calling this method returns the answers of a completed form.

There is an example in cURL in the next block:

curl --location --request GET 'https://api.portasigma.com/v1/signatures/{reqId}/form/' \
--header 'Authorization: Basic {auth_token}' \
--header 'Accept: application/json'

Signature Request (sign a Document with token)

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>

Sign a no registered user request

Calling this method it is possible to sign a signature request with no registered user. This request must be created with type field value of 2 o 5 (ONETIME or ONETIMEID).

Type 2 or ONETIME does not require introduce the user identifier as authentication method, instead of type 5 is mandatory this user id.

For getting authentication token you must create the signature request data with JSON format, and as response you will receive the this token as a field.

Below a list of optionals fields that the method allows in order to get a signature more detailed:

Name	Type	Size	M/O	Description
comment	text	500	O	The comment for the signature
signatureImage	text		O	The signature image in base 64
lastRefresh	text		O	The date when client renders the signature web page
location	text		O	The location of the signer
otp	text	6	O	The otp code if signature requires otp

There is an example in cURL for every case in the following blocks:

For type 2 (ONETIME):

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/sign/' \
--header 'Authorization: Token {auth_token}' \
--header 'Accept: application/json' \
--data-raw '{"comments": "Optional signer comments"}'

And for type 5 (ONETIMEID), in this case authId must be added in the data delivered in the POST.

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/sign/' \
--header 'Authorization: Token {auth_token}' \
--header 'Accept: application/json' \
--data-raw '{"comments": "Optional signer comments", "authId": "{digital-id}"}'

Reject a no registered user request

Same way that a request is signed, is rejected but with the correct resource.

There are an example in cURL for every case in the following blocks:

For type 2 (ONETIME):

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/reject/' \
--header 'Authorization: Token {auth_token}' \
--header 'Accept: application/json' \
--data-raw '{"comments": "Optional signer comments"}'

And for type 5 (ONETIMEID), in this case authId must be added in the data delivered in the POST.

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/reject/' \
--header 'Authorization: Token {auth_token}' \
--header 'Accept: application/json' \
--data-raw '{"comments": "Optional signer comments", "authId": "{digital-id}"}'

A completed signature request for type 5 (ONETIMEID) and otp, in this case authId must be added in the data delivered in the POST.

curl --location --request POST 'https://api.portasigma.com/v1/signatures/{reqId}/reject/' \
--header 'Authorization: Token {auth_token}' \
--header 'Accept: application/json' \
--data-raw '{"comments": "Optional signer comments", "authId": "{digital-id}", "otp": "X21Z96", "lastRefresh": "2022-05-30 01:35:55", "location": "41.275789772312436, 1.9886966083610682", "signatureImage": "data:image/png;base64,iVB..mCC"}'

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

Signup a new user

Sign up a new user though a json sent via data-raw.

Description of the json fields:

Name	M/O	Description
email	M	The email of the user for notifications (will be also the username)
firstName	M	The first name of the user (used in email headings)
lastName	M	The last name of the user (used in email headings)
phoneNumber	M	Indicates phone number where signer will receive a SMS code
phonePrefix	O	The phone prefix
country	M	Abridged country code (ISO 3166)
notifLang	M	Notification language (available ES,EN,CA,FR)
password	M	The password of the account
confirmPassword	M	The confirmation of the password
passwordHint	M	The word that will help you to remember the password

Sample json sent to sign up a user:

{
    "email": "testing@isigma.es",
    "firstName": "firstname test",
    "lastName": "lastname test",
    "phoneNumber": "123456789",
    "phonePrefix": "",
    "country": "ES",
    "notifLang": "ES",
    "password": "1234",
    "confirmPassword": "1234",
    "passwordHint": "1234"
}

Get user details

To get user details, you should make a call like this:

curl -L -g -X GET 'https://api.portasigma.com/v1/users/{username}/' \
-H 'Accept: application/json' \
-H 'Authorization: Basic base64[username:password]'

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

Get customer customization

Through this resource, customizable aspects of each user are obtained. The response is a JSON with the color and logo fields.

curl -X GET 'https://api.portasigma.com/custom/{associationName}/'

The obtained response has the following format:

{
        "image":"iVBO...w0",
        "color":"#2c5080"
}

The image field is a base 64 encoded SVG file. It’s recommended that the logo has a resolution of 300 x 58 px. The color field is a hexadecimal code representation.

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.