{"openapi":"3.1.0","info":{"title":"UrbanStock DGII RNC API (República Dominicana)","version":"1.0.0","description":"API REST pública, gratuita y sin autenticación obligatoria para consultar el Padrón Nacional de Contribuyentes (RNC y Cédula) de la Dirección General de Impuestos Internos (DGII) de República Dominicana. Actualizada automáticamente cada madrugada con Razón Social completa, Nombre Comercial, Actividad Económica y estado fiscal.","contact":{"name":"UrbanStock POS","url":"https://urbanstockpos.com"},"license":{"name":"Datos Públicos Oficiales DGII RD","url":"https://dgii.gov.do"}},"externalDocs":{"description":"Guía optimizada para modelos de IA y agentes (llms.txt)","url":"https://rnc.urbanstockpos.com/llms.txt"},"servers":[{"url":"https://rnc.urbanstockpos.com","description":"Servidor público en producción (UrbanStock DGII RNC)"}],"tags":[{"name":"Contribuyentes","description":"Búsqueda exacta y por nombre en el padrón DGII RD"},{"name":"Estado","description":"Disponibilidad del servicio y última actualización del padrón"}],"paths":{"/api/v1/rnc/{rnc}":{"get":{"tags":["Contribuyentes"],"operationId":"getTaxpayerByRnc","summary":"Consultar contribuyente por RNC o Cédula","description":"Busca un contribuyente en República Dominicana por RNC (9 dígitos, formato oficial X-XX-XXXXX-X) o Cédula (11 dígitos, XXX-XXXXXXX-X), aceptando con o sin guiones. Para pruebas sin exponer datos reales usa '000000000' o '00000000000'.","parameters":[{"name":"rnc","in":"path","required":true,"description":"RNC (9 dígitos) o Cédula (11 dígitos), con o sin guiones. Ej. sintético de prueba: 000000000","schema":{"type":"string","pattern":"^[0-9.\\-_\\s]{8,15}$"},"examples":{"demoRnc":{"summary":"RNC de prueba sintético","value":"000000000"},"demoCedula":{"summary":"Cédula de prueba sintética","value":"00000000000"}}}],"responses":{"200":{"description":"Contribuyente encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"},"example":{"ok":true,"found":true,"data":{"rnc":"000000000","formattedRnc":"0-00-00000-0","tipoDocumento":"RNC","razonSocial":"EMPRESA DE PRUEBA URBANSTOCK SRL","nombreComercial":"COMERCIO EJEMPLO (TEST)","actividadEconomica":"REGISTRO SINTÉTICO DE PRUEBA PARA DEMOSTRACIÓN E INTEGRACIÓN API (NO REAL)","fechaInicio":"01/01/2026","estado":"PRUEBA (TEST)","isActive":false,"regimenPago":"DEMO","isTestExample":true},"meta":{"padronFecha":"2026-11-07","datasetVersion":2,"cached":false,"coalesced":false,"isTestExample":true}}}}},"304":{"description":"Sin cambios desde el último ETag"},"400":{"description":"Formato de RNC o Cédula inválido (requiere 8 a 11 dígitos)"},"404":{"description":"No encontrado en el padrón vigente de la DGII"},"429":{"description":"Límite de frecuencia temporal excedido"},"503":{"description":"Servicio inicializando descarga del padrón"}}}},"/api/v1/search":{"get":{"tags":["Contribuyentes"],"operationId":"searchTaxpayersByName","summary":"Buscar empresas o negocios por Razón Social o Nombre Comercial","description":"Búsqueda parcial rápida e insensible a tildes y mayúsculas sobre todo el padrón DGII de República Dominicana. Para probar sin consultar empresas reales usa q='EMPRESA DE PRUEBA'.","parameters":[{"name":"q","in":"query","required":true,"description":"Texto a buscar (mínimo 3 caracteres y una palabra de 3+ letras). Ejemplo de prueba: EMPRESA DE PRUEBA","schema":{"type":"string","minLength":3},"example":"EMPRESA DE PRUEBA"},{"name":"estado","in":"query","required":false,"description":"Filtrar por estado tributario DGII","schema":{"type":"string","enum":["ACTIVO","SUSPENDIDO","DADO DE BAJA","CESE TEMPORAL","ANULADO","RECHAZADO"]}},{"name":"limit","in":"query","required":false,"description":"Máximo de resultados (1 a 25, por defecto 15)","schema":{"type":"integer","minimum":1,"maximum":25,"default":15}}],"responses":{"200":{"description":"Resultados de búsqueda","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Parámetro de búsqueda o estado inválido"},"429":{"description":"Límite de frecuencia temporal excedido"}}}},"/api/v1/rnc/batch":{"get":{"tags":["Contribuyentes"],"operationId":"batchLookupRncsGet","summary":"Consulta en lote vía GET (separado por comas)","description":"Resuelve múltiples RNC o Cédulas pasando ?rncs=id1,id2 (hasta 100 valores).","parameters":[{"name":"rncs","in":"query","required":true,"description":"Lista separada por comas. Ejemplo de prueba: 00000000000,000000000","schema":{"type":"string"},"example":"00000000000,000000000"}],"responses":{"200":{"description":"Mapa de contribuyentes encontrados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}}}},"post":{"tags":["Contribuyentes"],"operationId":"batchLookupRncs","summary":"Consulta en lote (hasta 100 RNC/Cédulas)","description":"Resuelve múltiples RNC o Cédulas en una sola petición HTTP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rncs"],"properties":{"rncs":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"},"example":["00000000000","000000000"]}}}}}},"responses":{"200":{"description":"Mapa de contribuyentes encontrados más no encontrados e inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"},"example":{"ok":true,"totalRequested":2,"totalFound":2,"data":{"00000000000":{"rnc":"00000000000","formattedRnc":"000-0000000-0","tipoDocumento":"CEDULA","razonSocial":"CONTRIBUYENTE DE PRUEBA EJEMPLO","nombreComercial":"SERVICIOS DEMO TEST","actividadEconomica":"CÉDULA FICTICIA DE PRUEBA (NO CORRESPONDE A NINGUNA PERSONA REAL)","fechaInicio":"01/01/2026","estado":"PRUEBA (TEST)","isActive":false,"regimenPago":"DEMO","isTestExample":true},"000000000":{"rnc":"000000000","formattedRnc":"0-00-00000-0","tipoDocumento":"RNC","razonSocial":"EMPRESA DE PRUEBA URBANSTOCK SRL","nombreComercial":"COMERCIO EJEMPLO (TEST)","actividadEconomica":"REGISTRO SINTÉTICO DE PRUEBA PARA DEMOSTRACIÓN E INTEGRACIÓN API (NO REAL)","fechaInicio":"01/01/2026","estado":"PRUEBA (TEST)","isActive":false,"regimenPago":"DEMO","isTestExample":true}},"notFound":[],"invalid":[],"meta":{"padronFecha":"2026-11-07","datasetVersion":2,"isTestExample":true}}}}}}}},"/api/v1/meta":{"get":{"tags":["Estado"],"operationId":"getDatasetMeta","summary":"Metadatos del padrón DGII sincronizado","responses":{"200":{"description":"Totales del padrón y fecha de última actualización DGII"}}}},"/health":{"get":{"tags":["Estado"],"operationId":"getHealth","summary":"Estado de disponibilidad del servicio","responses":{"200":{"description":"Estado operativo del servicio"}}}}},"components":{"schemas":{"RncRecord":{"type":"object","required":["rnc","formattedRnc","tipoDocumento","razonSocial","actividadEconomica","estado","isActive","regimenPago"],"properties":{"rnc":{"type":"string","description":"Número limpio sin guiones (8 a 11 dígitos)"},"formattedRnc":{"type":"string","description":"Formato oficial legible con guiones (X-XX-XXXXX-X o XXX-XXXXXXX-X)"},"tipoDocumento":{"type":"string","enum":["RNC","CEDULA","OTRO"]},"razonSocial":{"type":"string"},"nombreComercial":{"type":["string","null"]},"actividadEconomica":{"type":"string"},"fechaInicio":{"type":["string","null"],"description":"DD/MM/YYYY"},"estado":{"type":"string"},"isActive":{"type":"boolean","description":"true únicamente cuando el contribuyente real está ACTIVO"},"regimenPago":{"type":"string"},"isTestExample":{"type":"boolean","description":"Presente y true solo en ejemplos sintéticos de prueba"}}},"LookupResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"found":{"type":"boolean"},"data":{"$ref":"#/components/schemas/RncRecord"},"meta":{"type":"object","additionalProperties":true}}},"SearchResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"query":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/RncRecord"}},"meta":{"type":"object","additionalProperties":true}}},"BatchResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"totalRequested":{"type":"integer"},"totalFound":{"type":"integer"},"data":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/RncRecord"}},"notFound":{"type":"array","items":{"type":"string"}},"invalid":{"type":"array","items":{"type":"string"}},"meta":{"type":"object","additionalProperties":true}}}}}}