UANATACA ONE-SHOT API
- Wilter Torres Enriquez
UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)
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.
It is designed in such a way that no sensitive data has to be sent away from your premises, as only hashes of the documents to be signed need to be transmitted to the signature service. Documents are signed by means of the creation of single-use digital certificates, which are created at the moment of the signature operation for immediate use to electronically sign all documents included.
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.
One-Shot Optimizer performs the most computationally expensive workload of the signature process, thus reducing data traffic on the local network and performing most cryptographic hardware acceleration. The documents to be signed are processed in the customer business layer and are not send to Uanataca Services since a hash of the document is sent, created from a hash algorithm.
Uanataca is a Qualified Trusted Service Provider that issues digital certificates by means of its own trusted Certification Authority (CA). Additionally, the role of the Registration Authority Officials (RAO) is vital in the process as they manage every request for new digital certificates that is received from new users. Issued certificates can be used to electronically sign documents.
One-Shot Signature certificates are generated on the spot every time a new set of documents requires a signature. Through One-Shot Signature service you will play RAO's role, providing identification data for each user and requesting the generation of signature certificates. Once user registration data has been provided and the certificate is ready to be issued, the end user triggers the generation of the digital certificate. This action completes the signature procedure.
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:
https://one-shot.developers.uanataca.comIn sandbox environment, requests can be easily created, validated or approved by using a stored default Operator credentials set represented by an alfanumeric string called token. This token can be found when executing the List Tokens call.
List Tokens call output:
{
"status": "success",
"detail": {
"3bf8d8eb-d96c-41ea-83ad-d78a7016c7da": {
"username": "1125824",
"password": true,
"pin": true,
"rao_id": 44,
"env": "sandbox"
}
}
}
When using our test-mode Optimizer, you must consider:
Billing credentials are required.
The Registration Authority id number will be explicitly assigned by our staff.
The token
3bf8d8eb-d96c-41ea-83ad-d78a7016c7dais valid for using in Create Request call. Cannot be deleted.
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.
One-Shot Signature can use other external authentication methods instead of Uanataca SMS. This alternative methods are subjected to approval.
The following images summarize One-Shot Signature flow involving both authentication methods:
The business application creates a new digital signature request, providing all required user data
One-Shot Optimizer returns an identifier for the certificate request
The business application provides the documents to be signed by the end user
The business application retrieves the service contract
The business application shows the documents to be signed and the service contract to its end user
After reviewing the documents, the end user agrees to sign them
The business application starts the signature process by requesting the generation of an One-Time Password (OTP) token for the signature
Uanataca services sends the OTP code directly to the end user through an SMS message
By introducing the OTP code, the end user identifies himself as the subject of the signature certificate
The business application provides the OTP and the identifier of the signature request to the One-Shot Optimizer
One-Shot Optimizer takes care of computing the hash of the documents to be signed in the business layer
Hashes are sent with the request identifier and OTP code to Uanataca Services
The end user signature certificate is generated and used to sign the hashes
The signed hashes and the signature identifier are returned to the One-Shot Optimizer
One-Shot Optimizer generates the signed document envelopment, combining the original documents with the signed hashes
Finallly, the business application calls One-Shot Optimizer API to obtain the signed documents
Other authentication methods
The business application creates a new digital signature request, providing all required user data
One-Shot Optimizer returns an identifier for the certificate request
The business application provides the documents to be signed by the end user
The business application retrieves the service contract
The business application shows the documents to be signed and the service contract to its end user
After reviewing the documents, the end user agrees to sign them
The client application starts the signature process with an authentication method provided by the client
One-Shot Optimizer takes care of computing the hash of the documents to be signed in the business layer
Hashes are sent together with the request identifier and an id of the business authentication method to Uanataca Services
The end user signature certificate is generated and used to sign the hashes
The signed hashes and the signature identifier are returned to the One-Shot Optimizer
One-Shot Optimizer generates the signed document envelopment, combining the original documents with the signed hashes
Finally, the business application calls One-Shot Optimizer API to obtain the signed documents
The next section presents the workflow for a simple use case of the One-Shot Signature service with a step-by-step description of the API calls required to allow a user to digitally sign a document provided by the client application.
The basic digital signature process involves the following steps:
RETRIEVE AN EXISTING TOKEN FOR THE RAO
CREATE A NEW DIGITAL SIGNATURE REQUEST
UPLOAD A DOCUMENT
RETRIEVE SERVICE CONTRACT
GENERATE AN OTP (only for Uanataca SMS)
SIGN THE DOCUMENT
RETRIEVE SIGNED DOCUMENT
DELETE DOCUMENTS FROM OPTIMIZER
STEP 1: RETRIEVE AN EXISTING TOKEN FOR THE RAO
API Reference: List Tokens
The test-mode One-Shot Optimizer is pre-configured with a Registration Authority Officer (RAO) account ready to be used within sandbox environment. This account has an associated token that can be used to identify the RAO in API calls.
curl -X GET https://one-shot.developers.uanataca.com/oneshot/api/v1/tokensThis call should return the following JSON object:
This output tells us that a single token "3bf8d8eb-d96c-41ea-83ad-d78a7016c7da" exists. This token is associated to the RAO account with id "1125824" and can be used instead of the password and pin.
To use tokens in a production environment, you will need to create them first using the corresponding Create token API call.
STEP 2: CREATE A NEW DIGITAL SIGNATURE REQUEST
API Reference: Create Request
In One-Shot Signature Service, all data corresponding to a given digital signature is collected within a Digital Signature Request. This includes both the identifying information of the signing user -provided when you create the signature request- and the document or documents to be signed, to be uploaded in an upcoming step.
This call must include enough information to identify both the signing user and the RAO approving the request. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation, but for now it is enough to include at least the following:
where "token" is the token representing the RAO's credentials obtained in the previous step.
If the signature request is completed successfully, we will get the unique identifier assigned to it:
The code shown above will be used to identify the created signature request in subsequent calls.
STEP 3: UPLOAD A DOCUMENT
API Reference: Upload Document
After creating the the signature request, we can associate all pdf documents that must be signed by the user.
Note that the number at the end of the call is the request id we obtained in the previous step.
If the upload is successful, the response will contain the identifier assigned to each document:
STEP 4: RETRIEVE SERVICE CONTRACT
API Reference: Retrieve Contract
As a Trusted Service Provider, Uanataca must inform certificate requesters about terms and conditions ruling the issuance of certificates.
A service contract is generated for each digital certificate issue. The user must view the request-associated service contract to be signed in the same step as the documents, using the one-time certificate just issued.
The response by the server will be the service contract document file in binary format:
STEP 5: GENERATE AN OTP (only for Uanataca SMS)
API Reference: Generate OTP code
This step applies only for signatures made using Uanataca SMS method.
Once the documents to be signed are ready, we need to generate a secure One-time password (OTP) that allows the user to sign them. The OTP code is generated by executing the Generate OTP call and the resulting OTP is sent as an SMS message directly to the phone number is provided when creating the signature request.
When calling the OTP endpoint you must add the request identifier returned by the Create Request call:
A successful call will look like this:
With this call, an SMS with the secret code is sent to the mobile phone number associated to the signature request.
STEP 6: SIGN THE DOCUMENT
API Reference: Sign
In this step the digital signature certificate is issued, then it signs all documents previously uploaded for the signature request.
Execute the sign call with the request id and json parameters containing the OTP code sent:
params.json for Uanataca SMS:
params.json for other authentication methods:
A successful call will result in the following response:
STEP 7: RETRIEVE SIGNED DOCUMENT
API reference: Retrieve Document
Once the signature is done, the next step is to get all signed documents.
To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the document unique identifier.
The response obtained by the server will be the document in binary format:
STEP 8: DELETE DOCUMENTS FROM OPTIMIZER
API reference: Delete All Documents
⚠ Since the service does not delete uploaded files unless explicitly requested through an API call, it is strongly recommended that you backup any file you want to preserve using an alternative system.
Delete all documents associated to a finished digital signature request.
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.
This is the structure that the uploaded json needs to contain to be able to perform this signature.
The hash signature process involves the following steps:
RETRIEVE AN EXISTING TOKEN FOR THE RAO
CREATE A NEW DIGITAL SIGNATURE REQUEST
UPLOAD A DOCUMENT
RETRIEVE SERVICE CONTRACT
GENERATE AN OTP (only for Uanataca SMS)
SIGN THE HASH
RETRIEVE SIGNED P7M
DELETE DOCUMENTS FROM OPTIMIZER
STEP 1: RETRIEVE AN EXISTING TOKEN FOR THE RAO
API Reference: List Tokens
The test-mode One-Shot Optimizer is pre-configured with a Registration Authority Officer (RAO) account ready to be used within sandbox environment. This account has an associated token that can be used to identify the RAO in API calls.
This call should return the following JSON object:
This output tells us that a single token "3bf8d8eb-d96c-41ea-83ad-d78a7016c7da" exists. This token is associated to the RAO account with id "1125824" and can be used instead of the password and pin.
To use tokens in a production environment, you will need to create them first using the corresponding Create token API call.
STEP 2: CREATE A NEW DIGITAL SIGNATURE REQUEST
API Reference: Create Request
In One-Shot Signature Service, all data corresponding to a given digital signature is collected within a Digital Signature Request. This includes both the identifying information of the signing user -provided when you create the signature request- and the document or documents to be signed, to be uploaded in an upcoming step.
This call must include enough information to identify both the signing user and the RAO approving the request. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation, but for now it is enough to include at least the following:
where "token" is the token representing the RAO's credentials obtained in the previous step.
If the signature request is completed successfully, we will get the unique identifier assigned to it:
The code shown above will be used to identify the created signature request in subsequent calls.
STEP 3: UPLOAD A DOCUMENT
API Reference: Upload Document
After creating the the signature request, we can associate the json that contains the message digest and its properties.
Note that the number at the end of the call is the request id we obtained in the previous step.
If the upload is successful, the response will contain the identifier assigned to each document:
STEP 4: RETRIEVE SERVICE CONTRACT
API Reference: Retrieve Contract
As a Trusted Service Provider, Uanataca must inform certificate requesters about terms and conditions ruling the issuance of certificates.
A service contract is generated for each digital certificate issue. The user must view the request-associated service contract to be signed in the same step as the documents, using the one-time certificate just issued.
The response by the server will be the service contract document file in binary format:
STEP 5: GENERATE AN OTP (only for Uanataca SMS)
API Reference: Generate OTP code
This step applies only for signatures made using Uanataca SMS method.
Once the documents to be signed are ready, we need to generate a secure One-time password (OTP) that allows the user to sign them. The OTP code is generated by executing the Generate OTP call and the resulting OTP is sent as an SMS message directly to the phone number is provided when creating the signature request.
When calling the OTP endpoint you must add the request identifier returned by the Create Request call:
A successful call will look like this:
With this call, an SMS with the secret code is sent to the mobile phone number associated to the signature request.
STEP 6: SIGN THE DOCUMENT
API Reference: Sign
In this step the digital signature certificate is issued, then it signs all documents previously uploaded for the signature request.
Execute the sign call with the request id and json parameters containing the OTP code sent:
params.json for Uanataca SMS:
params.json for other authentication methods:
A successful call will result in the following response:
STEP 7: RETRIEVE SIGNED P7M
API reference: Retrieve Document
Once the signature is done, the next step is to get the signed document.
To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the document unique identifier.
The response obtained by the server will be the signed hash in a p7m structure, it's important to add .p7m extension to the information obtained
STEP 8: DELETE DOCUMENTS FROM OPTIMIZER
API reference: Delete All Documents
Delete all documents associated to a finished digital signature request.
Asynchronous mode flow
This functionality is focused on providing the user with more transparency about the processes running in the background. Through a webhook designated by the user it is possible to collect state changes and the information they carry in order to enhance the end-user experience. Asynchronous flow includes shorter API response times to save resources, but the overall processing time is still the same as classic workflow.
The asynchronous signature process involves the following steps:
RETRIEVE AN EXISTING TOKEN FOR THE RAO
CREATE A NEW DIGITAL SIGNATURE REQUEST
UPLOAD A DOCUMENT
RETRIEVE SERVICE CONTRACT
GENERATE AN OTP (only for Uanataca SMS)
SIGN THE DOCUMENT
RETRIEVE SIGNED DOCUMENT
DELETE DOCUMENTS FROM OPTIMIZER
STEP 1: RETRIEVE AN EXISTING TOKEN FOR THE RAO
API Reference: List Tokens
The test-mode One-Shot Optimizer is pre-configured with a Registration Authority Officer (RAO) account ready to be used within sandbox environment. This account has an associated token that can be used to identify the RAO in API calls.
This call should return the following JSON object:
This output tells us that a single token "3bf8d8eb-d96c-41ea-83ad-d78a7016c7da" exists. This token is associated to the RAO account with id "1125824" and can be used instead of the password and pin.
To use tokens in a production environment, you will need to create them first using the corresponding Create token API call.
STEP 2: CREATE A NEW DIGITAL SIGNATURE REQUEST
API Reference: Create Request
In One-Shot Signature Service, all data corresponding to a given digital signature is collected within a Digital Signature Request. This includes both the identifying information of the signing user -provided when you create the signature request- and the document or documents to be signed, to be uploaded in an upcoming step.
This call must include enough information to identify both the signing user and the RAO approving the request. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation, but for now it is enough to include at least the following:
where "token" is the token representing the RAO's credentials obtained in the previous step.
If the signature request is completed successfully, we will get the unique identifier assigned to it:
The code shown above will be used to identify the created signature request in subsequent calls.
STEP 3: UPLOAD A DOCUMENT
API Reference: Upload Document
After creating the the signature request, we can associate all pdf documents that must be signed by the user.
Note that the number at the end of the call is the request id we obtained in the previous step.
If the upload is successful, the response will contain the identifier assigned to each document:
STEP 4: RETRIEVE SERVICE CONTRACT
API Reference: Retrieve Contract
As a Trusted Service Provider, Uanataca must inform certificate requesters about terms and conditions ruling the issuance of certificates.
A service contract is generated for each digital certificate issue. The user must view the request-associated service contract to be signed in the same step as the documents, using the one-time certificate just issued.
The response by the server will be the service contract document file in binary format:
STEP 5: GENERATE AN OTP (only for Uanataca SMS)
API Reference: Generate OTP code
Once the documents to be signed are ready, we need to generate a secure One-time password (OTP) that allows the user to sign them. The OTP code is generated by executing the Generate OTP call and the resulting OTP is sent as an SMS message directly to the phone number is provided when creating the signature request.
When calling the OTP endpoint you must add the request identifier returned by the Create Request call:
A successful call will look like this:
With this call, an SMS with the secret code is sent to the mobile phone number associated to the signature request.
STEP 6: SIGN THE DOCUMENT
API Reference: Sign
In this step the digital signature certificate is issued, then it signs all documents previously uploaded for the signature request.
Execute the sign call with the request id and json parameters containing the OTP code sent:
params.json for Uanataca SMS:
params.json for other authentication methods:
A successful call will result in the following response:
STEP 7: RETRIEVE SIGNED DOCUMENT
API reference: Retrieve Document
Once the signature is done, the next step is to get all signed documents.
To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the document unique identifier.
The response obtained by the server will be the document in binary format:
STEP 8: DELETE DOCUMENTS FROM OPTIMIZER
API reference: Delete All Documents
Delete all documents associated to a finished digital signature request.
Video ID Workflows
eIDAS VideoID
This workflow defines the complete process of issuing eIDAS certificates.
This process involves the following steps:
CREATE A NEW VIDEO ID SIGNATURE REQUEST
REQUEST APPROVAL
UPLOAD A DOCUMENT
RETRIEVE SERVICE CONTRACT
GENERATE AN OTP (only for Uanataca SMS)
SIGN THE DOCUMENT
RETRIEVE SIGNED DOCUMENT
DELETE DOCUMENTS FROM OPTIMIZER
STEP 1: CREATE A NEW VIDEO ID SIGNATURE REQUEST
API Reference: Create Video ID Request
This call must include preliminary information to identify the signer.
If the signature request is completed successfully, both video and request unique identifiers are returned, as well as the corresponding video id link:
The request starts at VIDEOPENDING status after creation. The request_pk output parameter will be used to identify this digital signature request in subsequent calls.
At this point, the workflow progress will depend on the video-identification successful completion. This action will change request status from VIDEOPENDING to VIDEOREVIEW.
To inform business app and validation RAO about this change at the time it takes place, we recommend the implementation of a Webhook. Check our documentation for Webhook Configuration.
If request data needs to be modified, use the Update Request call. Check API Reference.
If request data needs to be retrieved, use the Get Request call. Check API Reference.
STEP 2: REQUEST APPROVAL
API Reference: Approve Request
This call makes the request ready for signature. Its status changes to ENROLLREADY and webhook intervention at this point is important for status update. In 1-step mode, both validation and approval occur when executing this call.
In case of using a token containing RAO's credentials.
The response is a JSON object with added request approval information.
In case of not approving a request for any reason, the call Cancel Request must be executed. Check API Reference.
STEP 3: UPLOAD A DOCUMENT
API Reference: Upload Document
After creating the the signature request, we can associate all pdf documents that must be signed by the user.
Note that the number at the end of the call is the request id we obtained in the previous step.
If the upload is successful, the response will contain the identifier assigned to each document:
STEP 4: RETRIEVE SERVICE CONTRACT
API Reference: Retrieve Contract
As a Trusted Service Provider, Uanataca must inform certificate requesters about terms and conditions ruling the issuance of certificates.
A service contract is generated for each digital certificate issue. The user must view the request-associated service contract to be signed in the same step as the documents, using the one-time certificate just issued.
The response by the server will be the service contract document file in binary format:
STEP 5: GENERATE AN OTP (only for Uanataca SMS)
API Reference: Generate OTP code
Once the documents to be signed are ready, we need to generate a secure One-time password (OTP) that allows the user to sign them. The OTP code is generated by executing the Generate OTP call and the resulting OTP is sent as an SMS message directly to the phone number is provided when creating the signature request.
When calling the OTP endpoint you must add the request identifier returned by the Create Request call:
A successful call will look like this:
With this call, an SMS with the secret code is sent to the mobile phone number associated to the signature request.
STEP 6: SIGN THE DOCUMENT
API Reference: Sign
In this step the digital signature certificate is issued, then it signs all documents previously uploaded for the signature request.
Execute the sign call with the request id and json parameters containing the OTP code sent:
params.json for Uanataca SMS:
params.json for other authentication methods:
A successful call will result in the following response:
STEP 7: RETRIEVE SIGNED DOCUMENT
API reference: Retrieve Document
Once the signature is done, the next step is to get all signed documents.
To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the document unique identifier.
The response obtained by the server will be the document in binary format:
STEP 8: DELETE DOCUMENTS FROM OPTIMIZER
API reference: Delete All Documents
Delete all documents associated to a finished digital signature request.
External Mode
In External mode Video ID, digital evidences are uploaded to an independent Video ID platform.
This process involves the following steps:
CREATE A NEW VIDEO ID SIGNATURE REQUEST
UPLOAD DATA & VIDEO
REQUEST APPROVAL
UPLOAD A DOCUMENT
RETRIEVE SERVICE CONTRACT
GENERATE AN OTP (only for Uanataca SMS)
SIGN THE DOCUMENT
RETRIEVE SIGNED DOCUMENT
DELETE DOCUMENTS FROM OPTIMIZER
STEP 1: CREATE A NEW VIDEO ID SIGNATURE REQUEST
API Reference: Create Video ID Request
This call must include preliminary information to identify the signer.
If the signature request is completed successfully, we will get the unique identifier assigned to it:
The response is the a JSON containing important request parameters, in VIDEOPENDING status after creation. The request_pk output parameter will be used to identify this digital signature request in subsequent calls.
If request data needs to be modified, use the Update Request call. Check API Reference.
If request data needs to be retrieved, use the Get Request call. Check API Reference.
STEP 2: UPLOAD DATA & VIDEO
A previously created Video ID Request needs a set of information defined as evidences.
The successful upload of ALL information will change the request status to VIDEOREVIEW.
The partial upload of the information will change the request status to VIDEOINCOMPLETE.
If the upload process fails for any reason, the request status will change to VIDEOERROR.
Data and images are uploaded by using the Upload Data Evidence call.
API Reference: Upload Data Evidence
Data objects in detail:
acceptance : Client acceptance parameters (e.g. Terms & Conditions, Privacy Policy). This is a customizable JSON object.videoid_data : Set of information about the Request. Contains:
images: Pictures associated to the client's ID document plus a face selfie of him/her.ocr_data: Text information extracted from the client's ID document via Optical Character Recognition (OCR).security_checks: Set of validation fields associated to the client's identity (underaging, matching info, liveliness, etc)similarity_level: Similarity level between document picture and face selfie. Ranges within 0 to 100
This call must include all the information mentioned above.
Successful response status
In the same way, binary multiformat Video is uploaded by using the Upload Video call.
API Reference: Upload Video
Successful response status
If the uploaded video needs to be retrieved, use Download Video
STEP 3: REQUEST APPROVAL
API Reference: Approve Request
This call makes the request ready for signature. Its status changes to ENROLLREADY.
The response is a JSON object with added request approval information.
In case of not approving a request for any reason, the call Cancel Request must be executed. Check API Reference.
STEP 4: UPLOAD A DOCUMENT
API Reference: Upload Document
After creating the the signature request, we can associate all pdf documents that must be signed by the user.
Note that the number at the end of the call is the request id we obtained in the previous step.
If the upload is successful, the response will contain the identifier assigned to each document:
STEP 5: RETRIEVE SERVICE CONTRACT
API Reference: Retrieve Contract
As a Trusted Service Provider, Uanataca must inform certificate requesters about terms and conditions ruling the issuance of certificates.
A service contract is generated for each digital certificate issue. The user must view the request-associated service contract to be signed in the same step as the documents, using the one-time certificate just issued.
The response by the server will be the service contract document file in binary format:
STEP 6: GENERATE AN OTP (only for Uanataca SMS)
API Reference: Generate OTP code
Once the documents to be signed are ready, we need to generate a secure One-time password (OTP) that allows the user to sign them. The OTP code is generated by executing the Generate OTP call and the resulting OTP is sent as an SMS message directly to the phone number is provided when creating the signature request.
When calling the OTP endpoint you must add the request identifier returned by the Create Request call:
A successful call will look like this:
With this call, an SMS with the secret code is sent to the mobile phone number associated to the signature request.
STEP 7: SIGN THE DOCUMENT
API Reference: Sign
In this step the digital signature certificate is issued, then it signs all documents previously uploaded for the signature request.
Execute the sign call with the request id and json parameters containing the OTP code sent:
params.json for Uanataca SMS:
params.json for other authentication methods:
A successful call will result in the following response:
STEP 8: RETRIEVE SIGNED DOCUMENT
API reference: Retrieve Document
Once the signature is done, the next step is to get all signed documents.
To do this, query with an HTTP GET request the endpoint /api/v1/document/{pk}/{type}/{uid}, where {pk} is the Request's unique identifier, {type} is the type of the document (it can be "original" for the uploaded document or "signed" for the digitally-signed version) and {uid} is the document unique identifier.
The response obtained by the server will be the document in binary format:
STEP 9: DELETE DOCUMENTS FROM OPTIMIZER
API reference: Delete All Documents
Delete all documents associated to a finished digital signature request.
Configuration
One-Shot Optimizer can be supplied as a Docker image. See the configuration description in:
One-Shot Optimizer on Docker
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.
The commands show belown are suitable for Ubuntu. 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.
Run command sudo docker run hello-world to check the installation.
STEP 2: Extract and copy One-Shot Optimizer zip content to the server.
Extract all uanataca_optimizer_docker.zip content in a local folder.
Copy the folder to /opt path in the server.
The outcome should look like this:
STEP 3: Mapping volumes
In high performance environments working with a pool of Optimizers, service settings, data and logs must be stored in a shared volume outside Optimizer servers. These volumes must be defined in the docker-compose.yml file for each One-Shot Optimizer.
Docker-compose.yml settings file:
STEP 4: Load the One-Shot Docker images.
Run the following commands:
Remove image files:
STEP 5: Launch the service.
Run the following commands:
Check service status:
All services must be UP.
STEP 6: Service settings.
See service settings configuration section.
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.
STEP 1: Load certificates in the optimizer
Load the PEM files in the following path:
STEP 2: Execute the script
After all the desired certificates have been loaded into the optimizer, we must execute the following command on the container
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.
Path: /opt/uanataca_optimizer_docker/optimizer_data/certs/<sandbox/prod>
Settings.ini file
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.
The following is a view of the settings.ini file:
environment: Work environment of the optimizer, taken as default if not send through APItsa_url: Timestamping to apply on signaturesusername: Billing username of the desired environmentpassword: Billing password codified in base64
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.
Docker:
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:
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:
where {host} is the IP or domain from the server exposing the webhook.
Python
PHP
Logs
Service logs are stored in the running docker container. You can reach them executing:
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
API Reference
https://cdn.developers.uanataca.com/oneshot/oneshot.html