Skip to content
One-Shot
/
Enterprise Documentation
/
/Requests

Oneshot API (1.0.0)

One-Shot API for single-use certificate electronic signatures. All endpoints are relative to the base path /oneshot/api/v1.

For the public testing environment (sandbox URL, RAO token, prerequisites, and how to use the test Optimizer), see the Get started guide in the One-Shot documentation: Get started with One-Shot.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Public testing environment

https://optimizer-developers.uanataca.com/oneshot/api/v1/

Settings

Endpoints to manage the service settings

Operations

Tokens

Endpoints to manage the tokens

Operations

Requests

Endpoints to manage the signature requests

Operations

Call Create

Request

Creates a new digital signature request for the user identified.

Bodymultipart/form-data
given_namestringrequired

The user's given name

surname_1stringrequired

The user's first surname

surname_2string

The user's second surname

id_document_typestringrequired

Document types allowed for the user identification:

  • IDC - Identification based on national identity card number. Default when this field is not specified.
  • 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
  • CI - Tax Identification Number according to the European Commission
  • CE - Tax Identification Number according to the European Commission
id_document_countrystringrequired

The user's id document country two-letters code (ISO 3166-1 alpha-2).

serial_numberstringrequired

User's id document serial number

emailstringrequired

The user's email

mobile_phone_numberstringrequired

The user's mobile phone number including the international prefix

registration_authoritystringrequired

The Registration Authority id number.

profilestringrequired

Digital certificate profiles

tokenstringrequired

The Registration Authority Officer (RAO)'s token unique id containing RAO's digital identity credentials.

Not required when RAO's credentials (username, password, pin) are included as fields in this call.

usernamestringrequired

The RAO's digital identity username.

Not required when included in token (Create Token endpoint).

passwordstringrequired

The RAO's digital identity password.

Not required when included in token (Create Token endpoint).

pinstringrequired

The RAO's digital identity PIN.

Not required when included in token (Create Token endpoint).

document_frontstring(binary)

Front side image of the user's identification document (JPEG or PNG).

document_rearstring(binary)

Rear side image of the user's identification document (JPEG or PNG)

document_ownerstring(binary)

A selfie image of the user holding the identifying document below his/her chin (JPEG or PNG)

extra_documentstring(binary)

An extra document to upload.

envstringrequired

The API work environment.

Required only if not set at settings.toml file.

Enum"sandbox""prod"
billing_usernamestringrequired

Billing account username. > Required only if not set at settings.toml file.

billing_passwordstring(base64)required

The client billing password in Base64 format.

Required only if not set at settings.toml file.

useasyncboolean

This parameter enables One-Shot asynchronous workflow. When set to true, the callback parameter can be set by specifying a Webhook URL.

callbackstring

Webhook URL where the information of the asynchronous flow is going to be sent.

communication_languagestring

Two letter code language for communications(ISO3166-1 alpha-2). Default ES

Enum"ES""PL""EN"
residencestring

Required only in certain profiles

residence_citystring

Required only in certain profiles

residence_postal_codestring

Required only in certain profiles

residence_addressstring

Required only in certain profiles

special_conditionsstring

Required only in certain profiles

curl -i -X POST \
  https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/create \
  -H 'Content-Type: multipart/form-data' \
  -F given_name=string \
  -F surname_1=string \
  -F surname_2=string \
  -F id_document_type=string \
  -F id_document_country=string \
  -F serial_number=string \
  -F email=string \
  -F mobile_phone_number=string \
  -F registration_authority=string \
  -F profile=string \
  -F token=string \
  -F username=string \
  -F password=string \
  -F pin=string \
  -F document_front=string \
  -F document_rear=string \
  -F document_owner=string \
  -F extra_document=string \
  -F env=sandbox \
  -F billing_username=string \
  -F billing_password=string \
  -F useasync=true \
  -F callback=string \
  -F communication_language=ES \
  -F residence=string \
  -F residence_city=string \
  -F residence_postal_code=string \
  -F residence_address=string \
  -F special_conditions=string

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "status": "success",
  "message": "Request created with pk 123456",
  "details": {
    "status": "CREATED",
    "asyncmode": "xxx",
    "pk": "123456"
  }
}

Call Get Request

Request

Retrieve request information with the id obtained in the CREATE REQUEST response.

Path
request_pkinteger(The ID of the Request to get)required

The ID of the Request to get

curl -i -X GET \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/request/{request_pk}'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "secrets": {
    "puk": "70040984",
    "enrollment_code": "bGxB86WR",
    "pin": "58148177",
    "erc": "8239245862"
  },
  "request": {
    "pk": 822543,
    "given_name": "Nombre",
    "second_name": null,
    "surname_1": "Apellido1",
    "surname_2": null,
    "sex": null,
    "id_document_type": "IDC",
    "id_document_country": "ES",
    "serial_number": "0000000T",
    "country_name": "ES",
    "citizenship": null,
    "residence": null,
    "organization_email": null,
    "email": "name@domain.com",
    "titile": null,
    "organization_name": null,
    "organizational_unit_1": null,
    "organizational_unit_2": null,
    "organization_identifier": null,
    "responsible_name": null,
    "responsible_second_name": null,
    "responsible_first_surname": null,
    "responsible_second_surname": null,
    "responsible_email": null,
    "responsible_serial": null,
    "responsible_position": null,
    "subscriber_responsible_serial": null,
    "administrative_unit": null,
    "empowerment": null,
    "representation": null,
    "circumstances": null,
    "limit": null,
    "registration": null,
    "process_application": null,
    "entity_owner": null,
    "entity_owner_serial_number": null,
    "description": null,
    "certificate_set": [],
    "profile": "PFnubeAFCiudadano",
    "scratchcard": "3389580",
    "status": "ENROLLREADY",
    "registering_user": { … },
    "approving_user": { … },
    "producing_user": null,
    "registration_authority": 3,
    "secure_element": 2,
    "validity_time": "24h",
    "smartcard_sn": null,
    "citizen_tax_number": null,
    "birth_date": null
  }
}

Call Delete Request

Request

Cancels the Video ID One-Shot Signature request

Path
request_pkinteger(The ID of the Request to delete)required

The ID of the Request to delete

curl -i -X DELETE \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/request/{request_pk}'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "status": "success",
  "message": "Request 822880 deleted"
}

Call Update Request

Request

Updates a Video ID signature request.

Path
request_pkinteger(The ID of the Request to update)required

The ID of the Request to update

Bodyapplication/json
scratchcardstringrequired

⚠ The scratchcard id can be found in the details object when calling Get Request.

given_namestring

The signer's given name

surname_1string

The signer's first surname

surname_2string

The signer's second surname

birth_datestring

The signer's birth date

emailstringrequired

The signer's email

mobile_phone_numberstring

The signer's mobile phone number

serial_numberstring

The signer's document ID number

registration_authoritystringrequired

The Registration Authority id number

profilestringrequired

The certificate profile

country_namestringrequired

The user's id document country two-letters code (ISO 3166-1 alpha-2)

curl -i -X PUT \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/request/{request_pk}' \
  -H 'Content-Type: application/json' \
  -d '{
    "scratchcard": "string",
    "given_name": "string",
    "surname_1": "string",
    "surname_2": "string",
    "birth_date": "string",
    "email": "string",
    "mobile_phone_number": "string",
    "serial_number": "string",
    "registration_authority": "string",
    "profile": "string",
    "country_name": "string"
  }'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "pk": "926427,",
  "given_name": null,
  "second_name": null,
  "surname_1": null,
  "surname_2": null,
  "sex": null,
  "id_document_type": "IDC",
  "id_document_country": "ES",
  "serial_number": null,
  "country_name": "ES",
  "citizenship": null,
  "residence": "ES",
  "organization_email": null,
  "email": "s.cordon@external.namirial.com",
  "title": null,
  "organization_name": null,
  "organizational_unit_1": null,
  "organizational_unit_2": null,
  "organization_identifier": null,
  "responsible_name": null,
  "responsible_second_name": null,
  "responsible_first_surname": null,
  "responsible_second_surname": null,
  "responsible_email"": null,
  "esponsible_serial": null,
  "responsible_position": null,
  "subscriber_responsible_serial": null,
  "administrative_unit": null,
  "empowerment": null,
  "representation": null,
  "circumstances": null,
  "limit": null,
  "registration": null,
  "process_application": null,
  "entity_owner": null,
  "entity_owner_serial_number": null,
  "description": null,
  "certificate_set": [],
  "profile": "PFnubeQBCRCiudadano",
  "scratchcard": "2677829",
  "status": "VIDEOPENDING",
  "registering_user": {
    "pk": 1168,
    "permission_profile": 1,
    "registration_authority": 3,
    "request": 233342
  },
  "approving_user": null,
  "producing_user": null,
  "registration_authority": 892,
  "secure_element": 2,
  "validity_time": "1",
  "smartcard_sn": null,
  "citizen_tax_number": null,
  "birth_date": null,
  "birth_country": null,
  "birth_city": null,
  "birth_province": null,
  "birth_state": null,
  "birth_district": null,
  "birth_canton": null,
  "id_document_description": null,
  "id_document_issuer": null,
  "id_document_release": null,
  "id_document_expiry": null,
  "organization_rol": null,
  "professional_id_number": null,
  "mobile_phone_number": "+34640234526",
  "fix_phone_number": null,
  "residence_address": "test",
  "residence_city": "test",
  "residence_province": null,
  "residence_postal_code": "test",
  "residence_state": null,
  "residence_district": null,
  "residence_canton": null,
  "organization_tax_number": null,
  "organization_address": null,
  "organization_city": null,
  "organization_province": null,
  "organization_country": null,
  "organization_postal_code": null,
  "organization_state": null,
  "organization_url": null,
  "responsible_legal_level": null,
  "subscriber": null,
  "responsible_legal_documents": null,
  "special_conditions": null,
  "responsible_registry_data": null,
  "approving_rao": null,
  "producing_rao": null,
  "id_document_number": null,
  "id_responsible_document_type": null,
  "id_responsible_document_country": null,
  "id_responsible_document_number": null,
  "organizational_unit_3": null,
  "paperless_mode": false,
  "videoid_mode": true,
  "ext_recognition_data": null,
  "complement_number": null,
  "id_responsible_document_issuer": null,
  "provider_registration_number": null,
  "communication_language": "",
  "identification_rao": null,
  "videoid_data": {
    "pk": 16738,
    "status": "PENDING",
    "provider": 1,
    "videoid_link": "",
    "requests": 926427,
    "refusal_reason": "",
    "refusal_details": null,
    "data": {},
    "video_identifier": "688e1758cc0b4a7bbd7d5549353cd0ec",
    "validation_services": {},
    "acceptance": {},
    "validation_operator": null,
    "operation_urls": { … },
    "esaw_requests_involved": false,
    "external_onboarding_link": null,
    "manual_external_validation": false
  },
  "enrollment_success_url": null,
  "configuration_data": {},
  "external_profile": null,
  "responsible_citizenship": null,
  "responsible_city": null
}

Call Get Request Contract

Request

Get Request contract.

Path
request_pkinteger(The ID of the Request)required

The ID of the Request

curl -i -X GET \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/contract/{request_pk}'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
"The retrieved contract in pdf format"

Call Generate Otp

Request

Generates a One-Time Password (OTP) code for the user. The OTP is sent directly to the user's mobile phone as an SMS message.

This method is only required and available for requests using Uanataca SMS method

Path
request_pkinteger(The ID of the Request to which generate the otp)required

The ID of the Request to which generate the otp

Bodyapplication/json
delivery_methodstring

Method selector to send the code. Default "sms" if field is not included or not set in settings file.

Enum"sms""whatsapp"
curl -i -X POST \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/otp/{request_pk}' \
  -H 'Content-Type: application/json' \
  -d '{
    "delivery_method": "sms"
  }'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "status": "success",
  "detail": "OTP successfully sent to xxx"
}

Call Sign

Request

Sign documents assigned to specific Request

Path
request_pkinteger(The ID of the Request to which sign documents)required

The ID of the Request to which sign documents

Bodyapplication/jsonrequired
secretstring(Secret)required

The OTP code sent to the user. For external authentication method, a customer code is provided.

ext_unlock_valuestring(Ext Unlock Value)

The id of the external authentication request. This field is required for requests using external authenticacion methods.

ext_unlock_typestring(Ext Unlock Type)

The external authentication method type. This field is required for requests using external authenticacion methods.

signatureobject(SignatureParams)
countersignatureobject(CounterSignatureParams)
signature_by_docSignature By Doc (object) or Signature By Doc (null)(Signature By Doc)
Any of:
curl -i -X POST \
  'https://optimizer-developers.uanataca.com/oneshot/api/v1/api/v1/sign/{request_pk}' \
  -H 'Content-Type: application/json' \
  -d '{
    "secret": "string",
    "ext_unlock_value": "string",
    "ext_unlock_type": "string",
    "signature": {
      "appearance": {
        "horizontal": true,
        "text": [
          null
        ],
        "date": "string",
        "timezone": "string",
        "position": "string",
        "page": 0,
        "image": "string",
        "b64_image": "string",
        "qrcode": "string",
        "text_size": 0,
        "text_align": "string",
        "reason": "string",
        "location": "string"
      },
      "disable_ltv": true,
      "use_tsa": true,
      "metadata": "string",
      "level": "string",
      "subfilter": "adbe.pkcs7.detached"
    },
    "countersignature": {
      "appearance": {
        "horizontal": true,
        "text": [
          null
        ],
        "date": "string",
        "timezone": "string",
        "position": "string",
        "page": 0,
        "image": "string",
        "b64_image": "string",
        "qrcode": "string",
        "text_size": 0,
        "text_align": "string",
        "reason": "string",
        "location": "string"
      },
      "username": "string",
      "password": "string",
      "pin": "string",
      "subfilter": "adbe.pkcs7.detached"
    },
    "signature_by_doc": {
      "property1": {
        "appearance": {
          "horizontal": true,
          "text": [
            null
          ],
          "date": "string",
          "timezone": "string",
          "position": "string",
          "page": 0,
          "image": "string",
          "b64_image": "string",
          "qrcode": "string",
          "text_size": 0,
          "text_align": "string",
          "reason": "string",
          "location": "string"
        },
        "usecountersignature": true,
        "metadata": "string",
        "level": "string",
        "subfilter": "adbe.pkcs7.detached"
      },
      "property2": {
        "appearance": {
          "horizontal": true,
          "text": [
            null
          ],
          "date": "string",
          "timezone": "string",
          "position": "string",
          "page": 0,
          "image": "string",
          "b64_image": "string",
          "qrcode": "string",
          "text_size": 0,
          "text_align": "string",
          "reason": "string",
          "location": "string"
        },
        "usecountersignature": true,
        "metadata": "string",
        "level": "string",
        "subfilter": "adbe.pkcs7.detached"
      }
    }
  }'

Responses

Successful Response

Bodyapplication/json
any
Response
application/json
{
  "status": "success",
  "message": "Signature process for Request 825527 completed",
  "detail": {
    "request": 825527,
    "documents": { … }
  }
}

Documents

Endpoints to manage the documents

Operations

Images

Endpoints to manage the images

Operations

Video ID

Endpoints to manage the Video ID

Operations