calculateDv

Paquete: @tiendana/utils

Calcula el dígito de verificación (DV) para NITs colombianos utilizando el algoritmo Módulo 11 establecido por la DIAN.

Características

✅ Algoritmo oficial DIAN
✅ Soporta NITs de cualquier longitud (hasta 15 dígitos)
✅ Limpieza automática de caracteres no numéricos
✅ Type-safe con TypeScript
✅ Sin dependencias externas

Firma

function calculateDv(nit: string): number

Parámetros

Parámetro	Tipo	Descripción	Requerido
nit	string	Número de identificación tributaria sin dígito de verificación	✅

Retorno

Tipo: number

El dígito de verificación calculado (0-9).

Ejemplos de Uso

Cálculo Básico

import { calculateDv } from '@tiendana/utils';

// NIT simple
const dv = calculateDv('900123456');
console.log(dv);
// Retorna el dígito verificador (0-9)

// Mostrar NIT completo
const nit = '900123456';
console.log(`${nit}-${calculateDv(nit)}`);
// "900123456-X"

Con Caracteres Especiales

// La función limpia automáticamente caracteres no numéricos
calculateDv('900.123.456');     // Limpia puntos
calculateDv('900-123-456');     // Limpia guiones
calculateDv('900 123 456');     // Limpia espacios
calculateDv(' 900123456 ');     // Limpia espacios al inicio/fin

// Todos retornan el mismo resultado

Validación de NIT Existente

function validateNit(nitWithDv: string): boolean {
  // Formato esperado: 123456789-X
  const [nit, expectedDv] = nitWithDv.split('-');
  
  if (!nit || !expectedDv) {
    return false;
  }
  
  const calculatedDv = calculateDv(nit);
  return calculatedDv === parseInt(expectedDv, 10);
}

validateNit('900123456-7');  // true o false según el DV correcto

Formateo de NIT

function formatNit(nit: string): string {
  const cleanNit = nit.replace(/\D+/g, '');
  const dv = calculateDv(cleanNit);
  
  // Formato con puntos de miles
  const formatted = cleanNit.replace(/\B(?=(\d{3})+(?!\d))/g, '.');
  
  return `${formatted}-${dv}`;
}

formatNit('900123456');
// "900.123.456-X"

En Formularios de Registro

interface CompanyData {
  nit: string;
  name: string;
  // ...
}

function createCompany(data: CompanyData) {
  const dv = calculateDv(data.nit);
  
  return {
    ...data,
    nitCompleto: `${data.nit}-${dv}`,
    digitoVerificacion: dv
  };
}

Validación de Formulario Angular

import { AbstractControl, ValidationErrors } from '@angular/forms';
import { calculateDv } from '@tiendana/utils';

function validateNitDv(control: AbstractControl): ValidationErrors | null {
  const value = control.value;
  
  if (!value) return null;
  
  // Formato esperado: NIT-DV (ej: 900123456-7)
  const match = value.match(/^(\d+)-(\d)$/);
  
  if (!match) {
    return { invalidFormat: true };
  }
  
  const [, nit, dv] = match;
  const expectedDv = calculateDv(nit);
  
  if (parseInt(dv, 10) !== expectedDv) {
    return { invalidDv: true };
  }
  
  return null;
}

Auto-completar DV en Input

// React/Angular ejemplo de auto-completar
function onNitChange(nit: string) {
  const cleanNit = nit.replace(/\D+/g, '');
  
  if (cleanNit.length >= 8) {
    const dv = calculateDv(cleanNit);
    setNitWithDv(`${cleanNit}-${dv}`);
  }
}

Algoritmo

El cálculo del dígito de verificación utiliza el algoritmo Módulo 11 con los siguientes factores de ponderación:

const factors = [3, 7, 13, 17, 19, 23, 29, 37, 41, 43, 47, 53, 59, 67, 71];

Pasos del Algoritmo

1. Limpiar el NIT: Remover caracteres no numéricos
2. Multiplicar cada dígito por su factor correspondiente (de derecha a izquierda)
3. Sumar todos los productos
4. Calcular módulo 11 del total
5. Si el residuo es > 1: DV = 11 - residuo
6. Si el residuo es 0 o 1: DV = residuo

Ejemplo de Cálculo

Para el NIT 900123456:

Posición	Dígito	Factor	Producto
1	6	3	18
2	5	7	35
3	4	13	52
4	3	17	51
5	2	19	38
6	1	23	23
7	0	29	0
8	0	37	0
9	9	41	369

Suma: 586
Módulo 11: 586 % 11 = 3
DV: 11 - 3 = 8

Casos de Uso Comunes

• Registro de empresas: Calcular DV al registrar nuevas empresas
• Validación de facturas: Verificar NITs en facturación electrónica
• Importación de datos: Calcular DVs faltantes en migraciones
• Formularios: Auto-completar el DV cuando el usuario ingresa el NIT
• Integración DIAN: Validar NITs antes de enviar documentos electrónicos

Notas Técnicas

Longitud del NIT

Los NITs en Colombia pueden tener entre 8 y 15 dígitos. La función soporta cualquier longitud dentro de este rango.

Validación previa

La función asume que se le pasa un NIT válido (solo dígitos o con separadores). No valida si el NIT existe realmente en la DIAN.

// ✅ Correcto
calculateDv('900123456');

// ⚠️ Funciona pero limpia los caracteres
calculateDv('NIT-900123456');  // Extrae "900123456"

// ❌ Incorrecto - NIT vacío después de limpiar
calculateDv('ABC');  // 0 (sin dígitos, no es un DV real)

// ❌ Más de 15 dígitos
calculateDv('1234567890123456');  // NaN

Recomendación

Antes de calcular el DV, valida que el input contenga un NIT válido:

function isValidNitFormat(nit: string): boolean {
  const clean = nit.replace(/\D+/g, '');
  return clean.length >= 8 && clean.length <= 15;
}

if (isValidNitFormat(nit)) {
  const dv = calculateDv(nit);
}

Referencia

• Resolución 000042 de 2020 - DIAN: Especificación oficial del algoritmo
• Decreto 624 de 1989: Estatuto Tributario - Definición del NIT

Ver También

• hasValue - Para validar que el NIT no esté vacío
• Patterns - Patrones regex para validación de formatos