Requests

Manage Requests

Allowed HTTP verbs by this endpoint:

Verb Endpoint Action
POST /requests/ Create a new Request
POST /requests/{id}/generates_tbs_receipt/ Generate a tbs receipt for a Request
POST /requests/{id}/approve/ Approve a Request
POST /requests/{id}/cloud_enroll/ Enroll a Request with Cloud as secure element
POST /requests/{id}/p12_enroll/ Enroll a Request with Software as secure element
GET /requests/ Get a list of Requests
GET /requests/{id}/ Get information about a Request
DELETE /requests/{id}/cancel/ Cancel a Request
PUT /requests/{id}/ Update information about a Request
POST /requests/{id}/generate_document/ Retrieve the documents associated to the Request
GET /requests/{id}/validate/ Validate the Request fields
GET /requests/{id}/preauthlink/ Retrieve the pre-authenticated link associated to the Request.
POST /requests/{id}/preauthlink/ Create a new pre-authenticated link for the Request.

Create a Request

Every issue of a digital certificate starts with the creation of a new request.

The parameters needed to create a new Request, changes according to the profile used.

Endpoint:
/api/v1/requests/
Method:
POST
Response

If the response is successfully, the response status code is 201 and the body contains the JSON composed of all the parameters associated to the Request.

Instead in case of error, the response body is a JSON containing the error details and the response status code is the HTTP code related.

Example

An example profile is PFnubeAFCiudadano, that has these required fields:

  • The scratchcard is a serial number of an available and unused scratchcard from the file scratchcards.txt. Every RA (and RAO) has a list of available scratchcards assigned.
  • The secure_element can be 0, 1 or 2 which stands respectively to Software, Smartcard and Cloud. It represents the typology of the device where storing the digital identity. For this type of request, the only one available is Cloud.
  • The registration_authority is the unique identifier (PK) of the RA (it's assigned when is created).
  • The country_name is the country where the RA is registered.
  • The id_document_type is the document type that the end user is using for requesting the certificate.
  • The id_document_country is the country where was released the document (e.g. IT or ES).
  • The serial_number is the number that identifies the document.
  • The given_name is the first name of the end user requesting the certificate.
  • The surname_1 is the first surname of the end user requesting the certificate.
  • The email is the email of the end user requesting the certificate.
  • The mobile_phone_number is the number of the end user requesting the certificate.

            {
                "profile": "PFnubeAFCiudadano",
                "scratchcard": "111111111",
                "secure_element": "2",
                "registration_authority": "68",
                "country_name": "ES",
                "serial_number": "TSTAPI74S23C129Y",
                "id_document_country": "IT",
                "id_document_type" : "TIN",
                "given_name": "RAO",
                "surname_1": "API",
                "birth_date": "16/10/1965",
                "email": "email@bit4id.com",
                "mobile_phone_number": "391234567890"
            }

            curl -H "Content-Type: application/json" -d @params.json -X POST https://api.uanataca.com/api/v1/requests/
            

            {
                "pk": 2299,
                "given_name": "RAO",
                "surname_1": "COFTenerife",
                "surname_2": API,
                "sex": null,
                "id_document_type": "TIN",
                "id_document_country": "IT",
                "serial_number": "TSTAPI74S23C129Y",
                "country_name": "ES",
                "citizenship": null,
                "residence": null,
                "organization_email": null,
                "email": "email@bit4id.com",
                "title": null,
                "organization_name": null,
                "organizational_unit_1": null,
                "organizational_unit_2": null,
                "organization_identifier": null,
                "responsible_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": "120000400",
                "status": "CREATED",
                "registering_user": {
                    "pk": 118,
                    "permission_profile": 13,
                    "registration_authority": 68,
                    "request": 2298
                },
                "approving_user": null,
                "producing_user": null,
                "registration_authority": 68,
                "secure_element": 2,
                "validity_time": "730",
                "smartcard_sn": null,
                "citizen_tax_number": null,
                "birth_date": "16/10/1965",
                "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,
                "organization_rol": null,
                "professional_id_number": null,
                "mobile_phone_number": "3333333333",
                "fix_phone_number": null,
                "residence_address": null,
                "residence_city": null,
                "residence_province": null,
                "residence_postal_code": null,
                "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
            }

Generate a tbs receipt

The generation of a receipt for a request, is an important step for the approval.

Endpoint:
/api/v1/requests/{id}/generates_tbs_receipt/
Method:
POST

These endpoint accepts two parameters:

Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:
Parameter Description
rao The unique identifier of the RAO that will sign and approve the request
type The type of the receipt to generate
Response

The successful response is the receipt, that once saved in a file must be signed by the RAO.

The signature can be applied with a standard tool such as OpenSSL, and then saved as a base64 string. This signed receipt must be sent to the server, for the request approval.

Example

            {
                "rao": "100",
                "type": "APPROVE"
            }

Approve a Request

Once created a new Request, the next thing to do is approve it.

Endpoint:
/api/v1/requests/{id}/approve/
Method:
POST
Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:
Parameter Description
rao The unique identifier of the RAO that will sign and approve the request
receipt The signed receipt as a Base64 formatted string
Response

If the approval is successful, the response is a JSON object with the info and the secrets associated to it.

Example

            {
                "rao": "100",
                "receipt": "MIIHyTCCBbGgA..."
            }

            {
                "secrets": {
                    "puk": "06092551",
                    "enrollment_code": "8N!9xPhB",
                    "pin": "76293975",
                    "erc": "3706008596"
                },
                "request": {
                    "pk": 665,
                    "given_name": "TEST",
                    "surname_1": "API",
                    "surname_2": "Software P12",
                    "sex": null,
                    "id_document_type": "TIN",
                    "id_document_country": "IT",
                    "serial_number": "TSTAPI74S23C129Y",
                    "country_name": "ES",
                    "citizenship": null,
                    "residence": null,
                    "organization_email": null,
                    "email": "asi@bit4id.com",
                    "title": null,
                    "organization_name": null,
                    "organizational_unit_1": null,
                    "organizational_unit_2": null,
                    "organization_identifier": null,
                    "responsible_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": "PFSoftAFCiudadano",
                    "scratchcard": "120000026",
                    "status": "ENROLLREADY",
                    "registering_user": {
                        "pk": 34,
                        "permission_profile": 18,
                        "registration_authority": 39,
                        "request": 605
                    },
                    "approving_user": {
                        "pk": 34,
                        "permission_profile": 18,
                        "registration_authority": 39,
                        "request": 605
                    },
                    "producing_user": null,
                    "registration_authority": 39,
                    "secure_element": 0,
                    "validity_time": "730",
                    "smartcard_sn": null,
                    "citizen_tax_number": null,
                    "birth_date": "16/10/1965",
                    "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,
                    "organization_rol": null,
                    "professional_id_number": null,
                    "mobile_phone_number": "3333333333",
                    "fix_phone_number": null,
                    "residence_address": null,
                    "residence_city": null,
                    "residence_province": null,
                    "residence_postal_code": null,
                    "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": {
                        "pk": 218,
                        "given_name": "Alessandro",
                        "surname_1": "Silvestro",
                        "surname_2": "Bit4id",
                        "certificate": {
                            "profile": "EXTERNAL",
                            "status": 0,
                            "valid_from": "2018-10-16T11:07:00Z",
                            "valid_to": "2020-10-15T11:07:00Z",
                            "valid": "VALID",
                            "revokation_reason": null,
                            "serial_number": "0d0c1d8b1e4efefa",
                            "subject": "CN=Alessandro Silvestro Bit4id,
                            2.5.4.5=TINIT-RRRTST84R14F839U,
                            2.5.4.42=Alessandro,
                            2.5.4.4=Silvestro Bit4id, C=ES",
                            "data": "MIIH5zCCBc+gAwIBAgI...",
                            "issuer": "2.5.4.97=VATES-A66721499,
                            CN=UANATACA CA1 DEVEL 2016,
                            OU=AC-UANATACA,
                            O=UANATACA S.A.,
                            L=Barcelona C=ES"
                        },
                        "id_document_number": "RRRTST84R14F839U",
                        "id_document_description": null,
                        "id_document_issuer": null,
                        "registration_authority": [
                            39
                        ],
                        "registration_authority_master": 39
                    },
                    "producing_rao": null,
                    "id_document_number": null
                }
            }

Request Enrollment

The enrollment consist of the generation of a new digital certificate for a request already created and approved.

The API to invoke for the enrollment, change based on the profile and the secure element used for the request creation.

For a Request that has the secure element setted to Cloud, the correct endpoint for the enrollment is

For a Request that has the secure element setted to Software, the correct endpoint for the enrollment is /requests/{id}/p12_enroll/

Once the Request is Enrolled, its status will be ISSUED


Cloud Enrollment

Endpoint:
/api/v1/requests/{id}/cloud_enroll/
Method:
POST

The Cloud enrollment require these parameters:

Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:
Parameter Description
scratchcard The scratchcard of the request that needs enrollment
erc The enrollment code associated to the scratchcard
pin A new pin to assign
puk A new puk to assign

Pin and Puk must contain at least 2 letters, 2 numbers and must be at least 8 characters long

Response

The server will reply with the generated certificate in case of success.

Example

            {
                "scratchcard": "120000400",
                "erc": "bB7n9RYk",
                "pin": "belorado74",
                "puk": "belorado74"
            }

            curl -H "Content-Type: application/json" -d @params.json https://api.uanataca.com/api/v1/requests/1234/cloud_enroll/
            

            [
                {
                    "data": "MIIHyTCCBbGgAwIBAgIIcO...",
                    "profile": "PFnubeAF",
                    "subject": "CN=RAO COFTenerife API,
                    2.5.4.5=TINIT-TSTAPI74S23C129Y,
                    2.5.4.42=RAO, 2.5.4.4=COFTenerife, C=ES",
                    "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 DEVEL 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona, C=ES",
                    "valid_from": "2018-10-16T16:41:00",
                    "valid_to": "2020-10-15T16:41:00",
                    "serial_number": "70e07489bfccd478",
                    "status": 0,
                    "pk": 1980,
                    "revokation_reason": null,
                    "type": "FIRSTISSUE"
                }
            ]

Software Enrollment

Endpoint:
/api/v1/requests/{id}/p12_enroll/
Method:
POST

The Software Enrollment require only these parameters:

Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:
Parameter Description
scratchcard The scratchcard of the request that needs enrollment
enrollment_code The enrollment code associated to the scratchcard
Response

If the generation of the certificate is successful, the server response is the P12 file in Base64 format.

This P12 file, protected by a password that coincide with the enrollment_code, can be imported inside the OS (Windows/Linux/MacOS) or on a smartcard and then used with a dedicated software like SignCloudPC.

Example

            {
                "scratchcard": "120000400",
                "enrollment_code": "bB7n9RYk"
            }

            curl -H "Content-Type: application/json" -d @params.json -X POST https://api.uanataca.com/api/v1/requests/1234/p12_enroll/
            

            [
                "-----BEGIN PKCS12-----
                MIIN/AIBAzCCDcIGCSqGSIb3DQEHAaCCDbMEgg2vMIINqzCCCCgGCSqGSIb3DQEH
                AaCCCBkEgggVMIIIETCCCA0GCyqGSIb3DQEMCgEDoIIH2TCCB9UGCiqGSIb3DQEJ
                FgGgggfFBIIHwTCCB70wggWloAMCAQICCAw/8u9JFlHzMA0GCSqGSIb3DQEBCwUA
                MIG9MQswCQYDVQQGEwJFUzFEMEIGA1UEBww7QmFyY2Vsb25hIChzZWUgY3VycmVu
                dCBhZGRyZXNzIGF0IHd3dy51YW5hdGFjYS5jb20vYWRkcmVzcykxFjAUBgNVBAoM
                DVVBTkFUQUNBIFMuQS4xFDASBgNVBAsMC0FDLVVBTkFUQUNBMSAwHgYDVQQDDBdV
                QU5BVEFDQSBDQTEgREVWRUwgMjAxNjEYMBYGA1UEYQwPVkFURVMtQTY2NzIxNDk5
                MB4XDTE4MTEyMjE1MjgwMFoXDTIwMTEyMTE1MjgwMFoweDELMAkGA1UEBhMCRVMx
                GTAXBgNVBAQMEEFQSSBTb2Z0d2FyZSBQMTIxDTALBgNVBCoMBFRFU1QxHzAdBgNV
                BAUTFlRJTklULVRTVEFQSTc0UzIzQzEyOVkxHjAcBgNVBAMMFVRFU1QgQVBJIFNv
                ZnR3YXJlIFAxMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMf63BEB
                eKd1+oBVf8o/ybGCcs4ZUIsLaiI+uo/brGM40Uo0uoD1Y5e1Ewt6GdnB3+OQnCzv
                6prb/pSwZ5GxpjkYPjAf+MEyKsJfPTOW0gBQwvzo3oaXq9g/BqYRJcT7heM7knbb
                thT5mJTxnGoWAkTuRjwEsiyCAfVYrCwLqE4uNBvXju4nrZ51jA4kQx3oyVpy7Y3O
                uuVdIfOmxbKhb/iyBUAzYusRfUv+XVvDqiVLP+9a+i3JUpi2qMQNx4q3B4Ply1Fz
                1FgBw4icYtHfMrKHIkoKmYzPpUM97x4GE+Hz8esX98My0NROa59x0uoPuU+d4P1e
                e2x+aTKeiadfjkUCAwEAAaOCAwMwggL/MIHXBggrBgEFBQcBAQSByjCBxzBVBggr
                BgEFBQcwAoZJaHR0cDovL3d3dy51YW5hdGFjYS5jb20vcHVibGljL2Rvd25sb2Fk
                L3RzcF9jZXJ0aWZpY2F0ZXMvc3Vib3JkaW5hdGUxLmNydDA2BggrBgEFBQcwAYYq
                aHR0cDovL29jc3AxLnVhbmF0YWNhLmNvbS9wdWJsaWMvcGtpL29jc3AvMDYGCCsG
                AQUFBzABhipodHRwOi8vb2NzcDIudWFuYXRhY2EuY29tL3B1YmxpYy9wa2kvb2Nz
                cC8wHQYDVR0OBBYEFGDhXkciQE/205bmPJuEnR+ap8YPMAwGA1UdEwEB/wQCMAAw
                HwYDVR0jBBgwFoAUysyKpc+kjCJa1vuX90+0Tv3V764wVQYIKwYBBQUHAQMESTBH
                MAgGBgQAjkYBATALBgYEAI5GAQMCAQ8wLgYGBACORgEFDCRodHRwczovL3d3dy51
                YW5hdGFjYS5jb20vcHVibGljL2Nwcy8wgaEGA1UdIASBmTCBljAJBgcEAIvsQAEA
                MIGIBgsrBgEEAYLxNgEBATB5MDAGCCsGAQUFBwIBFiRodHRwczovL3d3dy51YW5h
                dGFjYS5jb20vcHVibGljL2Nwcy8wRQYIKwYBBQUHAgIwOQw3Q2VydGlmaWNhZG8g
                Y3VhbGlmaWNhZG8gZGUgUGVyc29uYSBGw61zaWNhIGVuIHNvZnR3YXJlLjCBjwYD
                VR0fBIGHMIGEMECgPqA8hjpodHRwOi8vY3JsMS51YW5hdGFjYS5jb20vcHVibGlj
                L3BraS9jcmwvQ0Exc3Vib3JkaW5hZGEuY3JsMECgPqA8hjpodHRwOi8vY3JsMi51
                YW5hdGFjYS5jb20vcHVibGljL3BraS9jcmwvQ0Exc3Vib3JkaW5hZGEuY3JsMA4G
                A1UdDwEB/wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwGQYD
                VR0RBBIwEIEOYXNpQGJpdDRpZC5jb20wDQYJKoZIhvcNAQELBQADggIBAJj7bPyq
                F+QojTNESKKxw0WdYgFEFF72hA44SZ5oCZ/ZORYZepVJnaI6zjRQ7ezQwNtc87mr
                Hdn7Bl9kNkgp1bFtllMzwr2/eg1/UrEE8+oWIXvaTU29/t1QXdPaMi/7Jq01yM1e
                VKF0lndz9qBuxlr1RwfcpznOhn+J+C4B6BeK0yc+jELDPpceuG0WNB5FDUrdy5x2
                +lYJLfSkg8+3l1mnSHZPUr3c3h2qX17XhV4r6lCFofBekrXfRrKUFmf0V9fs3N+k
                ymZQ8NCrOiPoDXTEdrhMvKFUQ7YEniwHJ7alzQGbKMd0X1BmvTw0HugbU6f/oMRM
                eDeP17lFbOMXkSdnHp3ly/ppfUJdnias1+vGs6V7HXd1irK+UjSTL6d0Eu64rwQK
                e9JY9hlaB9cdjFn4qqo1vDjQXfzIVOa8Xdatv1KXUqv45R3PhdZ3T3UsxXqbfHob
                mvR//ycrGZPzHeyqXYfzx1fXXmfrjqjePyzWoCu4HAAZWk+arG5DYEb6kmawK/kC
                lbI3nyNXQuUaZr/SxOROdtUH5aXdbhEOQf9voMvsiyhSUp5wCDg/CaSKwB48NWPx
                gliB9uuJqGWyub7fMj5OxRZVYlA3QqP7V2PvODE4jITJdOhemnrrdK/mlmIPwSJq
                8asL5rfwxyUs58FT2sDd6Qecw6Y5gK+ULgRjMSEwHwYJKoZIhvcNAQkVMRIEEAYu
                Zb4L5MZJKP6FifnzQFEwggV7BgkqhkiG9w0BBwagggVsMIIFaAIBADCCBWEGCSqG
                SIb3DQEHATAcBgoqhkiG9w0BDAEDMA4ECNOnUDg66SeRAgIIAKCCBTQEggUwTP5i
                TS5Uc2nSBvtWP+lNr5Y3PSjvn5or5KQglE0apYhscPQDSCdsTRua5uH6vYT5WcFd
                IvboQxlTZRXB0wOfLsAPWRiVB/Ex9IQkf01jQT4Zm4/0fHcAwDW0VlWqe6hTmjIL
                ssZKotCGOdJenqCiyqZSzUcfdAGTvKHOKo4fPoHFFiSDQwu0dcX7EKjM25kjXavG
                GztAYuxhA1WEYERJgz6R2Ex5QqSpvmLaFFQxrXDl7PZCS8eAdJvmWIZ+1yVudMP+
                KGTVED2LOeLoCJkFEESYDk2gHLv3ZVUvqjB/EshBj96UtpAEL+RvMXO8iuzWjIYD
                JVokM705iS53W+8Fe/Eq6K7yH3UgE1lCjrrrxuq5aNQ86mgCjXXFi7b8z6g/0Cbs
                f+e8kka7lRO+Tda/Iy3gKjnlvySsRGCw/1kOXuA+uFUjXWsA8zVcaKzeot43RoiB
                utelt+I8ypktPx2UrULYhPOLt7SJJJ2nngStVWFCmxMVEDrCbvygorePV9XkgTTQ
                z8TOpjJvEx/ZR7a5v+11l0KVzykLdU0t47yI3ruioMO64Eu2r+j7toJQv7Uld0Ok
                9vzxgjQk+Me+Fv+Bc9BgvXFGGdYcnAL8X60Au5kowHTeX0QdZp39hpNPHIQZHfxG
                A4ViZCq5hzCzAPP1kHzJLxus4zlKYON1zNZoTwg2YvySIGlZ6deMdREK7xjpCU6C
                aDajhmjEKfdOf1kNyfmjZxjgnY2uRhaEr3zsfaSP+yitrpIfHDSNP0vjanFj7MZX
                l0q6F3LPiYV62KBs95i0cBi3UVMfP67QRqeCv6pMCJxAwB0uUqzOQWXXfGVlInQL
                19Bi6Cd+aQT9DVZuR3v3mRPikx00v96RDQfaqvqxrXHs2AV/xs85kFUy0uL2VbjQ
                774OFLn9WbILgb2e7Mgd0AvIt9MBzbTjn04IWoLe85mi99K6xJFa+VAFvdxrdIcl
                DHN2UY+RdDMNddC/1oPdSM+XtnQxTG+VeI9g3du6RWjsLjaZzKuiDeQo5HjB0kSk
                6Di6PT0aXrIILlCf0abYJm6+8i7O7BGi25AbNE85j/kfoX+8vUo7Dp/mKb7gLhMY
                9HzJW/qrekzHagIqm/r1VreOQq3znciPD6Bfa+xQ4llbrCuY+OCNWWuVm+WuA6DU
                NuYy9zNJE0FYe1LQ4PUOiRX/EQHAPms3K2QeyzJ4rI9dXq1wTL1O5JJDAA2ZoBO3
                f9apY2e0JJE4RQRPcXBhC0D8ZysS2lMVCTL27DcwEFb8hMJvYTCRLhGu7xvp0Ct6
                w7EUyAQ8V6ZYG4IO9BE7u8M5niOcn0Wj2Dfo/VdSwxSAqCHRK5wYS/X/pJgux25M
                pu0e0mEChzoIxmBdN8WYLPq0SPrNTst/ljhy2RxS279BrPMgbZU/9hP072oqzzxF
                W1tgd/u8fdYKorfsxrtsxgrKJmmW8y7EcrmRj2b58fdEfQ5im76eDBRIaApyqAuT
                ta34S0A8aOwoNse4hKRYE6o6M6lhLwA1LTVTVR32hJSdiQoI6FgWFNq/eHfNfHJT
                CUIQvzSir0F7W3V27rK+qL/A54xTnXEhaXVXVuVrv2HV2ssD71++KvA0QMXvKdHm
                ELLAODHV207YgyCB1bJ3dy09Zc12QJbIoRK43bp0qMxhSPvtLxAiWWIoLuadW049
                8djnm0LcQL2lmVNV0niX6FAy2Ke4AcdMZyfFW7FOlAsx0YFh0AvcnG6or7yDeTVF
                VRjILhp+w87nLH1piXPyvcgmpg8PhUBsMfIsafswMTAhMAkGBSsOAwIaBQAEFMTL
                2+V/OTEk5UPr3hk4UchA399mBAiMGAxbKnlamQICCAA=
                -----END PKCS12-----"
            ]

Listing Requests

The list of requests can be retrieved with a simple GET.

Endpoint:
/api/v1/requests/
Method:
GET

The result can be filtered with these parameters:

Field
given_name
surname_1
surname_2
email
serial_number
scratchcard
profile
status
Response

The response is a JSON object with the list of Requests found.

Note that this endpoint take advantage of the mechanism of pagination

Example

In this example, we get the list of requests with the status ISSUED.


            curl -X GET https://api.uanataca.com/api/v1/requests/?status=ISSUED
            

            {
                "count": 408,
                "next": "https://api.uanataca.com/api/v1/requests/?page=2&status=ISSUED",
                "previous": null,
                "results": [...]
            }

Get info about a Request

This endpoint returns the information registered about a Request.

Endpoint:
/api/v1/requests/{id}/
Method:
GET
Path Parameters:
Parameter Description
id The unique identifier of the Request
Response

The response is a JSON object with all the information found.

Example

            {
                "pk": 123,
                "given_name": "given_name_1",
                "surname_1": "surname_1_1",
                "surname_2": "",
                "sex": "F",
                "id_document_type": null,
                "id_document_country": null,
                "serial_number": "serial_number",
                "country_name": "ES",
                "citizenship": "ES",
                "residence": "ES",
                "organization_email": null,
                "email": "dci@bit4id.com",
                "title": "title",
                "organization_name": "organization_name",
                "organizational_unit_1": "",
                "organizational_unit_2": null,
                "organization_identifier": null,
                "responsible_name": "responsible_name",
                "responsible_first_surname": "responsible_first_surname",
                "responsible_second_surname": "",
                "responsible_email": null,
                "responsible_serial": "responsible_serial",
                "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": "PFqscdAF",
                    "status": 0,
                    "valid_from": "2017-05-21T16:16:00Z",
                    "valid_to": "2018-05-21T16:16:00Z",
                    "valid": "EXPIRED",
                    "revokation_reason": null,
                    "serial_number": "4ac1ad258802b782",
                    "subject": "2.5.4.97=VATES-organization_tax_number, CN=given_name_1 surname_1_1 / organization_tax_number, 2.5.4.5=IDCES-serial_number, 2.5.4.42=given_name_1, 2.5.4.4=surname_1_1, 2.5.4.12=title, O=organization_name, C=ES",
                    "data": "MIIIUjCCBj...",
                    "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 DEVEL 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona (see current address at www.uanataca.com/address), C=ES"
                    }
                ],
                "profile": "PFqscdEmpresa",
                "scratchcard": "7000071",
                "status": "ISSUED",
                "registering_user": {
                    "pk": 1,
                    "permission_profile": 1,
                    "registration_authority": 1,
                    "request": 1
                },
                "approving_user": {
                    "pk": 1,
                    "permission_profile": 1,
                    "registration_authority": 1,
                    "request": 1
                },
                "producing_user": {
                    "pk": 1,
                    "permission_profile": 1,
                    "registration_authority": 1,
                    "request": 1
                },
                "registration_authority": 1,
                "secure_element": 1,
                "validity_time": "365",
                "smartcard_sn": "7420000300008275",
                "citizen_tax_number": "citizen_tax_number",
                "birth_date": "01/01/1980",
                "birth_country": "ES",
                "birth_city": "",
                "birth_province": "",
                "birth_state": "",
                "birth_district": "",
                "birth_canton": "",
                "id_document_description": "",
                "id_document_issuer": "",
                "organization_rol": "",
                "professional_id_number": null,
                "mobile_phone_number": "+39369258147",
                "fix_phone_number": "",
                "residence_address": "",
                "residence_city": "",
                "residence_province": "",
                "residence_postal_code": "",
                "residence_state": "",
                "residence_district": "",
                "residence_canton": "",
                "organization_tax_number": "organization_tax_number",
                "organization_address": "",
                "organization_city": "",
                "organization_province": "",
                "organization_country": "",
                "organization_postal_code": "",
                "organization_state": "",
                "organization_url": "",
                "responsible_legal_level": null,
                "subscriber": null,
                "responsible_legal_documents": null,
                "special_conditions": null,
                "responsible_registry_data": null,
                "approving_rao": {
                    "pk": 1,
                    "given_name": "User",
                    "surname_1": "Admin",
                    "surname_2": "",
                    "certificate": {
                        "profile": "PERSONA_FISICA_SOFT",
                        "status": 0,
                        "valid_from": "2017-01-24T11:00:31Z",
                        "valid_to": "2020-01-24T11:00:31Z",
                        "valid": "VALID",
                        "revokation_reason": null,
                        "serial_number": "3ef3696d2939241d",
                        "subject": "2.5.4.97=VATES-organization_tax_number, CN=given_name_1 surname_1_1 / organization_tax_number, 2.5.4.5=IDCES-serial_number, 2.5.4.42=given_name_1, 2.5.4.4=surname_1_1, 2.5.4.12=title, O=organization_name, C=ES",
                        "data": "MIIIUjCCBj...",
                        "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 DEVEL 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona (see current address at www.uanataca.com/address), C=ES"
                    },
                    "id_document_number": "5241651",
                    "id_document_description": "Patente",
                    "id_document_issuer": "Motorizzazione Civile",
                    "registration_authority": [
                    1,
                    2
                    ],
                    "registration_authority_master": 1
                },
                "producing_rao": {
                    "pk": 1,
                    "given_name": "User",
                    "surname_1": "Admin",
                    "surname_2": "",
                    "certificate": {
                        "profile": "PERSONA_FISICA_SOFT",
                        "status": 0,
                        "valid_from": "2017-01-24T11:00:31Z",
                        "valid_to": "2020-01-24T11:00:31Z",
                        "valid": "VALID",
                        "revokation_reason": null,
                        "serial_number": "3ef3696d2939241d",
                        "subject": "2.5.4.97=VATES-organization_tax_number, CN=given_name_1 surname_1_1 / organization_tax_number, 2.5.4.5=IDCES-serial_number, 2.5.4.42=given_name_1, 2.5.4.4=surname_1_1, 2.5.4.12=title, O=organization_name, C=ES",
                        "data": "MIIIUjCCBj...",
                        "issuer": "2.5.4.97=VATES-A66721499, CN=UANATACA CA1 DEVEL 2016, OU=AC-UANATACA, O=UANATACA S.A., L=Barcelona (see current address at www.uanataca.com/address), C=ES"
                    },
                    "id_document_number": "5241651",
                    "id_document_description": "Patente",
                    "id_document_issuer": "Motorizzazione Civile",
                    "registration_authority": [
                    1,
                    2
                    ],
                    "registration_authority_master": 1
                },
                "id_document_number": null,
                "id_responsible_document_type": null,
                "id_responsible_document_country": null,
                "id_responsible_document_number": null,
                "organizational_unit_3": null
            }

            curl -X GET https://api.uanataca.com/api/v1/requests/{id}/
            

Cancel a Request

Change the Request status to CANCELED.

Endpoint:
/api/v1/requests/{id}/cancel/
Method:
DELETE
Path Parameters:
Parameter Description
id The unique identifier of the Request
Response

If the Request is successfully canceled, the response status code is 200 and the with the response body reads:


            {
                "status": "Request cancelled"
            }
            

If the Request was already canceled, it will respond with status code 412 Precondition Failed instead:


                {
                    "code": "412",
                    "id": "a81b3fac3a7a431e",
                    "error": "Invalid request status"
                }
            
Example

            curl -X DELETE https://api.uanataca.com/api/v1/requests/1234/cancel/
            

Update a Request

Endpoint:
/api/v1/requests/{id}/
Method:
PUT
Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:

The body parameters changes according to the profile used.

Response

The successful response is a JSON with the info updated. The succes status code is 200.

Example

            {
                "given_name": "R2",
                "surname_1": "D2",
                "scratchcard": "100000146",
                "country_name": "ES",
                "email": "asi@bit4id.com",
                "registration_authority": 41
            }

            curl -H "Content-Type: application/json" -d @params.json -X PUT https://api.uanataca.com/api/v1/requests/1234/
            

            {
                "pk": 789,
                "given_name": "R2",
                "surname_1": "D2",
                "surname_2": "",
                "sex": null,
                "id_document_type": "IDC",
                "id_document_country": "ES",
                "serial_number": "12321321",
                "country_name": "ES",
                "citizenship": null,
                "residence": "ES",
                "organization_email": null,
                "email": "email@example.com",
                "title": null,
                "organization_name": null,
                "organizational_unit_1": null,
                "organizational_unit_2": null,
                "organization_identifier": null,
                "responsible_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": "100000146",
                "status": "CREATED",
                "registering_user": {
                    "pk": 1,
                    "permission_profile": 1,
                    "registration_authority": 1,
                    "request": 1
                },
                "approving_user": null,
                "producing_user": null,
                "registration_authority": 41,
                "secure_element": 2,
                "validity_time": "730",
                "smartcard_sn": "",
                "citizen_tax_number": "",
                "birth_date": null,
                "birth_country": null,
                "birth_city": "",
                "birth_province": "",
                "birth_state": "",
                "birth_district": "",
                "birth_canton": "",
                "id_document_description": "",
                "id_document_issuer": "",
                "organization_rol": null,
                "professional_id_number": null,
                "mobile_phone_number": "393389827525",
                "fix_phone_number": "",
                "residence_address": "",
                "residence_city": "",
                "residence_province": "",
                "residence_postal_code": "",
                "residence_state": "",
                "residence_district": "",
                "residence_canton": "",
                "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": "",
                "id_responsible_document_type": null,
                "id_responsible_document_country": null,
                "id_responsible_document_number": null,
                "organizational_unit_3": null
            }

Get the Request documents

The endpoint allows to retrieve the documents associated to the specified Request.

Endpoint:
/api/v1/requests/{id}/generate_document/
Method:
POST
Path Parameters:
Parameter Description
id The unique identifier of the Request
Body Parameters:
Parameter Description
doctype It represents the type of doc to retrieve. It can assume the values of: "acceptance", "contract" and "credentials". The acceptance is the receipt, the contract the Uanataca contract signed and credentials is the document where are written the scartchcards credentials generated during the creation phase (scratchcard serial and the erc).
lang The document language. The available languages are "es" and "en" (the default is en)
Response

The successful response is the actual document requested.

Example

This example retrieve the contract of the specified request.


            {
                "doctype": "contract",
                "lang": "en"
            }

            curl -H "Content-Type: application/json" -d @params.json -X POST https://api.uanataca.com/api/v1/requests/787/generate_document/
            

            {
                "document": "%PDF-1.4\n%\ufffd\ufffd\ufffd\ufffd Generated PDF document 0 obj\n<<\n/F1 2 0 R\n..."
            }

Validate Requests

This endpoint allows the validation of Request fields according to its profile.

Endpoint:
/api/v1/requests/{id}/validate/
Method:
GET
Path Parameters:
Parameter Description
id The unique identifier of the Request
Response

In case the query is successful, the server returns a list of fields required and missing (an empty list if all the required fields are setted).

Example

This example show the response of this endpoint that validates a Request with profile PFnubeAFCiudadano and with two required fields missing.


            curl -X GET https://api.uanataca.com/api/v1/requests/790/validate/
            

            [
                [
                    "serial_number",
                    "missing"
                ],
                [
                    "mobile_phone_number",
                    "missing"
                ]
            ]

Get Pre-authenticated link for the Request

This endpoint returns the pre-authenticated link that can be used to issue a new certificate for a request that is in the ENROLLREADY status. Note that the link has a validity of 24 hours so, if it is too old, you may need to generate a new one with a POST request to the same endpoint.

Endpoint:
/api/v1/requests/{id}/preauthlink/
Method:
GET
Path Parameters:
Parameter Description
id The unique identifier of the Request
Response

In case the query is successful, the server returns a text field containing the pre-authenticated link.

Example

The response returns the link as the value of the preauthenticatedlink field.


            curl -X GET https://api.uanataca.com/api/v1/requests/790/preauthlink/
            

            {
                "preauthenticatedlink" : "link-as-string"
            }

If the request is already approved or not ready (if its status is not ENROLLREADY) a 412 error wil be returned instead.


            {
                "code": "412",
                "id": "f9a97e20d43a034b",
                "error": "Invalid request status"
            }

Get Pre-authenticated link for the Request

This endpoint creates a new pre-authenticated link that can be used to issue a new certificate for a request that is in the ENROLLREADY status.

Endpoint:
/api/v1/requests/{id}/preauthlink/
Method:
POST
Path Parameters:
Parameter Description
id The unique identifier of the Request
Response

In case the query is successful, the server returns a text field containing the pre-authenticated link.

Example

The response returns the link as the value of the preauthenticatedlink field.


            curl -X POST https://api.uanataca.com/api/v1/requests/790/preauthlink/
            

            {
                "preauthenticatedlink" : "link-as-string"
            }

If the request is already approved or not ready (if its status is not ENROLLREADY) a 412 error wil be returned instead.


            {
                "code": "412",
                "id": "f9a97e20d43a034b",
                "error": "Invalid request status"
            }