Cómo integrar la consulta de RNC en tu sistema con nuestra API

Validar el RNC de un cliente o proveedor a mano funciona para unos pocos casos; cuando tu sistema de facturación, compras o contabilidad maneja decenas, conviene que lo haga solo. Esta guía muestra cómo integrar la API gratuita de consulta de RNC de Directorio RNC: los endpoints, el formato de respuesta, ejemplos en cuatro lenguajes, cómo manejar errores y límites, y qué hacer para usarla bien.

Aviso: es un servicio gratuito y no oficial. Usa datos públicos de la DGII, actualizados diariamente, y se ofrece sin garantía. No sustituye los servicios de la DGII para trámites oficiales. Soporte: [email protected].

Lo esencial

• Base: https://api.directoriornc.com/api/DGII
• Documentación interactiva (Swagger): api.directoriornc.com/swagger
• Autenticación: no requiere clave.
• Límites: 60 solicitudes por minuto y 10,000 por día, por dirección IP.
• Formato: JSON. Solo método GET.
• CORS: habilitado para peticiones GET desde el navegador.

Endpoints

Formato de respuesta

{
  "rnc": "132790316",
  "nombreCompleto": "OSCARSOFT SRL",
  "nombreComercial": "OSCARSOFT",
  "actividad": "PLANIFICACIÓN Y DISEÑO DE LOS",
  "fechaRegistro": "14/11/2022",
  "estado": "ACTIVO",
  "categoria": "RST"
}

• estado: ACTIVO, SUSPENDIDO, CESE TEMPORAL, DADO DE BAJA, ANULADO o RECHAZADO. Qué significa cada uno: verificar a un proveedor.
• categoria: el régimen de pago (NORMAL o RST). Ver tipos de contribuyentes.
• actividad: la DGII la publica truncada a unos 30 caracteres.
• fechaRegistro: en formato dd/MM/aaaa, y puede venir vacía.

Ejemplos

curl

curl https://api.directoriornc.com/api/DGII/132790316

JavaScript

async function consultarRnc(rnc) {
  const res = await fetch("https://api.directoriornc.com/api/DGII/" + rnc);

  if (res.status === 404) return null;           // no existe
  if (res.status === 429) {
    const espera = res.headers.get("Retry-After"); // segundos
    throw new Error("Limite alcanzado, reintenta en " + espera + " s");
  }
  if (!res.ok) throw new Error("Error " + res.status);

  return await res.json();
}

Python

import requests

def consultar_rnc(rnc):
    r = requests.get("https://api.directoriornc.com/api/DGII/" + rnc, timeout=15)
    if r.status_code == 404:
        return None
    r.raise_for_status()
    return r.json()

empresa = consultar_rnc("132790316")
print(empresa["nombreCompleto"], empresa["estado"])

C#

using System.Net.Http.Json;

var http = new HttpClient { BaseAddress = new Uri("https://api.directoriornc.com/") };
var res = await http.GetAsync("api/DGII/132790316");

if (res.IsSuccessStatusCode)
{
    var empresa = await res.Content.ReadFromJsonAsync<Contribuyente>();
}

public record Contribuyente(string Rnc, string NombreCompleto, string NombreComercial,
    string Actividad, string FechaRegistro, string Estado, string Categoria);

Códigos de respuesta y cómo manejarlos

Buenas prácticas para integrarla

1. Guarda los resultados en caché. Los datos se actualizan una vez al día; consultar el mismo RNC cada minuto no aporta nada. Un caché de unas horas reduce tus llamadas y evita topar el límite.
2. Normaliza la entrada. Quita guiones y espacios antes de consultar.
3. Valida en tu lado el formato. Un RNC tiene 9 dígitos (empresas) y una cédula 11. Ahorra llamadas innecesarias.
4. Maneja el 429 con gracia. Respeta Retry-After y escalona las consultas por lotes (por ejemplo, unas pocas por segundo).
5. Define un tiempo de espera (timeout) y un plan para cuando la API no responda: por ejemplo, permitir continuar y verificar después.
6. No dependas de ella para decisiones críticas sin respaldo. Es un servicio gratuito; para trámites oficiales, usa la DGII.
7. Haz las llamadas desde tu servidor cuando puedas, y no expongas listas de datos a terceros sin necesidad.

Casos de uso

• Facturación: validar el RNC del cliente antes de emitir un comprobante de crédito fiscal.
• Compras y cuentas por pagar: bloquear el registro de facturas de proveedores cuyo estado no sea ACTIVO.
• Alta de clientes y proveedores: autocompletar la razón social al escribir el RNC.
• Debida diligencia: revisar periódicamente el estado de tus terceros: debida diligencia fiscal.

Uso responsable de los datos

Los datos son públicos, pero incluyen información de personas. Úsalos solo para fines fiscales y comerciales legítimos (validar un cliente o un proveedor) y no para perfilar o contactar a personas sin su consentimiento. No la utilices para descargar masivamente la base: si necesitas el archivo completo, la DGII lo publica en su portal.

Preguntas frecuentes

¿Necesito registrarme o pedir una clave?

No. Es de uso libre, dentro de los límites indicados. Si tu caso necesita un volumen mayor, escríbenos a [email protected].

¿Qué tan actualizados están los datos?

Se actualizan diariamente a partir del archivo público de la DGII, así que un cambio reciente puede tardar un día en reflejarse.

¿Puedo usarla en producción?

Sí, con las precauciones anteriores. Considera que es un servicio gratuito y que no ofrece garantía de disponibilidad.

¿Por qué un RNC existe en la DGII pero la API devuelve 404?

Puede ser un número mal escrito, un registro reciente que aún no está en el archivo o un contribuyente que no figura en el listado público.

Importante: esta guía es informativa. La API es un servicio no oficial de OscarSoft SRL y sus condiciones pueden cambiar; consulta el sitio de documentación para ver las vigentes.