Librería TypeScript para validación e integración con la DGII de República Dominicana — RNC, cédula, NCF, e-NCF.
La Dirección General de Impuestos Internos (DGII) no ofrece un API REST público para consultas básicas de RNC o NCF. Los desarrolladores dominicanos dependen de scrapers frágiles que parsean páginas ASP.NET con ViewState — y esas páginas han cambiado de URL al menos tres veces, rompiendo cada integración existente.
dgii-ts resuelve esto con un enfoque de cuatro capas diseñado para resiliencia:
- Validación offline — nunca falla, cero llamadas de red
- Web scraping — consultas en tiempo real contra las páginas ASP.NET de la DGII
- Cliente SOAP (deprecated) — wrapper del servicio WSMovilDGII, bloqueado por la DGII en enero 2025
- Datos masivos — importación del archivo diario DGII_RNC.zip
Validación algorítmica de dígitos verificadores para RNC (9 dígitos), cédula (11 dígitos), NCF (serie B) y e-NCF (serie E). Sin dependencias de red, sin puntos de fallo externos. Incluye whitelists de 578 cédulas y 23 RNCs (fuente: python-stdnum) que pasan validación aunque no cumplan el algoritmo de dígito verificador.
DgiiClient es el punto de entrada recomendado para consultas en tiempo real.
Usa web scraping como estrategia primaria con fallback a SOAP, circuit breaker
para evitar cascadas de errores, y retry con backoff exponencial.
Consulta las páginas ASP.NET de la DGII extrayendo tokens ViewState y parseando el HTML de respuesta. Es la estrategia principal desde que la DGII bloqueó el endpoint SOAP en enero 2025.
Wrapper tipado alrededor del servicio SOAP de la DGII. Bloqueado permanentemente por la DGII en enero 2025. Se mantiene como fallback interno pero no se recomienda su uso directo.
Descarga y parseo del archivo ZIP diario de contribuyentes que publica la DGII
(DGII_RNC.zip). Ideal para operaciones en lote y búsquedas locales rápidas.
npm install dgii-tspnpm add dgii-tsyarn add dgii-tsimport { validateRnc } from 'dgii-ts';
const result = validateRnc('131098193');
// { valid: true, formatted: '1-31-09819-3' }import { validateCedula } from 'dgii-ts';
const result = validateCedula('00114272360');
// { valid: true, formatted: '001-1427236-0' }import { validateNcf } from 'dgii-ts';
const result = validateNcf('B0100000001');
// { valid: true, type: 'CREDITO_FISCAL', serie: 'B01' }import { validateEcf } from 'dgii-ts';
const result = validateEcf('E310000000001');
// { valid: true, type: 'CREDITO_FISCAL_ELECTRONICA', serie: 'E31' }import { validateRnc } from 'dgii-ts/validators';Los submódulos disponibles son dgii-ts/validators, dgii-ts/client,
dgii-ts/scraping, dgii-ts/soap, dgii-ts/bulk y dgii-ts/errors.
import { DgiiClient } from 'dgii-ts/client';
const client = new DgiiClient();
const result = await client.getContribuyente('131098193');
// { rnc: '131098193', nombre: '...', estado: '...', ... }const ncfResult = await client.getNCF('131098193', 'B0100000001');
// { rnc: '131098193', ncf: 'B0100000001', estado: '...', ... }| Función | Descripción |
|---|---|
validateRnc(value) |
Valida RNC de 9 dígitos con dígito verificador |
validateCedula(value) |
Valida cédula de 11 dígitos con dígito verificador |
validateNcf(value) |
Valida formato y tipo de NCF (serie B) |
validateEcf(value) |
Valida formato y tipo de e-NCF (serie E) |
| Clase/Método | Descripción |
|---|---|
DgiiClient |
Cliente con scraping + SOAP fallback, circuit breaker y retry |
client.getContribuyente(rnc) |
Consulta datos de un contribuyente por RNC |
client.getNCF(rnc, ncf) |
Valida un comprobante fiscal contra la DGII |
| Clase/Método | Descripción |
|---|---|
ScrapingClient |
Consulta páginas ASP.NET de la DGII |
client.getContribuyente(rnc) |
Consulta contribuyente por RNC |
client.getNCF(rnc, ncf) |
Valida comprobante fiscal |
| Clase/Método | Descripción |
|---|---|
DgiiSoapClient |
Cliente para WSMovilDGII (bloqueado) |
client.getContribuyente(rnc) |
Consulta contribuyente por RNC |
client.getNCF(rnc, ncf) |
Valida comprobante fiscal |
| Clase/Método | Descripción |
|---|---|
downloadBulkFile(options) |
Descarga DGII_RNC.zip |
parseBulkFile(options) |
Parsea el archivo TXT |
┌─────────────────────────────────────────────────┐
│ Tu aplicación │
├─────────────────────────────────────────────────┤
│ Capa 1: Validación offline │
│ ✓ Check-digit RNC/Cédula ✓ Formato NCF/e-NCF │
├─────────────────────────────────────────────────┤
│ Capa 2: DgiiClient (resiliente) │
│ ✓ Web scraping (primario) │
│ ✓ SOAP fallback ✓ Circuit breaker ✓ Retry │
├─────────────────────────────────────────────────┤
│ Capa 3: Datos masivos (DGII_RNC.zip) │
│ ✓ Descarga diaria ✓ Parseo TXT │
└─────────────────────────────────────────────────┘
La capa 1 es instantánea y funciona sin conexión. La capa 2 ofrece datos en tiempo real con web scraping como estrategia primaria, fallback a SOAP, circuit breaker y retry con backoff exponencial. La capa 3 es ideal para operaciones en lote donde necesitas buscar miles de RNC rápidamente.
- Validación offline (RNC, cédula, NCF, e-NCF)
- Web scraping de las páginas ASP.NET de la DGII
- Cliente SOAP WSMovilDGII (deprecated — bloqueado por la DGII)
- Cliente resiliente con circuit breaker y retry
- Importador DGII_RNC.zip (descarga + parseo)
- Publicado en npm
Para reportar vulnerabilidades, consulta SECURITY.md.
Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para más detalles.
Esta es una librería comunitaria independiente, no está afiliada ni respaldada por la DGII. Para datos fiscales críticos, verifica siempre con un profesional contable autorizado.