Si tu stack es Python — Django, FastAPI o un script standalone — integrar la API de feriados.io requiere solo la librería requests o httpx. Todos los endpoints responden JSON estándar con autenticación Bearer token.

Autenticación

Todos los endpoints requieren un API key en el header Authorization:

http Header de autenticación requerido

Authorization: Bearer frd_tu_api_key

bash .env — guardar la key en variables de entorno, nunca en el código

FERIADOS_API_KEY=frd_tu_api_key

Con requests (sin dependencias extra)

python Verificar si hoy es hábil en Chile con requests

import os
import requests
from datetime import date
API_KEY = os.environ[“FERIADOS_API_KEY”]
BASE_URL = “https://api.feriados.io/v1”
headers = {“Authorization”: f”Bearer {API_KEY}”}
today = date.today().isoformat()
res = requests.get(
f”{BASE_URL}/CL/is-business-day”,
params={“date”: today},
headers=headers,
)
data = res.json()[“data”]
if not data[“is_business_day”]:
print(f”Hoy es feriado en Chile ({data[‘day_of_week’]}), saltando proceso.”)
else:
procesar_cobros()

Cliente reutilizable

Para usar en múltiples partes del proyecto, conviene encapsular la lógica en una clase:

python Clase FeriadosClient reutilizable con Session y métodos para cada endpoint

import os
import requests
from datetime import date
class FeriadosClient:
BASE_URL = “https://api.feriados.io/v1”
def __init__(self, api_key: str | None = None):
    self._session = requests.Session()
    self._session.headers["Authorization"] = (
        f"Bearer {api_key or os.environ['FERIADOS_API_KEY']}"
    )

def is_business_day(self, country: str, date: str) -> bool:
    res = self._session.get(
        f"{self.BASE_URL}/{country}/is-business-day",
        params={"date": date},
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]["is_business_day"]

def add_business_days(self, country: str, date: str, days: int) -> str:
    """Requiere plan Starter o superior."""
    res = self._session.get(
        f"{self.BASE_URL}/{country}/business-days/add",
        params={"date": date, "days": days},
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]["result_date"]

def count_business_days(self, country: str, from_date: str, to_date: str) -> int:
    """Requiere plan Starter o superior."""
    res = self._session.get(
        f"{self.BASE_URL}/{country}/business-days/between",
        params={"from": from_date, "to": to_date},
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]["business_days"]

def next_holiday(self, country: str) -> dict:
    res = self._session.get(
        f"{self.BASE_URL}/{country}/next-holiday",
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]
Uso
feriados = FeriadosClient()
today = date.today().isoformat()
es_habil = feriados.is_business_day(“CO”, today)
entrega  = feriados.add_business_days(“MX”, today, 5)
dias     = feriados.count_business_days(“AR”, “2026-01-01”, “2026-03-31”)

Con Django

Registra la key en settings.py:

python settings.py — exponer la key desde variables de entorno

import os
FERIADOS_API_KEY = os.environ[“FERIADOS_API_KEY”]

python myapp/services.py — servicio encapsulado para toda la app Django

import requests
from django.conf import settings
class FeriadosService:
BASE_URL = “https://api.feriados.io/v1”
def __init__(self):
    self._session = requests.Session()
    self._session.headers["Authorization"] = f"Bearer {settings.FERIADOS_API_KEY}"

def is_business_day(self, country: str, date: str) -> bool:
    res = self._session.get(
        f"{self.BASE_URL}/{country}/is-business-day",
        params={"date": date},
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]["is_business_day"]

def add_business_days(self, country: str, date: str, days: int) -> str:
    res = self._session.get(
        f"{self.BASE_URL}/{country}/business-days/add",
        params={"date": date, "days": days},
        timeout=5,
    )
    res.raise_for_status()
    return res.json()["data"]["result_date"]</pre>

python Vista Django — uso del servicio en un endpoint

from datetime import date
from django.http import JsonResponse
from .services import FeriadosService
feriados = FeriadosService()
def calcular_entrega(request):
fecha_despacho = request.GET.get(“fecha_despacho”, date.today().isoformat())
fecha_entrega  = feriados.add_business_days(“CL”, fecha_despacho, 3)
return JsonResponse({“entrega”: fecha_entrega})

Con FastAPI y httpx (async)

FastAPI trabaja mejor con clientes HTTP asíncronos. httpx ofrece la misma API que requests pero con soporte async/await:

bash Instalar httpx

pip install httpx

python App FastAPI con cliente httpx compartido y endpoints async

import os
import httpx
from contextlib import asynccontextmanager
from fastapi import FastAPI, Depends
BASE_URL = “https://api.feriados.io/v1”
API_KEY  = os.environ[“FERIADOS_API_KEY”]
Cliente compartido por toda la app — se crea al iniciar y se cierra al terminar
http_client: httpx.AsyncClient | None = None
@asynccontextmanager
async def lifespan(app: FastAPI):
global http_client
http_client = httpx.AsyncClient(
headers={“Authorization”: f”Bearer {API_KEY}”},
timeout=5,
)
yield
await http_client.aclose()
app = FastAPI(lifespan=lifespan)
def get_client() -> httpx.AsyncClient:
return http_client
@app.get(“/entrega”)
async def calcular_entrega(
pais: str,
fecha: str,
dias: int = 3,
client: httpx.AsyncClient = Depends(get_client),
):
res = await client.get(
f”{BASE_URL}/{pais}/business-days/add”,
params={“date”: fecha, “days”: dias},
)
res.raise_for_status()
return {“entrega”: res.json()[“data”][“result_date”]}
@app.get(“/es-habil”)
async def es_dia_habil(
pais: str,
fecha: str,
client: httpx.AsyncClient = Depends(get_client),
):
res = await client.get(
f”{BASE_URL}/{pais}/is-business-day”,
params={“date”: fecha},
)
res.raise_for_status()
return res.json()[“data”]

Manejo de errores

La API devuelve siempre un campo success: bool. Para producción, maneja tanto los errores HTTP como los errores de negocio:

python Wrapper con manejo de Timeout y HTTPError — retorna None en error para que el caller decida el fallback

import requests
from requests.exceptions import Timeout, HTTPError
def safe_is_business_day(country: str, date: str) -> bool | None:
"""
Retorna True/False si la consulta fue exitosa.
Retorna None si hubo un error — el caller decide el fallback.
"""
try:
res = requests.get(
f”https://api.feriados.io/v1/{country}/is-business-day”,
params={“date”: date},
headers={“Authorization”: f”Bearer {os.environ[‘FERIADOS_API_KEY’]}”},
timeout=3,
)
res.raise_for_status()
body = res.json()
if not body[“success”]:
return None
return body[“data”][“is_business_day”]
except (Timeout, HTTPError):
return None  # fallback a tu lógica default

Los errores retornan success: false con error.code y error.status. Los más comunes: API_KEY_REQUIRED (401), RATE_LIMIT_EXCEEDED (429), COUNTRY_NOT_SUPPORTED (404).

Lista para producción en menos de 5 minutos

Sin tarjeta de crédito. El plan Free cubre is-business-day y consulta de feriados.

API key gratis — sin tarjeta →

Ver también

Docs

Documentación completa de endpoints →

Tutorial

API de feriados en PHP →

Tutorial

Calcular días hábiles en JavaScript →

Blog

API de feriados para LATAM →