UANATACA SIGNBOX API (LEGACY)
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.
ย
ย
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
ย
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.
ย
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:
ย
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:
STEP 4: Load SignBox Docker image.
Run the following commands:
Remove image file:
ย
STEP 5: Launch the service.
Run:
Check service status:
All services must be UP.
ย
Update Signbox
Run the following commands:
List all Docker images to find the image ID or name.and then remove the image.
Then remove the image.
Load the new Signbox Docker image.
ย
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.
Parameter | Description | Example |
---|---|---|
[alias] | img_bookmark parameter in SIGN Call | uanataca |
x1 | Left X Coordinate (measured from page left side) | 150 |
y1 | Bottom Y Coordinate (measured from page bottom) | 80 |
x2 | Right X Coordinate (measured from page left side) | 500 |
y2 | Top Y Coordinate (measured from page bottom) | 180 |
img | Image argb filename | uanataca.argb |
size_x | Horizontal image size in pt | 512 |
size_y | Vertical image size in pt | 512 |
paragraph_format | Text 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):
ย
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
(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:
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.
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:
The result of this command will consist in two files:
An
alias.ini
file with all image parametersA
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:
Error response:
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:
The urlback parameter is defined as:
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
PHP
ย
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.
Docker
STEP 1: Load certificates in the optimizer
Load the PEM files in the following path or your mapped volume:
STEP 2: Restart the service
After all the desired certificates have been loaded into the optimizer, we must fully restart the services with
Followed by
ย
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:
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 host
variable 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
ย