# API del panel de BookClock (para agentes de IA)

El servidor MCP de BookClock (`/mcp`) expone la API REST que usa el panel del negocio a través de cuatro
herramientas, separadas por tipo de operación:

- `consultar_api`: GET (solo lectura).
- `crear_en_api`: POST.
- `actualizar_en_api`: PUT y PATCH.
- `borrar_en_api`: DELETE.

Cada llamada corre como el dueño de la cuenta conectada, con las mismas validaciones, permisos y límites que
el panel. Las escrituras devuelven una vista previa y no hacen nada hasta que se repiten con `confirm: true`.
Las respuestas son JSON en inglés, con los nombres de las columnas; los errores son `{"error": texto, "code": código}`
con su código HTTP. Las claves con nombre de credencial (token, secret, password, hash...), los nombres de archivo
de los comprobantes y todo lo que tenga forma de token llegan como `"[oculto]"`. Una respuesta de más de 60.000
caracteres llega recortada: de la lista más larga vienen los primeros elementos que entran, con el total y
cuántos vinieron (`truncado: true`, `elementos`). Ninguna ruta pagina: los turnos se piden por partes con
`listar_turnos`, que filtra por fechas, estado, origen, servicio o cliente.

Las fechas son AAAA-MM-DD y las horas HH:MM, en la zona horaria del negocio.

## Rutas

### /api/provider/settings

Perfil y reglas de reserva (los datos de transferencia y la foto nueva, no).

- `GET` (`consultar_api`): sin parámetros
- `PUT` (`actualizar_en_api`): cualquier subconjunto de: name, service_name, description, location, contact_phone, image_url (solo null, para quitar la foto: una foto nueva se sube con cambiar_foto), slot_minutes, buffer_minutes, min_notice_minutes, booking_phone ("hidden"|"optional"|"required"), allow_guest_booking, max_appointments_per_user, allow_client_reschedule, max_reschedules, cancellation_window_hours, requires_deposit, deposit_amount, deposit_currency, notify_bookings, notify_email, timezone, currency. Campos desconocidos se rechazan (400).

### /api/provider/services

Servicios.

- `GET` (`consultar_api`): sin parámetros
- `POST` (`crear_en_api`): {"name": texto, "duration_minutes": 5-720, "description"?: texto|null, "price"?: número|null, "charge"?: "none"|"deposit"|"full" (cobrar al reservar: solo tiendas Shopify), "deposit_percent"?: 1-100|null, "deposit_amount"?: número|null}

### /api/provider/services/{id}

Un servicio: cambiarlo (PUT), subirlo o bajarlo en la lista (PATCH) o borrarlo (DELETE).

- `PUT` (`actualizar_en_api`): {"name": texto, "duration_minutes": 5-720, "description"?: texto|null, "price"?: número|null, "charge"?: "none"|"deposit"|"full" (cobrar al reservar: solo tiendas Shopify), "deposit_percent"?: 1-100|null, "deposit_amount"?: número|null}
- `PATCH` (`actualizar_en_api`): {"move": "up"|"down"}
- `DELETE` (`borrar_en_api`): sin cuerpo

### /api/provider/bookings

Horarios libres de un día y carga manual de turnos.

- `GET` (`consultar_api`): query `?date=AAAA-MM-DD[&serviceId=uuid]`
- `POST` (`crear_en_api`): {"date": "AAAA-MM-DD", "time": "HH:MM", "name": texto, "email"?: texto, "phone"?: texto, "note"?: texto, "serviceId"?: uuid, "notify"?: boolean (mail al cliente, por defecto true), "language"?: "es"|"en"}

### /api/provider/stats

Resumen de 30 días.

- `GET` (`consultar_api`): sin parámetros

### /api/provider/getting-started

Primeros pasos.

- `GET` (`consultar_api`): sin parámetros

### /api/provider/walk-ins

Registrar a alguien que llegó sin turno.

- `POST` (`crear_en_api`): {"idempotencyKey": uuid nuevo por cada llegada, "name"?: texto}

### /api/provider/calendar-feed

Link de calendario: su estado (GET) o revocarlo (DELETE).

- `GET` (`consultar_api`): sin parámetros
- `DELETE` (`borrar_en_api`): sin cuerpo
- `POST`: no disponible. El link de calendario se crea con crear_link_de_calendario, que lo muestra una sola vez.

### /api/appointments

Todos los turnos del negocio.

- `GET` (`consultar_api`): sin parámetros
- `POST`: no disponible. Eso es reservar como cliente en otro negocio. Un turno en esta agenda se carga con crear_turno.

### /api/appointments/{id}

Un turno: cancelarlo, cerrarlo, marcar la seña o moverlo.

- `PATCH` (`actualizar_en_api`): {"action": "cancel"|"complete"|"no_show"|"mark_deposit_paid"} o {"action": "move", "date": "AAAA-MM-DD", "time": "HH:MM"}

### /api/availability

Horarios puntuales (y con ?providerId= la grilla pública de este negocio).

- `GET` (`consultar_api`): query `[?providerId=<id de este negocio>&serviceId=uuid]`
- `POST` (`crear_en_api`): {"date": "AAAA-MM-DD", "startTime": "HH:MM", "endTime": "HH:MM"}

### /api/availability/{id}

Quitar un horario puntual.

- `DELETE` (`borrar_en_api`): sin cuerpo

### /api/recurring-availability

Horario semanal entero.

- `GET` (`consultar_api`): sin parámetros
- `PUT` (`actualizar_en_api`): {"days": [{"day": 0-6 (0 = domingo), "startTime": "HH:MM", "endTime": "HH:MM"}, ...]} (reemplaza la semana entera)

### /api/time-off

Cierres.

- `GET` (`consultar_api`): sin parámetros
- `POST` (`crear_en_api`): {"startDate": "AAAA-MM-DD", "endDate"?: "AAAA-MM-DD", "startTime"?: "HH:MM", "endTime"?: "HH:MM", "reason"?: texto}

### /api/time-off/{id}

Quitar un cierre.

- `DELETE` (`borrar_en_api`): sin cuerpo

### /api/waitlist

Lista de espera del negocio.

- `GET` (`consultar_api`): sin parámetros
- `POST`: no disponible. Anotarse en una lista de espera es de un cliente, no del negocio.

### /api/payment-proofs/{id}

Aprobar o rechazar un comprobante de seña.

- `PATCH` (`actualizar_en_api`): {"status": "approved"|"rejected"}

### /api/shopify/setup

Ocultar o mostrar la guía de inicio en Shopify (solo tiendas Shopify).

- `PUT` (`actualizar_en_api`): {"dismissed": boolean}

### /api/providers

El directorio público.

- `GET` (`consultar_api`): sin parámetros

### /api/embed/{id}

Lo que muestra el widget público de un negocio.

- `GET` (`consultar_api`): sin parámetros

## Rutas que no están disponibles

- `/api/account/*`: La contraseña, cerrar sesión en todos lados y borrar la cuenta son solo del dueño, desde el panel. La cuenta se ve con ver_cuenta.
- `/api/provider/agent-tokens/*`: Un agente no crea tokens. Las conexiones se ven con ver_cuenta y se cortan con desconectar_agente.
- `/api/payments/*`: Los pagos no pasan por agentes: el directorio de conectores de Claude no admite mover dinero. pagar_plan devuelve el link de pago del plan, que el dueño abre y paga en su navegador; nada se cobra desde acá.
- `/api/provider/image`: La foto se cambia con cambiar_foto, que comprueba que sea una imagen.
- `GET /api/payment-proofs`: Los comprobantes de esta agenda se ven con ver_comprobantes y ver_comprobante.
- `/api/files/*, /api/images/*`: Los archivos no salen por la API: un comprobante se ve con ver_comprobante.
- `/api/calendar/*`: Es el link privado del calendario: ver_calendario_externo y crear_link_de_calendario.
- `/api/guest/*`: Son las páginas de quien reservó sin cuenta, con su link. Para el negocio: crear_turno, reprogramar_turno, cancelar_turno, reenviar_confirmacion.
- `/api/waitlist/{id}`: Salir de una lista de espera es de un cliente, no del negocio.
- `/api/cron, /api/realtime, /api/devices, /api/health, /api/ready, /api/shopify/webhooks, /api/shopify/proxy`: Es maquinaria del servidor, de Shopify o del teléfono, no de la cuenta.