Scratchcards

Handle Scratchcards

Allowed HTTP verbs by this endpoint:

Verb Endpoint Action
POST /scratchcards/ Create a new scratchcard
GET /scratchcards/ Get the list of scratchcards
GET /scratchcard/{id}/ Retrieve info about a scratchcard
POST /scratchcards/isused/ Get the state of a known scratchcard
PUT /scratchcards/{id}/ Update a Scratchcard
GET /scratchcards/get_first_unused/ Get the first unused scratchcard
POST /scratchcards/whoami/ Get the Request associated to the scratchcard
POST /scratchcards/revoke/ Revoke certificates associated to the request that use the specified scratchcard
POST /scratchcards/move/ Move scratchcard from an ra to another one

Create a Scratchcard

Endpoint:
/api/v1/scratchcards/
Method:
POST
Body Parameters:
Parameter Description Required
registration_authority The registration authority id Yes
sn The scratchcard serial number Yes
secrets The secrets that will be associated to the scratchcard Yes

The sn is the serial number that the scratchcard will have. This must be a unique number all over Uanataca.

The secrets parameter is a string with an escaped JSON containing these fields:

Field Description
erc It is a security code used for recovery or revocation purpose
enrollment_code This is the security code. It is requested for different operations (like the certificate enrollment).
pin It is the default pin assigned to the scratchcard. This will be changed in the enrollment phase.
puk This is the default puk assigned to the scratchcard. This will be changed in the enrollment phase.
Response

The success response code is 201 and the response body is the complete JSON that describe the scratchcard.

Example

            {
                "sn": "110000150",
                "registration_authority": 41,
                "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"44024058\"}"
            }

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

            {
                "pk": 1245,
                "sn": "110000150",
                "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"44024058\"}",
                "registration_authority": 41
            }

List scratchcards

Endpoint:
/api/v1/scratchcards/
Method:
GET

It is possibile to filter the result of the search with the query parameters:

Parameter Description
registration_authority List all the scratchcards that belongs to a registration authority
Response

The success status code is 200 and the response body is the complete list of all the scratchcards found.

Example

Listing the scratchcards of the registration authority with the unique id 41.


            curl -X GET https://api.uanataca.com/api/v1/scratchcards/?registration_authority=41
            

            {
                "count": 3,
                "next": null,
                "previous": null,
                "results": [
                    {
                        "pk": 1245,
                        "sn": "110000150",
                        "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"25936657\"}",
                        "registration_authority": 41
                    },
                    {
                        "pk": 1193,
                        "sn": "100000147",
                        "secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
                        "registration_authority": 41
                    },
                    {
                        "pk": 1192,
                        "sn": "100000146",
                        "secrets": "{\"erc\": \"8117606937\", \"enrollment_code\": \",8cj6Ax2\", \"pin\": \"85376977\", \"puk\": \"86175206\"}",
                        "registration_authority": 41
                    }
                ]
            }

Retrieve a scratchcard

Get the scratchcard details.

Endpoint:
/api/v1/scratchcard/{id}/
Method:
GET
Path parameters:
Parameter Description
id The scratchcard unique id
Response

The success response status code is 200 as body the JSON with the details of the scratchcard found.

Example

Getting the details of the scratchcard #1193


            curl -X GET https://api.uanataca.com/api/v1/scratchards/1193/
            

            {
                "pk": 1193,
                "sn": "100000147",
                "secrets": "{\"erc\": \"6292998123\", \"enrollment_code\": \"_,463vt:\", \"pin\": \"08695572\", \"puk\": \"52351291\"}",
                "registration_authority": 41
            }

Check if a scratchcard is used

Get the status of a known scratchcard.

Endpoint:
/api/v1/scratchcard/{id}/
Method:
POST
Path parameters:
Parameter Description
id The scratchcard unique id
Body parameters:
Parameter Description Required
sn The scratchcard serial number Yes
Response

The response status code is 200 and the body containts a boolean value (true/false).

Example

Checking if the scratchcard with serial 110000150 is used by a Request.


            {
                "sn": "110000150"
            }

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

            false
            

Update a scratchcard

Update the scratchcard details.

Endpoint:
/api/v1/scratchcard/{id}/
Method:
PUT
Path parameters:
Parameter Description
id The scratchcard unique id
Body parameters:
Parameter Description Required
registration_authority The registration authority id Yes
sn The scratchcard serial number Yes
secrets The secrets that will be associated to the scratchcard Yes
Response

The successful response body is the details of the scratchcard updated, and the response status code is 200.

Example

Showing the update of the scratchcard with serial 110000150.


            {
                "sn": "110000150",
                "registration_authority": 41,
                "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"25936657\"}"
            }

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

            {
                "pk": 1245,
                "sn": "110000150",
                "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"25936657\"}",
                "registration_authority": 41
            }

Get the first unused

Get the first scratchcard associated to a RA, that has not been used yet.

Endpoint:
/api/v1/scratchcards/get_first_unused/
Method:
GET
Body parameters:
Parameter Description Required
ra The RA id from which getting the first unused scratchcard No
Response

The success response body is a JSON with the info about the scratchcard and the status code is 200.

Example

            curl -X GET https://api.uanataca.com/api/v1/scratchcards/get_first_unused/
            

            {
                "pk": 1245,
                "sn": "110000150",
                "secrets": "{\"erc\": \"8207878566\", \"enrollment_code\": \"97Q6B,6W\", \"pin\": \"25936657\", \"puk\": \"25936657\"}",
                "registration_authority": 41
            }

Whoami

Starting from a serial is possible to get the Request that use that scratchcard.

Endpoint:
/api/v1/scratchcards/whoami/
Method:
POST
Body parameters:
Parameter Description Required
scratchcard The scratchcard serial number Yes
erc The scratchcard enrollment code Yes
Response

The successful response status code is 200 and the response body contains the complete details of the Request.

Example

Getting the info about the Request that use the scratchcard with the serial 110000150.


            {
                "scratchcard": "110000150",
                "erc": "97Q6B,6W"
            }

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

            {
                "pk": 788,
                "given_name": "R2",
                "surname_1": "D2",
                "surname_2": "",
                "sex": null,
                "id_document_type": "IDC",
                "id_document_country": "ES",
                "serial_number": "12321",
                "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": "110000150",
                "status": "ENROLLREADY",
                "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": 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": {
                    "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": "CN=User Admin, 2.5.4.5=u12345678, 2.5.4.42=User, 2.5.4.4=Admin, O=no presente, C=IT",
                        "data": "MIIIEDCCBfigAwIBAgIIPvNpbSk5JB0wDQYJKoZIhvcNAQELBQ...",
                        "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": null,
                "id_document_number": "",
                "id_responsible_document_type": null,
                "id_responsible_document_country": null,
                "id_responsible_document_number": null,
                "organizational_unit_3": null
            }

Revoke scratchcard

This endpoint aims at revoking all certificates associated to the holder of a specific scratchcard.

This can be used in an emergency situation, like the compromission of a scratchcard secrets.

Endpoint:
/api/v1/scratchcards/revoke/
Method:
POST
Body parameters:
Parameter Description Required
scratchcard The scratchcard serial number Yes
erc The scratchcard security code Yes
reason The revocation reason Yes

The reason can be one of the following:

  • NOT_REVOKED
  • UNSPECIFIED
  • KEYCOMPROMISE
  • CACOMPROMISE
  • AFFILIATIONCHANGED
  • SUPERSEDED
  • CESSATIONOFOPERATION
  • CERTIFICATEHOLD
  • REMOVEFROMCRL
  • PRIVILEGESWITHDRAWN
  • AACOMPROMISE
Response

The successful response status code is 200 and the response body contains a list of certificates revoked.

Example

Revoking the certificates associated to the scratchcard 2000265 with reason "UNSPECIFIED".


            {
                "scratchcard": "2000265",
                "erc": "9219995130",
                "reason": "UNSPECIFIED"
            }

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

            [
                {
                    "data": "MIIH2zCCBcOgAwIBAgIIC3a...",
                    "profile": "PFnubeAF",
                    "subject": "CN=Alessandrp adsnio, 2.5.4.5=IDCIT-TSTAPI74S23C129Y, 2.5.4.42=Alessandrp, 2.5.4.4=adsnio, C=ES",
                    "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",
                    "valid_from": "2019-01-22T16:42:00Z",
                    "valid_to": "2019-01-23T16:42:00Z",
                    "serial_number": "0b7687af3c8a833f",
                    "status": 2,
                    "pk": 761,
                    "revokation_reason": 1,
                    "type": "FIRSTISSUE"
                }
            ]

Move scratchcard

Move unused scratchcards from a registration authority to another.

Endpoint:
/api/v1/scratchcards/move/
Method:
POST
Body parameters:
Parameter Description Required
from_ra The source RA that will give the scratchcards. Yes
to_ra The destination RA that will recevive the scratchcards. Yes
amount The amount of scratchcards to move Yes
from_sn The starting serial No
to_sn The ending serial No

Note that if you don't have access to an RA, you can't move scratchcards from/to that RA.

Response

The response is the amount of scratchcards actually transferred.

Example

Let's move 2 scratchcards from the RA with id 39 to the one with id 41.


            {
                "from_ra": 39,
                "to_ra": 41,
                "amount": 2
            }

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

            {
                "moved": 2
            }