API de feriados en Python: integración con requests, Django y FastAPI

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:

Authorization: Bearer frd_tu_api_key

Guardá la key en tus variables de entorno, nunca en el código:

# .env
FERIADOS_API_KEY=frd_tu_api_key

Con requests (sin dependencias extra)

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}"}

# ¿Es hábil hoy en Chile?
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:

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

Registrá la key en settings.py:

# settings.py
import os

FERIADOS_API_KEY = os.environ["FERIADOS_API_KEY"]

Creá un servicio en myapp/services.py:

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"]

Uso en una vista:

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:

pip install httpx

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, manejá tanto los errores HTTP como los errores de negocio:

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. API key gratis — sin tarjeta →

Ver también: Documentación completa de endpoints → · API de feriados en PHP → · Calcular días hábiles en JavaScript → · API de feriados para LATAM →