INE nominal list async service

In Tu identidad we will have, as part of our service proposal, a new form of integration with an asynchronous processing flow.

This is an integration mechanism where the verification response is not delivered in the same request but in a subsequent message immediately after it is made available. So it is understood that for every verification request there will be a processing response even when the verification process fails.

This new integration flow will allow Tu identidad to have a better management of latency and intermittency caused by official sources of information, which will lead to greater scaling and performance of the service.

As part of the integration process, a service configuration step will be necessary, where Tu identidad will record the URL and connection data with security for the delivery of the verification result.

One of the first services to have this mechanism will be the verification of the registration of the official identification before the nominal list of the INE.

Web service description

Create verification request

This method performs the creation of verification of the INE document and get the id to track it.

Verification retries policies

The service incorporates a retry policy that allows the request to be sent again when the source site is under maintenance or a processing error has occurred, two verification retries will be performed; the first retry will be 20 minutes after the request is processed and the second, if necessary, will be 40 minutes later.

~/api/IneNominalList/validateIneNominalListAsync

Request Parameters

Tag Type Required Description
type string yes Type C, D, E, F, G, or H.
id string yes The method receive CIC for types D, E, F, G and H. The method receive the elector code for type C.
ocr string yes The method receive OCR for type C. The method receive and citizen identifier for type types E, F, G and H.
issueNumber string Only in type C It can be sent null or empty when type is different to C.

Headers

Tag Type Required Description
apikey string yes Customer key.
Content-Type string No application/json.

FormBody

{
  "type": "string", // One of C|D|E|F|G|H
  "id": "string", // CIC or Elector code
  "ocr": "string", // OCR
  "issueNumber": "string" // Only for type C, it can be null of empty for other types.
}

Examples

Type C ID Model C

{
  "type": "C",
  "id": "TSVREL72100209M100",
  "ocr": "3854006556540",
  "issueNumber": "03"
}

Type D ID Model D

{
  "type": "D",
  "id": "115568150",
  "ocr": "4855115346145",
  "issueNumber": ""
}

Type E ID Model EG

{
  "type": "E",
  "id": "145591720",
  "ocr": "0535000172485",
  "issueNumber": ""
}

Type G

{
  "type": "G",
  "id": "204978519",
  "ocr": "092333274",
  "issueNumber": ""
}

Response:

The service responds an id to track the verification.

Success

Name Type Description
verificationId int Id of the transaction.

Error structure

Name Type Description
code string Error code.
message string Error message.

JSON

{
  "verificationId": 0 // Id of the transaction
}

Error model

{
  "error": "string", // Error code
  "message": "string" // Error message
}

Get verification request status

This method allows to get the status of verification of the INE document.

~/api/IneNominalList/validateIneNominalListAsync

Request Parameters

Query

Tag Type Required Description
verificationId int Yes Id of the verification to track.

Headers

Tag Type Required Description
apikey string Yes Customer key.
Content-Type string No application/json.

Response:

The service responds with the status, general data of the verification and some details from it.

Success

Name Type Description
verificationId int Id of the transaction.
verificationType int Type of verification. 0.- Sync, 1.- Async.
verificationStatus int Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
verification
valid true If the document is valid or not as official identification.
canVote true If the document can be used to vote or not.
verification data
type string Document type.
electorCode string Elector code.
cicNumber string CIC number.
issueNumber string Issue number.
issueYear string Issue year.
registrationYear string Registration year.
ocrNumber string OCR.
expDate string Effective date.
warnings
code string Error code.
message string Error message.

Error structure

Name Type Description
code string Error code.
message string Error message.

JSON

{
  "verificationId": 0, 
  "verificationType": 0, // Type of verification. 0.- Sync, 1.- Async.
  "verificationStatus": 0, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": {
    "valid": true, // Valid as identification
    "canVote": true, // Can vote
    "data": {
        "type": "string", // Document type
        "electorCode": "string", // Elector code
        "cicNumber": "string", // CIC number
        "issueNumber": "string", // issue number
        "issueYear": "string", // Issue year
        "registrationYear": "string", // Registration year
        "ocrNumber": "string", // OCR
        "expDate": "string" // Effective date
    }
  },
  "warnings": [ // List of warning messages
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Error model

{
  "error": "string", // Error code
  "message": "string" // Error message
}

Verification result

When the verification process ends a message is sent with the result of the verification to the url and with the credentials specified in the integration configuration of the service.

Delivery retries policies

The service incorporates a retry policy that allows the information related to the requested verification to be sent again, a maximum of 5 communication attempts will be made; the first retry will be 15 minutes after the verification and will be consistent until a favorable response is obtained or 5 attempts are reached.

~/

Request Parameters

Name Type Description
verificationId int Id of the transaction.
verificationType int Type of verification. 0.- Sync, 1.- Async.
verificationStatus int Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
verification
valid true If the document is valid or not as official identification.
canVote true If the document can be used to vote or not.
verification data
type string Document type.
electorCode string Elector code.
cicNumber string CIC number.
issueNumber string Issue number.
issueYear string Issue year.
registrationYear string Registration year.
ocrNumber string OCR.
expDate string Effective date.
warnings
code string Error code.
message string Error message.

Headers

Tag Type Required Description
apikey string Yes Customer key.
Content-Type string No application/json.

FormBody

{
  "verificationId": 0, 
  "verificationType": 0, // Type of verification. 0.- Sync, 1.- Async.
  "verificationStatus": 0, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": {
    "valid": true, // Valid as identification
    "canVote": true, // Can vote
    "data": {
        "type": "string", // Document type
        "electorCode": "string", // Elector code
        "cicNumber": "string", // CIC number
        "issueNumber": "string", // issue number
        "issueYear": "string", // Issue year
        "registrationYear": "string", // Registration year
        "ocrNumber": "string", // OCR
        "expDate": "string" // Effective date
    }
  },
  "warnings": [ // List of warning messages
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Response:

The service must response with status code 200 and confirm that the data was receipt.

Success

Name Type Description
completed bool Confirmation that the data was receipt.

Error structure

Name Type Description
code string Error code.
message string Error message.

JSON

{
  "completed": true
}

Error model

{
  "error": "string", // Error code
  "message": "string" // Error message
}

Service messages

Code Message Description
INENL001 Unable to validate data with source. Message shown when the INE servers cannot be consulted.
INENL002 Something was wrong, we are working on the failure. Message displayed when there is an error on the server.
INENL003 Access Denied. ApiKey header not found. Message to be displayed when the user enters an incorrect apikey or when the apikey is not displayed.
INENL004 Invalid issue number format. Message that is displayed when the "issueNumber" field is not numeric and has a length other than 2 characters.
INENL005 Invalid Id format. Message that is displayed when the "Id" field is not numeric and has a length other than 9 or 18.
INENL006 Invalid OCR format. Message that is displayed when the "ocr" field is not numeric and has a length other than 9 or 13.
INENL007 Invalid type. Message displayed when the "type" field does not have a value of "C", "D", "E", "F", "G" or "H".
INENL015 Access denied the company could not be identified. Message displayed when the verification id does not belong to the company.
INENL016 The register could not be found. Message displayed when the verification id is not valid.