Async Verification 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.

In this process it is necessary to have a client-side webhook that receives notifications when the asynchronous process ends.
Link to webhook: https://docs.tuidentidad.com/async-verification-service/#verification-result-webhook

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.

The services to have this mechanism will be: - The verification of the registration of the official identification before the nominal list of the INE. - The verification of the RFC by CURP. - The verification of the NSS by CURP.

Verification retries policies

The services 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.

Delivering retries policy

The service executes 3 attempts to deliver the message on the client's webhook, if the webhook does not receive the message the status will remain as 3 = delivering, because it was never received.

Web service description

Create verification request for INE Nominal List

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

~/api/AsyncVerication/IneNominalList

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": ""
}

Create verification request for RFC by CURP

This method performs the creation of exchange of a CURP for the RFC and get the id to track it.

~/api/AsyncVerication/RfcByCurp

Request Parameters

Tag Type Required Description
curp string yes Clave Única de Registro de Población.
state int yes Id for the registration state of the RFC
State Catalog
Id State
1 Aguascalientes
2 Baja California
3 Baja California Sur
4 Campeche
5 Coahuila
6 Colima
7 Chiapas
8 Chihuahua
9 Ciudad de México
10 Durango
11 Guanajuato
12 Guerrero
13 Hidalgo
14 Jalisco
15 Estado de México
16 Michoacán
17 Morelos
18 Nayarit
19 Nuevo León
20 Oaxaca
21 Puebla
22 Querétaro
23 Quintana Roo
24 San Luis Potosí
25 Sinaloa
26 Sonora
27 Tabasco
28 Tamaulipas
29 Tlaxcala
30 Veracruz
31 Yucatán
32 Zacatecas

Headers

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

FormBody

{
  "curp": "string",
  "state": "int"
}

Example

{
  "curp": "XAXA010101XXXXXX01",
  "state": 01
}

Create verification request for NSS by CURP

This method performs the creation of exchange of a CURP for the NSS and get the id to track it.

~/api/AsyncVerication/NssByCurp

Request Parameters

Tag Type Required Description
curp string yes Clave Única de Registro de Población.

Headers

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

FormBody

{
  "curp": "string"
}

Example

{
  "curp": "XAXA010101XXXXXX01"
}

Response:

The services responds an id to track the verification.

Success

Name Type Description
verificationId string Id of the transaction.

Error structure

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

JSON

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

Error model

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

Get verification request status

This method allows to get the status of verification of the requested data.

~/api/AsyncVerication/verificationStatus

Request Parameters

Query

Tag Type Required Description
verificationId string 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 string Id of the transaction.
verificationType int Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
verificationStatus int Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
verification string Verification Data for each type in JSON format encoded as a string.
warnings
code string Error code.
message string Error message.
Ine Nominal List Data
Name Type Description
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.
RFC by CURP Data
Name Type Description
rfc string RFC related with the given CURP.
NSS by CURP Data
Name Type Description
nss string NSS related with the given CURP.

Error structure

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

JSON

Type INE Nominal List
{
  "verificationId": "", 
  "verificationType": 1, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // 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"
    }
  ]
}
Type RFC by CURP
{
  "verificationId": "", 
  "verificationType": 2, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": "{
    \"rfc\": \"string\"
  }",
  "warnings": [ // List of warning messages
    {
      "code": "string",
      "message": "string"
    }
  ]
}
Type NSS by CURP
{
  "verificationId": "", 
  "verificationType": 3, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": "{
    \"nss\": \"string\"
  }",
  "warnings": [ // List of warning messages
    {
      "code": "string",
      "message": "string"
    }
  ]
}

Error model

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

Verification result - Webhook

It is necessary to have a webhook developed and installed by the client.

The client must share to Tu Identidad the webhook URL and its authentication method so that Tu Identidad can communicate with the webhook.

The process is shown in the following image.

The POST API is executed, will generate a verification ID that allows the result to be verified later, at the same time it will execute the corresponding process to obtain the desired information, later once the information is obtained, it will be sent to the client's webhook and Tu Identidad will remain waiting for confirmation that the client did receive said information, once the client notifies with a status of 200, for more information access to this link Response webhook.

The service of Tu Identidad will change the verificationStatus to 4 and the information can be consulted from the GET API.

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

diagram

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 string Id of the transaction.
verificationType int Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
verificationStatus int Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
verification string Ine Nominal List Verification Data in JSON format encoded as a string.
warnings
code string Error code.
message string Error message.
Ine Nominal List Data
Name Type Description
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.
RFC by CURP Data
Name Type Description
rfc string RFC related with the given CURP.
NSS by CURP Data
Name Type Description
nss string NSS related with the given CURP.

Headers

Tag Type Required Description
authorization string No Authorization method
Content-Type string No application/json.
Authorization methods

As part of this solution Tu Identidad implement two authorization methods to make requests secure. These methods are the follow:

Authorization basic For this authorization method we need our customer provide us an user and password. We take this parameters, encode this as base64 string and send it in each request as a header.

Tag Type Required Example
authorization string No Basic

Example: User: user Password: password String: user:password String encoded: dXNlcjpwYXNzd29yZA== Header: authorization Header value: Basic dXNlcjpwYXNzd29yZA==

Authorization token For this authorization method we need our customer provide us a token. We take this parameter and send it in each request as a header.

Tag Type Required Example
authorization string No Bearer

Example: Token: 123456 Header: authorization Header value: Bearer 123456

FormBody

Type INE Nominal List
{
  "verificationId": "", 
  "verificationType": 1, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // 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"
    }
  ]
}
Type RFC by CURP
{
  "verificationId": "", 
  "verificationType": 2, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": "{
    \"rfc\": \"string\"
  }",
  "warnings": [ // List of warning messages
    {
      "code": "string",
      "message": "string"
    }
  ]
}
Type NSS by CURP
{
  "verificationId": "", 
  "verificationType": 3, // Type of verification. 1.- IneNominalList, 2.- RfcByCurp, 3.- NssByCurp.
  "verificationStatus": 3, // Status of verification. 1.- Processing, 2.- Retrying, 3.- Delivering, 4.- Completed.
  "verification": "{
    \"nss\": \"string\"
  }",
  "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

{
  "code": "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 service of INE verification.
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.
RFC002 Access Denied. ApiKey header not found. Message to be displayed when the apikey is not displayed.
RFC003 The apiKey is not valid. Message to be displayed when the user enters an incorrect apikey.
RFC004 Something was wrong, we are working on the failure Message displayed when there is an error on the service.
RFC005 CURP does not match with source Message displayed when the input CURP does not have information related.
RFC006 The structure of the CURP is not correct Message displayed when the input CURP does not match with the format.
RFC007 The structure of the state is not correct Message displayed when the input state in not into the catalog.
RFC008 The information associated to the RFC was not found. Message displayed when the information of the CURP could not be found.
RFC010 SAT source unavailable. Message displayed when the SAT servers cannot be consulted.
NSS002 Access Denied. ApiKey header not found. Message to be displayed when the apikey is not displayed.
NSS003 The apiKey is not valid. Message to be displayed when the user enters an incorrect apikey.
NSS004 Something was wrong, We are working on the failure Message displayed when there is an error on the service.
NSS006 The structure of the CURP is not correct Message displayed when the input CURP does not match with the format.
NSS005 CURP does not match with source. Message displayed when the input CURP does not have information related.
NSS007 IMSS source unavailable. Message displayed when the IMSS servers cannot be consulted.
NSS008 The number of operations per period has been reached. Message displayed when the number of operations per period (2 operation(s) every 1 day(s)) have already been carried out.