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
{
"type": "C",
"id": "TSVREL72100209M100",
"ocr": "3854006556540",
"issueNumber": "03"
}
Type D
{
"type": "D",
"id": "115568150",
"ocr": "4855115346145",
"issueNumber": ""
}
Type E
{
"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. |