Metadata-Version: 2.4
Name: multiserviciosweb
Version: 1.1.2
Summary: Validate, calculate and obtain CURP information in México.
Author-email: Edson Burgos <edsonburgosmacedo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://valida-curp.com.mx/
Project-URL: Repository, https://github.com/EdsonBurgosMsWeb/valida-curp-client-py
Project-URL: Bug Reports, https://github.com/EdsonBurgosMsWeb/valida-curp-client-py/issues
Project-URL: Documentation, https://api.valida-curp.com.mx/documentacion/
Keywords: valida,curp,méxico,client,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: license-file

# **ValidaCurp Python Client**

[![PyPI version](https://badge.fury.io/py/multiserviciosweb.svg)](https://badge.fury.io/py/multiserviciosweb)
[![Python versions](https://img.shields.io/pypi/pyversions/multiserviciosweb.svg)](https://pypi.org/project/multiserviciosweb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/MIT)

Python client for validating, calculating, and obtaining CURP (Clave Única de Registro de Población) information in México.

- Copyright (c) Multiservicios Web JCA S.A. de C.V., https://multiservicios-web.com.mx
- More information: https://valida-curp.com.mx
- License: MIT (https://opensource.org/license/MIT)

## 1. Requirements

- Python 3.7 or later

## 2. Installation

```bash
pip install multiserviciosweb
```

## 3. Account

### 3.1. Create an account
Create an account by following this link: https://valida-curp.tawk.help/article/registro-de-usuario

### 3.2. Create a project
Create a project by following this link: https://valida-curp.tawk.help/article/creaci%C3%B3n-de-proyecto

### 3.3. Get a token
Get your token by following this link: https://valida-curp.tawk.help/article/obtener-token-llave-privada-proyecto

## 4. Usage

### 4.1. Import the library

```python
from MultiServiciosWeb import ValidaCurp, ValidaCurpException
```

### 4.2. Create an instance

The constructor receives the token as first parameter. Optionally you can pass a custom endpoint.

```python
valida_curp = ValidaCurp('YOUR-TOKEN')
```

You can also set the token via environment variable. Create a `.env` file:

```env
TOKEN_VALIDA_API_CURP=YOUR-TOKEN
```

Then instantiate without arguments:

```python
valida_curp = ValidaCurp()
```

### 4.3. (Optional) Set API version

You can set the API version to query. Default value is 2.

```python
valida_curp.set_version(2)  # 1 or 2
```

> Version 1 of the API is deprecated. Please use version 2.

### 4.4. (Optional) Custom endpoint

```python
valida_curp = ValidaCurp('YOUR-TOKEN', 'https://custom.valida-curp.com.mx/curp/')
```

## 5. Methods

### 5.1. Validate CURP

The method `is_valid()` takes a CURP as parameter and validates its structure.

```python
result = valida_curp.is_valid('PXNE660720HMCXTN06')
print(result)
```

Response:

```python
{'valido': 1}
```

### 5.2. Get CURP data

The method `get_data()` takes a CURP as parameter and consults the CURP information in RENAPO.

```python
data = valida_curp.get_data('PXNE660720HMCXTN06')
print(data)
```

Response:

```python
{
    'Applicant': {
        'CURP': 'PXNE660720HMCXTN06',
        'Names': 'ENRIQUE',
        'LastName': 'PEÑA',
        'SecondLastName': 'NIETO',
        'GenderKey': 'H',
        'Gender': 'Hombre',
        'DateOfBirth': '1966-07-20',
        'Nacionality': 'MEX',
        'CodeEntityBirth': '',
        'EntityBirth': '',
        'KeyEvidentiaryDocument': 1,
        'EvidentiaryDocument': 'Acta de nacimiento',
        'CurpStatusKey': 'AN',
        'CurpStatus': 'Alta Normal'
    },
    'EvidentiaryDocument': {
        'YearRegistration': 1966,
        'KeyIssuingEntity': '',
        'KeyMunicipalityRegistration': 14,
        'MunicipalityRegistration': '',
        'Foja': 0,
        'FolioLetter': '',
        'Book': 0,
        'CertificateNumber': 985,
        'RegistrantNumber': 15,
        'RegistrationEntity': 'México',
        'ForeignRegistrationNumber': '',
        'Volume': 0
    }
}
```

### 5.3. Calculate a CURP

The method `calculate()` takes a dictionary as parameter and calculates the CURP structure from the provided data.

```python
result = valida_curp.calculate({
    'names': 'Enrique',
    'lastName': 'Peña',
    'secondLastName': 'Nieto',
    'birthDay': '20',
    'birthMonth': '07',
    'birthYear': '1966',
    'gender': 'H',
    'entity': '15',
})
print(result)
```

**Required fields:**

| Field            | Description                             | Example    |
|------------------|-----------------------------------------|------------|
| `names`          | First name(s)                           | `'Juan'`   |
| `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`         | `'H'` for male, `'M'` for female        | `'H'`      |
| `entity`         | Entity code (2-digit state code)        | `'09'`     |

Response:

```python
{'curp': 'PXNE660720HMCXTN06'}
```

### 5.4. Get entities

The method `get_entities()` doesn't take any parameters and returns the list of entities.

```python
entities = valida_curp.get_entities()
print(entities)
```

Response:

```python
{
    'clave_entidad': [
        {'clave_entidad': '01', 'nombre_entidad': 'AGUASCALIENTES', 'abreviatura_entidad': 'AS'},
        {'clave_entidad': '02', 'nombre_entidad': 'BAJA CALIFORNIA', 'abreviatura_entidad': 'BC'},
        ...
    ]
}
```

## 6. Error handling

All methods raise `ValidaCurpException` on API errors.

```python
from MultiServiciosWeb import ValidaCurp, ValidaCurpException

try:
    data = valida_curp.get_data('PXNE660720HMCXTN06')
except ValidaCurpException as e:
    print(f'API Error: {e}')
except Exception as e:
    print(f'Unexpected Error: {e}')
```

## 7. Full example

```python
from MultiServiciosWeb import ValidaCurp, ValidaCurpException

try:
    valida_curp = ValidaCurp('YOUR-TOKEN')

    # Validate CURP structure
    print(valida_curp.is_valid('PXNE660720HMCXTN06'))

    # Get CURP data from RENAPO
    print(valida_curp.get_data('PXNE660720HMCXTN06'))

    # Calculate CURP
    print(valida_curp.calculate({
        'names': 'Enrique',
        'lastName': 'Peña',
        'secondLastName': 'Nieto',
        'birthDay': '20',
        'birthMonth': '07',
        'birthYear': '1966',
        'gender': 'H',
        'entity': '15',
    }))

    # Get entities
    print(valida_curp.get_entities())

except ValidaCurpException as e:
    print(f'ValidaCurp Exception: {e}')
except Exception as e:
    print(f'Unexpected Error: {e}')
```

## 8. Credits

- Copyright (c) **Multiservicios Web JCA S.A. de C.V.**, https://multiservicios-web.com.mx
- **Author:** Edson Burgos <edsonburgosmacedo@gmail.com>

## 9. License

This project is released under the MIT License. See the **[LICENSE](./LICENSE)** file for details.
