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

# Schedules API

> Endpoints for creating, listing, and updating vacation schedules (cronogramas) for each employee and vacation year.

A **schedule** (`CronogramaVacaciones`) represents one vacation year for a single employee. It tracks the total days available, how many flexible and block days have been used, and the approval state. The actual vacation date ranges are stored separately and linked to the schedule — see [Ranges](/api/ranges).

Each employee gets exactly **30 total vacation days** per period:

* Up to **7 flexible days** — short ranges of 1–7 days
* **23 block days** — continuous ranges of 7 or more days

<Note>
  All endpoints require a valid `Authorization: Bearer <token>` header. See [Authentication](/api/authentication) for details.
</Note>

***

## List all schedules

Returns every schedule in the system across all employees.

### `GET /api/schedules`

**No request body.**

**Response** — `CronogramaVacaciones[]`

<ResponseField name="id" type="string" required>
  Unique identifier for the schedule.
</ResponseField>

<ResponseField name="personalId" type="string" required>
  ID of the employee this schedule belongs to.
</ResponseField>

<ResponseField name="anioVacacional" type="string" required>
  Vacation year label (e.g. `"2026-2027"`).
</ResponseField>

<ResponseField name="fechaInicioAnio" type="string" required>
  ISO 8601 date string for when the vacation period begins.
</ResponseField>

<ResponseField name="fechaFinAnio" type="string" required>
  ISO 8601 date string for when the vacation period ends.
</ResponseField>

<ResponseField name="diasTotales" type="number" required>
  Total vacation days in the period. Always `30`.
</ResponseField>

<ResponseField name="diasFlexiblesDisponibles" type="number" required>
  Maximum flexible days available. Always `7`.
</ResponseField>

<ResponseField name="diasFlexiblesUsados" type="number" required>
  Flexible days already scheduled.
</ResponseField>

<ResponseField name="diasBloqueDisponibles" type="number" required>
  Block days available. Always `23`.
</ResponseField>

<ResponseField name="diasBloqueUsados" type="number" required>
  Block days already scheduled.
</ResponseField>

<ResponseField name="diasAdelanto" type="number" required>
  Days used as an advance (adelanto) against this period.
</ResponseField>

<ResponseField name="rangos" type="RangoVacaciones[]" required>
  Vacation date ranges belonging to this schedule. May be an empty array if ranges have not been fetched separately.
</ResponseField>

<ResponseField name="estado" type="string" required>
  Approval status: `"pendiente"`, `"aprobado"`, or `"rechazado"`.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:5175/api/schedules \
    -H "Authorization: Bearer <token>"
  ```

  ```json Response theme={null}
  [
    {
      "id": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "anioVacacional": "2026-2027",
      "fechaInicioAnio": "2026-06-01",
      "fechaFinAnio": "2027-05-31",
      "diasTotales": 30,
      "diasFlexiblesDisponibles": 7,
      "diasFlexiblesUsados": 3,
      "diasBloqueDisponibles": 23,
      "diasBloqueUsados": 14,
      "diasAdelanto": 0,
      "rangos": [],
      "estado": "pendiente"
    }
  ]
  ```
</CodeGroup>

***

## List schedules for an employee

Returns all schedules that belong to a specific employee. Use this when you need only the records for one person.

### `GET /api/schedules/:personalId`

<ParamField path="personalId" type="string" required>
  The UUID of the employee whose schedules you want to retrieve.
</ParamField>

**No request body.**

**Response** — `CronogramaVacaciones[]` filtered to the given employee. The response shape is identical to [List all schedules](#list-all-schedules).

<Note>
  Ranges are not embedded in this response. Fetch them separately with `GET /api/ranges/:scheduleId` for each schedule returned.
</Note>

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:5175/api/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer <token>"
  ```

  ```json Response theme={null}
  [
    {
      "id": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "anioVacacional": "2026-2027",
      "fechaInicioAnio": "2026-06-01",
      "fechaFinAnio": "2027-05-31",
      "diasTotales": 30,
      "diasFlexiblesDisponibles": 7,
      "diasFlexiblesUsados": 3,
      "diasBloqueDisponibles": 23,
      "diasBloqueUsados": 14,
      "diasAdelanto": 0,
      "rangos": [],
      "estado": "pendiente"
    }
  ]
  ```
</CodeGroup>

***

## Create a schedule

Creates a new vacation schedule for an employee. Send all schedule fields except `rangos` — ranges are managed through the [Ranges API](/api/ranges).

### `POST /api/schedules`

<ParamField body="id" type="string" required>
  Client-generated UUID for the schedule.
</ParamField>

<ParamField body="personalId" type="string" required>
  ID of the employee this schedule belongs to.
</ParamField>

<ParamField body="anioVacacional" type="string" required>
  Vacation year label (e.g. `"2026-2027"`).
</ParamField>

<ParamField body="fechaInicioAnio" type="string" required>
  ISO 8601 start date of the vacation period.
</ParamField>

<ParamField body="fechaFinAnio" type="string" required>
  ISO 8601 end date of the vacation period.
</ParamField>

<ParamField body="diasTotales" type="number" required default="30">
  Total vacation days. Always `30`.
</ParamField>

<ParamField body="diasFlexiblesDisponibles" type="number" required default="7">
  Maximum flexible days. Always `7`.
</ParamField>

<ParamField body="diasFlexiblesUsados" type="number" required default="0">
  Flexible days already used. Set to `0` on creation.
</ParamField>

<ParamField body="diasBloqueDisponibles" type="number" required default="23">
  Block days available. Always `23`.
</ParamField>

<ParamField body="diasBloqueUsados" type="number" required default="0">
  Block days already used. Set to `0` on creation.
</ParamField>

<ParamField body="diasAdelanto" type="number" required default="0">
  Advance days already deducted. Set to `0` on creation.
</ParamField>

<ParamField body="estado" type="string" required default="pendiente">
  Initial approval status. One of `"pendiente"`, `"aprobado"`, `"rechazado"`.
</ParamField>

**Response** — the created `CronogramaVacaciones` object.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST http://localhost:5175/api/schedules \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "anioVacacional": "2026-2027",
      "fechaInicioAnio": "2026-06-01",
      "fechaFinAnio": "2027-05-31",
      "diasTotales": 30,
      "diasFlexiblesDisponibles": 7,
      "diasFlexiblesUsados": 0,
      "diasBloqueDisponibles": 23,
      "diasBloqueUsados": 0,
      "diasAdelanto": 0,
      "estado": "pendiente"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "sched-001",
    "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "anioVacacional": "2026-2027",
    "fechaInicioAnio": "2026-06-01",
    "fechaFinAnio": "2027-05-31",
    "diasTotales": 30,
    "diasFlexiblesDisponibles": 7,
    "diasFlexiblesUsados": 0,
    "diasBloqueDisponibles": 23,
    "diasBloqueUsados": 0,
    "diasAdelanto": 0,
    "estado": "pendiente"
  }
  ```
</CodeGroup>

***

## Update a schedule

Updates day counters and approval status on an existing schedule. This endpoint is called whenever a range is added, deleted, or rescheduled to keep the schedule's counters in sync.

### `PUT /api/schedules/:id`

<ParamField path="id" type="string" required>
  The UUID of the schedule to update.
</ParamField>

<ParamField body="id" type="string" required>
  Schedule ID (must match the path parameter).
</ParamField>

<ParamField body="personalId" type="string" required>
  ID of the employee.
</ParamField>

<ParamField body="anioVacacional" type="string" required>
  Vacation year label.
</ParamField>

<ParamField body="fechaInicioAnio" type="string" required>
  ISO 8601 start date.
</ParamField>

<ParamField body="fechaFinAnio" type="string" required>
  ISO 8601 end date.
</ParamField>

<ParamField body="diasTotales" type="number" required>
  Total vacation days.
</ParamField>

<ParamField body="diasFlexiblesDisponibles" type="number" required>
  Maximum flexible days available.
</ParamField>

<ParamField body="diasFlexiblesUsados" type="number" required>
  Updated flexible days used.
</ParamField>

<ParamField body="diasBloqueDisponibles" type="number" required>
  Block days available.
</ParamField>

<ParamField body="diasBloqueUsados" type="number" required>
  Updated block days used.
</ParamField>

<ParamField body="diasAdelanto" type="number" required>
  Updated advance days.
</ParamField>

<ParamField body="estado" type="string" required>
  Approval status: `"pendiente"`, `"aprobado"`, or `"rechazado"`.
</ParamField>

**Response** — the updated `CronogramaVacaciones` object.

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT http://localhost:5175/api/schedules/sched-001 \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "anioVacacional": "2026-2027",
      "fechaInicioAnio": "2026-06-01",
      "fechaFinAnio": "2027-05-31",
      "diasTotales": 30,
      "diasFlexiblesDisponibles": 7,
      "diasFlexiblesUsados": 3,
      "diasBloqueDisponibles": 23,
      "diasBloqueUsados": 14,
      "diasAdelanto": 0,
      "estado": "aprobado"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "sched-001",
    "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "anioVacacional": "2026-2027",
    "fechaInicioAnio": "2026-06-01",
    "fechaFinAnio": "2027-05-31",
    "diasTotales": 30,
    "diasFlexiblesDisponibles": 7,
    "diasFlexiblesUsados": 3,
    "diasBloqueDisponibles": 23,
    "diasBloqueUsados": 14,
    "diasAdelanto": 0,
    "estado": "aprobado"
  }
  ```
</CodeGroup>