¿Qué países tiene disponibles la API de feriados?

La API de feriados.io soporta 11 países: Chile (CL), Uruguay (UY), Paraguay (PY), Colombia (CO), Perú (PE), Bolivia (BO), Ecuador (EC), Costa Rica (CR), Panamá (PA), Argentina (AR) y México (MX).

¿Necesito registro para usar la API de feriados?

Sí, todos los planes requieren una API key, incluyendo el plan Free. El registro es gratis, sin tarjeta de crédito, y toma menos de 30 segundos. Recibes 1.000 requests por mes sin costo.

¿Cómo consulto los feriados de Chile por API?

Realiza un GET a https://api.feriados.io/v1/CL/holidays/2026 para obtener todos los feriados de Chile en 2026. Puedes filtrar por mes agregando el número de mes al final: /v1/CL/holidays/2026/4

Documentación

feriados.io es el motor de calendario operativo para Latinoamérica — días hábiles, plazos y feriados para 11 países en un solo endpoint. Todos los endpoints retornan JSON y soportan CORS.

Base URL

https://api.feriados.io

Autenticación

Todos los planes requieren una API key, incluyendo el plan Free. Obtén la tuya gratis en feriados.io/register — sin tarjeta. Inclúyela en cada request:

Authorization: Bearer frd_tu_api_key

Límites de uso

Plan	Requests / mes	Identificación	Endpoints
Free	1.000	Por API key	Consulta y validación
Starter	25.000	Por API key	Consulta + lógica operativa completa
Team	100.000	Por API key	Consulta + lógica operativa + iCal live
Business	Fair use	Por API key	Completo + alertas legislativas

Los headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se incluyen en todas las respuestas.

Formato de respuesta

Todos los endpoints retornan la misma estructura base:

Éxito

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "country": "CL",
    "total": 18
  }
}

Error

{
  "success": false,
  "error": {
    "code": "INVALID_YEAR",
    "message": "Year must be a number between 1900 and 2100.",
    "status": 400
  }
}

Endpoints

GET /v1/countries

Retorna la lista de países soportados, su estado de disponibilidad y los endpoints disponibles para cada uno.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "code": "CL",
      "name": "Chile",
      "status": "available",
      "years_covered": { "from": 2020, "to": 2030 },
      "endpoints": [
        "/v1/CL/holidays/{year}",
        "/v1/CL/holidays/{year}/{month}",
        "/v1/CL/is-business-day",
        "/v1/CL/next-holiday"
      ]
    }
  ],
  "meta": { "total": 11, "available": 11 }
}

GET /v1/{country}/holidays/{year}

Retorna todos los feriados del país indicado para el año indicado.

Parámetros de ruta

Parámetro	Tipo	Descripción
country	string	Código ISO 3166-1 alpha-2 (ej: `CL`, `CO`, `PE`)
year	número	Año entre 1900 y 2100

Ejemplo

GET /v1/UY/holidays/2026

{
  "success": true,
  "data": [
    { "date": "2026-01-01", "name": "Año Nuevo", "type": "national", "irrenunciable": true },
    { "date": "2026-01-06", "name": "Día de los Niños", "type": "national", "irrenunciable": false },
    ...
  ],
  "meta": { "country": "UY", "year": 2026, "total": 15 }
}

Ver tabla completa: Chile 2026, Colombia, Perú, Uruguay y más países →

GET /v1/{country}/holidays/{year}/{month}

Retorna los feriados del país indicado para un mes específico.

Parámetros de ruta

Parámetro	Tipo	Descripción
country	string	Código ISO 3166-1 alpha-2
year	número	Año entre 1900 y 2100
month	número	Mes entre 1 y 12

Ejemplo

GET /v1/PY/holidays/2026/5

{
  "success": true,
  "data": [
    { "date": "2026-05-01", "name": "Día de los Trabajadores", "type": "national" },
    { "date": "2026-05-14", "name": "Víspera de la Independencia Nacional", "type": "national" },
    { "date": "2026-05-15", "name": "Independencia Nacional", "type": "national" }
  ],
  "meta": { "country": "PY", "year": 2026, "month": 5, "total": 3 }
}

GET /v1/{country}/is-business-day

Indica si una fecha es día hábil, considerando fines de semana y feriados del país indicado. El parámetro region aplica solo a Chile (feriados regionales).

Query parameters

Parámetro	Requerido	Descripción
date	Sí	Fecha en formato `YYYY-MM-DD`
region	No	Código ISO 3166-2 de la región, solo para CL (ej: `CL-AP`)

Ejemplos

GET /v1/CL/is-business-day?date=2026-09-18

{
  "success": true,
  "data": { "date": "2026-09-18", "is_business_day": false, "day_of_week": "Friday", "region": null },
  "meta": { "country": "CL", "total": 1 }
}

GET /v1/UY/is-business-day?date=2026-01-06

{
  "success": true,
  "data": { "date": "2026-01-06", "is_business_day": false, "day_of_week": "Tuesday", "region": null },
  "meta": { "country": "UY", "total": 1 }
}

Ver días hábiles por mes: Chile 2026, Colombia, Uruguay y más países →

GET /v1/{country}/next-holiday

Retorna el próximo feriado a partir de una fecha. Si no se indica fecha, usa el día de hoy.

Query parameters

Parámetro	Requerido	Descripción
from	No	Fecha de inicio en formato `YYYY-MM-DD`. Default: hoy.

Ejemplo

GET /v1/PY/next-holiday?from=2026-03-14

{
  "success": true,
  "data": { "date": "2026-04-02", "name": "Jueves Santo", "type": "national", "days_until": 19 },
  "meta": { "country": "PY", "from": "2026-03-14", "total": 1 }
}

Ver próximos feriados: Chile, Colombia, Paraguay y más países →

GET /v1/{country}/calendar/{year} iCal

Retorna un archivo iCalendar (.ics) con todos los feriados del año. Compatible con Google Calendar, Apple Calendar, Outlook, Notion Calendar y cualquier app que soporte RFC 5545.

Ejemplo de contenido

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Feriados API//feriados.io//ES
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Feriados Chile 2026
BEGIN:VEVENT
UID:20260101-cl-añ[email protected]
DTSTART;VALUE=DATE:20260101
SUMMARY:Año Nuevo
END:VEVENT
...
END:VCALENDAR

GET /v1/{country}/calendar iCal Team / Business

URL de suscripción permanente. Siempre devuelve los feriados del año en curso. Requiere plan Team o Business.

El plan Free recibe un error 403 PLAN_UPGRADE_REQUIRED. Usa /calendar/{year} para descarga manual sin costo.

Lógica operativa

Endpoints que resuelven cálculos de calendario operativo directamente en la API — sin que tengas que implementarlos en tu código.

Disponible en planes Starter, Team y Business

GET /v1/:country/business-days/add

Suma N días hábiles a una fecha. Útil para calcular fechas de entrega, vencimientos o deadlines reales.

Parámetro	Tipo	Descripción
date	string	Fecha de inicio en formato YYYY-MM-DD
days	número	Cantidad de días hábiles a sumar (1–365)

GET /v1/CL/business-days/add?date=2026-09-18&days=5

{
  "success": true,
  "data": { "result_date": "2026-09-25" },
  "meta": { "country": "CL", "start_date": "2026-09-18", "business_days_added": 5 }
}

GET /v1/:country/business-days/subtract

Resta N días hábiles a una fecha. Útil para calcular fechas límite hacia atrás desde un vencimiento.

Parámetro	Tipo	Descripción
date	string	Fecha de referencia en formato YYYY-MM-DD
days	número	Cantidad de días hábiles a restar (1–365)

GET /v1/CO/business-days/subtract?date=2026-12-31&days=3

{
  "success": true,
  "data": { "result_date": "2026-12-28" },
  "meta": { "country": "CO", "start_date": "2026-12-31", "business_days_subtracted": 3 }
}

GET /v1/:country/business-days/between

Cuenta los días hábiles entre dos fechas, ambas inclusive. Útil para SLAs, cálculo de plazos contractuales o reportes de productividad.

Parámetro	Tipo	Descripción
from	string	Fecha de inicio en formato YYYY-MM-DD
to	string	Fecha de término en formato YYYY-MM-DD

GET /v1/PE/business-days/between?from=2026-01-01&to=2026-01-31

{
  "success": true,
  "data": { "business_days": 20 },
  "meta": { "country": "PE", "from": "2026-01-01", "to": "2026-01-31" }
}

GET /v1/:country/last-business-day

Retorna el último día hábil del mes de la fecha indicada. Útil para cierres contables, cortes de facturación y liquidaciones.

Parámetro	Tipo	Descripción
date	string	Cualquier fecha del mes a consultar (YYYY-MM-DD)

GET /v1/UY/last-business-day?date=2026-01-15

{
  "success": true,
  "data": { "last_business_day": "2026-01-30" },
  "meta": { "country": "UY", "month": "2026-01" }
}

Probar la API

Ejecuta cualquier endpoint directamente desde aquí y mira la respuesta real.

Run in Postman Descargar colección (.json)

Endpoint

País

Año

Snippets por lenguaje

Listos para copiar. Todos los ejemplos usan el endpoint más común: verificar si una fecha es día hábil.

# ¿Es día hábil?
curl -H "Authorization: Bearer frd_tu_key" \
     "https://api.feriados.io/v1/CL/is-business-day?date=2026-04-03"

# Próximo feriado en Uruguay
curl -H "Authorization: Bearer frd_tu_key" \
     "https://api.feriados.io/v1/UY/next-holiday"

# Todos los feriados de Paraguay 2026
curl -H "Authorization: Bearer frd_tu_key" \
     "https://api.feriados.io/v1/PY/holidays/2026"

// ¿Es día hábil? (fetch nativo — Node 18+)
const today = new Date().toISOString().slice(0, 10);

const res = await fetch(
  `https://api.feriados.io/v1/CL/is-business-day?date=${today}`,
  { headers: { Authorization: "Bearer frd_tu_key" } }
);
const { data } = await res.json();

console.log(data.is_business_day); // true | false
console.log(data.day_of_week);     // "Monday"

// Próximo feriado
const r2 = await fetch(
  "https://api.feriados.io/v1/CL/next-holiday",
  { headers: { Authorization: "Bearer frd_tu_key" } }
);
const { data: next } = await r2.json();
console.log(`${next.name} — en ${next.days_until} días`);

# pip install requests
import requests
from datetime import date

API = "https://api.feriados.io/v1"
HEADERS = {"Authorization": "Bearer frd_tu_key"}

# ¿Es día hábil?
today = date.today().isoformat()
r = requests.get(f"{API}/CL/is-business-day", params={"date": today}, headers=HEADERS)
data = r.json()["data"]
print(data["is_business_day"])  # True | False
print(data["day_of_week"])      # "Monday"

# Próximo feriado en Uruguay
r2 = requests.get(f"{API}/UY/next-holiday", headers=HEADERS)
next_h = r2.json()["data"]
print(f"{next_h['name']} — en {next_h['days_until']} días")

// ¿Es día hábil?
$date = date('Y-m-d');
$url  = "https://api.feriados.io/v1/CL/is-business-day?date={$date}";

$ctx = stream_context_create(['http' => [
    'header' => "Authorization: Bearer frd_tu_key\r\n",
]]);

$res  = file_get_contents($url, false, $ctx);
$data = json_decode($res, true)['data'];

echo $data['is_business_day'] ? 'día hábil' : 'feriado';

// Con Guzzle (Laravel / Symfony)
$response = Http::withToken('frd_tu_key')
               ->get('https://api.feriados.io/v1/CL/is-business-day', [
                   'date' => now()->toDateString(),
               ]);
$isBusinessDay = $response->json('data.is_business_day');

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

func isBusinessDay(country, date, apiKey string) (bool, error) {
    url := fmt.Sprintf(
        "https://api.feriados.io/v1/%s/is-business-day?date=%s",
        country, date,
    )
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil { return false, err }
    defer resp.Body.Close()

    var result struct {
        Data struct { IsBusinessDay bool `json:"is_business_day"` } `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.Data.IsBusinessDay, nil
}

func main() {
    today := time.Now().Format("2006-01-02")
    ok, _ := isBusinessDay("CL", today, "frd_tu_key")
    fmt.Println(ok) // true | false
}

Casos de uso

Patrones comunes listos para adaptar.

No ejecutar un job en feriado

Útil para crons de cobro, liquidaciones, notificaciones o cualquier proceso que no deba correr en feriados.

// Node.js
async function runIfBusinessDay(country, job) {
  const today = new Date().toISOString().slice(0, 10);
  const res   = await fetch(
    `https://api.feriados.io/v1/${country}/is-business-day?date=${today}`,
    { headers: { Authorization: `Bearer ${process.env.FERIADOS_API_KEY}` } }
  );
  const { data } = await res.json();
  if (data.is_business_day) {
    await job();
  } else {
    console.log(`Skipping — ${data.day_of_week} no hábil en ${country}`);
  }
}

await runIfBusinessDay("CL", procesarPagos);
await runIfBusinessDay("UY", enviarLiquidaciones);

Calcular fecha de vencimiento o despacho

Encontrar el próximo día hábil a partir de una fecha dada.

// Node.js — próximo día hábil a partir de una fecha
async function nextBusinessDay(fromDate, country = "CL") {
  let date = new Date(fromDate + "T00:00:00");

  for (let i = 0; i < 10; i++) {
    const dateStr = date.toISOString().slice(0, 10);
    const res     = await fetch(
      `https://api.feriados.io/v1/${country}/is-business-day?date=${dateStr}`,
      { headers: { Authorization: `Bearer ${process.env.FERIADOS_API_KEY}` } }
    );
    const { data } = await res.json();
    if (data.is_business_day) return dateStr;
    date.setDate(date.getDate() + 1);
  }
}

const vencimiento = await nextBusinessDay("2026-09-18", "CL");
// → "2026-09-21" (Monday, because Sept 18 is Fiestas Patrias)

Mostrar fecha de entrega estimada

Calcular cuándo llegará un pedido considerando feriados y fines de semana.

# Python — N días hábiles a partir de hoy
import requests
from datetime import date, timedelta

def add_business_days(start: date, days: int, country: str = "CL") -> date:
    current = start
    added   = 0
    while added < days:
        current += timedelta(days=1)
        r = requests.get(
            f"https://api.feriados.io/v1/{country}/is-business-day",
            params={"date": current.isoformat()},
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        if r.json()["data"]["is_business_day"]:
            added += 1
    return current

# Entrega en 3 días hábiles desde hoy
entrega = add_business_days(date.today(), 3, "CL")
print(f"Fecha estimada de entrega: {entrega}")

Integraciones de calendario

Los endpoints de calendario retornan un archivo iCalendar estándar compatible con cualquier aplicación.

Google Calendar

Abre Google Calendar → panel izquierdo → Otros calendarios → +
Selecciona "Desde URL"
Pega la URL y haz clic en Añadir calendario

# Free — año fijo
https://api.feriados.io/v1/CL/calendar/2026

# Team / Business — URL permanente (auth via header Authorization: Bearer frd_tu_key)
https://api.feriados.io/v1/CL/calendar

Apple Calendar

macOS: menú Archivo → Nueva suscripción de calendario…
iPhone/iPad: Calendarios → Añadir calendario → Añadir calendario con suscripción
Pega la URL y confirma

Outlook / Microsoft 365

Abre Outlook Calendar → Añadir calendario
Selecciona "Suscribirse desde la web"
Pega la URL y asigna un nombre al calendario

Países disponibles

🇨🇱 CL Chile Disponible

🇺🇾 UY Uruguay Disponible

🇵🇾 PY Paraguay Disponible

🇨🇴 CO Colombia Disponible

🇵🇪 PE Perú Disponible

🇧🇴 BO Bolivia Disponible

🇪🇨 EC Ecuador Disponible

🇨🇷 CR Costa Rica Disponible

🇵🇦 PA Panamá Disponible

🇦🇷 AR Argentina Disponible

🇲🇽 MX México Disponible

¿Necesitas integrar feriados en tu app?

Empezar gratis →