dian-nit-validator 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- dian_nit_validator-1.0.0/PKG-INFO +227 -0
- dian_nit_validator-1.0.0/README.md +205 -0
- dian_nit_validator-1.0.0/dian_nit_validator.egg-info/PKG-INFO +227 -0
- dian_nit_validator-1.0.0/dian_nit_validator.egg-info/SOURCES.txt +12 -0
- dian_nit_validator-1.0.0/dian_nit_validator.egg-info/dependency_links.txt +1 -0
- dian_nit_validator-1.0.0/dian_nit_validator.egg-info/entry_points.txt +3 -0
- dian_nit_validator-1.0.0/dian_nit_validator.egg-info/top_level.txt +1 -0
- dian_nit_validator-1.0.0/nit_validator/__init__.py +22 -0
- dian_nit_validator-1.0.0/nit_validator/__main__.py +4 -0
- dian_nit_validator-1.0.0/nit_validator/cli.py +58 -0
- dian_nit_validator-1.0.0/nit_validator/validator.py +130 -0
- dian_nit_validator-1.0.0/pyproject.toml +47 -0
- dian_nit_validator-1.0.0/setup.cfg +4 -0
- dian_nit_validator-1.0.0/tests/test_validator.py +62 -0
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dian-nit-validator
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Librería y CLI en Python para cálculo y validación del Dígito de Verificación del NIT DIAN en Colombia (Módulo 11).
|
|
5
|
+
Author-email: Kevin Andrey Herrera Silva <kahs_kevin@hotmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/KevinAndrey96/dian-nit-validator-python
|
|
8
|
+
Project-URL: Repository, https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
9
|
+
Keywords: dian,colombia,nit,validador-nit,modulo-11,digito-verificacion,facturacion-electronica,fintech
|
|
10
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial :: Accounting
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Validador y Calculador de Dígito de Verificación (DV) NIT DIAN Colombia 🇨🇴
|
|
24
|
+
|
|
25
|
+
> **Librería ultraligera y CLI en Python para el cálculo y validación del Dígito de Verificación del NIT en Colombia (Módulo 11).**
|
|
26
|
+
> Fielmente implementado según el **Artículo 375 del Estatuto Tributario** y el **Decreto 2460 de 2013 de la DIAN**.
|
|
27
|
+
|
|
28
|
+
[](https://github.com/KevinAndrey96/dian-nit-validator-python/actions/workflows/ci.yml)
|
|
29
|
+
[](https://www.python.org/)
|
|
30
|
+
[](tests/test_validator.py)
|
|
31
|
+
[](pyproject.toml)
|
|
32
|
+
[](LICENSE)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 📌 Tabla de Contenidos
|
|
37
|
+
1. [Características Principales](#-características-principales)
|
|
38
|
+
2. [Fundamento Legal y Algoritmo Matemático](#-fundamento-legal-y-algoritmo-matemático)
|
|
39
|
+
3. [Instalación](#-instalación)
|
|
40
|
+
4. [Guía de Uso Rápido (Python API)](#-guía-de-uso-rápido-python-api)
|
|
41
|
+
- [Cálculo del Dígito de Verificación](#1-cálculo-del-dígito-de-verificación-dv)
|
|
42
|
+
- [Validación de NIT Completo](#2-validación-de-nit-completo)
|
|
43
|
+
- [Formateo de NIT con Puntos y Guión](#3-formateo-de-nit)
|
|
44
|
+
- [Integración con Pydantic / FastAPI](#4-ejemplo-de-integración-con-pydantic--fastapi)
|
|
45
|
+
5. [Uso desde la Línea de Comandos (CLI)](#-uso-desde-la-línea-de-comandos-cli)
|
|
46
|
+
6. [Casos de Prueba Verificados](#-casos-de-prueba-verificados)
|
|
47
|
+
7. [Ejercicios y Algoritmos Históricos](#-ejercicios-y-algoritmos-históricos)
|
|
48
|
+
8. [Autor](#-autor)
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## ✨ Características Principales
|
|
53
|
+
|
|
54
|
+
* ⚡ **Cero Dependencias Externas:** Funciona exclusivamente con la biblioteca estándar de Python sin sobrecargar tu entorno ni generar vulnerabilidades en tu árbol de dependencias.
|
|
55
|
+
* 🏢 **Soporte Universal de Longitud:** Compatible con NITs de **1 a 15 dígitos** (personas naturales, cédulas de ciudadanía, personas jurídicas, consorcios y entidades estatales).
|
|
56
|
+
* 🧼 **Sanitización Automática:** Acepta enteros (`860007386`), cadenas con puntos (`"860.007.386"`), espacios o formatos con guión (`"860007386-1"`).
|
|
57
|
+
* 💻 **Herramienta de Consola (CLI):** Comando interactivo para terminales y scripts bash / pipelines CI/CD.
|
|
58
|
+
* 🧪 **Suite de Pruebas Exhaustiva:** Verificado con empresas reales del listado de Grandes Contribuyentes de Colombia.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 📐 Fundamento Legal y Algoritmo Matemático
|
|
63
|
+
|
|
64
|
+
En Colombia, el Número de Identificación Tributaria (**NIT**) expedido por la **Dirección de Impuestos y Aduanas Nacionales (DIAN)** utiliza un algoritmo ponderado basado en **Módulo 11** para evitar errores de digitación y fraude en transacciones comerciales y facturación electrónica.
|
|
65
|
+
|
|
66
|
+
### Vector de Pesos Primos Oficial DIAN:
|
|
67
|
+
Para un NIT de hasta 15 dígitos, se multiplica cada dígito de derecha a izquierda por los factores de ponderación primos:
|
|
68
|
+
|
|
69
|
+
$$P = [71, 67, 59, 53, 47, 43, 41, 37, 29, 23, 19, 17, 13, 7, 3]$$
|
|
70
|
+
|
|
71
|
+
Para el estándar más común de 9 dígitos, se emplean los últimos 9 coeficientes: `[41, 37, 29, 23, 19, 17, 13, 7, 3]`.
|
|
72
|
+
|
|
73
|
+
```mermaid
|
|
74
|
+
flowchart LR
|
|
75
|
+
NIT["NIT: d1, d2, ..., dn"] --> DotProduct["Producto Escalar con Pesos DIAN<br/>Suma = Σ (di × Pi)"]
|
|
76
|
+
DotProduct --> Modulo["Residuo = Suma mod 11"]
|
|
77
|
+
Modulo --> Condicion{"¿Residuo en (0, 1)?"}
|
|
78
|
+
Condicion -->|Sí| Exacto["DV = Residuo"]
|
|
79
|
+
Condicion -->|No| Resta["DV = 11 - Residuo"]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 📦 Instalación
|
|
85
|
+
|
|
86
|
+
Puedes instalar la librería directamente desde GitHub usando `pip`:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pip install git+https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
O clonar el repositorio localmente para desarrollo:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
git clone https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
96
|
+
cd dian-nit-validator-python
|
|
97
|
+
pip install -e .
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🚀 Guía de Uso Rápido (Python API)
|
|
103
|
+
|
|
104
|
+
### 1. Cálculo del Dígito de Verificación (DV)
|
|
105
|
+
Calcula el dígito que debe acompañar a cualquier NIT:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from nit_validator import calcular_dv
|
|
109
|
+
|
|
110
|
+
# Entrada como cadena o entero
|
|
111
|
+
dv_bancolombia = calcular_dv("860007386")
|
|
112
|
+
print(dv_bancolombia) # 1
|
|
113
|
+
|
|
114
|
+
# Soporta NITs con formato de puntos
|
|
115
|
+
dv_ecopetrol = calcular_dv("899.999.068")
|
|
116
|
+
print(dv_ecopetrol) # 1
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 2. Validación de NIT Completo
|
|
120
|
+
Valida si el dígito proporcionado coincide con el cálculo matemático oficial:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from nit_validator import validar_nit
|
|
124
|
+
|
|
125
|
+
# Formato cadena unificada con guión:
|
|
126
|
+
print(validar_nit("860007386-1")) # True
|
|
127
|
+
print(validar_nit("860.007.386-1")) # True
|
|
128
|
+
print(validar_nit("860007386-9")) # False (DV incorrecto)
|
|
129
|
+
|
|
130
|
+
# Formato separado (NIT, DV):
|
|
131
|
+
print(validar_nit(860007386, 1)) # True
|
|
132
|
+
print(validar_nit("860007386", "1")) # True
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 3. Formateo de NIT
|
|
136
|
+
Convierte números crudos a la representación estándar colombiana:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from nit_validator import formatear_nit
|
|
140
|
+
|
|
141
|
+
print(formatear_nit(860007386)) # "860.007.386-1"
|
|
142
|
+
print(formatear_nit(860007386, incluir_dv=False)) # "860.007.386"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 4. Ejemplo de Integración con Pydantic / FastAPI
|
|
146
|
+
|
|
147
|
+
Ideal para microservicios de facturación electrónica y pasarelas de pago:
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from pydantic import BaseModel, validator
|
|
151
|
+
from nit_validator import validar_nit, formatear_nit
|
|
152
|
+
|
|
153
|
+
class EmpresaSchema(BaseModel):
|
|
154
|
+
razon_social: str
|
|
155
|
+
nit: str
|
|
156
|
+
|
|
157
|
+
@validator('nit')
|
|
158
|
+
def validar_nit_dian(cls, v):
|
|
159
|
+
if not validar_nit(v):
|
|
160
|
+
raise ValueError('El NIT proporcionado o su dígito de verificación no son válidos ante la DIAN')
|
|
161
|
+
return formatear_nit(v)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 🖥️ Uso desde la Línea de Comandos (CLI)
|
|
167
|
+
|
|
168
|
+
El paquete incluye una CLI que puedes invocar directamente:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
# Calcular el DV de un NIT:
|
|
172
|
+
python3 -m nit_validator 860007386
|
|
173
|
+
# Salida:
|
|
174
|
+
# Dígito de Verificación (DV): 1
|
|
175
|
+
# NIT Completo: 860.007.386-1
|
|
176
|
+
|
|
177
|
+
# Validar un NIT (retorna código de salida 0 si es válido, 1 si es inválido):
|
|
178
|
+
python3 -m nit_validator 860007386-1
|
|
179
|
+
# Salida:
|
|
180
|
+
# ✅ VÁLIDO: El NIT 860007386-1 coincide con el algoritmo oficial DIAN.
|
|
181
|
+
|
|
182
|
+
# Formatear con separadores de miles y guión:
|
|
183
|
+
python3 -m nit_validator -f 890900050
|
|
184
|
+
# Salida:
|
|
185
|
+
# 890.900.050-1
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 🏢 Casos de Prueba Verificados
|
|
191
|
+
|
|
192
|
+
El algoritmo ha sido probado contra registros reales de la DIAN:
|
|
193
|
+
|
|
194
|
+
| Entidad / Gran Contribuyente | NIT Base | Dígito (DV) | NIT Completo | Estado |
|
|
195
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
196
|
+
| **Bancolombia S.A.** | `860007386` | **1** | `860.007.386-1` | ✅ Válido |
|
|
197
|
+
| **Ecopetrol S.A.** | `899999068` | **1** | `899.999.068-1` | ✅ Válido |
|
|
198
|
+
| **Grupo Nutresa S.A.** | `890900050` | **1** | `890.900.050-1` | ✅ Válido |
|
|
199
|
+
| **Almacenes Éxito S.A.** | `890900608` | **9** | `890.900.608-9` | ✅ Válido |
|
|
200
|
+
| **DIAN** | `800197268` | **4** | `800.197.268-4` | ✅ Válido |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## 🗃️ Ejercicios y Algoritmos Históricos
|
|
205
|
+
|
|
206
|
+
Este repositorio conserva su antigüedad histórica de commits. Los ejercicios complementarios desarrollados previamente se preservan organizados en el directorio `extra_algorithms/`:
|
|
207
|
+
* `extra_algorithms/robot_fsm.py`: Simulación de orientación 2D mediante Máquina de Estados Finitos (FSM).
|
|
208
|
+
* `extra_algorithms/student_ranking.py`: Agregación y ordenamiento multivariable de estructuras de datos.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 🧪 Ejecución de Pruebas Unitarias
|
|
213
|
+
|
|
214
|
+
Para ejecutar la suite de pruebas del proyecto:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
python3 -m unittest discover -s tests -v
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 👨💻 Autor
|
|
223
|
+
|
|
224
|
+
**Kevin Andrey Herrera Silva**
|
|
225
|
+
*Senior Backend Engineer & Software Architect*
|
|
226
|
+
* GitHub: [@KevinAndrey96](https://github.com/KevinAndrey96)
|
|
227
|
+
* Email: kahs_kevin@hotmail.com
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
# Validador y Calculador de Dígito de Verificación (DV) NIT DIAN Colombia 🇨🇴
|
|
2
|
+
|
|
3
|
+
> **Librería ultraligera y CLI en Python para el cálculo y validación del Dígito de Verificación del NIT en Colombia (Módulo 11).**
|
|
4
|
+
> Fielmente implementado según el **Artículo 375 del Estatuto Tributario** y el **Decreto 2460 de 2013 de la DIAN**.
|
|
5
|
+
|
|
6
|
+
[](https://github.com/KevinAndrey96/dian-nit-validator-python/actions/workflows/ci.yml)
|
|
7
|
+
[](https://www.python.org/)
|
|
8
|
+
[](tests/test_validator.py)
|
|
9
|
+
[](pyproject.toml)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 📌 Tabla de Contenidos
|
|
15
|
+
1. [Características Principales](#-características-principales)
|
|
16
|
+
2. [Fundamento Legal y Algoritmo Matemático](#-fundamento-legal-y-algoritmo-matemático)
|
|
17
|
+
3. [Instalación](#-instalación)
|
|
18
|
+
4. [Guía de Uso Rápido (Python API)](#-guía-de-uso-rápido-python-api)
|
|
19
|
+
- [Cálculo del Dígito de Verificación](#1-cálculo-del-dígito-de-verificación-dv)
|
|
20
|
+
- [Validación de NIT Completo](#2-validación-de-nit-completo)
|
|
21
|
+
- [Formateo de NIT con Puntos y Guión](#3-formateo-de-nit)
|
|
22
|
+
- [Integración con Pydantic / FastAPI](#4-ejemplo-de-integración-con-pydantic--fastapi)
|
|
23
|
+
5. [Uso desde la Línea de Comandos (CLI)](#-uso-desde-la-línea-de-comandos-cli)
|
|
24
|
+
6. [Casos de Prueba Verificados](#-casos-de-prueba-verificados)
|
|
25
|
+
7. [Ejercicios y Algoritmos Históricos](#-ejercicios-y-algoritmos-históricos)
|
|
26
|
+
8. [Autor](#-autor)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## ✨ Características Principales
|
|
31
|
+
|
|
32
|
+
* ⚡ **Cero Dependencias Externas:** Funciona exclusivamente con la biblioteca estándar de Python sin sobrecargar tu entorno ni generar vulnerabilidades en tu árbol de dependencias.
|
|
33
|
+
* 🏢 **Soporte Universal de Longitud:** Compatible con NITs de **1 a 15 dígitos** (personas naturales, cédulas de ciudadanía, personas jurídicas, consorcios y entidades estatales).
|
|
34
|
+
* 🧼 **Sanitización Automática:** Acepta enteros (`860007386`), cadenas con puntos (`"860.007.386"`), espacios o formatos con guión (`"860007386-1"`).
|
|
35
|
+
* 💻 **Herramienta de Consola (CLI):** Comando interactivo para terminales y scripts bash / pipelines CI/CD.
|
|
36
|
+
* 🧪 **Suite de Pruebas Exhaustiva:** Verificado con empresas reales del listado de Grandes Contribuyentes de Colombia.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 📐 Fundamento Legal y Algoritmo Matemático
|
|
41
|
+
|
|
42
|
+
En Colombia, el Número de Identificación Tributaria (**NIT**) expedido por la **Dirección de Impuestos y Aduanas Nacionales (DIAN)** utiliza un algoritmo ponderado basado en **Módulo 11** para evitar errores de digitación y fraude en transacciones comerciales y facturación electrónica.
|
|
43
|
+
|
|
44
|
+
### Vector de Pesos Primos Oficial DIAN:
|
|
45
|
+
Para un NIT de hasta 15 dígitos, se multiplica cada dígito de derecha a izquierda por los factores de ponderación primos:
|
|
46
|
+
|
|
47
|
+
$$P = [71, 67, 59, 53, 47, 43, 41, 37, 29, 23, 19, 17, 13, 7, 3]$$
|
|
48
|
+
|
|
49
|
+
Para el estándar más común de 9 dígitos, se emplean los últimos 9 coeficientes: `[41, 37, 29, 23, 19, 17, 13, 7, 3]`.
|
|
50
|
+
|
|
51
|
+
```mermaid
|
|
52
|
+
flowchart LR
|
|
53
|
+
NIT["NIT: d1, d2, ..., dn"] --> DotProduct["Producto Escalar con Pesos DIAN<br/>Suma = Σ (di × Pi)"]
|
|
54
|
+
DotProduct --> Modulo["Residuo = Suma mod 11"]
|
|
55
|
+
Modulo --> Condicion{"¿Residuo en (0, 1)?"}
|
|
56
|
+
Condicion -->|Sí| Exacto["DV = Residuo"]
|
|
57
|
+
Condicion -->|No| Resta["DV = 11 - Residuo"]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 📦 Instalación
|
|
63
|
+
|
|
64
|
+
Puedes instalar la librería directamente desde GitHub usando `pip`:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install git+https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
O clonar el repositorio localmente para desarrollo:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
git clone https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
74
|
+
cd dian-nit-validator-python
|
|
75
|
+
pip install -e .
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 🚀 Guía de Uso Rápido (Python API)
|
|
81
|
+
|
|
82
|
+
### 1. Cálculo del Dígito de Verificación (DV)
|
|
83
|
+
Calcula el dígito que debe acompañar a cualquier NIT:
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
from nit_validator import calcular_dv
|
|
87
|
+
|
|
88
|
+
# Entrada como cadena o entero
|
|
89
|
+
dv_bancolombia = calcular_dv("860007386")
|
|
90
|
+
print(dv_bancolombia) # 1
|
|
91
|
+
|
|
92
|
+
# Soporta NITs con formato de puntos
|
|
93
|
+
dv_ecopetrol = calcular_dv("899.999.068")
|
|
94
|
+
print(dv_ecopetrol) # 1
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### 2. Validación de NIT Completo
|
|
98
|
+
Valida si el dígito proporcionado coincide con el cálculo matemático oficial:
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from nit_validator import validar_nit
|
|
102
|
+
|
|
103
|
+
# Formato cadena unificada con guión:
|
|
104
|
+
print(validar_nit("860007386-1")) # True
|
|
105
|
+
print(validar_nit("860.007.386-1")) # True
|
|
106
|
+
print(validar_nit("860007386-9")) # False (DV incorrecto)
|
|
107
|
+
|
|
108
|
+
# Formato separado (NIT, DV):
|
|
109
|
+
print(validar_nit(860007386, 1)) # True
|
|
110
|
+
print(validar_nit("860007386", "1")) # True
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 3. Formateo de NIT
|
|
114
|
+
Convierte números crudos a la representación estándar colombiana:
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
from nit_validator import formatear_nit
|
|
118
|
+
|
|
119
|
+
print(formatear_nit(860007386)) # "860.007.386-1"
|
|
120
|
+
print(formatear_nit(860007386, incluir_dv=False)) # "860.007.386"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### 4. Ejemplo de Integración con Pydantic / FastAPI
|
|
124
|
+
|
|
125
|
+
Ideal para microservicios de facturación electrónica y pasarelas de pago:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from pydantic import BaseModel, validator
|
|
129
|
+
from nit_validator import validar_nit, formatear_nit
|
|
130
|
+
|
|
131
|
+
class EmpresaSchema(BaseModel):
|
|
132
|
+
razon_social: str
|
|
133
|
+
nit: str
|
|
134
|
+
|
|
135
|
+
@validator('nit')
|
|
136
|
+
def validar_nit_dian(cls, v):
|
|
137
|
+
if not validar_nit(v):
|
|
138
|
+
raise ValueError('El NIT proporcionado o su dígito de verificación no son válidos ante la DIAN')
|
|
139
|
+
return formatear_nit(v)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 🖥️ Uso desde la Línea de Comandos (CLI)
|
|
145
|
+
|
|
146
|
+
El paquete incluye una CLI que puedes invocar directamente:
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
# Calcular el DV de un NIT:
|
|
150
|
+
python3 -m nit_validator 860007386
|
|
151
|
+
# Salida:
|
|
152
|
+
# Dígito de Verificación (DV): 1
|
|
153
|
+
# NIT Completo: 860.007.386-1
|
|
154
|
+
|
|
155
|
+
# Validar un NIT (retorna código de salida 0 si es válido, 1 si es inválido):
|
|
156
|
+
python3 -m nit_validator 860007386-1
|
|
157
|
+
# Salida:
|
|
158
|
+
# ✅ VÁLIDO: El NIT 860007386-1 coincide con el algoritmo oficial DIAN.
|
|
159
|
+
|
|
160
|
+
# Formatear con separadores de miles y guión:
|
|
161
|
+
python3 -m nit_validator -f 890900050
|
|
162
|
+
# Salida:
|
|
163
|
+
# 890.900.050-1
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 🏢 Casos de Prueba Verificados
|
|
169
|
+
|
|
170
|
+
El algoritmo ha sido probado contra registros reales de la DIAN:
|
|
171
|
+
|
|
172
|
+
| Entidad / Gran Contribuyente | NIT Base | Dígito (DV) | NIT Completo | Estado |
|
|
173
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
174
|
+
| **Bancolombia S.A.** | `860007386` | **1** | `860.007.386-1` | ✅ Válido |
|
|
175
|
+
| **Ecopetrol S.A.** | `899999068` | **1** | `899.999.068-1` | ✅ Válido |
|
|
176
|
+
| **Grupo Nutresa S.A.** | `890900050` | **1** | `890.900.050-1` | ✅ Válido |
|
|
177
|
+
| **Almacenes Éxito S.A.** | `890900608` | **9** | `890.900.608-9` | ✅ Válido |
|
|
178
|
+
| **DIAN** | `800197268` | **4** | `800.197.268-4` | ✅ Válido |
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 🗃️ Ejercicios y Algoritmos Históricos
|
|
183
|
+
|
|
184
|
+
Este repositorio conserva su antigüedad histórica de commits. Los ejercicios complementarios desarrollados previamente se preservan organizados en el directorio `extra_algorithms/`:
|
|
185
|
+
* `extra_algorithms/robot_fsm.py`: Simulación de orientación 2D mediante Máquina de Estados Finitos (FSM).
|
|
186
|
+
* `extra_algorithms/student_ranking.py`: Agregación y ordenamiento multivariable de estructuras de datos.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 🧪 Ejecución de Pruebas Unitarias
|
|
191
|
+
|
|
192
|
+
Para ejecutar la suite de pruebas del proyecto:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
python3 -m unittest discover -s tests -v
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 👨💻 Autor
|
|
201
|
+
|
|
202
|
+
**Kevin Andrey Herrera Silva**
|
|
203
|
+
*Senior Backend Engineer & Software Architect*
|
|
204
|
+
* GitHub: [@KevinAndrey96](https://github.com/KevinAndrey96)
|
|
205
|
+
* Email: kahs_kevin@hotmail.com
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dian-nit-validator
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Librería y CLI en Python para cálculo y validación del Dígito de Verificación del NIT DIAN en Colombia (Módulo 11).
|
|
5
|
+
Author-email: Kevin Andrey Herrera Silva <kahs_kevin@hotmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/KevinAndrey96/dian-nit-validator-python
|
|
8
|
+
Project-URL: Repository, https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
9
|
+
Keywords: dian,colombia,nit,validador-nit,modulo-11,digito-verificacion,facturacion-electronica,fintech
|
|
10
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial :: Accounting
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# Validador y Calculador de Dígito de Verificación (DV) NIT DIAN Colombia 🇨🇴
|
|
24
|
+
|
|
25
|
+
> **Librería ultraligera y CLI en Python para el cálculo y validación del Dígito de Verificación del NIT en Colombia (Módulo 11).**
|
|
26
|
+
> Fielmente implementado según el **Artículo 375 del Estatuto Tributario** y el **Decreto 2460 de 2013 de la DIAN**.
|
|
27
|
+
|
|
28
|
+
[](https://github.com/KevinAndrey96/dian-nit-validator-python/actions/workflows/ci.yml)
|
|
29
|
+
[](https://www.python.org/)
|
|
30
|
+
[](tests/test_validator.py)
|
|
31
|
+
[](pyproject.toml)
|
|
32
|
+
[](LICENSE)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 📌 Tabla de Contenidos
|
|
37
|
+
1. [Características Principales](#-características-principales)
|
|
38
|
+
2. [Fundamento Legal y Algoritmo Matemático](#-fundamento-legal-y-algoritmo-matemático)
|
|
39
|
+
3. [Instalación](#-instalación)
|
|
40
|
+
4. [Guía de Uso Rápido (Python API)](#-guía-de-uso-rápido-python-api)
|
|
41
|
+
- [Cálculo del Dígito de Verificación](#1-cálculo-del-dígito-de-verificación-dv)
|
|
42
|
+
- [Validación de NIT Completo](#2-validación-de-nit-completo)
|
|
43
|
+
- [Formateo de NIT con Puntos y Guión](#3-formateo-de-nit)
|
|
44
|
+
- [Integración con Pydantic / FastAPI](#4-ejemplo-de-integración-con-pydantic--fastapi)
|
|
45
|
+
5. [Uso desde la Línea de Comandos (CLI)](#-uso-desde-la-línea-de-comandos-cli)
|
|
46
|
+
6. [Casos de Prueba Verificados](#-casos-de-prueba-verificados)
|
|
47
|
+
7. [Ejercicios y Algoritmos Históricos](#-ejercicios-y-algoritmos-históricos)
|
|
48
|
+
8. [Autor](#-autor)
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## ✨ Características Principales
|
|
53
|
+
|
|
54
|
+
* ⚡ **Cero Dependencias Externas:** Funciona exclusivamente con la biblioteca estándar de Python sin sobrecargar tu entorno ni generar vulnerabilidades en tu árbol de dependencias.
|
|
55
|
+
* 🏢 **Soporte Universal de Longitud:** Compatible con NITs de **1 a 15 dígitos** (personas naturales, cédulas de ciudadanía, personas jurídicas, consorcios y entidades estatales).
|
|
56
|
+
* 🧼 **Sanitización Automática:** Acepta enteros (`860007386`), cadenas con puntos (`"860.007.386"`), espacios o formatos con guión (`"860007386-1"`).
|
|
57
|
+
* 💻 **Herramienta de Consola (CLI):** Comando interactivo para terminales y scripts bash / pipelines CI/CD.
|
|
58
|
+
* 🧪 **Suite de Pruebas Exhaustiva:** Verificado con empresas reales del listado de Grandes Contribuyentes de Colombia.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 📐 Fundamento Legal y Algoritmo Matemático
|
|
63
|
+
|
|
64
|
+
En Colombia, el Número de Identificación Tributaria (**NIT**) expedido por la **Dirección de Impuestos y Aduanas Nacionales (DIAN)** utiliza un algoritmo ponderado basado en **Módulo 11** para evitar errores de digitación y fraude en transacciones comerciales y facturación electrónica.
|
|
65
|
+
|
|
66
|
+
### Vector de Pesos Primos Oficial DIAN:
|
|
67
|
+
Para un NIT de hasta 15 dígitos, se multiplica cada dígito de derecha a izquierda por los factores de ponderación primos:
|
|
68
|
+
|
|
69
|
+
$$P = [71, 67, 59, 53, 47, 43, 41, 37, 29, 23, 19, 17, 13, 7, 3]$$
|
|
70
|
+
|
|
71
|
+
Para el estándar más común de 9 dígitos, se emplean los últimos 9 coeficientes: `[41, 37, 29, 23, 19, 17, 13, 7, 3]`.
|
|
72
|
+
|
|
73
|
+
```mermaid
|
|
74
|
+
flowchart LR
|
|
75
|
+
NIT["NIT: d1, d2, ..., dn"] --> DotProduct["Producto Escalar con Pesos DIAN<br/>Suma = Σ (di × Pi)"]
|
|
76
|
+
DotProduct --> Modulo["Residuo = Suma mod 11"]
|
|
77
|
+
Modulo --> Condicion{"¿Residuo en (0, 1)?"}
|
|
78
|
+
Condicion -->|Sí| Exacto["DV = Residuo"]
|
|
79
|
+
Condicion -->|No| Resta["DV = 11 - Residuo"]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## 📦 Instalación
|
|
85
|
+
|
|
86
|
+
Puedes instalar la librería directamente desde GitHub usando `pip`:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pip install git+https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
O clonar el repositorio localmente para desarrollo:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
git clone https://github.com/KevinAndrey96/dian-nit-validator-python.git
|
|
96
|
+
cd dian-nit-validator-python
|
|
97
|
+
pip install -e .
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🚀 Guía de Uso Rápido (Python API)
|
|
103
|
+
|
|
104
|
+
### 1. Cálculo del Dígito de Verificación (DV)
|
|
105
|
+
Calcula el dígito que debe acompañar a cualquier NIT:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from nit_validator import calcular_dv
|
|
109
|
+
|
|
110
|
+
# Entrada como cadena o entero
|
|
111
|
+
dv_bancolombia = calcular_dv("860007386")
|
|
112
|
+
print(dv_bancolombia) # 1
|
|
113
|
+
|
|
114
|
+
# Soporta NITs con formato de puntos
|
|
115
|
+
dv_ecopetrol = calcular_dv("899.999.068")
|
|
116
|
+
print(dv_ecopetrol) # 1
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 2. Validación de NIT Completo
|
|
120
|
+
Valida si el dígito proporcionado coincide con el cálculo matemático oficial:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from nit_validator import validar_nit
|
|
124
|
+
|
|
125
|
+
# Formato cadena unificada con guión:
|
|
126
|
+
print(validar_nit("860007386-1")) # True
|
|
127
|
+
print(validar_nit("860.007.386-1")) # True
|
|
128
|
+
print(validar_nit("860007386-9")) # False (DV incorrecto)
|
|
129
|
+
|
|
130
|
+
# Formato separado (NIT, DV):
|
|
131
|
+
print(validar_nit(860007386, 1)) # True
|
|
132
|
+
print(validar_nit("860007386", "1")) # True
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 3. Formateo de NIT
|
|
136
|
+
Convierte números crudos a la representación estándar colombiana:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
from nit_validator import formatear_nit
|
|
140
|
+
|
|
141
|
+
print(formatear_nit(860007386)) # "860.007.386-1"
|
|
142
|
+
print(formatear_nit(860007386, incluir_dv=False)) # "860.007.386"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### 4. Ejemplo de Integración con Pydantic / FastAPI
|
|
146
|
+
|
|
147
|
+
Ideal para microservicios de facturación electrónica y pasarelas de pago:
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from pydantic import BaseModel, validator
|
|
151
|
+
from nit_validator import validar_nit, formatear_nit
|
|
152
|
+
|
|
153
|
+
class EmpresaSchema(BaseModel):
|
|
154
|
+
razon_social: str
|
|
155
|
+
nit: str
|
|
156
|
+
|
|
157
|
+
@validator('nit')
|
|
158
|
+
def validar_nit_dian(cls, v):
|
|
159
|
+
if not validar_nit(v):
|
|
160
|
+
raise ValueError('El NIT proporcionado o su dígito de verificación no son válidos ante la DIAN')
|
|
161
|
+
return formatear_nit(v)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 🖥️ Uso desde la Línea de Comandos (CLI)
|
|
167
|
+
|
|
168
|
+
El paquete incluye una CLI que puedes invocar directamente:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
# Calcular el DV de un NIT:
|
|
172
|
+
python3 -m nit_validator 860007386
|
|
173
|
+
# Salida:
|
|
174
|
+
# Dígito de Verificación (DV): 1
|
|
175
|
+
# NIT Completo: 860.007.386-1
|
|
176
|
+
|
|
177
|
+
# Validar un NIT (retorna código de salida 0 si es válido, 1 si es inválido):
|
|
178
|
+
python3 -m nit_validator 860007386-1
|
|
179
|
+
# Salida:
|
|
180
|
+
# ✅ VÁLIDO: El NIT 860007386-1 coincide con el algoritmo oficial DIAN.
|
|
181
|
+
|
|
182
|
+
# Formatear con separadores de miles y guión:
|
|
183
|
+
python3 -m nit_validator -f 890900050
|
|
184
|
+
# Salida:
|
|
185
|
+
# 890.900.050-1
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## 🏢 Casos de Prueba Verificados
|
|
191
|
+
|
|
192
|
+
El algoritmo ha sido probado contra registros reales de la DIAN:
|
|
193
|
+
|
|
194
|
+
| Entidad / Gran Contribuyente | NIT Base | Dígito (DV) | NIT Completo | Estado |
|
|
195
|
+
| :--- | :---: | :---: | :---: | :---: |
|
|
196
|
+
| **Bancolombia S.A.** | `860007386` | **1** | `860.007.386-1` | ✅ Válido |
|
|
197
|
+
| **Ecopetrol S.A.** | `899999068` | **1** | `899.999.068-1` | ✅ Válido |
|
|
198
|
+
| **Grupo Nutresa S.A.** | `890900050` | **1** | `890.900.050-1` | ✅ Válido |
|
|
199
|
+
| **Almacenes Éxito S.A.** | `890900608` | **9** | `890.900.608-9` | ✅ Válido |
|
|
200
|
+
| **DIAN** | `800197268` | **4** | `800.197.268-4` | ✅ Válido |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## 🗃️ Ejercicios y Algoritmos Históricos
|
|
205
|
+
|
|
206
|
+
Este repositorio conserva su antigüedad histórica de commits. Los ejercicios complementarios desarrollados previamente se preservan organizados en el directorio `extra_algorithms/`:
|
|
207
|
+
* `extra_algorithms/robot_fsm.py`: Simulación de orientación 2D mediante Máquina de Estados Finitos (FSM).
|
|
208
|
+
* `extra_algorithms/student_ranking.py`: Agregación y ordenamiento multivariable de estructuras de datos.
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 🧪 Ejecución de Pruebas Unitarias
|
|
213
|
+
|
|
214
|
+
Para ejecutar la suite de pruebas del proyecto:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
python3 -m unittest discover -s tests -v
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## 👨💻 Autor
|
|
223
|
+
|
|
224
|
+
**Kevin Andrey Herrera Silva**
|
|
225
|
+
*Senior Backend Engineer & Software Architect*
|
|
226
|
+
* GitHub: [@KevinAndrey96](https://github.com/KevinAndrey96)
|
|
227
|
+
* Email: kahs_kevin@hotmail.com
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
dian_nit_validator.egg-info/PKG-INFO
|
|
4
|
+
dian_nit_validator.egg-info/SOURCES.txt
|
|
5
|
+
dian_nit_validator.egg-info/dependency_links.txt
|
|
6
|
+
dian_nit_validator.egg-info/entry_points.txt
|
|
7
|
+
dian_nit_validator.egg-info/top_level.txt
|
|
8
|
+
nit_validator/__init__.py
|
|
9
|
+
nit_validator/__main__.py
|
|
10
|
+
nit_validator/cli.py
|
|
11
|
+
nit_validator/validator.py
|
|
12
|
+
tests/test_validator.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
nit_validator
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""
|
|
2
|
+
DIAN NIT Validator & Modulo 11 Check Digit Calculator for Colombia.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from .validator import (
|
|
6
|
+
calcular_dv,
|
|
7
|
+
validar_nit,
|
|
8
|
+
formatear_nit,
|
|
9
|
+
limpiar_nit,
|
|
10
|
+
NITValidator,
|
|
11
|
+
PESOS_DIAN,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__version__ = "1.0.0"
|
|
15
|
+
__all__ = [
|
|
16
|
+
"calcular_dv",
|
|
17
|
+
"validar_nit",
|
|
18
|
+
"formatear_nit",
|
|
19
|
+
"limpiar_nit",
|
|
20
|
+
"NITValidator",
|
|
21
|
+
"PESOS_DIAN",
|
|
22
|
+
]
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CLI para cálculo y validación de NIT DIAN desde la terminal.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import sys
|
|
6
|
+
import argparse
|
|
7
|
+
from .validator import calcular_dv, validar_nit, formatear_nit
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main():
|
|
11
|
+
parser = argparse.ArgumentParser(
|
|
12
|
+
description="Calcula o valida el Dígito de Verificación (DV) de un NIT según el algoritmo DIAN (Colombia)."
|
|
13
|
+
)
|
|
14
|
+
parser.add_argument(
|
|
15
|
+
"nit",
|
|
16
|
+
help="Número de NIT a evaluar (ej. '860007386', '860007386-1' o '860.007.386-1')."
|
|
17
|
+
)
|
|
18
|
+
parser.add_argument(
|
|
19
|
+
"-v", "--validate",
|
|
20
|
+
help="Dígito de verificación esperado para validar (opcional si el NIT ya incluye '-DV').",
|
|
21
|
+
default=None
|
|
22
|
+
)
|
|
23
|
+
parser.add_argument(
|
|
24
|
+
"-f", "--format",
|
|
25
|
+
action="store_true",
|
|
26
|
+
help="Imprime el NIT formateado con puntos de miles y guión de DV."
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
args = parser.parse_args()
|
|
30
|
+
|
|
31
|
+
try:
|
|
32
|
+
if args.format:
|
|
33
|
+
print(formatear_nit(args.nit, incluir_dv=True))
|
|
34
|
+
sys.exit(0)
|
|
35
|
+
|
|
36
|
+
# Si el input contiene guión o se pasó --validate, validamos
|
|
37
|
+
if '-' in args.nit or args.validate is not None:
|
|
38
|
+
es_valido = validar_nit(args.nit, args.validate)
|
|
39
|
+
if es_valido:
|
|
40
|
+
print(f"✅ VÁLIDO: El NIT {args.nit} coincide con el algoritmo oficial DIAN.")
|
|
41
|
+
sys.exit(0)
|
|
42
|
+
else:
|
|
43
|
+
print(f"❌ INVÁLIDO: El dígito de verificación del NIT {args.nit} es incorrecto.")
|
|
44
|
+
sys.exit(1)
|
|
45
|
+
else:
|
|
46
|
+
# Modo cálculo de DV
|
|
47
|
+
dv = calcular_dv(args.nit)
|
|
48
|
+
print(f"Dígito de Verificación (DV): {dv}")
|
|
49
|
+
print(f"NIT Completo: {formatear_nit(args.nit, incluir_dv=True)}")
|
|
50
|
+
sys.exit(0)
|
|
51
|
+
|
|
52
|
+
except Exception as e:
|
|
53
|
+
print(f"Error: {e}", file=sys.stderr)
|
|
54
|
+
sys.exit(2)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
if __name__ == "__main__":
|
|
58
|
+
main()
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Cálculo y Validación del Dígito de Verificación (DV) del NIT en Colombia.
|
|
3
|
+
Basado en el algoritmo oficial de la DIAN (Estatuto Tributario, Art. 375 y Decreto 2460 de 2013).
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from typing import Union, Tuple, Optional
|
|
7
|
+
import re
|
|
8
|
+
|
|
9
|
+
# Factores primos de ponderación oficial DIAN (hasta 15 dígitos, de derecha a izquierda)
|
|
10
|
+
PESOS_DIAN = [71, 67, 59, 53, 47, 43, 41, 37, 29, 23, 19, 17, 13, 7, 3]
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def limpiar_nit(nit: Union[str, int]) -> str:
|
|
14
|
+
"""
|
|
15
|
+
Limpia el NIT eliminando puntos, espacios y caracteres no numéricos.
|
|
16
|
+
Si incluye guión separador de DV (e.g. 860007386-1), extrae únicamente el cuerpo del NIT.
|
|
17
|
+
"""
|
|
18
|
+
nit_str = str(nit).strip()
|
|
19
|
+
if '-' in nit_str:
|
|
20
|
+
nit_str = nit_str.split('-')[0]
|
|
21
|
+
|
|
22
|
+
# Remover cualquier caracter no numérico
|
|
23
|
+
limpio = re.sub(r'\D', '', nit_str)
|
|
24
|
+
if not limpio:
|
|
25
|
+
raise ValueError(f"El NIT proporcionado '{nit}' no contiene dígitos numéricos válidos.")
|
|
26
|
+
if len(limpio) > len(PESOS_DIAN):
|
|
27
|
+
raise ValueError(
|
|
28
|
+
f"El NIT '{nit}' excede la longitud máxima soportada por la DIAN ({len(PESOS_DIAN)} dígitos)."
|
|
29
|
+
)
|
|
30
|
+
return limpio
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def calcular_dv(nit: Union[str, int]) -> int:
|
|
34
|
+
"""
|
|
35
|
+
Calcula el Dígito de Verificación (DV) de un NIT según el algoritmo Módulo 11 de la DIAN.
|
|
36
|
+
|
|
37
|
+
:param nit: Número de NIT (sin el dígito de verificación). Puede ser int o str.
|
|
38
|
+
:return: Dígito de verificación entre 0 y 9.
|
|
39
|
+
:raises ValueError: Si el NIT no contiene dígitos válidos o excede la longitud máxima.
|
|
40
|
+
"""
|
|
41
|
+
cuerpo = limpiar_nit(nit)
|
|
42
|
+
longitud = len(cuerpo)
|
|
43
|
+
|
|
44
|
+
# Seleccionar la sublista de pesos alineada a la derecha
|
|
45
|
+
pesos = PESOS_DIAN[-longitud:]
|
|
46
|
+
|
|
47
|
+
suma = sum(int(digito) * peso for digito, peso in zip(cuerpo, pesos))
|
|
48
|
+
residuo = suma % 11
|
|
49
|
+
|
|
50
|
+
if residuo in (0, 1):
|
|
51
|
+
return residuo
|
|
52
|
+
return 11 - residuo
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def validar_nit(nit: Union[str, int], dv: Optional[Union[str, int]] = None) -> bool:
|
|
56
|
+
"""
|
|
57
|
+
Valida si un NIT y su dígito de verificación son correctos.
|
|
58
|
+
|
|
59
|
+
Soporta múltiples formatos:
|
|
60
|
+
- validar_nit("860007386-1")
|
|
61
|
+
- validar_nit("860.007.386-1")
|
|
62
|
+
- validar_nit(860007386, 1)
|
|
63
|
+
- validar_nit("860007386", "1")
|
|
64
|
+
|
|
65
|
+
:param nit: NIT con o sin formato, opcionalmente con '-DV' al final.
|
|
66
|
+
:param dv: Dígito de verificación si no viene concatenado con guión.
|
|
67
|
+
:return: True si el DV coincide con el cálculo matemático oficial, False en caso contrario.
|
|
68
|
+
"""
|
|
69
|
+
nit_str = str(nit).strip()
|
|
70
|
+
|
|
71
|
+
if dv is None:
|
|
72
|
+
if '-' in nit_str:
|
|
73
|
+
partes = nit_str.rsplit('-', 1)
|
|
74
|
+
cuerpo = partes[0]
|
|
75
|
+
dv_esperado = partes[1].strip()
|
|
76
|
+
else:
|
|
77
|
+
raise ValueError(
|
|
78
|
+
"Debe proporcionar el dígito de verificación mediante el parámetro 'dv' "
|
|
79
|
+
"o en el formato 'NIT-DV' (ej. '860007386-1')."
|
|
80
|
+
)
|
|
81
|
+
else:
|
|
82
|
+
cuerpo = nit_str
|
|
83
|
+
dv_esperado = str(dv).strip()
|
|
84
|
+
|
|
85
|
+
try:
|
|
86
|
+
dv_esperado_int = int(dv_esperado)
|
|
87
|
+
except ValueError:
|
|
88
|
+
return False
|
|
89
|
+
|
|
90
|
+
try:
|
|
91
|
+
dv_calculado = calcular_dv(cuerpo)
|
|
92
|
+
return dv_calculado == dv_esperado_int
|
|
93
|
+
except ValueError:
|
|
94
|
+
return False
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def formatear_nit(nit: Union[str, int], incluir_dv: bool = True) -> str:
|
|
98
|
+
"""
|
|
99
|
+
Formatea un NIT con separadores de miles y guión de DV.
|
|
100
|
+
Ejemplo: 860007386 -> "860.007.386-1"
|
|
101
|
+
|
|
102
|
+
:param nit: NIT numérico o cadena.
|
|
103
|
+
:param incluir_dv: Si es True, calcula y añade el "-DV" al final.
|
|
104
|
+
:return: Cadena formateada.
|
|
105
|
+
"""
|
|
106
|
+
cuerpo = limpiar_nit(nit)
|
|
107
|
+
num = int(cuerpo)
|
|
108
|
+
# Formato con puntos de miles
|
|
109
|
+
formateado = f"{num:,}".replace(',', '.')
|
|
110
|
+
|
|
111
|
+
if incluir_dv:
|
|
112
|
+
dv = calcular_dv(cuerpo)
|
|
113
|
+
return f"{formateado}-{dv}"
|
|
114
|
+
return formateado
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
class NITValidator:
|
|
118
|
+
"""Clase utilitaria de conveniencia para validación y formateo de NITs."""
|
|
119
|
+
|
|
120
|
+
@staticmethod
|
|
121
|
+
def calcular_dv(nit: Union[str, int]) -> int:
|
|
122
|
+
return calcular_dv(nit)
|
|
123
|
+
|
|
124
|
+
@staticmethod
|
|
125
|
+
def validar(nit: Union[str, int], dv: Optional[Union[str, int]] = None) -> bool:
|
|
126
|
+
return validar_nit(nit, dv)
|
|
127
|
+
|
|
128
|
+
@staticmethod
|
|
129
|
+
def formatear(nit: Union[str, int], incluir_dv: bool = True) -> str:
|
|
130
|
+
return formatear_nit(nit, incluir_dv)
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "dian-nit-validator"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Librería y CLI en Python para cálculo y validación del Dígito de Verificación del NIT DIAN en Colombia (Módulo 11)."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [
|
|
11
|
+
{ name = "Kevin Andrey Herrera Silva", email = "kahs_kevin@hotmail.com" }
|
|
12
|
+
]
|
|
13
|
+
license = "MIT"
|
|
14
|
+
keywords = [
|
|
15
|
+
"dian",
|
|
16
|
+
"colombia",
|
|
17
|
+
"nit",
|
|
18
|
+
"validador-nit",
|
|
19
|
+
"modulo-11",
|
|
20
|
+
"digito-verificacion",
|
|
21
|
+
"facturacion-electronica",
|
|
22
|
+
"fintech"
|
|
23
|
+
]
|
|
24
|
+
classifiers = [
|
|
25
|
+
"Development Status :: 5 - Production/Stable",
|
|
26
|
+
"Intended Audience :: Developers",
|
|
27
|
+
"Intended Audience :: Financial and Insurance Industry",
|
|
28
|
+
"Programming Language :: Python :: 3",
|
|
29
|
+
"Programming Language :: Python :: 3.10",
|
|
30
|
+
"Programming Language :: Python :: 3.11",
|
|
31
|
+
"Programming Language :: Python :: 3.12",
|
|
32
|
+
"Programming Language :: Python :: 3.13",
|
|
33
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
34
|
+
"Topic :: Office/Business :: Financial :: Accounting"
|
|
35
|
+
]
|
|
36
|
+
requires-python = ">=3.10"
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Homepage = "https://github.com/KevinAndrey96/dian-nit-validator-python"
|
|
40
|
+
Repository = "https://github.com/KevinAndrey96/dian-nit-validator-python.git"
|
|
41
|
+
|
|
42
|
+
[project.scripts]
|
|
43
|
+
dian-nit = "nit_validator.cli:main"
|
|
44
|
+
nit-validator = "nit_validator.cli:main"
|
|
45
|
+
|
|
46
|
+
[tool.setuptools.packages.find]
|
|
47
|
+
include = ["nit_validator*"]
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Suite de pruebas unitarias para nit_validator.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import unittest
|
|
6
|
+
from nit_validator import calcular_dv, validar_nit, formatear_nit, NITValidator
|
|
7
|
+
from verification import verificar_nit
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class TestNITValidator(unittest.TestCase):
|
|
11
|
+
|
|
12
|
+
def test_calcular_dv_empresas_colombianas(self):
|
|
13
|
+
casos = [
|
|
14
|
+
("860007386", 1), # Bancolombia S.A.
|
|
15
|
+
("899999068", 1), # Ecopetrol S.A.
|
|
16
|
+
("890900050", 1), # Grupo Nutresa S.A.
|
|
17
|
+
("890900608", 9), # Almacenes Éxito S.A.
|
|
18
|
+
("800197268", 4), # DIAN (Dirección de Impuestos y Aduanas Nacionales)
|
|
19
|
+
("800000008", 0), # Residuo 0 -> DV 0
|
|
20
|
+
("800000001", 1), # Residuo 1 -> DV 1
|
|
21
|
+
(860007386, 1), # Entrada como entero
|
|
22
|
+
("860.007.386", 1),# Entrada con puntos
|
|
23
|
+
]
|
|
24
|
+
for nit, dv_esperado in casos:
|
|
25
|
+
with self.subTest(nit=nit, dv_esperado=dv_esperado):
|
|
26
|
+
self.assertEqual(calcular_dv(nit), dv_esperado)
|
|
27
|
+
self.assertEqual(NITValidator.calcular_dv(nit), dv_esperado)
|
|
28
|
+
|
|
29
|
+
def test_validar_nit_formatos(self):
|
|
30
|
+
# NITs válidos con diferentes formatos
|
|
31
|
+
self.assertTrue(validar_nit("860007386-1"))
|
|
32
|
+
self.assertTrue(validar_nit("860.007.386-1"))
|
|
33
|
+
self.assertTrue(validar_nit("860007386", 1))
|
|
34
|
+
self.assertTrue(validar_nit("860007386", "1"))
|
|
35
|
+
self.assertTrue(validar_nit(860007386, 1))
|
|
36
|
+
|
|
37
|
+
# NITs inválidos
|
|
38
|
+
self.assertFalse(validar_nit("860007386-2"))
|
|
39
|
+
self.assertFalse(validar_nit("860007386", 9))
|
|
40
|
+
self.assertFalse(validar_nit("860007386", "X"))
|
|
41
|
+
|
|
42
|
+
def test_formatear_nit(self):
|
|
43
|
+
self.assertEqual(formatear_nit(860007386), "860.007.386-1")
|
|
44
|
+
self.assertEqual(formatear_nit("860007386", incluir_dv=False), "860.007.386")
|
|
45
|
+
self.assertEqual(formatear_nit("860.007.386-1"), "860.007.386-1")
|
|
46
|
+
|
|
47
|
+
def test_compatibilidad_historica(self):
|
|
48
|
+
self.assertTrue(verificar_nit(860007386, 1))
|
|
49
|
+
self.assertFalse(verificar_nit(860007386, 5))
|
|
50
|
+
|
|
51
|
+
def test_entradas_invalidas(self):
|
|
52
|
+
with self.assertRaises(ValueError):
|
|
53
|
+
calcular_dv("ABCDE")
|
|
54
|
+
with self.assertRaises(ValueError):
|
|
55
|
+
calcular_dv("")
|
|
56
|
+
with self.assertRaises(ValueError):
|
|
57
|
+
# Excede los 15 dígitos máximos soportados por la DIAN
|
|
58
|
+
calcular_dv("123456789012345678")
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
if __name__ == '__main__':
|
|
62
|
+
unittest.main()
|