UANATACA SIGNBOX API DOCUMENTATION (1.0)

What it is

The high-performance solution for Bulk, Interactive and LTV signature service. Our best option for signing large number of documents and transactions.

SignBox API is an enterprise-grade solution for automated electronic signature of any type of file or document. A turnkey system that can be easily integrated with any business application without altering the user experience and guaranteeing the legal security of your electronically signed documents. SignBox API is a high-level web API based on the http RESTful paradigm.

How it works

The API is given with SignBox Optimizer that is a server system exposing http RESTful API by means of which, business applications are enabled to require the electronic signature of large number of documents.

SignBox Optimizer performs the most computationally expensive workload of the signature process, thus reducing the data traffic on the local network and make the most of the cryptographic hardware acceleration. The documents to be signed are processed in the customer business layer and are not send to Uanataca Services, instead is sent a hash of the document created using a hash algorithm. For environments demanding high performance, SignBox can be coupled with a pool of SignBox Optimizer.

The system provides options for several electronic signature formats including time stamping and long term validation. The electronic signatures are performed in Uanataca Trusted Service Center side, where signature keys are stored in a Qualified Electronic Signature Creation Device (QSCD) system.


img

Sandbox Environment

For testing purposes, Uanataca provides integrators of a pre-configured test-mode SignBox Optimizer accessible at the following URL:


https://signbox.developers.uanataca.com

Want to configure your own test-mode Optimizer? Find instructions in the configuration section.

Configuration

SignBox Optimizer can be supplied as a Docker or as a Virtual Machine image. See the configuration description in:
SignBox Optimizer on Docker
SignBox Optimizer on Virtual Machine

Hardware requirements

CPU: modern multicore (minimum 4 core)

RAM: 8GB

HDD: 200 GB

SignBox Optimizer on Docker

This configuration requires a server with a Linux operating system.

The commands show belown are suitable for CentOS. Each Linux distribution will require it's own commands.

 Watch on video!

STEP 1: Install Docker and Docker-Compose.

Docker and Docker-Compose

Run the following commands in this order.

sudo yum install -y yum-utils

sudo yum-config-manager \
--add-repo \
https://download.docker.com/linux/centos/docker-ce.repo

sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker

Run command sudo docker run hello-world to check the installation.


STEP 2: Extract and copy SignBox Optimizer zip content to the server.

Extract all signbox_optimizer_docker.zip content in a local folder.

Move SignBox Optimizer folder to the path /opt in the server.

The outcome should look like this:

img


STEP 3: Mapping volumes (for environments with a pool of SignBox Optimizer).

In high performance environments with a pool of SignBox Optimizer, service settings and logs must be stored in a shared volume outside Optimizer servers. These volumes must be defined in docker-compose.yml file in each SignBox Optimizer.

cd /opt/signbox_optimizer

Docker-compose.yml settings file:

img


STEP 4: Load SignBox Docker image.

Run the following commands:

cd /opt/signbox_optimizer
docker image load -i signbox.tar 

Remove image file:

rm -rf /opt/signbox_optimizer/signbox.tar

STEP 5: Launch the service.

Run:

docker-compose up -d --scale api=4 --scale cryptosvc=8

Check service status:

docker-compose ps

             Name                                 Command                State                 Ports
----------------------------------------------------------------------------------------------------------------------
signbox_optimizer_nginx_1               /docker-entrypoint.sh ngin ...   Up      0.0.0.0:443->443/tcp,:::443->443/tcp,
                                                                                  0.0.0.0:80->80/tcp,:::80->80/tcp
signbox_optimizer_signbox_api_1         signbox start                    Up
signbox_optimizer_signbox_cryptosvc_1   signbox start                    Up

All services must be UP.


SignBox Optimizer on Virtual Machine (OVA)

The Virtual Machine is supplied in an OVA file. SignBox Optimizer image is compatible with common virtual environments like VMWare, AWS, Azure or VirtualBox.

STEP 1: Import SignBox Optimizer (VM) in the virtual environment.

Adjust the system requirements for optimal usage considering host terminal resources described in hardware requirements.

STEP 2: Network configuration.

The network settings are configured on the file ifcfg-ens160, which can be found in the path /etc/sysconfig/network-scripts. Edit the file and insert the correct IP address, network mask, gateway and DNS for your network.

Example:

img

Restart network services with command:

service network restart

Proxy network settings

The Proxy settings are configured in the file settings.ini which can be found in path /opt/bit4id/de/etc. Edit the file and insert proxy address, port and credentials if are needed.

It is possible to include url exceptions for services that don't use proxy network. Exceptions must be included in regular expression format.

Example:

img

Signature Image Configuration

A visual signature can be placed as an image in the signed document. The visual signature is composed by an image and text. SignBox allows to create and store multiple templates. The parameters can be adjusted on the alias.ini file which is located at:

/opt/signbox_optimizer/img or custom mapped volume (Docker)

/opt/bit4id/de/etc/img (Virtual Machine)

The alias.ini file contains templates with size parameters of each stored image as well as the signature associated text, all represented by an "alias" which is included as a parameter in the SIGN API call.

ParameterDescriptionExample
[alias] img_bookmark parameter in SIGN Calluanataca
x1Left X Coordinate (measured from page left side)150
y1Bottom Y Coordinate (measured from page bottom)80
x2Right X Coordinate (measured from page left side)500
y2Top Y Coordinate (measured from page bottom)180
imgImage argb filenameuanataca.argb
size_xHorizontal image size in pt512
size_yVertical image size in pt512
paragraph_formatText details structure. See description[{ "font" : ["Universal-Bold", 50]...

Image .argb files must be locateed in the same /img directory where alias.ini is placed. Those files are created from the .png or .jpg files by using the ARGB Tool.

This is how the alias.ini file should look like (three different images are stored in this example):

img

Paragraph format

The signature image permits the addition of identifying text with the signer's associated data. This parameter allows to define the style and the content of the signature image, according to the following JSON object:

[{ "font": [< FONTFAMILY >,< FONTSIZE >],"align" : < ALIGNVALUE >, "format": [< LINE1 >,< LINE2 >,...,< LINEN > ]}]

font (optional): defines the text format to include in the signature image. The parameters < FONTFAMILY > and < FONTSIZE > correspond to the font style and size respectively. The supported styles are the following:

  • Universal (default): This style belongs to the Sans-Serif category (normal)
  • Univeral-Bold: Universal font in bold
  • Univeral-Italic: Universal font in italic
  • Universal-BoldItalic: Universal font in bold and italic
  • Times: This style belongs to the Serif category
  • Times-Bold: Times font in bold
  • Times-Italic: Times font in italic
  • Times-BoldItalic: Times font in bold and italic

< FONTSIZE > specifies the character size, defined as points. The sofware adjusts automatically the font size according to the dimensions of the signature image.

align (optional): defines the text alignment related to an image (if exists). It can assume the following values:

  • right: right text alignment (default)
  • left: left text alignment
  • middle: overlapped text

format: defines the text lines that will appear on the signature image. These lines can be created from static text and information included in the signer's digital certificate:

  • $(CN)s : CommonName
  • $(L)s : Locality
  • $(S)s : stateOrProvinceName
  • $(OU)s : organizationalUnitName
  • $(E)s : email
  • $(Email)s : email included in the Subject Alternative Name
  • $(Issuer)s : Certificate CA Issuer Common Name
  • $(date)s : Date and time of the signature. Compliant to ISO 8601 standard.
  • $(reason)s : “bit4-reason” parameter value
  • $(location)s : “bit4-location” parameter value

Example:

[{ "font" : [" Universal ",50]," align ":" right","format ": [" Digitally Signed by $(CN)s","O=$(O)s","C=$(C)s","S=$(S)s","Date: $(date)s","CustomField1: CustomValue1 ","CustomField2: CustomValue1 ","CustomField3: CustomValue3 "]}]

From this configuration, the image paragraph should look like as shown below:

img

ARGB Tool

ARGB Tool is a Windows software that converts a PNG or JPG image to ARGB image type and generates the settings to include in the alias.ini file.

Download: ARGB Tool

STEP 1: Extract zip content

Extract the zip content in a local folder.


STEP 2: Convert image and create alias settings

The ARGB Tool is performed through an executable file that is accessible in a Windows terminal at:
..\argb-graphic_signature\argb-tool\bin

It just requires to copy the original image to this path and open a command prompt. Then run this command with the position <x1,y1,x2,y2> coordenates:

argb utils make-ini image_filename.png [--out-dir folder_name] [--alias your_alias_name] [--position 80,80,380,230] 

The result of this command will consist in two files:

  • An alias.ini file with all image parameters
  • A image_filename.argb file

Both files must be moved to the /img directory in SignBox Optimizer (see image folders path)

Webhooks

SignBox API requires that the customer business develop a webhook to manage the service callbacks. There are two callbacks in the service that must be set in the parameters url_out and urlback of the SIGN API call.

urlback

The service logs are sent as a string in a HTTP POST request to the webhook url defined in this parameter. Each signature generates a single string composed by the error message and the signature job identifier. For a successful signature the string only contains the job id.

Successful response:

id=104.2

Error response:

message=Error%3A+Pin+invalid&exception=Error&id=980.4

url_out

In a successful signature process, the result signed file is sent as a binary file in a HTTP POST request to the webhoook url defined in this parameter.

Sample code

In this sample, signed files are saved with the original filename in a folder named 'signbox-files'. For the logs, a new log file is generated everyday containing daily logs. Log files are saved in a folder name 'logs', inside signbox-files folder.

The url_out parameter is defined as:

{host}/result_{filename}

The urlback parameter is defined as:

{host}/servicelogs

where {filename} is the filename of the document to be signed, and {host} is the IP or domaing from the server exposing the webhook.

Python

import web
import os

urls = (
        '/result_(.+), 'url_out',
        '/servicelogs', 'urlback'
        )

app = web.application(urls, globals())
app = app.wsgifunc()

class url_out:
    def POST(self, name):
        data = web.data()
        os.chdir('/signbox-files')
        f = open("%s" % name,'w')
        f.write(data)
        f.close()
        return ''

class urlback:
    def POST(self,name):
        data = web.data()
        os.chdir('/signbox-files/logs')
        f = open("%Y%m%d.txt" % name, 'a+')
        f.write(str(data))
        f.write(str("\n"))
        f.close()
        return ''

if __name__ == "__main__":
    app.run()

PHP

<?php

//url_out

$post = file_get_contents('php://input',true);
$file_handle = fopen('/signbox-files/', 'w');
fwrite($file_handle, $post);
fclose($file_handle);


//urlback

$post = file_get_contents('php://input');
$line = $post.PHP_EOL;
$myfile = fopen("/signbox-files/logs/%Y%m%d.txt", "a") or die("Unable to open file!");
fwrite($myfile, $line );
fclose($myfile);

?>

Rootstore configuration

As a requirement for LTV/LTVLITE signature level, we must add to the optimizer every chain of trust for each certificate that is involved in the signature.

In case that you don't make use of LTV/LVTLITE signature level, this process is NOT necessary.

This process vary depending on the selected optimizer install method.

Every certificate introduced in the optimizer regarding the rootstore needs to be formatted as a PEM file and introduced in a specific folder. Below an example of the general structure that is needed.

Note: Number of lines below the header are not representative of a real certificate.

-----BEGIN CERTIFICATE-----
MIIIWjCCBkKgAwIBAgIIICfKLtFjrRMwDQYJKoZIhvcNAQELBQAwgbkxCzAJBgNV
BAYTAkVTMUQwQgYDVQQHDDtCYXJjZWxvbmEgKHNlZSBjdXJyZW50IGFkZHJlc3Mg
YXQgd3d3LnVhbmF0YWNhLmNvbS9hZGRyZXNzKTEWMBQGA1UECgwNVUFOQVRBQ0Eg
Uy5BLjEVMBMGA1UECwwMVFNQLVVBTkFUQUNBMRswGQYDVQQDDBJVQU5BVEFDQSBS
K+0fx83luCN81YLsUpdpc3e0URG7eDMKNG54WvtW
-----END CERTIFICATE-----

Docker

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path or your mapped volume:

/signbox_optimizer/etc/trusted_roots/certs

STEP 2: Restart the service

After all the desired certificates have been loaded into the optimizer, we must fully restart the services with

docker compose down

Followed by

docker compose up -d

OVA

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path:

/opt/bit4id/de/etc/trusted_roots/certs

STEP 2: Restart the service

After all the desired certificates have been loaded into the optimizer, we must fully restart the services with

systemctl stop bit4-de.api.service bit4-de.cryptosvc.service nginx

Followed by

systemctl start bit4-de.api.service bit4-de.cryptosvc.service nginx

Logs

Service logs files are stored in a local folder in OVA or stored inside the containers in Docker.

To read logs in Docker version of SignBox Optimizer run this command:

docker-compose logs

To read logs in OVA version of SignBox Optimizer you can find logfile in this path:

/var/log/de

Postman collection

A postman collection is available as a support for a quick start.
It is only required to edit hostvariable in Postman environment with the IP or domain of SignBox Optimizer.

SignBox Postman collection download

Video tutorials

Need a better understanding of SignBox API? Check the video tutorials below and follow step-by-step instructions! They will guarantee you use our API efficiently for the best experience in document signatures.

Docker Optimizer Configuration

The Docker Optimizer configuration requires a SignBox Optimizer image package and a server using Linux Operating System with Internet access. Please check our documentation.

Error codes

Message Reason
ProcessTerminated: process ended with exit code X Webhook malfunctioning
Token not found Non existent certificate
Invalid credentials Incorrect credentials
PasswordProtected Input PDF protected with password
Error: Pin invalid Incorrect pin value
Error: Token locked Certificate credentials locked
Error: Invalid Otp Wrong or expired OTP code
Exception: Invalid Environment. Supported values are: [] Incorrect environment value
Exception: Remote Signature Failed: 401 Unauthorized Wrong billing credentials
Exception: Invalid TSA alias Incorrect timestamping alias
Exception: Invalid Image alias Incorrect image alias
Exception: Remote Signature Failed: 400 Bad Request Insufficient credits
Exception: Need tsa_bookmark for ltv signature Performing LTV with timestamping disabled
Exception: UnknownIssuer Certificate of any hierarchy missing
Exception: Time Stamping Failed: 400 Bad Request Non existent timestamping

API Reference

Signature

MethodEndpointAction
GET/api/echoChecks service availability
POST/api/signSigns a local or a remote hosted file
POST/api/generate_otpSend an otp code by sms to the signer

ECHO

Replies back what it receives to check the service availability.

Request
query Parameters
message
required
string

The message to be replied back

Responses
200

Successful response

get/api/echo
Request samples
curl -i -X GET 'https://signbox.developers.uanataca.com/api/echo?message=HelloWorld'
Response samples
text/plain
HelloWorld

SIGN

Signs a local or a remote hosted file.

Request
Request Body schema: multipart/form-data
required
file_in
required
string <binary>

Local path of the file to be signed.

  • File type in base64 is not accepted
  • If this parameter is specified, leave url_in blank
url_in
required
string

Url where to get the document to be signed.

  • If this parameter is specified, leave file_in blank
url_out
required
string

Url where to send signed file. See description and sample code in Webhooks configuration

urlback
required
string

Url where to send signing process log. See description and sample code in Webhooks configuration

env
required
string

Reference environment for sandbox or production

Enum: "prod" "sandbox"
format
string
Default: "pades"

Types of supported signature profiles:

  • pades for PDF files
  • xades for XML files
  • cades for other files
Enum: "pades" "xades" "cades"
username
required
string

Digital identity username

password
required
string

Digital identity password

pin
required
string

Digital identity PIN

level
string
Default: "BES"

Specify the level of the signature. Must consider that LTVLITE is a LTV signature lighter and efficient in comparison with the standard LTV level. The allowed values are:

  • BES, T, LTV, LTVLITE for pades
  • BES, T, EPES, XL for xades
  • BES, T, EPES for cades
identifier
string

Location of the token. If the certificate used is a renewed certificate use DS1

Enum: "DS0" "DS1"
tsa_bookmark
string

Timestamp service alias name. This field is required for signatures with levels T, LTV or XL

Value: "uanataca"
billing_username
required
string

Billing account username

billing_password
required
string

Billing account password

reason
string

Reason about the signature

location
string

Geographic location about the signature

npage
string
Default: 0

Page number where the image signature is placed. The first page starts in 0

  • It is required an img_bookmark alias
otp
string

The OTP code previously sent to the user. This parameter is only required and available for specific digital identities

metadata
string

Optional metadata information associated to the signed document

metadata_oid
string

OID identifier associated to the metadata

metadata_enveloped
string

Set to 0 if metadata is in DER format, or 1 (default) for ASN1 Octet String enveloping

img_bookmark
string

Signature image alias name corresponding to a previously stored image in the Optimizer
It is required to previous create an image template. See Image Configuration

  • If img_bookmark is specified, img , img_size and position cannot, since these parameters are included in Optimizer alias.ini file
img
string

Base64 preconverted image string

img_size
string

The original image size in pixels. (Example: 200,140) Any mismatch will cause wrong adjustments of the image or it would simply not appear.

position
string

The image rectangle bottom-left & top-right corner coordinates in pixels corresponding to 72DPI resolution. For an A4 document page, X-Y values ranges from 0-595 and 0-842 pixels respectively. (Example: 300,100,500,150)

paragraph_format
string

Identifying text with the signer's associated data. See description

Responses
200

The sign request was executed

post/api/sign
Request samples
curl -i -X POST \
  'https://signbox.developers.uanataca.com/api/sign' \
  -H 'Content-Type: multipart/form-data' \
  -F file_in=@sample_folder/document.pdf \
  -F url_in=http://example.com/document.pdf \
  -F url_out=https://example.com/result \
  -F urlback=https://example.com/log \
  -F env=sandbox \
  -F format=pades \
  -F username=1122338 \
  -F password=7T8xdGBN \
  -F pin=w98nZZDR \
  -F level=T \
  -F tsa_bookmark=uanataca \
  -F billing_username=billing_user@domain \
  -F billing_password=z5qNqkfB \
  -F reason=Signature test \
  -F location='Barcelona, Spain' \
  -F npage=2 \
  -F otp=123123 \ 
  -F metadata='Tm9tYnJlOiBEb2N1bWVudG8gU...' \
  -F metadata_oid='1.3.6.1.5.5.7.20' \
  -F metadata_enveloped=1 \
  -F img_bookmark=uanataca \
  -F img='iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAY...' \
  -F img_size='200,140' \
  -F position='300,100,500,150' \
  -F paragraph_format='[{ "font" : ["Universal-Bold",15],"align":"right","data_format" : { "timezone":"Europe/Madrid", "strtime":"%d/%m/%Y %H:%M:%S%z"},"format": ["Firmado por:","$(CN)s","$(serialNumber)s","Fecha: $(date)s"]}]'
Response samples
text/plain
id=14.1

OTP

Generates an otp for the specified digital identity.

⚠This method is only required and available for specific digital identities

Request
Request Body schema: multipart/form-data
required
username
required
string

Digital identity username

password
required
string

Digital identity password

uses
number

Amount of uses for the generated otp

env
required
string

Reference environment for sandbox or production

Enum: "prod" "sandbox"
Responses
200

Successful Response

post/api/generate_otp
Request samples
curl -i -X POST \
  'https://signbox.developers.uanataca.com/api/generate_otp' \
  -H 'Content-Type: multipart/form-data' \
  -F env=prod \
  -F password=7T8xdGBN \
  -F username=1122338 \
  -F uses=10
Response samples
text/plain
generated

Troubleshooting

MethodEndpointAction
GET/api/job/{id}Gets the state of a job
GET/api/result/{id}Gets the signed file

JOB

Gets the state of a signature request by its job id.

⚠This method is only used for testing purpose. In a production environment is required to use urlback service.

Request
path Parameters
id
required
string

The job id got in a sign response

Responses
200

Successful Response

502

Bad Gateway. Incorrect job id

get/api/job/{id}
Request samples
curl -i -X GET 'https://signbox.developers.uanataca.com/api/job/14.1'
Response samples
text/plain
state=done&type=sign

RESULT

Returns the signed file of a signature request by its job id.

⚠This method is only used for testing purpose. In a production environment is required to use url_out service
The signed file is only available if url_out is not specified in sign call

Request
path Parameters
id
required
string

The job id got in a sign response

Responses
200

Successful Response

502

Bad Gateway. Incorrect job id or failed signature.

get/api/result/{id}
Request samples
curl -i -X GET 'https://signbox.developers.uanataca.com/api/result/14.1'
Response samples
text/plain
 %PDF-1.7
 %����
 1 0 obj
 <</Type/Catalog/Pages 2 0 R/Lang(es-ES) /StructTreeRoot 10 0 R/MarkInfo<</Marked true>>/Metadata 26 0 R/ViewerPreferences 27 0 R>>
 endobj


2 0 obj
 <</Type/Pages/Count 1/Kids[ 3 0 R] >>
 endobj


3 0 obj
 <</Type/Page/Parent 2 0 R/Resources<</Font<</F1 5 0 R>>/ExtGState<</GS7 7 0 R/GS8 8 0 R>>/ProcSet[/PDF/Text/ImageB/ImageC/ImageI] >>/MediaBox[ 0 0 595.32 841.92] /Contents 4 0 R/Group<</Type/Group/S/Transparency/CS/DeviceRGB>>/Tabs/S/StructParents 0>>
 endobj
 (...)