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.