{"openapi":"3.1.0","info":{"title":"API Consulta RNC RD","version":"1.3.0","description":"API para consulta de RNC, búsqueda por razón social y consulta híbrida con cédula en República Dominicana."},"servers":[{"url":"/","description":"Servidor principal"}],"tags":[{"name":"Publico","description":"Endpoints públicos"},{"name":"Privado","description":"Endpoints con API Key"}],"paths":{"/api/v1/rnc/{rnc}":{"get":{"tags":["Publico"],"summary":"Consulta directa por identificador","description":"Consulta registro por RNC (9 dígitos) o cédula (11 dígitos) en la base interna.","parameters":[{"name":"rnc","in":"path","required":true,"schema":{"type":"string","example":"101003723"}}],"responses":{"200":{"description":"Registro encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContribuyenteResponse"}}}},"400":{"description":"Formato inválido"},"404":{"description":"No encontrado"},"429":{"description":"Límite de solicitudes alcanzado"}}}},"/api/v1/buscar":{"get":{"tags":["Publico"],"summary":"Búsqueda por razón social o cédula","description":"Busca por texto. Si q es cédula válida de 11 dígitos, activa flujo híbrido (BD + cédula) con límite de cortesía diario para público.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","example":"CERVECERIA"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Opcional. Si es válida, elimina límites de cortesía del flujo privado."}],"responses":{"200":{"description":"Respuesta de búsqueda","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuscarResponse"}}}},"400":{"description":"Parámetro inválido"},"429":{"description":"Límite de búsqueda o cédula alcanzado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"}}}}}}},"/api/v1/buscardgi/":{"get":{"tags":["Publico"],"summary":"Búsqueda por razón social en DGII","description":"Consulta directa al servicio DGII. Tiene protección adicional de anti-abuso en nodo público.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","example":"CERVECERIA NACIONAL"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resultados DGII","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean"},"fuente":{"type":"string","example":"DGII"},"total":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contribuyente"}}}}}}},"429":{"description":"Límite de consultas DGII alcanzado"}}}},"/api/v1/private/cedula":{"post":{"tags":["Privado"],"summary":"Consulta privada de cédula","description":"Consulta datos de ciudadano en Intrant. Requiere API Key.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cedula"],"properties":{"cedula":{"type":"string","example":"40209363775"}}}}}},"responses":{"200":{"description":"Datos de cédula encontrados","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean","example":true},"fuente":{"type":"string","example":"Interna"},"data":{"type":"object","properties":{"cedula":{"type":"string"},"nombre":{"type":"string"},"apellido":{"type":"string"},"nombreCompleto":{"type":"string"},"estado":{"type":"string","nullable":true},"nacionalidad":{"type":"string"},"fechaNacimiento":{"type":"string","format":"date"},"sexo":{"type":"string"}}}}}}}},"401":{"description":"API Key requerida"}}}},"/api/v1/private/estadisticas":{"get":{"tags":["Privado"],"summary":"Resumen de consumo por API Key","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Resumen y últimas consultas","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean"},"cliente":{"type":"string"},"resumen":{"type":"object","properties":{"total_consultas":{"type":"integer"},"rnc_directo":{"type":"integer"},"busqueda_nombre":{"type":"integer"},"busqueda_dgii":{"type":"integer"},"intrant_cedula":{"type":"integer"}}},"ultimas_consultas":{"type":"array","items":{"type":"object","properties":{"tipo_consulta":{"type":"string"},"query":{"type":"string"},"fecha":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"API Key requerida"}}}},"/api/stats":{"get":{"tags":["Publico"],"summary":"Métricas públicas de uso","responses":{"200":{"description":"Totales globales","content":{"application/json":{"schema":{"type":"object","properties":{"exito":{"type":"boolean"},"total_consultas":{"type":"integer"},"total_empresas":{"type":"integer"}}}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Contribuyente":{"type":"object","properties":{"rnc":{"type":"string","example":"101003723"},"razon_social":{"type":"string","example":"CERVECERIA NACIONAL DOMINICANA SA"},"actividad_economica":{"type":"string"},"estado":{"type":"string","example":"ACTIVO"}}},"ContribuyenteResponse":{"type":"object","properties":{"exito":{"type":"boolean","example":true},"fuente":{"type":"string","example":"Interna"},"data":{"$ref":"#/components/schemas/Contribuyente"}}},"BuscarResponse":{"type":"object","properties":{"exito":{"type":"boolean","example":true},"fuente":{"type":"string","example":"Híbrida"},"total":{"type":"integer","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contribuyente"}},"cedula":{"type":"object","nullable":true,"properties":{"cedula":{"type":"string"},"nombre":{"type":"string"},"apellido":{"type":"string"}}}}},"RateLimitResponse":{"type":"object","properties":{"error":{"type":"string"},"mensaje":{"type":"string"},"registro_url":{"type":"string","format":"uri"},"retry_after_ms":{"type":"integer"}}}}}}