Documentación API - Consulta RNC

code

Documentación de la API

Guía completa para integrar la API de consulta de RNC

1. Buscar por RNC

Obtiene la información de un contribuyente específico por su RNC.

Endpoint:

GET /api/rnc/:rnc

Ejemplo de uso:

cURL:

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

JavaScript (Fetch):

fetch('http://localhost:3000/api/rnc/123456789')

Respuesta exitosa (200):

{
  "id": 1,
  "rnc": "123456789",
  "razon_social": "EMPRESA EJEMPLO SRL",
  "actividad_economica": "SERVICIOS DE CONSULTORÍA EMPRESARIAL",
  "fecha_inicio_operaciones": "15/03/2020",
  "estado": "ACTIVO",
  "regimen_pago": "NORMAL",
  "fecha_carga": "2024-11-19T14:30:00.000Z"
}

2. Buscar por Nombre

Busca contribuyentes por nombre o razón social (búsqueda parcial, no case-sensitive).

Endpoint:

GET /api/buscar?nombre=:nombre&limit=:limit

Parámetros:

nombre
(requerido) - Texto a buscar en la razón social
limit
(opcional) - Número máximo de resultados (default: 10, máx: 100)

Ejemplo de uso:

cURL:

curl "http://localhost:3000/api/buscar?nombre=EMPRESA&limit=5"

JavaScript (Fetch):

fetch('http://localhost:3000/api/buscar?nombre=EMPRESA&limit=5')

Respuesta exitosa (200):

[
  {
    "id": 1,
    "rnc": "123456789",
    "razon_social": "EMPRESA EJEMPLO SRL",
    "actividad_economica": "SERVICIOS DE CONSULTORÍA EMPRESARIAL",
    "fecha_inicio_operaciones": "15/03/2020",
    "estado": "ACTIVO",
    "regimen_pago": "NORMAL",
    "fecha_carga": "2024-11-19T14:30:00.000Z"
  },
  {
    "id": 2,
    "rnc": "987654321",
    "razon_social": "EMPRESA COMERCIAL ABC",
    "actividad_economica": "VENTA AL POR MENOR DE PRODUCTOS VARIOS",
    "fecha_inicio_operaciones": "10/06/2018",
    "estado": "ACTIVO",
    "regimen_pago": "RST",
    "fecha_carga": "2024-11-19T14:30:00.000Z"
  }
]

3. Estadísticas

Obtiene estadísticas generales de la base de datos de contribuyentes.

Endpoint:

GET /api/stats

Ejemplo de uso:

cURL:

curl http://localhost:3000/api/stats

JavaScript (Fetch):

fetch('http://localhost:3000/api/stats')

Respuesta exitosa (200):

{
  "total": 345283,
  "activos": 345283,
  "regimenes": [
    {
      "regimen_pago": "NORMAL",
      "cantidad": "313981"
    },
    {
      "regimen_pago": "RST",
      "cantidad": "31302"
    }
  ]
}

Códigos de Error

400

Bad Request

Parámetros faltantes o inválidos

{"error": "Parámetro nombre requerido"}

404

Not Found

RNC no encontrado en la base de datos

{"error": "RNC no encontrado"}

500

Internal Server Error

Error en el servidor o base de datos

{"error": "Error al consultar la base de datos"}

info

Notas Importantes

check_circle Todos los endpoints devuelven respuestas en formato JSON
check_circle La búsqueda por nombre no es case-sensitive (mayúsculas/minúsculas)
check_circle Solo se incluyen RNC con estado ACTIVO en la base de datos
check_circle Los datos fueron actualizados el 15 de noviembre de 2025
check_circle No se requiere autenticación para usar la API