Buscar un contribuyente

Escribe un RNC de 9 dígitos o una cédula de 11 dígitos. Si no conoces el número, busca por nombre o razón social y elige una sugerencia.

Entender el resultado

La búsqueda por nombre devuelve taxpayers con solo tres campos: taxId, registeredName y commercialName. Elige una coincidencia o escribe un identificador exacto para obtener taxpayer, con 13 campos planos: seis de identidad y siete datos adicionales de la DGII. Las sugerencias no incluyen estados de registro ni datos del perfil.

Campo	Significado
`taxId`	RNC o cédula. Guárdalo como texto para conservar los ceros iniciales.
`kind`	`rnc` o `cedula`.
`registeredName`	Nombre registrado según las observaciones disponibles de la DGII.
`commercialName`	Nombre comercial, o `null` cuando el dato se desconoce o no está disponible.
`registrationStatus`	`active` o `inactive` en la observación actual.
`checksumStatus`	Clasificación de la validación del identificador; no demuestra que exista un registro ni que esté al día.
`category`	Categoría de la DGII, o `null`; no es una forma jurídica ni una clasificación por tamaño.
`classification`	Clasificación de la lista de implementación de facturación electrónica para contribuyentes locales y medianos de la DGII, o `null`.
`isElectronicInvoicer`	`true`, `false` o `null`, según el formulario web de la DGII.
`economicActivity`	Descripción de la actividad según la DGII, o `null`.
`operationsStartedOn`	Fecha de inicio de operaciones (`YYYY-MM-DD`), o `null`.
`paymentRegime`	Régimen publicado, como `NORMAL`, `RST` o `PST`, o `null`.
`dgiiStatus`	Estado tal como lo publica la DGII, o `null`.

null significa que el dato es desconocido o no está disponible. En particular, isElectronicInvoicer: null no equivale a false. La API convierte SI/SÍ en true y NO en false; los valores no reconocidos quedan como null. El régimen, la categoría y el estado de la DGII conservan las etiquetas de la fuente. Encontrar un resultado no confirma el cumplimiento tributario actual. El directorio incluye los contribuyentes publicados por la DGII; no es un registro de toda la ciudadanía ni permite exportaciones masivas.

classification conserva etiquetas de la lista de la DGII para implementar la facturación electrónica en contribuyentes locales y medianos, como Grande Local y Mediana; es independiente de category y de la certificación del MICM. No se incluye la lista de Grandes Contribuyentes Nacionales. classification: null significa que no hubo un resultado utilizable en esta fuente; no permite determinar si el contribuyente es un gran contribuyente. La API no infiere este dato a partir de los dígitos del identificador.

La respuesta de detalle combina la información disponible de la DGII usando el RNC o la cédula como identificador común. Un valor ausente en una fuente no borra un valor disponible en otra; por ejemplo, la fecha de inicio de operaciones del directorio se conserva aunque el formulario web no la incluya. Los datos pueden corresponder a la última observación conocida y no confirman el cumplimiento tributario actual.

Los contribuyentes encontrados mediante una consulta web por identificador se guardan y pasan a estar disponibles en la búsqueda por nombre e identificador. La búsqueda consulta los datos guardados sin enviar el formulario de la DGII. Las consultas de detalle posteriores pueden actualizar la información, pero un fallo temporal de la DGII conserva los datos conocidos. Una respuesta que confirma que el identificador no está registrado se trata de forma distinta a una consulta fallida.

Integrar la consulta en tu aplicación

Para buscar un número exacto, envía solo dígitos:

const apiOrigin = '__API_ORIGIN__';
const taxId = '101850043';
const response = await fetch(`${apiOrigin}/v1/taxpayers/${encodeURIComponent(taxId)}`);
if (!response.ok) throw new Error(`La consulta del contribuyente falló: ${response.status}`);
const { taxpayer } = await response.json();

Para obtener sugerencias por nombre, pide hasta diez coincidencias y luego confirma el número elegido con la consulta exacta:

const apiOrigin = '__API_ORIGIN__';
const query = new URLSearchParams({ q: 'ferreteria', limit: '10' });
const response = await fetch(`${apiOrigin}/v1/taxpayers/search?${query}`);
if (!response.ok) throw new Error(`La búsqueda de contribuyentes falló: ${response.status}`);
const { taxpayers } = await response.json();

La búsqueda ignora mayúsculas y acentos, reduce los espacios repetidos y trata signos como % y _ literalmente. Usa entre 3 y 120 caracteres normalizados, con al menos tres letras o números consecutivos. Primero aparecen las coincidencias exactas, luego los prefijos y las coincidencias parciales. Los resultados no tienen paginación; escribe un nombre más específico para reducir la lista.

La consulta completa puede añadir datos del formulario a un registro del directorio sin sustituir su identidad ni los campos originales del perfil. Si la consulta falla o alcanza su límite, los datos adicionales quedan desconocidos y se conserva la respuesta disponible del directorio. Una respuesta completa del formulario no incluye la fecha de inicio de operaciones. No muestres estos detalles en las sugerencias del buscador.

La respuesta pública contiene datos del contribuyente, sin metadatos de importación o consulta. La API no dispone actualmente de una fecha oficial que indique cuándo la DGII actualizó por última vez el registro de ese contribuyente, por lo que no devuelve updatedAt. La fecha de publicación de una fuente o el momento en que consultamos el registro no permiten establecer esa fecha.

Gestionar resultados vacíos, errores y caché

No conviertas cada consulta fallida en «el contribuyente no está registrado». Un 404 en la consulta exacta significa que el servicio no encontró el número según su política actual de fuentes. Una búsqueda por nombre vacía tampoco demuestra que no exista: la consulta exacta todavía puede encontrarlo mediante una fuente de respaldo.

HTTP 400 indica que debes corregir el dato enviado. HTTP 503 significa que no hay una respuesta utilizable; una observación antigua, por sí sola, no provoca un error. Conserva el valor escrito y ofrece reintentar. Si recibes 429, reduce la frecuencia y respeta Retry-After cuando esté presente.

Respeta las cabeceras de caché de la respuesta; las respuestas exitosas pueden guardarse hasta 60 segundos. No guardes los errores en caché.

Entender la vigencia y la consulta de respaldo

La consulta exacta puede devolver registros actuales o la última observación conocida del directorio y usar la consulta limitada al formulario web de la DGII. Una publicación antigua no oculta por sí sola un registro disponible. Si una publicación nueva omite al contribuyente, la última observación conocida sigue disponible; esa omisión no demuestra suspensión ni ausencia de registro.

Las fechas de publicación y consulta, los hashes y los metadatos de vigencia permanecen en las APIs internas. La búsqueda por nombre usa la publicación actual. Un identificador enviado a /v1/taxpayers/search también puede consultar la última observación conocida. Ninguna modalidad de búsqueda consulta el formulario de la DGII.

La respuesta no es una certificación de la DGII. Lee calidad y límites de los datos o el contrato del directorio (en inglés) cuando necesites todas las reglas de fuentes y vigencia.

Certificación MICM para servicios autenticados

La certificación MICM no forma parte del perfil público ni está disponible a través de este portal de APIs. Los servicios con una identidad Vercel OIDC autorizada pueden consultar directamente Taxpayer Directory en https://taxpayer-directory-api.vercel.app:

GET /internal/v1/taxpayers/{taxId}/profile incluye mipymeCertification, que puede ser null.
GET /internal/v1/taxpayers/{taxId}/mipyme-certification devuelve { "certification": ... }, aunque la DGII no tenga un registro de identidad para ese número.

Cada certificado contiene companyName, activity y classification (ambos pueden ser null), issuedOn, validUntil y su propio publishedAt. La emisión y el vencimiento usan YYYY-MM-DD; la publicación incluye fecha y hora. Interpreta estas fechas por separado de las observaciones de la DGII. Un certificado vencido puede devolverse si se identifica de forma inequívoca, y una publicación antigua no lo oculta por sí sola.

Un certificado nulo significa que no se pudo determinar un único registro confiable: la fuente puede no estar disponible, el contribuyente puede no aparecer, puede haber registros contradictorios o fechas de vigencia inciertas. No demuestra que la empresa carezca de certificación. Estos datos no determinan por sí solos el tamaño de la empresa, su tratamiento tributario ni su elegibilidad comercial. Los hashes y diagnósticos de importación siguen siendo internos. Mantén las credenciales del servicio en el servidor.

Explorar la API de contribuyentes →