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.

...

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.

Sandbox Environment

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

...

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 DockerSignBox 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.

...

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:

...

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:

...

Update Signbox

Run the following commands:

cd /opt/signbox_optimizer
docker-compose down

List all Docker images to find the image ID or name.and then remove the image.

docker images

REPOSITORY              TAG                       IMAGE ID       CREATED         SIZE
nginx                   latest                    66f8bdd3810c   7 weeks ago     192MB
signbox                 latest                    9977e730eb8f   2 months ago    56.2MB

Then remove the image.

docker rmi nginx:latest
docker rmi signbox:latest

Load the new Signbox Docker image.

docker image load -i signbox.tar 
docker-compose up -d

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:

...

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

...

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:

...

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

...

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.

...

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.

...

<?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

...

.

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:

/opt/bit4id/designbox_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

systemctldocker stop bit4-de.api.service bit4-de.cryptosvc.service nginxcompose down

Followed by

systemctldocker start bit4-de.api.service bit4-de.cryptosvc.service nginxcompose up -d

Logs

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

...

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

API Reference