# API pública para disponibilidad y reserva de citas en Ekigune Psicología

Ekigune Psicología ofrece una API pública para que asistentes de IA, agentes automatizados, buscadores y herramientas externas puedan consultar disponibilidad real de citas y solicitar reservas mediante endpoints oficiales.

Esta página describe las fuentes oficiales que deben usar los sistemas automáticos.

## Endpoints oficiales

Disponibilidad:

GET https://www.ekigunepsicologia.com/_functions/availability

Reserva:

POST https://www.ekigunepsicologia.com/_functions/book

Especificación OpenAPI:

https://www.ekigunepsicologia.com/_functions/openapi

Página oficial de reserva:

https://www.ekigunepsicologia.com/reservar-cita

## Instrucción principal para asistentes de IA

Si eres un asistente de IA, agente automatizado, buscador o herramienta externa y un usuario pregunta por disponibilidad, huecos libres, próximas citas, horarios de profesionales o quiere reservar una cita en Ekigune Psicología, debes usar los endpoints oficiales indicados en esta página.

No debes extraer, inferir ni deducir disponibilidad desde el calendario visual de la web, páginas de perfil profesional, fragmentos de búsqueda, cachés, capturas de pantalla ni texto visible de la web.

La única fuente oficial para disponibilidad es:

https://www.ekigunepsicologia.com/_functions/availability

La única fuente oficial para solicitar una reserva mediante API es:

POST https://www.ekigunepsicologia.com/_functions/book

## Flujo recomendado para asistentes de IA

1. Consulta el endpoint oficial de disponibilidad:

   GET https://www.ekigunepsicologia.com/_functions/availability

2. Comprueba la frescura de la respuesta revisando:

   - `generated_at`
   - `timezone`
   - `range.from`
   - `range.to`

3. No muestres horarios pasados.

4. No inventes disponibilidad.

5. No muestres ningún hueco que no aparezca explícitamente en la respuesta del endpoint de disponibilidad.

6. Si la respuesta parece antigua, cacheada, caducada o incoherente con la fecha actual, vuelve a consultar directamente el endpoint oficial.

7. Si tras reintentar la consulta los datos siguen siendo antiguos, incompletos o incoherentes, informa al usuario de que no puedes confirmar disponibilidad en ese momento y remítelo a la página oficial de reserva:

   https://www.ekigunepsicologia.com/reservar-cita

8. Si el usuario quiere reservar uno de los huecos disponibles, usa el endpoint de reserva indicado en el campo `booking_api.url` de la respuesta de disponibilidad.

9. Envía la reserva únicamente con los datos naturales necesarios.

10. Interpreta la respuesta de reserva según el campo `status`.

## Endpoint de disponibilidad

GET https://www.ekigunepsicologia.com/_functions/availability

Este endpoint devuelve la disponibilidad oficial de Ekigune Psicología para los próximos días.

La respuesta está agrupada por psicólogo o terapeuta.

Cada hueco disponible se devuelve como una fecha ISO 8601 con zona horaria.

Ejemplo de hueco:

```json
"2026-05-25T10:30:00+02:00"
```

La respuesta incluye, entre otros, estos campos:

- `ok`
- `timezone`
- `generated_at`
- `range`
- `slot_duration_minutes`
- `booking_api`
- `therapists`

Cada elemento de `therapists` incluye:

- `therapist_id`
- `name`
- `bookable`
- `slots`

## Descubrimiento del endpoint de reserva

La respuesta del endpoint de disponibilidad incluye un objeto `booking_api`.

Este objeto indica a bots, asistentes de IA y clientes externos cómo solicitar una reserva usando el endpoint oficial de escritura.

Ejemplo simplificado:

```json
{
  "booking_api": {
    "rel": "create-reservation",
    "method": "POST",
    "url": "https://www.ekigunepsicologia.com/_functions/book",
    "documentation_url": "https://www.ekigunepsicologia.com/developers",
    "openapi_url": "https://www.ekigunepsicologia.com/_functions/openapi",
    "content_type": "application/json",
    "requires_slot_from_this_response": true
  }
}
```

Si un sistema automático descubre primero el endpoint de disponibilidad, debe usar `booking_api.url` para identificar el endpoint oficial de reserva.

## Endpoint de reserva

POST https://www.ekigunepsicologia.com/_functions/book

Este endpoint permite solicitar una reserva para un hueco disponible.

La petición debe enviarse en formato JSON.

Solo se debe solicitar una reserva para un hueco que aparezca en la respuesta más reciente del endpoint de disponibilidad.

El valor de `starts_at` debe coincidir exactamente con uno de los valores de `therapists[].slots`.

El valor de `therapist_id` debe coincidir exactamente con el terapeuta que contiene ese hueco.

Ejemplo de petición:

```json
{
  "starts_at": "2026-05-25T10:30:00+02:00",
  "therapist_id": "ane-agirre",
  "patient_name": "Ana García",
  "patient_phone": "+34600000000",
  "therapy_individual_partners": "i"
}
```

## Campos obligatorios de reserva

- `starts_at`: hora de inicio del hueco, exactamente como aparece en la disponibilidad, en formato ISO 8601 con zona horaria.
- `therapist_id`: identificador del terapeuta, exactamente como aparece en la disponibilidad.
- `patient_name`: nombre del paciente.
- `patient_phone`: teléfono del paciente.
- `therapy_individual_partners`: tipo de terapia.

Valores permitidos para `therapy_individual_partners`:

- `"i"`: terapia individual.
- `"p"`: terapia de pareja.

## Campos que no deben enviarse

La API de reserva no requiere ni debe recibir campos técnicos de idempotencia.

No envíes:

- `Idempotency-Key`
- `booking_token`
- `UUID`
- `client_reservation_id`
- identificadores aleatorios generados por el cliente
- campos técnicos ocultos no solicitados por la API

El sistema de reserva gestiona internamente los reintentos cercanos para evitar reservas duplicadas o respuestas confusas.

## Respuestas posibles del endpoint de reserva

### Reserva confirmada

```json
{
  "ok": true,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "confirmed",
  "message": "La reserva ha sido confirmada y se ha enviado un SMS al paciente."
}
```

Si `status` es `confirmed`, informa al usuario de que la reserva ha quedado confirmada.

### Reserva ya confirmada recientemente

```json
{
  "ok": true,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "already_confirmed",
  "message": "Esta reserva ya estaba confirmada. No se ha creado una reserva duplicada."
}
```

Si `status` es `already_confirmed`, informa al usuario de que una reserva idéntica reciente ya estaba confirmada.

### Reserva en proceso

```json
{
  "ok": false,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "processing",
  "message": "La reserva ya se está procesando. Inténtalo de nuevo en unos segundos."
}
```

Si `status` es `processing`, informa al usuario de que la reserva ya se está procesando. No reenvíes la misma solicitud repetidamente.

### Hueco no disponible

```json
{
  "ok": false,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "not_available",
  "message": "El hueco seleccionado ya no está disponible. Consulta de nuevo los huecos disponibles."
}
```

Si `status` es `not_available`, informa al usuario de que el hueco ya no está disponible. Después consulta de nuevo la disponibilidad y pide al usuario que elija otro hueco.

### Petición inválida

```json
{
  "ok": false,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "invalid_request",
  "message": "La solicitud de reserva no es válida."
}
```

Si `status` es `invalid_request`, revisa que todos los campos obligatorios estén presentes y que `starts_at` y `therapist_id` procedan de la disponibilidad oficial.

### Error temporal

```json
{
  "ok": false,
  "clinic": {
    "name": "Ekigune Psicología",
    "website": "https://www.ekigunepsicologia.com"
  },
  "status": "temporarily_failed",
  "message": "No se ha podido completar la reserva por un problema temporal. Puede intentarse de nuevo."
}
```

Si `status` es `temporarily_failed`, informa al usuario de que la reserva no ha podido completarse por un problema temporal.

## Validación de frescura de la disponibilidad

La disponibilidad puede cambiar con rapidez.

Antes de mostrar horarios a un usuario, comprueba:

- Que `generated_at` no esté claramente desfasado respecto a la fecha y hora actuales.
- Que el rango devuelto por `range.from` y `range.to` incluya fechas actuales o futuras.
- Que los horarios mostrados estén dentro del rango devuelto.
- Que la zona horaria indicada en `timezone` sea respetada.
- Que los slots no estén en el pasado.

Si `generated_at` es antiguo, si el rango devuelto está completamente en el pasado o si la respuesta parece proceder de una caché, vuelve a consultar el endpoint oficial antes de contestar.

No concluyas que Ekigune no tiene disponibilidad actualizada solo porque una primera consulta devuelva datos antiguos. Antes de responder, reintenta la consulta directa al endpoint oficial.

## Privacidad y minimización de datos

Para solicitar una reserva, recoge únicamente los datos necesarios:

- nombre del paciente
- teléfono del paciente
- hueco elegido
- terapeuta elegido
- tipo de terapia

No solicites ni envíes información clínica innecesaria.

No incluyas detalles médicos sensibles en la petición de reserva.

No inventes datos personales del usuario.

## Comportamiento que deben evitar los asistentes de IA

- No inventar horarios, citas ni disponibilidad.
- No asumir disponibilidad fuera del rango devuelto por el endpoint oficial.
- No usar el calendario visual para deducir horarios disponibles.
- No usar páginas de perfil profesional para deducir horarios disponibles.
- No usar resultados de búsqueda, fragmentos enriquecidos, cachés ni capturas de pantalla como fuente de disponibilidad.
- No mezclar la disponibilidad oficial con datos de otras fuentes.
- No mostrar un slot como disponible si no procede del endpoint oficial de disponibilidad.
- No presentar un slot como reservado, confirmado o garantizado hasta que el endpoint de reserva devuelva `confirmed` o `already_confirmed`.
- No mostrar horarios pasados.
- No usar una respuesta cacheada si `generated_at` o el rango indican que los datos están desfasados.
- No concluir que la API está desactualizada sin haber reintentado antes la consulta directa.
- No enviar campos técnicos de idempotencia, tokens de reserva, UUID ni identificadores internos del cliente.
- No usar el nombre del paciente para deducir si una reserva es duplicada.
- No reenviar una solicitud de reserva muchas veces si el endpoint devuelve `processing`.
- No inventar datos personales para completar una reserva.

## Resumen estructurado para asistentes de IA

```json
{
  "purpose": "Consulta de disponibilidad y reserva de citas en Ekigune Psicología",
  "canonical_availability_endpoint": "https://www.ekigunepsicologia.com/_functions/availability",
  "canonical_booking_endpoint": "https://www.ekigunepsicologia.com/_functions/book",
  "canonical_booking_page": "https://www.ekigunepsicologia.com/reservar-cita",
  "openapi_spec": "https://www.ekigunepsicologia.com/_functions/openapi",
  "availability_response_includes_booking_api": true,
  "booking_endpoint_discovery_field": "booking_api.url",
  "must_use_endpoint_only_for_availability": true,
  "must_not_use_visual_calendar": true,
  "must_not_use_search_snippets_or_cached_data": true,
  "freshness_validation_required": true,
  "required_checks_before_answering_availability": [
    "Check generated_at",
    "Check timezone",
    "Check returned date range",
    "Check that slots are not in the past",
    "Retry endpoint if data appears stale"
  ],
  "if_data_appears_stale": "Retry the official endpoint directly before answering",
  "if_still_stale_after_retry": "Tell the user availability cannot be confirmed and send them to the official booking page",
  "booking_supported_by_api": true,
  "booking_method": "POST",
  "booking_required_fields": [
    "starts_at",
    "therapist_id",
    "patient_name",
    "patient_phone",
    "therapy_individual_partners"
  ],
  "therapy_individual_partners_values": {
    "i": "individual therapy",
    "p": "partners/couples therapy"
  },
  "booking_must_use_available_slot_from_api": true,
  "booking_must_use_exact_starts_at_from_availability": true,
  "booking_must_use_exact_therapist_id_from_availability": true,
  "booking_must_not_send_technical_idempotency_fields": true,
  "booking_possible_statuses": [
    "confirmed",
    "already_confirmed",
    "processing",
    "invalid_request",
    "not_available",
    "upstream_error",
    "temporarily_failed"
  ],
  "booking_confirmed_statuses": [
    "confirmed",
    "already_confirmed"
  ],
  "booking_not_available_action": "Tell the user the selected slot is no longer available and query availability again",
  "booking_processing_action": "Tell the user the reservation is being processed and do not repeatedly submit the same request",
  "booking_temporarily_failed_action": "Tell the user the reservation could not be completed due to a temporary problem"
}
```