Ir al contenido
Franklin Martinez
Todo el trabajo

dgii-ts

Librería open source de validación e integración con la DGII para TypeScript

Resumen. dgii-ts es una librería open source de TypeScript para trabajar con identificadores fiscales dominicanos como el RNC, la cédula, el NCF y el e-NCF. Los valida y los consulta contra la DGII, la autoridad tributaria del país.

Dígito430587125
× Peso79865432
Producto2827030402834
Suma 160160 mod 11 = 6Dígito verificador: esperado 5, recibido 5

RNC: los dígitos 1 a 8 por los pesos 7, 9, 8, 6, 5, 4, 3, 2. El residuo de la suma entre 11 da el dígito verificador.

validateRnc("430587125"){valid: true, formatted: "4-30-58712-5"}

Válido

Fig. 3. dgii-ts 0.3.0 desde npm, importada por esta página. Los pasos muestran la aritmética del dígito verificador; el resultado es el de la librería. Los números de ejemplo son inventados.

El problema

La DGII, la autoridad tributaria dominicana, no tiene una API REST pública, y apagó su viejo servicio SOAP en enero de 2025. Todo lo que necesita verificar un RNC o un NCF dominicano ha dependido de scrapers de viejas páginas ASP.NET cuyas URL cambian de lugar, y eso rompe en silencio cada integración que depende de ellas.

El diseño

dgii-ts esconde todo eso detrás de un cliente tipado construido por capas: validación offline del dígito verificador para RNC, cédula, NCF (serie B) y e-NCF (serie E) que nunca toca la red; consultas en vivo que hacen scraping de las páginas de la DGII cuando hacen falta datos actuales; un cliente con circuit breaker y reintentos con backoff, para que una mala respuesta no se propague; y una importación masiva del dataset diario de RNC de la DGII.

La Fig. 3 de arriba es la propia librería, importada desde npm y corriendo en esta página. La aritmética del dígito verificador se dibuja paso a paso, y el veredicto es el de la librería. Un número que no cumple el algoritmo puede ser real igual: dgii-ts trae listas blancas de cédulas y RNC que la DGII emitió de todos modos, tomadas de python-stdnum.

Lo que se publica

npm install dgii-ts

En npm con licencia MIT y CI, más un skill para agentes, para que un agente de código use los validadores offline antes de ir a la red.

Hablar de este proyecto