{"openapi":"3.1.0","info":{"title":"Mi SaludRD — disponibilidad pública de citas","version":"1.0.0","description":"API pública de solo lectura para proponer médicos, tipos de consulta, fechas y horarios. La reserva final siempre requiere que el usuario inicie sesión, revise los datos y confirme."},"servers":[{"url":"https://mi-saludrd.com"}],"paths":{"/api/public/appointment-options":{"get":{"operationId":"searchAppointmentOptions","summary":"Buscar próximas opciones de cita","description":"Devuelve hasta el límite solicitado, tomando el primer día disponible de cada médico dentro del intervalo. Cada opción incluye un enlace de reserva preconfigurado. Los datos son orientativos durante 30 segundos y se vuelven a validar antes de reservar.","security":[],"parameters":[{"name":"specialty","in":"query","description":"Especialidad canónica en español. Omítela para buscar todas.","schema":{"type":"string","enum":["Alergología e Inmunología","Anestesiología","Cardiología","Cirugía Cardiovascular","Cirugía General","Cirugía Pediátrica","Cirugía Plástica y Reconstructiva","Cirugía Torácica","Cirugía Vascular","Dermatología","Endocrinología","Fisiatría y Rehabilitación","Gastroenterología","Geriatría","Ginecología y Obstetricia","Hematología","Infectología","Medicina de Emergencia","Medicina Familiar","Medicina General","Medicina Interna","Nefrología","Neumología","Neurocirugía","Neurología","Nutrición Clínica","Odontología","Oftalmología","Oncología","Ortopedia y Traumatología","Otorrinolaringología","Patología","Pediatría","Psiquiatría","Radiología","Reumatología","Urología","Otro"]}},{"name":"city","in":"query","description":"Ciudad de la consulta, por ejemplo Santo Domingo o Santiago.","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"from","in":"query","description":"Primer día del intervalo en República Dominicana. Por defecto: hoy.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","description":"Cantidad de días consecutivos que se deben examinar.","schema":{"type":"integer","minimum":1,"maximum":31,"default":14}},{"name":"limit","in":"query","description":"Cantidad máxima de combinaciones médico/tipo/fecha/hora.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Opciones disponibles; una lista vacía es un resultado válido.","headers":{"X-Data-Generated-At":{"description":"Instante ISO 8601 en que se calcularon las opciones.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentOptionsResponse"}}}},"400":{"description":"Parámetros inválidos o ambiguos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Límite de solicitudes alcanzado."},"503":{"description":"La disponibilidad no se pudo comprobar. No debe interpretarse como una agenda vacía.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"AppointmentOptionsResponse":{"type":"object","additionalProperties":false,"required":["schema_version","status","generated_at","expires_at","timezone","query","scope","doctors_considered","count","options","links"],"properties":{"schema_version":{"type":"string","const":"1.0"},"status":{"type":"string","const":"ok"},"generated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"timezone":{"type":"string","const":"America/Santo_Domingo"},"scope":{"type":"string","const":"first_available_day_per_doctor_in_range"},"doctors_considered":{"type":"integer","minimum":0},"count":{"type":"integer","minimum":0},"query":{"type":"object","required":["specialty","city","from","to","days","limit"],"additionalProperties":false,"properties":{"specialty":{"type":["string","null"]},"city":{"type":["string","null"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"limit":{"type":"integer"}}},"options":{"type":"array","items":{"$ref":"#/components/schemas/AppointmentOption"}},"links":{"type":"object","required":["human_view","api","openapi"],"additionalProperties":false,"properties":{"human_view":{"type":"string","format":"uri"},"api":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"}}}}},"AppointmentOption":{"type":"object","additionalProperties":false,"required":["doctor","consultation","slot","booking_url","requires_login","requires_final_confirmation"],"properties":{"doctor":{"type":"object","required":["id","name","specialty","city","province","verified","rating","review_count","profile_image_url","profile_url"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"specialty":{"type":"string"},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"verified":{"type":"boolean"},"rating":{"type":["number","null"]},"review_count":{"type":"integer","minimum":0},"profile_image_url":{"type":["string","null"],"format":"uri"},"profile_url":{"type":"string","format":"uri"}}},"consultation":{"type":"object","required":["id","name","duration_minutes","price","currency"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"duration_minutes":{"type":"integer","minimum":1},"price":{"type":"number","minimum":0},"currency":{"type":"string","const":"DOP"}}},"slot":{"type":"object","required":["date","start_time","end_time","timezone"],"additionalProperties":false,"properties":{"date":{"type":"string","format":"date"},"start_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$","examples":["09:30:00"]},"end_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$","examples":["10:00:00"]},"timezone":{"type":"string","const":"America/Santo_Domingo"}}},"booking_url":{"type":"string","format":"uri"},"requires_login":{"type":"boolean","const":true},"requires_final_confirmation":{"type":"boolean","const":true}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["status","code","message"],"properties":{"status":{"type":"string","const":"error"},"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"string"}},"openapi_url":{"type":"string","format":"uri"}}}}}}