{"openapi":"3.1.0","info":{"title":"UrbanStock DGII RNC API (República Dominicana)","version":"1.1.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, validar dígitos verificadores oficiales (Módulo 11 / Módulo 10) y analizar comprobantes fiscales NCF / e-CF.","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":"Comprobantes","description":"Validación estructural NCF / e-CF, QR DGII y emisor"},{"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. Incluye verificación matemática de dígito verificador (Módulo 11 DGII / Módulo 10 JCE). 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":4,"cached":false,"coalesced":false,"isTestExample":true,"validCheckDigit":false,"checkDigitAlgorithm":"MOD11_DGII"}}}}},"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 (incluye diagnóstico de dígito verificador)"},"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 50 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 y verificación de dígitos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}}}},"post":{"tags":["Contribuyentes"],"operationId":"batchLookupRncs","summary":"Consulta en lote (hasta 50 RNC/Cédulas)","description":"Resuelve múltiples RNC o Cédulas en una sola petición HTTP con verificación de dígito verificador.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rncs"],"properties":{"rncs":{"type":"array","minItems":1,"maxItems":50,"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":4,"isTestExample":true}}}}}}}},"/api/v1/validate/ncf":{"get":{"tags":["Comprobantes"],"operationId":"validateNcfGet","summary":"Validar estructura NCF / e-CF, QR DGII y estado del emisor (GET)","description":"Valida formato oficial de NCF (Serie B, 11 caracteres) o e-CF electrónico (Serie E, 13 caracteres), elegibilidad para crédito fiscal ITBIS / Formato 606, enlace QR oficial DGII y situación del RNC emisor/comprador en el padrón.","parameters":[{"name":"ncf","in":"query","required":false,"description":"NCF tradicional (ej. B0100000001) o e-CF electrónico (ej. E310000000001)","schema":{"type":"string"}},{"name":"rncEmisor","in":"query","required":false,"description":"RNC o Cédula del emisor del comprobante","schema":{"type":"string"}},{"name":"rncComprador","in":"query","required":false,"description":"RNC o Cédula del comprador (opcional)","schema":{"type":"string"}},{"name":"qrUrl","in":"query","required":false,"description":"URL extraída del código QR de e-CF (ecf.dgii.gov.do o fc.dgii.gov.do)","schema":{"type":"string"}}],"responses":{"200":{"description":"Resultado detallado de estructura NCF/e-CF, emisor y enlace directo de verificación en DGII","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NcfValidationResponse"}}}},"400":{"description":"Falta 'ncf'/'qrUrl' o la URL QR no pertenece a dgii.gov.do"}}},"post":{"tags":["Comprobantes"],"operationId":"validateNcfPost","summary":"Validar estructura NCF / e-CF, QR DGII y estado del emisor (POST)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ncf":{"type":"string","example":"E310000000001"},"rncEmisor":{"type":"string","example":"000000000"},"rncComprador":{"type":"string"},"qrUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Diagnóstico completo de comprobante fiscal, reglas 606/ITBIS, estado del emisor y URL oficial DGII","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NcfValidationResponse"}}}},"400":{"description":"Solicitud vacía o URL de código QR inválida"}}}},"/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"}},"checkDigits":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}}},"NcfValidationResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"valid":{"type":"boolean"},"verdict":{"type":"string","enum":["ESTRUCTURA_Y_EMISOR_VALIDOS","ESTRUCTURA_VALIDA","MODO_PRUEBA","ADVERTENCIA","NO_VALIDO"]},"ncf":{"type":"object","additionalProperties":true},"emisor":{"type":["object","null"],"additionalProperties":true},"comprador":{"type":["object","null"],"additionalProperties":true},"qr":{"type":["object","null"],"additionalProperties":true},"warnings":{"type":"array","items":{"type":"string"}},"dgiiVerification":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}}}}}}