Requests

A Digital Signature Request is how the One-Shot Signature API collects information about a single digital signature operation, including both identifying information for the signing user and all documents that will be signed.

While documents to be signed can be added or modified later, the creation of a new digital signature request requires providing all user identification data.

Verb Endpoint Action
POST /request Create a new Request
GET /request/{pk} Retrieve a Request
POST /otp/{pk} Generate a new OTP
POST /sign/{pk} Start the signature process

Create a Request

Description

Create a new digital signature request for the user identified by the provided information.

Endpoint

/api/v1/request

Method

POST

Parameters
Body parameters

The call must include enough information to identify both the signing user and the RAO initiating the request. The specifics of the user-identifying data depend on the user profile used internally, but they should include at least the following:

Field Value Description Mandatory
profile PFnubeAFCiudadano or PFnubeNC The user profile defines the user identifying data that will be included in the signature. If not given, the default profile name set in custom.ini will be used. PFnubeAFCiudadano is used for qualified signature, while PFnubeNC is used for non-qualified signature. No
registration_authority The Registration Authority id number. By default, the RA set in custom.ini will be used. No
id_document_type [IDC,PAS,PNO,TIN] Document type for the user identification document. IDC - Identification based on national identity card number. PAS - Identification based on passport number. PNO - Identification based on (national) personal number (national civic registration number). TIN - Tax Identification Number according to the European Commission. Yes
id_document_country ISO 3166-1 alpha-2 Two-letter code for the country issuing the user's id document. Yes
serial_number Serial number of the user's id document. Yes
given_name The user's given name. Yes
surname_1 The user's (first) surname. Yes
email The user's email. Yes
mobile_phone_number User's mobile phone number. Yes

The parameters in the table above are the minimum set of values required by the One-Shot API. The full list of available arguments is given here.

Besides the identifying information required for each user, the following parameters identifying the RAO initiating the digital signature request can be provided:

Parameter Description Mandatory
token The token representing the RAO's credentials No
username The RAO's username No
password The RAO's password No
pin The RAO's pin No
rao The RAO's unique identifier No

At least a token or a set of username, password and pin should be provided. Note that individual tokens can stand for some or all of the RAO credentials. For example if the token "81cc334d8e384d52812125c7bf952933" has associated the username and password (but not the pin), this endpoint will expect to receive both the token and the pin (the RAO unique identifier is always automatically retrieved when creating a token).

If the Registration Authority requires users' documents to allow their enrollment, these should be provided as additional arguments in the Request call:

Parameter Description Mandatory
document_front An image of the front face of the user's document Yes
document_rear An image of the back face of the user's document Yes
document_owner An image of the user holding the identifying document Yes
JSON input

When the Registration Authority does not require identifying documents to create certificates, the request endpoint can also be called with JSON input. The parameters required are the same as above, except for the document images.

Response

Returns a JSON object with the Request's unique identifier just created.


                    {
                        "status": "201 Created",
                        "details": 1461
                    }
                
Example

Request with form data:


                    curl --location --request POST 'https://oneshot.demo.uanataca.com/api/v1/request' \
                         --form 'token=791ef6ff519b41cfa2f311e6cd144586' \
                         --form 'profile=PFnubeAFCiudadano' \
                         --form 'given_name=name_of_the_user' \
                         --form 'surname_1=surname_of_the_user' \
                         --form 'id_document_type=IDC' \
                         --form 'id_document_country=ES' \
                         --form 'serial_number=12345678A' \
                         --form 'email=user-example@domain.com' \
                         --form 'mobile_phone_number=+34666123456' \
                         --form 'document_front=@document_front.png' \
                         --form 'document_rear=@document_rear.png' \
                         --form 'document_owner=@document_owner.png'
                

                    {
                        "status": "201 Created",
                        "details": 1461
                    }
                

Request with JSON data (only available when user documents are not required):

params.json:

                    {
                        "given_name": "Example",
                        "surname_1": "Request",
                        "id_document_type": "IDC",
                        "id_document_country": "ES",
                        "serial_number": "12345678A",
                        "email": "example@uanataca.com",
                        "mobile_phone_number": "+34666123456",
                        "token": "81cc334d8e384d52812125c7bf952933",
                        "pin": "my-RA-pin"
                    }
                
curl -d@params.json -X POST https://oneshot.demo.uanataca.com/api/v1/request

                    {
                        "status": "201 Created",
                        "details": 1461
                    }
                

Retrieve a Request

Description

Returns user information for a signature request with the given id number

Endpoint

                    /api/v1/request/{request-id}
                
Method
GET
Parameters
Path parameters
Parameter Description
request-id The Request's unique identifier
Response

A JSON object containing the information related to the Request found

Errors

If the Request is not found, an HTTP 404 error is returned:


                    {
                        "status": "404 Not Found",
                        "details": "No Request matches the given query."
                    }
                
Example
                    
                        curl -X GET https://oneshot.demo.uanataca.com/api/v1/request/1433
                    
                
                    
                        {
                            "status": "200 OK",
                            "details": {
                                "given_name": "Alessandro",
                                "surname_1": "Rossi",
                                ...
                            }
                        }
                    
                

Generate an OTP

Description:

This endpoint can be used to generate a new One-Time Password (OTP) for a user. The OTP is used as part of the signature process to confirm the identity of the signer. As such, the generated OTP is not returned in the response, but sent directly to the user as an SMS message to the phone number provided when creating the signature request.

Endpoint

/api/v1/otp/{request-id}

Method

POST

Parameters
Path parameters
Parameter Description
request-id The Request's unique identifier
Response

Returns a JSON object with a success message. Additionally, an SMS with the secret code generated will be sent to the mobile phone number given when creating the request.

Errors

If the digital signature operation for this request has been completed (the documents have already been signed), this resource will return an HTTP 412 error:


                {
                    "status": "412 Precondition Failed",
                    "details": "Error occured during OTP generation: Invalid request status"
                }
Example


                    curl -X POST https://oneshot.demo.uanataca.com/api/v1/otp/1454
                

                    {
                        "status": "200 OK",
                        "details": "OTP generated"
                    }
                

Sign

Description

Sign previously uploaded documents using the certificate generated for the Request.

Endpoint

/api/v1/sign/{request-id}

Method

POST

Parameters
Path parameters
Parameter Description
request-id The Request's unique identifier
Body parameters
Parameter Description Mandatory
secret The OTP generated for this Request Yes
options A JSON object used to specify signature settings for individual documents. To do this, use the document unique id string as key and one or more of the following parameters as values: No
image Unique id of a previously uploaded image. For a given document, use this image to graphically represent the digital signature within the PDF file. No
page For a given document, page where the image representing the signature will be inserted. Note that PDF pages are counted from 0. No
position For a given document, position of the graphical signature. Coordinates expressed as: "bottom left x, bottom left y, top right x, top right y", increasing from the lower left corner of the page. No
disable_tsa For a given document, if this parameter is set to 1 or true, the signature of the document will not be timestamped. No

By default, the signature of all documents will include a timestamp. Use the disable_tsa parameter to override this behavior for a given document.

Response

Returns a JSON object with a success message.

Errors

If the digital signature operation for this request has been completed (the documents have already been signed), this resource will return an HTTP 412 error:


                {
                    "status": "412 Precondition Failed",
                    "details": "Request already in ISSUED status"
                }
                
Example

The following example shows how to set a graphical representation of the signature for two of the documents and disable the timestamp of the first one.

params.json:

                    {
                        "secret"   : "000000",
                        "options": {
                            "5f04778a-54f6-426a-b204-5573eb01e5da": {
                                "position": "300, 100, 500, 150",
                                "image": "b0b6370e-8b54-4d8b-ab6f-a002cf08dd28",
                                "page": 1,
                                "disable_tsa": 1
                            },
                            "b8145ea0-b4f8-4d0e-9f3f-522ddbe6806b": {
                                "position": "300, 100, 500, 150",
                                "page": 1,
                                "image": "b0b6370e-8b54-4d8b-ab6f-a002cf08dd28"
                            }
                        }
                    }
                
curl -d @params.json -X POST https://oneshot.demo.uanataca.com/api/v1/sign/1454

                    {
                        "status": "200 OK",
                        "details": "Documents successfully signed"
                    }