DGII RNC – Biblioteca de Node.js

Este paquete ofrece un sencillo envoltorio en Node.js para el conjunto de datos del Registro Nacional de Contribuyentes (RNC) de la República Dominicana, publicado por la Dirección General de Impuestos Internos (DGII). Está basado en el trabajo de Boyer Marketing pero se empaquetó para que pueda consumirse desde tus propias aplicaciones y frameworks sin necesidad de ejecutar un servidor API completo.

Características

• Descarga automática del dataset – La primera vez que llamas a cualquier método de consulta, la biblioteca descargará el ZIP más reciente del RNC de la DGII, extraerá el archivo DGII_RNC.TXT y lo almacenará en caché localmente.
• Actualizaciones periódicas – Ofrece un helper llamado scheduleUpdates que comprueba si hay un nuevo dataset en un intervalo configurable (por defecto una vez al día). También puedes ejecutar el CLI incluido (dgii-rnc-update) manualmente o mediante cron.
• API de búsqueda sencilla – Permite buscar por ID de RNC, NOMBRE de la empresa o NOMBRE_COMERCIAL con coincidencias sin distinción de mayúsculas. Todo el dataset se carga en memoria para búsquedas rápidas.
• Almacenamiento configurable – Por defecto el archivo de datos se almacena en un directorio oculto dentro de la carpeta de inicio del usuario (~/.dgii-rnc/DGII_RNC.TXT). Puedes cambiar esta ruta mediante la variable de entorno DGII_RNC_DATA_PATH o pasando un objeto de opciones al constructor de RNCHandler.

Instalación

Instalar con npm:

npm install dgii-rnc

o con yarn:

 yarn add dgii-rnc

Uso

Importa la biblioteca en tu código e instancia un RNCHandler. La primera llamada desencadenará la descarga del dataset si es necesario.

const { RNCHandler, scheduleUpdates } = require('dgii-rnc');

// Crea una instancia. Puedes pasar opciones aquí para personalizar la ruta del dataset
const handler = new RNCHandler({
  // opcional: ruta absoluta donde guardar el dataset
  // dataPath: '/ruta/personalizada/DGII_RNC.TXT'
});

async function run() {
  // Buscar por ID de RNC
  const company = await handler.search({ ID: '401007551' });
  console.log(company);

  // Buscar por nombre (sin distinguir mayúsculas/minúsculas)
  const banks = await handler.search({ NOMBRE: 'banco' });
  console.log(`Encontradas ${banks.length} entradas que coinciden con \"banco\"`);
}
run();

// Opcionalmente configura una actualización periódica (por defecto cada 24 horas)
scheduleUpdates({ handler });

CLI

El paquete expone una pequeña interfaz de línea de comandos que comprueba y actualiza el dataset. Puede utilizarse en un cron o manualmente desde la terminal.

npx dgii-rnc-update

En cada ejecución, el script descargará el archivo ZIP de los servidores de la DGII (si la copia local está desactualizada), extraerá el archivo DGII_RNC.TXT más reciente y sobrescribirá el archivo en caché.

Programación con cron

Para comprobar si hay actualizaciones todos los días a las 3 a.m., añade la siguiente línea a tu crontab (crontab -e):

0 3 * * * npx dgii-rnc-update >> /var/log/dgii-rnc-update.log 2>&1

API

new RNCHandler(options?: { dataPath?: string; zipUrl?: string; })

Construye un nuevo manejador. La opción dataPath define dónde se guardará el archivo DGII_RNC.TXT; debe ser una ruta absoluta. Por defecto, el archivo se guarda en path.join(os.homedir(), '.dgii-rnc', 'DGII_RNC.TXT'). También puedes sobrescribir la URL del ZIP de origen mediante zipUrl (no recomendado).

handler.search(criteria: { ID?: string; NOMBRE?: string; NOMBRE_COMERCIAL?: string; }): Promise<Array<Record>>

Busca en el dataset de forma local. Las claves soportadas son:

• ID – coincidencia exacta del identificador de RNC.
• NOMBRE – coincidencia parcial (subcadena) del nombre formal de la empresa, sin distinción de mayúsculas.
• NOMBRE_COMERCIAL – coincidencia parcial (subcadena) del nombre comercial, sin distinción de mayúsculas.

Devuelve un array de registros coincidentes; si se proporciona ID, el array contendrá como máximo un elemento.

handler.rncDf(): Promise<Array<Record>>

Devuelve el dataset completo como un array de objetos. Este método desencadenará una descarga si el archivo local no existe o está desactualizado.

handler.checkFile(): Promise<void>

Helper interno que comprueba la fecha de modificación del dataset en caché. Si el archivo no está presente o es anterior al día actual, descarga el último archivo y lo reprocesa.

scheduleUpdates(options?: { handler?: RNCHandler; intervalMs?: number; }): void

Programa actualizaciones periódicas del dataset. El intervalo por defecto es de 24 horas (86 400 000 ms). Puedes pasar una instancia existente de RNCHandler mediante handler; si se omite, se crea una de forma perezosa. Llamar a esta función configura un temporizador con setInterval y devuelve inmediatamente.

Licencia

MIT – ver LICENSE para más detalles. Ten en cuenta que los datos subyacentes provienen de la DGII y están sujetos a sus términos de uso.