> ## 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.

# Ranges API

> Endpoints for listing, creating, and deleting vacation date ranges (rangos) within a schedule.

A **range** (`RangoVacaciones`) is a single block of vacation dates within a schedule. Ranges are linked to a schedule via `scheduleId` and to an employee via `personalId`. Multiple ranges make up an employee's vacation plan for the year.

## Range types

| Type       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `flexible` | Short vacation of 1–7 days. Up to 7 flexible days can be taken per period.         |
| `bloque`   | Continuous vacation of 7 or more days. Uses days from the 23-day block allocation. |

The type is determined automatically by the number of days requested. If `diasSolicitados <= 7` and the employee still has flexible days remaining, the type is `flexible`; otherwise it is `bloque`.

## Range states

| State          | Description                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `activo`       | The range is active and has not been rescheduled.                                                                                         |
| `reprogramado` | The range was replaced by a new range. The original is kept for audit purposes and its `reprogramadoPor` field points to the replacement. |

## Reschedule linkage

When a range is rescheduled, the system creates a new range and marks the original as `reprogramado`:

* `reprogramadoPor` — ID of the new range that replaced this one (set on the original).
* `reprogramadoDesde` — array of IDs of original ranges that were merged or replaced to create this new range (set on the new range).

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

***

## List ranges for a schedule

Returns all vacation ranges belonging to a specific schedule.

### `GET /api/ranges/:scheduleId`

<ParamField path="scheduleId" type="string" required>
  The UUID of the schedule whose ranges you want to retrieve.
</ParamField>

**No request body.**

**Response** — `RangoVacaciones[]`

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

<ResponseField name="scheduleId" type="string">
  ID of the schedule this range belongs to.
</ResponseField>

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

<ResponseField name="fechaInicio" type="string" required>
  ISO 8601 start date of the vacation range (e.g. `"2026-07-14"`).
</ResponseField>

<ResponseField name="fechaFin" type="string" required>
  ISO 8601 end date of the vacation range (e.g. `"2026-07-20"`).
</ResponseField>

<ResponseField name="diasSolicitados" type="number" required>
  Number of vacation days in this range.
</ResponseField>

<ResponseField name="tipo" type="string" required>
  Range type: `"flexible"` or `"bloque"`.
</ResponseField>

<ResponseField name="incluye_finde" type="boolean">
  `true` if the range was extended to include a weekend because the start or end date fell on a Friday.
</ResponseField>

<ResponseField name="estado" type="string">
  `"activo"` or `"reprogramado"`. Defaults to `"activo"`.
</ResponseField>

<ResponseField name="esAdelanto" type="boolean">
  `true` if this range was created as a vacation advance (adelanto) against a future period.
</ResponseField>

<ResponseField name="reprogramadoDesde" type="string[]">
  IDs of the original ranges that were replaced or merged to create this range. Present only on rescheduled replacement ranges.
</ResponseField>

<ResponseField name="reprogramadoPor" type="string | null">
  ID of the replacement range that rescheduled this range. `null` if the range is still active.
</ResponseField>

<ResponseField name="esinadId" type="string | null">
  ID of the linked ESINAD document, if any.
</ResponseField>

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

  ```json Response theme={null}
  [
    {
      "id": "VAC-2026-001",
      "scheduleId": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fechaInicio": "2026-07-14",
      "fechaFin": "2026-07-20",
      "diasSolicitados": 7,
      "tipo": "flexible",
      "incluye_finde": false,
      "estado": "activo",
      "esAdelanto": false,
      "reprogramadoDesde": [],
      "reprogramadoPor": null,
      "esinadId": null
    }
  ]
  ```
</CodeGroup>

***

## Create a range

Creates a new vacation date range and associates it with a schedule.

### `POST /api/ranges`

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

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

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

<ParamField body="fechaInicio" type="string" required>
  ISO 8601 start date (e.g. `"2026-07-14"`).
</ParamField>

<ParamField body="fechaFin" type="string" required>
  ISO 8601 end date (e.g. `"2026-07-20"`). Must be on or after `fechaInicio`.
</ParamField>

<ParamField body="diasSolicitados" type="number" required>
  Number of vacation days being requested.
</ParamField>

<ParamField body="tipo" type="string" required>
  `"flexible"` for ranges up to 7 days; `"bloque"` for 7 or more days.
</ParamField>

<ParamField body="incluye_finde" type="boolean">
  Whether the range extends over a weekend because a Friday was selected.
</ParamField>

<ParamField body="estado" type="string" default="activo">
  Initial state. Use `"activo"` for new ranges.
</ParamField>

<ParamField body="esAdelanto" type="boolean" default="false">
  Set to `true` when creating a vacation advance.
</ParamField>

<ParamField body="reprogramadoPor" type="string | null" default="null">
  ID of the range that rescheduled this one. Pass `null` for new ranges.
</ParamField>

<ParamField body="esinadId" type="string | null" default="null">
  ID of a linked ESINAD document. Pass `null` if not applicable.
</ParamField>

<Note>
  After creating a range, update the parent schedule's day counters with `PUT /api/schedules/:id` to keep `diasFlexiblesUsados` and `diasBloqueUsados` accurate.
</Note>

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

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST http://localhost:5175/api/ranges \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "VAC-2026-001",
      "scheduleId": "sched-001",
      "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "fechaInicio": "2026-07-14",
      "fechaFin": "2026-07-20",
      "diasSolicitados": 7,
      "tipo": "flexible",
      "incluye_finde": false,
      "estado": "activo",
      "esAdelanto": false,
      "reprogramadoPor": null,
      "esinadId": null
    }'
  ```

  ```json Response theme={null}
  {
    "id": "VAC-2026-001",
    "scheduleId": "sched-001",
    "personalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fechaInicio": "2026-07-14",
    "fechaFin": "2026-07-20",
    "diasSolicitados": 7,
    "tipo": "flexible",
    "incluye_finde": false,
    "estado": "activo",
    "esAdelanto": false,
    "reprogramadoPor": null,
    "esinadId": null
  }
  ```
</CodeGroup>

***

## Delete a range

Deletes a vacation range by its ID.

### `DELETE /api/ranges/:id`

<ParamField path="id" type="string" required>
  The ID of the range to delete.
</ParamField>

**No request body.**

**Response** — `200 OK` on success.

<Warning>
  Ranges with `estado: "reprogramado"` are kept for audit purposes and cannot be deleted through the front end. However, the API will accept the delete request if called directly. After deleting a range, update the parent schedule's day counters with `PUT /api/schedules/:id`.
</Warning>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE http://localhost:5175/api/ranges/VAC-2026-001 \
    -H "Authorization: Bearer <token>"
  ```

  ```json Response theme={null}
  {}
  ```
</CodeGroup>

***

## Rescheduling workflow

Rescheduling a range involves two coordinated API calls:

<Steps>
  <Step title="Create the replacement range(s)">
    `POST /api/ranges` for each new range, setting `reprogramadoDesde` to the IDs of the original ranges being replaced, and `estado: "activo"`.
  </Step>

  <Step title="Delete the original ranges">
    `DELETE /api/ranges/:id` for each original range being replaced. The front end archives these by removing them and storing rescheduling metadata client-side.
  </Step>

  <Step title="Update the schedule counters">
    `PUT /api/schedules/:id` with the recalculated `diasFlexiblesUsados` and `diasBloqueUsados` values to keep the schedule in sync.
  </Step>
</Steps>

<Note>
  The `reprogramadoDesde` array on the new range records which original ranges it replaced. This linkage powers the rescheduling history displayed in the Vacation Overview module.
</Note>