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

# Agenda

> Franjas semanales del camello y citas de 60 minutos.

La agenda guarda dos cosas distintas: la semana que el camello ofrece y la cita concreta de un trabajo.

## Ventanas

Cada fila de `CamelloAvailability` es un tramo recurrente: día de la semana (`0` domingo … `6` sábado), inicio y fin en minutos desde medianoche, hora de Colombia (`America/Bogota`).

El camello las reemplaza todas con `PUT /api/me/availability`. Las reglas:

* empiezan y terminan en punto;
* el fin es posterior al inicio y cabe en el día;
* el mismo día no se solapan;
* como máximo 21 franjas.

`GET /api/me/availability` devuelve las del camello de la sesión. Otro rol recibe `403`. Sin ficha de camello, `409`.

La ficha pública muestra esos tramos («Lunes 08:00–12:00»). No muestra qué huecos ya están ocupados.

## Huecos

Un hueco dura 60 minutos y se corta desde el inicio de cada ventana. El horizonte de reserva es de 14 días.

`GET /api/camellos/:id/slots?from=&to=` lista los huecos libres de un camello `ACTIVO`. Lo pueden pedir el cliente y el admin. El rol `CAMELLOS` recibe `403`.

Un hueco está libre si ningún otro trabajo de ese camello, con estado distinto de `CANCELADO`, solapa el intervalo. La comprobación se repite dentro de la transacción que crea o mueve la cita, para que dos reservas del mismo hueco no se pisen.

## Quién reserva

* Con camello elegido (`EXPLORE`), el cliente puede mandar `scheduledStart` al crear el trabajo. El servidor exige que sea un hueco libre de ese camello.
* Sin camello, una fecha en el alta responde `400`. El trabajo queda sin cita hasta que haya camello.
* Después, el cliente dueño usa `POST /api/jobs/:id/schedule` si el trabajo tiene camello y está `PENDIENTE` o `EN_PROGRESO`.

Si el camello no publicó ventanas, la solicitud sigue adelante sin hora.

## Vista

`/agenda` muestra la semana o el mes (`?view=week` o `?view=month`; sin `view` es la semana). `from=YYYY-MM-DD` ancla el periodo en hora de Colombia. La rejilla del mes empieza en lunes e incluye los días vecinos atenuados; cada día enlaza a esa semana.

`GET /api/agenda?from=&to=` usa la misma visibilidad que la lista de trabajos: el cliente ve las suyas, el camello las de su ficha y el admin todas las del rango. El listado admite hasta 42 días, lo que cabe en una rejilla mensual. El horizonte de 14 días sigue aplicando solo a la reserva de huecos.

## Recordatorio

`POST /api/cron/appointment-reminders` busca citas no canceladas cuya hora cae en las próximas 24 horas y que aún no tienen `reminderSentAt`. Avisa al cliente y al camello por la bandeja (`APPOINTMENT_REMINDER`) y marca la cita para no repetirla. Lo llama un cron externo con `Authorization: Bearer` y `CRON_SECRET`. Sin esa variable responde `503`.


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