# Feriados

## GET /api/quantis/v2/holidays/

Devuelve la lista de feriados bancarios y nacionales venezolanos para un año dado, con contexto sobre si hoy es feriado.

| | |
|---|---|
| **Método** | `GET` |
| **URL** | `https://app.vzla.io/api/quantis/v2/holidays/` |
| **Autenticación** | `Authorization: Bearer vzlaio_...` |

### Parámetros de consulta

| Parámetro | Tipo | Requerido | Descripción | Por defecto |
|---|---|---|---|---|
| `year` | integer | No | El año calendario a consultar, p. ej. `2025` | Año actual |
| `type` | string | No | Filtrar por tipo: `bancario` o `feriado` | Todos los tipos |

### Solicitud

```bash
# Todos los feriados de 2025
curl --request GET \
  --url 'https://app.vzla.io/api/quantis/v2/holidays/?year=2025' \
  --header 'Authorization: Bearer vzlaio_TU_TOKEN_AQUI'

# Solo feriados bancarios
curl --request GET \
  --url 'https://app.vzla.io/api/quantis/v2/holidays/?year=2025&type=bancario' \
  --header 'Authorization: Bearer vzlaio_TU_TOKEN_AQUI'
```

---

### Respuesta

#### `data`

Un array plano de objetos de feriado.

| Campo | Tipo | Descripción |
|---|---|---|
| `date` | string (fecha ISO 8601) | Fecha del feriado, p. ej. `"2025-01-01"` |
| `name` | string | Nombre del feriado |
| `type` | string | `"bancario"` o `"feriado"` |
| `notes` | string | Notas opcionales sobre este feriado |

#### `meta`

| Campo | Tipo | Descripción |
|---|---|---|
| `today` | object | Contexto sobre el día calendario actual |

**`meta.today`**

| Campo | Tipo | Descripción |
|---|---|---|
| `date` | string (fecha ISO 8601) | La fecha de hoy |
| `is_bank_holiday` | boolean | Si hoy es feriado bancario |
| `is_weekend` | boolean | Si hoy es sábado o domingo |

`meta.today` siempre refleja el día actual, independientemente del `year` consultado.

---

### Encabezados de respuesta

| Encabezado | Descripción |
|---|---|
| `X-API-Version` | `2.0` |
| `X-Quota-Limit` | Tu límite mensual de solicitudes |
| `X-Quota-Remaining` | Solicitudes restantes este mes |
| `X-Quota-Reset` | Timestamp ISO 8601 del próximo reinicio de cuota |
| `X-Request-ID` | UUID de esta solicitud |

---

### Ejemplo de respuesta

```json
{
  "data": [
    {
      "date": "2025-01-01",
      "name": "Año Nuevo",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-05-12",
      "name": "Día del Trabajador",
      "type": "feriado",
      "notes": ""
    },
    {
      "date": "2025-06-03",
      "name": "Día de la Independencia",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-11-04",
      "name": "Día de la Resistencia Indígena",
      "type": "bancario",
      "notes": ""
    },
    {
      "date": "2025-11-12",
      "name": "Día de la Raza",
      "type": "feriado",
      "notes": ""
    }
  ],
  "meta": {
    "today": {
      "date": "2026-05-06",
      "is_bank_holiday": false,
      "is_weekend": false
    }
  }
}
```

---

### Códigos de estado HTTP

| Código | Significado |
|---|---|
| `200 OK` | Éxito. |
| `400 Bad Request` | Parámetro `year` o `type` inválido. |
| `401 Unauthorized` | Token ausente o inválido. |
| `405 Method Not Allowed` | Solo se admite GET. |
| `429 Too Many Requests` | Cuota mensual agotada. |
| `500 Internal Server Error` | Error del servidor. Reintenta después de un momento. |

#### 400 — año inválido

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "year must be a 4-digit integer",
    "details": {}
  }
}
```

#### 400 — tipo inválido

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "type must be one of: bancario, feriado",
    "details": {}
  }
}
```

#### 401 — sin encabezado Authorization

```json
{
  "error": {
    "code": "auth_missing",
    "message": "Authentication credentials were not provided"
  }
}
```

#### 401 — token inválido

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid token format"
  }
}
```

#### 429

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota limit exceeded.",
    "details": {
      "reset_at": "2026-06-01T00:00:00Z"
    }
  }
}
```
**Note:** Este endpoint tiene caché de **24 horas** por combinación de año y tipo.