ValidaCurp Node.js Client

Node.js client for validating, calculating, and obtaining CURP (Clave Única de Registro de Población) information in México. This library provides a simple interface to interact with the Valida CURP API service.

Features

• ✅ Validate CURP structure
• 🔍 Retrieve CURP data from RENAPO
• 🧮 Calculate CURP from personal data
• 🗺️ Get list of Mexican entities (states)
• 🔄 Support for both v1 and v2 API versions
• 🔐 Secure token-based authentication

Requirements

• Node.js >= 14.0.0
• API token from valida-curp.com.mx

Installation

Install the package using npm:

npm install multiserviciosweb

Account Setup

1. Create an account

Register at: https://valida-curp.tawk.help/article/registro-de-usuario

2. Create a project

Create a project at: https://valida-curp.tawk.help/article/creaci%C3%B3n-de-proyecto

3. Get your API token

Obtain your token at: https://valida-curp.tawk.help/article/obtener-token-llave-privada-proyecto

Configuration

Add your token to a .env file in your project root:

TOKEN_VALIDA_API_CURP=your_api_token_here

Usage

Importing the Client

const { ValidaCurp, ValidaCurpException } = require('multiserviciosweb');

Creating an Instance

// Using token from .env file
const client = new ValidaCurp();

// Or explicitly passing token
const clientWithToken = new ValidaCurp('your_api_token_here');

Setting API Version

// Set API version (1 or 2, default is 2)
client.setVersion(2);

API Methods

1. Validate CURP Structure

Validates the structure of a CURP.

async function validateCURP() {
    try {
        const result = await client.isValid('XXXX980528XXXXXX02');
        console.log('Validation Result:', result);
    } catch (error) {
        console.error('Validation Error:', error.message);
    }
}

Response Example:

{
  "valid": true,
  "curp": "XXXX980528XXXXXX02",
  "details": "Valid CURP structure"
}

2. Get CURP Data

Retrieves CURP information from RENAPO.

async function getCURPData() {
    try {
        const data = await client.getData('XXXX980528XXXXXX02');
        console.log('CURP Data:', data);
    } catch (error) {
        console.error('Data Retrieval Error:', error.message);
    }
}

Response Example:

{
  "nombres": "EDSON EDIAN",
  "apellidoPaterno": "BURGOS",
  "apellidoMaterno": "MACEDO",
  "sexo": "H",
  "fechaNacimiento": "1998-05-28",
  "entidadNacimiento": "CIUDAD DE MÉXICO",
  "nacionalidad": "MEXICANA"
}

3. Calculate CURP

Calculates a CURP from personal data.

async function calculateCURP() {
    const personData = {
        names: 'Edson Edian',
        lastName: 'Burgos',
        secondLastName: 'Macedo',
        birthDay: '28',
        birthMonth: '05',
        birthYear: '1998',
        gender: 'H',  // H = Hombre, M = Mujer
        entity: '15'  // Estado de México
    };

    try {
        const result = await client.calculate(personData);
        console.log('Calculated CURP:', result);
    } catch (error) {
        console.error('Calculation Error:', error.message);
    }
}

Response Example:

{
  "curp": "XXXX980528XXXXXX02",
  "digitoVerificador": "2"
}

4. Get Mexican Entities

Retrieves a list of Mexican entities (states).

async function getEntities() {
    try {
        const entities = await client.getEntities();
        console.log('Mexican Entities:', entities);
    } catch (error) {
        console.error('Entities Retrieval Error:', error.message);
    }
}

Response Example:

{
  "01": "AGUASCALIENTES",
  "02": "BAJA CALIFORNIA",
  "03": "BAJA CALIFORNIA SUR",
  "04": "CAMPECHE",
  "05": "COAHUILA",
  ...
}

Full Example

const { ValidaCurp, ValidaCurpException } = require('multiserviciosweb');

async function main() {
    try {
        // Initialize client
        const client = new ValidaCurp();
        
        // Set API version to 2 (recommended)
        client.setVersion(2);
        
        console.log("=== ValidaCurp Node.js Client Example ===");
        
        // 1. Validate CURP
        console.log("\n1. Validating CURP...");
        const validation = await client.isValid('XXXX980528XXXXXX02');
        console.log('Validation Result:', validation);
        
        // 2. Get CURP data
        console.log("\n2. Retrieving CURP data...");
        const data = await client.getData('XXXX980528XXXXXX02');
        console.log('CURP Data:', data);
        
        // 3. Calculate CURP
        console.log("\n3. Calculating CURP...");
        const personData = {
            names: 'Edson Edian',
            lastName: 'Burgos',
            secondLastName: 'Macedo',
            birthDay: '28',
            birthMonth: '05',
            birthYear: '1998',
            gender: 'H',
            entity: '15'
        };
        const calculated = await client.calculate(personData);
        console.log('Calculated CURP:', calculated);
        
        // 4. Get entities
        console.log("\n4. Retrieving entities...");
        const entities = await client.getEntities();
        console.log('Entities Count:', Object.keys(entities).length);
        
        // 5. API version info
        console.log("\n5. API Information:");
        console.log('Current Version:', client.getVersion());
        console.log('Current Endpoint:', client.getEndpoint());
        
    } catch (error) {
        if (error instanceof ValidaCurpException) {
            console.error('API Error:', error.message);
        } else {
            console.error('Unexpected Error:', error.message);
        }
    }
}

main();

Personal Data Structure for CURP Calculation

| Property | Description | Example | |------------------|-----------------------------------------------------------------------------|---------------| | names | First name(s) | 'Juan Carlos' | | lastName | Paternal last name | 'Pérez' | | secondLastName | Maternal last name | 'López' | | birthDay | Day of birth (2 digits) | '15' | | birthMonth | Month of birth (2 digits) | '09' | | birthYear | Year of birth (4 digits) | '1990' | | gender | Gender: 'H' for male, 'M' for female | 'H' | | entity | Entity code (2-digit code for Mexican state) | '09' (CDMX) |

Error Handling

Handle API errors using try/catch blocks:

try {
    const result = await client.getData('INVALID_CURP');
} catch (error) {
    if (error instanceof ValidaCurpException) {
        // Handle API-specific errors
        console.error('API Error:', error.message);
    } else {
        // Handle other errors (network issues, etc.)
        console.error('Unexpected Error:', error.message);
    }
}

API Version Information

• v1: Deprecated (default endpoint: https://api.valida-curp.com.mx/curp/)
• v2: Current version (default endpoint: https://version.valida-curp.com.mx/api/v2/curp/)

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

GitHub Repository:
https://github.com/EdsonBurgosMsWeb/valida-curp-client-nodejs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

• Copyright (c) Multiservicios Web JCA S.A. de C.V., https://multiservicios-web.com.mx
• Author: Edson Burgos [email protected]
• Node.js Port: Assistant

Support

For support, please visit: https://valida-curp.com.mx

Disclaimer: This library is not affiliated with or endorsed by the Mexican government. CURP validation and data retrieval services are provided through third-party API services.