> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtener disponibilidad

> Obtener las horas de inicio de franjas reservables de una sola ubicación

Devuelve los inicios de franja reservables de una única ubicación durante el periodo solicitado. Las franjas se
generan a partir de `open_hours` de la ubicación, omitiendo las fechas bloqueadas globales o por ubicación y
restando las citas de Aniva ya reservadas, de modo que el resultado refleja lo que tus pacientes pueden
reservar realmente en el cliente.

Requiere el alcance `appointments_schedule`. La ubicación también debe estar dentro del contexto de acceso de grupo de ubicaciones de tu clave de API.

> [!NOTE]
>
> Usa este endpoint en lugar de deducir la disponibilidad a partir del campo estático `open_hours` que devuelve [Listar
> ubicaciones](https://docs.anivahealth.com/es/api/locations/list-locations.md) — solo este endpoint tiene en cuenta las reservas en tiempo real,
> las excepciones de horario por fecha y el [preaviso
> mínimo](https://docs.anivahealth.com/es/api/appointments/create-appointment.md#antelacion-minima) de 12 horas en las ubicaciones gestionadas por Aniva. Todas las
> franjas devueltas aquí se pueden reservar tal cual.

Las respuestas incluyen `Cache-Control: private, max-age=30, stale-while-revalidate=60`, por lo que un navegador puede
servir una respuesta en caché durante hasta \~30 segundos — una franja reservada en ese intervalo puede seguir apareciendo
como reservable hasta la próxima actualización. Muestra también los conflictos en el momento de reservar.

## Parámetros de ruta

**id** `string` *required*

Identificador de la ubicación (UUID). Usa el `id` de [Listar ubicaciones](https://docs.anivahealth.com/es/api/locations/list-locations.md).

## Parámetros de consulta

**start\_date** `string`

Inicio inclusivo del periodo en formato `YYYY-MM-DD` (interpretado en `timezone`). Opcional. Por defecto es
**hoy** cuando no se indica ninguna fecha, o **`end_date − 30 days`** cuando solo se indica `end_date`.
Las fechas pasadas se ajustan silenciosamente a hoy.

**end\_date** `string`

Fin inclusivo del periodo en formato `YYYY-MM-DD` (interpretado en `timezone`). Opcional. Por defecto es
**hoy + 30 días** cuando no se indica ninguna fecha, o **`start_date + 30 days`** cuando solo se indica
`start_date`. Debe ser igual o posterior a `start_date` y estar dentro de los 90 días a partir de hoy.

**timezone** `string`

Zona horaria IANA (p. ej., `Europe/Berlin`) utilizada para interpretar `start_date` / `end_date` y agrupar
las franjas por fecha de calendario. Opcional — por defecto usa la propia zona horaria de la ubicación. Las horas de inicio de las franjas
se devuelven siempre como instantes UTC (`Z`) y nunca cambian con este parámetro — la
cuadrícula de franjas siempre se proyecta desde la zona horaria de la ubicación; el parámetro solo afecta a en qué
día de calendario se agrupa una franja. Las entradas de día en la respuesta cubren exactamente
`start_date`..`end_date` como días de calendario en esta zona horaria. Omítelo salvo que muestres el selector
en otra zona horaria.

## Respuesta

Si tiene éxito, la API devuelve `200 OK` con un único objeto de disponibilidad.

**location\_id** `string` *required*

Identificador de la ubicación reflejado.

**timezone** `string` *required*

Zona horaria IANA en la que se devuelve la respuesta (p. ej., `Europe/Berlin`) — refleja el parámetro de consulta `timezone`
cuando se indica; de lo contrario, la propia zona horaria de la ubicación.

**slot\_interval\_minutes** `integer`

Espaciado en minutos entre inicios consecutivos de franjas reservables. El intervalo de cuadrícula configurado en la ubicación —
todas las franjas de `availability` caen en esta cuadrícula. Solo es `null` cuando la ubicación no tiene configuración
de horarios. **No es una ventana de duración de la cita:** las reservas solapadas con horas de inicio distintas no
entran en conflicto; solo las coincidencias exactas de hora de inicio cuentan para la concurrencia.

**availability** `array` *required*

Franjas reservables por día. Los días sin franjas reservables se omiten para mantener la respuesta ligera.
Cada entrada contiene:

**entrada por día**

**date** `string` *required*

Fecha de calendario en el `timezone` de la respuesta (`YYYY-MM-DD`).

**slots** `array` *required*

Inicios de franja como instantes UTC (ISO 8601 con sufijo `Z`), ordenados de forma ascendente.

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | ID de ubicación no válido, formato de fecha o zona horaria no válido, `end_date` anterior a `start_date`, o `end_date` a más de 90 días en el futuro. |
| `403` | Prohibido — falta el alcance `appointments_schedule` o la ubicación está fuera de tu contexto de acceso. |
| `404` | Ubicación no encontrada o inactiva. |
| `500` | Error interno del servidor. |

```bash cURL theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/locations/b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b/availability?start_date=2026-05-01&end_date=2026-05-07' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "timezone": "Europe/Berlin",
  "slot_interval_minutes": 15,
  "availability": [
    {
      "date": "2026-05-04",
      "slots": ["2026-05-04T07:00:00Z", "2026-05-04T07:15:00Z", "2026-05-04T07:30:00Z"]
    },
    {
      "date": "2026-05-05",
      "slots": ["2026-05-05T06:00:00Z", "2026-05-05T06:15:00Z"]
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.