UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)

...

Table of Contents

style	none

What it is

One-Shot represents the solution for electronic signatures based on a single-use certificate issuance. One-Shot API is the solution for Uanataca One-Shot Signature service, a complete option that can be implemented as part of your application or web.

...

Electronic signatures include a time stamp, providing a document signature with a reliable date and time.

How it works

The API is given with a module called One-Shot Optimizer, a server system that exposes our One-Shot HTTP RESTful API through which business applications are able to process their electronic signature requests.

...

The electronic signatures are performed on Uanataca Trusted Service Center side, where signature keys are generated and stored in a Qualified Electronic Signature Creation Device (QSCD) system.

Sandbox environment

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

...

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

Classic Workflow

In a common One-Shot Signature service, an OTP (One-Time Password) code is sent via SMS to the end user, directly from Uanataca services. The OTP verification method is used to trigger the issuance of the single-use digital signature certificate, which is inmediately used to sign the request associated documents e.g. the service contract.

...

Code Block
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464

Alternative Workflows

Hash signature flow

Our software nowadays is capable of performing a hash signature with the return of a p7m structure (CMS object) instead of building and returning a whole built document. It's important to mention that this modality needs a specific extracted message digest. These would be the objects that the hash should contain to be introduced into the optimizer.

...

Code Block
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464

# Video ID Workflows

eIDAS VideoID

This workflow defines the complete process of issuing eIDAS certificates.

...

Code Block
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464

External Mode

In External mode Video ID, digital evidences are uploaded to an independent Video ID platform.

...

Code Block
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464

Configuration

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

Hardware requirements

CPU: modern multicore (minimum 4 core)

RAM: 8GB

HDD: 200 GB

One-Shot Optimizer on Docker

This configuration requires a server with a Linux operating system.

...

See service settings configuration section.

Update One-shot

Run the following commands:

Code Block
cd /opt/oneshot_optimizer docker-compose down

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

Code Block

docker images

REPOSITORY              TAG                       IMAGE ID       CREATED         SIZE
nginx                   latest                    66f8bdd3810c   7 weeks ago     192MB
oneshot_optimizer       0.2.8                     ec613a792ac5   13 months ago   156MB
oneshot_imgconverter    0.1.18                    b694fdda9066   4 years ago     143MB

Then remove the image.

Code Block
docker rmi nginx:latest docker rmi oneshot_optimizer:0.2.8 docker rmi oneshot_imgconverter:0.1.18

Load the new Signbox Docker image.

Code Block
docker image load -i oneshot_optimizer.tar docker image load -i oneshot_imgconverter.tar docker-compose up -d

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.

Code Block

Docker

Prior to following the steps, you must have a mapped volume with rootstore folder and a mapped volume with 'dockergeneraterootstore.sh' file.

In case you don't have this volumes, below you can find an example showing how to define them.

Code Block

    optimizer:
        image: oneshot_optimizer:0.2.8
        environment:
            - OPTIMIZER_BIND=socket
            - TZ=Europe/Madrid
        networks:
            oneshot-optimizer:
                aliases:
                    - optimizer.oneshot-optimizer.loc
        volumes:
            # Rootstore files
            # - [your_folder]:/opt/bit4id/oneshot_optimizer/rootstore:rw
            - ./common/etc/rootstore:/opt/bit4id/oneshot_optimizer/rootstore:rw

            # Script file
            # - [your_folder]:/opt/bit4id/oneshot_optimizer/rootstore:rw
            - ./common/etc/dockergeneraterootstore.sh:/dockergeneraterootstore.sh:rw

STEP 1: Load certificates in the optimizer

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

Code Block
/oneshot_optimizer/common/etc/rootstore/cert

STEP 2: Set settings.ini (only for latest versions where this param is already in the file)

Set rootstore parameter with "manual" value

Code Block

1 |[general]
2 |environment = sandbox
3 |usepdfclean = false
4 |configuration = default
5 |rootstore = manual
6 |
7 |[tsa]
8 |tsa_url = https://tsa.uanataca.com/tsa/tss03
9 |
10|[billing]
11|billing_username = user@uanataca.com
12|billing_password = ejVxTnFrZkaI=
13|
14|[request]
15|default_profile = PFnubeQAFCiudadano
16|default_ra = 1000
17|
18|[proxy]
19|useproxy = false
20|proxy_host = 192.168.1.34
21|proxy_port = 8888
22|proxy_protocol = http
23|proxy_username = user
24|proxy_password = password
25|useproxycredentials = true

STEP 3: Execute the script

It is needed the execution of the script INSIDE the container, this can be done through

Code Block
docker exec -it <container_id> ./dockergeneraterootstore.sh

STEP 4: Restart the service

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

Code Block
docker compose down

Followed by

Code Block
docker compose up -d

Service settings

Requirements:

Billing credentials for the selected environment.
Credentials or token generated from these belonging to the authorized operator.
Certificate (.cer) and key (.key) files for connection to the selected environment.
The Id number for the Registration Authority that will issue the certificates.

This steps are for both sandbox or production environment.

You should have received a certificate (.cer) and a key (.key) file to be used to identify your application in communications with Uanataca signature services. Place both files in the certificates folder.

settings.ini file location:

/opt/oneshot_optimizer/common/etc/certs/<sandbox/prod> or custom mapped volume (Docker)
/opt/bit4id/oneshot_optimizer/etc/certs/<sandbox/prod> (Virtual Machine)

...

This is the file that contains all the optimizer setting variables, here you can set values that will be taken as default in case that they did not get sent directly through the api call. There are some shared values between the API call and this file, and some regarding background configurations. You can find a brief explanation below.

Important: If billing password is specified, it must be previously converted into Base64 format. Run the following command to convert your password to base64:

Code Block
echo -n <<billing_password>> \| base64

The following is a view of the settings.ini file:

Code Block

1 |[general]
2 |environment = sandbox
3 |usepdfclean = false
4 |configuration = default
5 |rootstore = uanataca
6 |
7 |[tsa]
8 |tsa_url = https://tsa.uanataca.com/tsa/tss03
9 |
10|[billing]
11|billing_username = user@uanataca.com
12|billing_password = ejVxTnFrZkaI=
13|
14|[request]
15|default_profile = PFnubeQAFCiudadano
16|default_ra = 1000
17|
18|[proxy]
19|useproxy = false
20|proxy_host = 192.168.1.34
21|proxy_port = 8888
22|proxy_protocol = http
23|proxy_username = user
24|proxy_password = password
25|useproxycredentials = true

environment: Work environment of the optimizer, taken as default if not send through API
usepdfclean: Enables sanitization of loaded documents. If the document contains multiple signatures this process would remove the previous signatures that the document has as they got treaten like an external structure to PDF standard
configuration: Configuration preset, only for determinated use-cases
rootstore: Chains of trust that the optimizer will work with, the value can be set with the customer name, only for determinated use-cases
tsa_url: Timestamping to apply on signatures
billing_username: Billing username of the desired environment
billing_password: Billing password codified in base64
default_profile: Certificate profile to issue, taken as default if not sent through API
default_ra: Registration Authority in which to issue, taken as default if not send through API

The file settings.ini contains default parameters that can also be adjusted via API using the Update Settings call.

Except by tsa_url, all parameters shown below are replaced every time the Create Video ID Request call is executed.

Once you are done editing the file, restart the One-Shot Optimizer service to changes take effect.

Virtual Machine:

Code Block
systemctl restart optimizer

Docker:

Code Block
cd /opt/oneshot_optimizer docker-compose restart optimizer

Webhook Configuration

One-Shot API requires a Webhook implemented on customer business side to manage our service callbacks. Every request status change will trigger a simple event-notification via HTTP POST, consisting on a JSON object to an URL that must be explicitly included as an optional parameter in the Create Video ID Request call. Keep in mind that the webhook passed as parameter will be only for testing purposes, the definitive webhook has to be set in your belonging RA by Operations Department.

The following is a sample view of the JSON object that is sent as a callback at every status change:

Code Block
{ "status": "VIDEOINCOMPLETE", "date": "2021-07-20T08:08:21.132394", "previous_status": "VIDEOPENDING", "request": 46760, "registration_authority": 139 }

Where: status is the most recent status, this is, the status that triggered the notification.
date is the date of the request status change in datetime format.
previous_status is the status inmediately previous to last change.
request is the request unique id.
registration_authority is the Registration Authority id number the request is associated.

Sample code

In this sample, every JSON object is stored in a file named 'videoid'.

The webhook parameter used in the Create Video ID Request call is defined as:

Code Block
{host}/videoid

where {host} is the IP or domain from the server exposing the webhook.

Python

Code Block

import web
import datetime

urls = (
        '/videoid, 'videoid',
        )

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

class video:
    def POST(self):
        data = web.data()
        f = open("status.json",'a+')
        f.write(data)
        f.close()
        return ''

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

PHP

Code Block
<?php //videoid.json $post = file_get_contents('php://input',true); $file_handle = fopen('/videoid/status.json', 'w'); fwrite($file_handle, $post); fclose($file_handle); ?>

Logs

Service logs file optimizer.log is stored in a One-Shot Optimizer local folder.

Docker:

Code Block
/opt/oneshot_optimizer/common/logs or custom mapped volume Command 'docker-compose logs > log.txt'

Virtual Machine:

Code Block
/opt/bit4id/oneshot_optimizer/logs

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 One-Shot Optimizer.

One-Shot Postman collection download

Version	Old Version 3	New Version Current
Changes made by	Saray Cordón Arnau	Saray Cordón Arnau
Saved on	Nov 15, 2024	Jan 20, 2025

Versions Compared

Key

UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)

What it is

How it works

Sandbox environment

Classic Workflow

Alternative Workflows

Hash signature flow

eIDAS VideoID

External Mode

Configuration

Hardware requirements

One-Shot Optimizer on Docker

Update One-shot

Rootstore configuration

Docker

Service settings

Webhook Configuration

Logs

Postman collection

API Reference

Content Comparison

Versions Compared

Key

UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)

What it is

How it works

Sandbox environment

Classic Workflow

Alternative Workflows

Hash signature flow

eIDAS VideoID

External Mode

Configuration

Hardware requirements

One-Shot Optimizer on Docker

Update One-shot

Rootstore configuration

Docker

Service settings

Webhook Configuration

Logs

Postman collection

API Reference