API DGII RNC — Documentacion Completa

API comunitaria para consultar el Registro Nacional de Contribuyentes (RNC) de la DGII (República Dominicana).

Desarrollado por Boyer Marketing.

Estado: Activo · Versión: 1.0.0 · Licencia: MIT

---

📚 Índice

• Descripción

• Características

• Arquitectura & Estructura

• Instalación & Ejecución

• Configuración

• Dataset: Descarga, Formato y Actualización

• API Reference

• Esquema de Datos

• Interfaz Web (Frontend)

• Rendimiento y Requisitos

• Seguridad

• Registro & Manejo de Errores

• Despliegue (PM2 / Docker / Servicios)

• Pruebas Rápidas

• Resolución de Problemas

• Roadmap

• Licencia y Crédito

---

🧩 Descripción

Esta aplicación ofrece:

• Un servidor REST en Node.js (Express) para consultar contribuyentes por RNC, nombre o búsqueda avanzada.

• Una biblioteca que descarga, descomprime y procesa el dataset oficial diariamente desde la DGII, leyendo el TXT interno codificado en Latin-1.

• Un frontend web (HTML/CSS/JS) con documentación, ejemplos y un demo interactivo.

El proyecto es 100% JavaScript, sin dependencias de Python, e implementa la lógica de descarga/extracción/parseo y búsqueda local sobre ~735 000 registros.

---

✨ Características

• API REST completa: /api/health, /api/dataset, /api/rnc/:id, /api/nombre/:nombre, /api/search

• Descarga y actualización automática del dataset (verifica fecha del archivo y vuelve a descargar si cambió)

• Extracción de TMP/DGII_RNC.TXT desde el ZIP oficial con adm-zip y codificación Latin-1

• Frontend responsive con navegación lateral, secciones de referencia y demo

• CORS habilitado, validaciones y manejo centralizado de errores

---

🏗️ Arquitectura & Estructura

Diagrama (alto nivel)

flowchart LR
  A[Cliente Frontend] <--> B[Express API]
  B -->|usa| C[Lib RNC]
  C -->|descarga| D[(ZIP DGII)]
  C -->|extrae TXT| E[(data/DGII_RNC.TXT)]
  C -->|parsea| F[(Memoria)]

Loading

Estructura del repo

dgii-rnc-api/

├─ server.js # Servidor Express (+ rutas, CORS, logs, errores)

├─ lib/

│ └─ dgii-rnc.js # Lógica: descarga, extracción TXT, carga y búsqueda

├─ public/

│ └─ index.html # Documentación visual + demo interactivo

├─ data/

│ └─ DGII_RNC.TXT # Generado automáticamente (Latin-1, '|' delimitado)

├─ package.json # Dependencias y scripts (start/dev)

├─ package-lock.json # Versionado exacto de dependencias

├─ README.md # Docs (parciales) existentes

└─ README-API.md # Docs adicionales de API

---

🚀 Instalación & Ejecución

Requisitos: Node.js 14+, npm o yarn, conexión a Internet para la primera descarga de datos.

# 1) Instala dependencias

npm  install

  

# 2) Desarrollo (con nodemon)

npm  run  dev  # nodemon server.js

  

# 3) Producción

npm  start  # node server.js

Acceso rápido:

• Frontend: http://localhost:3000

• Health: http://localhost:3000/api/health

---

⚙️ Configuración

Variables de entorno (opcionales)

PORT=3000

NODE_ENV=development # o production

Por defecto, el servidor usa PORT o 3000. El modo afecta mensajes de error detallados.

Scripts (npm)

• start: node server.js

• dev: nodemon server.js

Dependencias clave

| Paquete | Uso |

| ------------- | ---------------------------- |

| express | Servidor HTTP/REST |

| cors | CORS middleware |

| body-parser | Parseo JSON/URL-encoded |

| adm-zip | Lectura ZIP + extracción TXT |

| nodemon (dev) | Recarga en desarrollo |

---

🗃️ Dataset: Descarga, Formato y Actualización

• URL fuente (en la librería): https://dgii.gov.do/app/WebApps/Consultas/RNC/DGII_RNC.zip

• Ruta interna extraída: TMP/DGII_RNC.TXT (dentro del ZIP)

• Codificación: latin1

• Delimitador: | (pipe)

• Ubicación local: data/DGII_RNC.TXT

Flujo:

1. Si data/DGII_RNC.TXT no existe → descarga el ZIP, extrae el TXT y guarda.

2. Si existe, compara la fecha del archivo con la fecha actual (día) → si no coincide, re-descarga.

3. Tras asegurar el TXT, carga a memoria (this.df) mapeando columnas.

El dataset reporta ~735 000+ registros, de acuerdo con la documentación del proyecto y la UI.

---

📡 API Reference

Todas las rutas devuelven JSON y registran peticiones con timestamp. Errores centralizados con códigos HTTP adecuados.

Health Check

GET /api/health

Respuesta 200:

{

"status":"OK",

"message":"API DGII RNC funcionando correctamente",

"timestamp":"2025-10-30T00:00:00.000Z",

"version":"1.0.0"

}

Dataset completo

GET /api/dataset

Respuesta 200:

{

"success": true,

"data": [ /* array de registros */ ],

"count": 735000,

"timestamp": "2025-10-30T00:00:00.000Z"

}

Errores: 500 en caso de fallo de lectura/descarga.

Buscar por RNC exacto

GET /api/rnc/:id

• Búsqueda exacta por ID (string, 9–11 dígitos).

• 200 si encuentra, 404 si no hay coincidencias.

Respuesta 200:

{

"success": true,

"data": {

"ID":"401007551",

"NOMBRE":"BANCO CENTRAL DE LA REPUBLICA DOMINICANA",

"NOMBRE_COMERCIAL":"BANCO CENTRAL",

"CATEGORIA":"SERVICIOS FINANCIEROS",

"FECHA":"YYYY-MM-DD",

"REGIMEN_PAGO":"X",

"ESTADO":"ACTIVO"

},

"timestamp":"2025-10-30T00:00:00.000Z"

}

Respuesta 404:

{ "success": false, "error": "RNC no encontrado" }

Buscar por nombre (contiene, case-insensitive)

GET /api/nombre/:nombre

• Filtra por NOMBRE conteniendo el valor suministrado (normalizado a mayúsculas).

• 200 con arreglo de coincidencias (puede ser vacío).

Respuesta 200:

{

"success": true,

"data": [ /* coincidencias */ ],

"count": 12,

"timestamp":"2025-10-30T00:00:00.000Z"

}

Búsqueda avanzada (múltiples criterios)

POST /api/search

Content-Type: application/json

  

{

"criteria": {

"ID": "401007551",

"NOMBRE": "BANCO CENTRAL",

"NOMBRE_COMERCIAL": "COMERCIAL",

"CATEGORIA": "COMERCIO"

}

}

• criteria debe ser un objeto; de lo contrario → 400 con mensaje explicativo.

• Combina filtros: ID exacto, los demás por contiene (case-insensitive).

• 200 con coincidencias. Errores 500 si falla la operación.

Respuesta 400:

{ "success": false, "error": "Se requiere un objeto \"criteria\" con los criterios de búsqueda" }

---

🧾 Esquema de Datos

Los registros mapeados desde el TXT son objetos con campos:

| Campo | Fuente TXT | Descripción |

| ------------------ | ---------- | --------------------------------------- |

| ID | col 0 | Número de RNC |

| NOMBRE | col 1 | Razón social / nombre del contribuyente |

| NOMBRE_COMERCIAL | col 2 | Nombre comercial |

| CATEGORIA | col 3 | Actividad económica |

| FECHA | col 8 | Fecha de registro |

| REGIMEN_PAGO | col 9 | Régimen de pago |

| ESTADO | col 10 | Estado del contribuyente |

El parseo separa por | y aplica trim() a cada campo. Codificación de lectura: Latin-1.

---

🖥️ Interfaz Web (Frontend)

El archivo public/index.html provee:

• Navegación lateral con secciones Inicio, Inicio Rápido, Características, Endpoints, Ejemplos, Demo, Estructura de Datos, Errores, Instalación, Aviso Legal.

• Bloques de código etiquetados, tablas, alertas de estado, y una demo interactiva.

• Schema.org (WebAPI) embebido y diseño con la estética de Boyer Marketing.

---

⚡ Rendimiento y Requisitos

• Primera carga (descarga + parseo): ~30 s (estimado)

• Búsqueda local: ~<1 s (en memoria, filtros en JS)

• Tamaño: ~150 MB (TXT descomprimido)

• RAM: 512 MB mínimo (1 GB recomendado)

El rendimiento depende del hardware y del tamaño real del dataset del día.

---

🔒 Seguridad

• CORS habilitado (dominios abiertos por defecto)

• Validación de inputs para endpoints con criteria y rutas paramétricas

• Manejo consistente de errores y ocultación de mensajes internos en production

Nota: Esta API es comunitaria y no implementa autenticación por defecto. Si se expone públicamente, agregue API keys, rate limiting y WAF/Reverse Proxy según su contexto.

---

🪵 Registro & Manejo de Errores

• Logging básico: middleware que imprime timestamp, método y ruta.

• 404 genérico para cualquier ruta inexistente.

• Error handler global: responde 500 con mensaje genérico (o detallado en desarrollo).

---

🚢 Despliegue (PM2 / Docker / Servicios)

Opción A – PM2 (recomendada en VPS/Linux)

npm  ci

npm  run  build  # (si aplica en el futuro)

pm2  start  server.js  --name  dgii-rnc-api

pm2  save

pm2  startup

Opción B – Docker (ejemplo de Dockerfile mínimo)

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm ci --only=production

COPY . .

ENV NODE_ENV=production

ENV PORT=3000

EXPOSE 3000

CMD ["node", "server.js"]

docker  build  -t  dgii-rnc-api  .

docker  run  --name  dgii-rnc  -p  3000:3000  dgii-rnc-api

Opción C – Servicio systemd (Linux)

[Unit]

Description=DGII RNC API

After=network.target

  

[Service]

Type=simple

User=www-data

WorkingDirectory=/opt/dgii-rnc-api

ExecStart=/usr/bin/node server.js

Restart=always

Environment=NODE_ENV=production

Environment=PORT=3000

  

[Install]

WantedBy=multi-user.target

---

✅ Pruebas Rápidas

cURL

# Health

curl  http://localhost:3000/api/health

  

# Por RNC

curl  http://localhost:3000/api/rnc/401007551

  

# Por nombre

curl  "http://localhost:3000/api/nombre/BANCO%20CENTRAL"

  

# Búsqueda avanzada

curl  -X  POST  http://localhost:3000/api/search  \

-H "Content-Type: application/json" \

-d  '{"criteria":{"NOMBRE":"SUPERMERCADOS","CATEGORIA":"COMERCIO"}}'

---

🧩 Resolución de Problemas

• No encuentra el archivo TXT / 500 al buscar

• Verifique conexión a Internet para la primera descarga.

• Revise permisos del directorio data/.

• Chequee logs de servidor para códigos HTTP de la descarga.

• Resultados vacíos al buscar por nombre

• Recuerde que el filtro es por contiene (case-insensitive), pero depende del texto exacto en DGII. Pruebe términos más cortos.

• Memoria alta

• El dataset se carga en memoria para acelerar búsquedas. Considere aumentar RAM o paginar respuestas a futuro.

---

🗺️ Roadmap

• Autenticación opcional por API Key / Token

• Rate limiting y caching

• Paginación en /api/dataset y /api/nombre

• Filtros adicionales (provincia, estado, fechas)

• CLI de administración y cron interno de actualización

---

📜 Licencia y Crédito

• Licencia: MIT (ver archivo de licencia del proyecto)

• Créditos base: Inspirado en el proyecto Python lcgarc1a/dgii_rnc.

---

📎 Referencias internas (fuentes del repo)

• package.json / dependencias y scripts

• package-lock.json / versiones exactas

• README.md (doc. general existente)

• README-API.md (doc. de API existente)

• server.js (rutas, CORS, logs, errores)

• public/index.html (frontend/documentación/demo)

• lib/dgii-rnc.js (descarga, extracción, parseo, búsqueda)

---

🏁 Contacto

📍 Punta Cana, República Dominicana
🌐 www.marketingboyer.com
📞 +1 (829) 250-2341