Documentación

La API de vacaciones devuelve días festivos y celebraciones por país y/o religión. El punto final de días hábiles (GET /api/business-days) utiliza la misma autenticación de clave API. Todas las solicitudes requieren autenticación con clave API. Puede crear y administrar claves API en su dashboard. El plan gratuito (estándar) utiliza la misma URL base y la misma clave API para que puedas probar la integración antes de pasar a producción.

Cada cuenta verificada comienza con el plan gratuito. Puede utilizar los mismos puntos finales, parámetros y autenticación para crear y probar su integración. Cuando el plan gratuito ya no sea suficiente, actualice el panel.

Qué funciona igual

Tienes acceso a la misma API de vacaciones: la misma URL base, GET /api/holidays y los mismos parámetros de consulta (country, religion, from, to, lang, region, provisional, type, scope). GET /api/business-days también está disponible con la misma autenticación y el formato de respuesta es idéntico, por lo que puede desarrollar y probar su código con la API real sin cambiar nada al actualizar.

Limitaciones

• Cuota mensual de solicitudes: El plan gratuito incluye una cantidad fija de solicitudes por mes calendario. Cuando alcanza la cuota, las solicitudes se bloquean hasta el mes siguiente o hasta que actualice.
• Límites de recursos: El plan gratuito limita las claves API, los idiomas y el acceso a vacaciones por subdivisión. Consulte precios para conocer los límites completos.
• Sin excedente en Gratis: El plan gratuito no incluye el excedente pagado. Actualice para continuar después de alcanzar el límite.

Para obtener el conjunto completo de resultados y límites listos para producción, elija un plan de precios o vaya a Uso o Facturación en su panel.

Envíe su clave API en la cabecera Authorization como token Bearer. Cree claves en la página Claves API de su panel de control.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

Utilice https://api.holidaydb.com para todas las solicitudes de API. Para CURL y integraciones del lado del servidor, debe utilizar esta URL absoluta.

Devuelve días festivos filtrados por country y/o religion. Al menos uno de country o religion es obligatorio.

Parámetros de consulta

Respuesta: Matriz JSON de objetos festivos con uuid, country_code, religion_slug, type, scope, region_codes, region_names, start_date, end_date, provisional, substitute, summary, language. Para los calendarios de países (country_code no nulos), type y scope describen categorías territoriales (día festivo frente a observancia, nacional frente a subnacional). Para los calendarios religiosos (religion_slug no nulo y, a menudo, country_code nulo), type y scope pueden ser "desconocidos" y no deben interpretarse como territoriales; utilice religion_slug (y fechas) para trabajar con estas observaciones. Los días festivos sustitutos incluyen canonical_uuid. Utilice include=canonical para incorporar el feriado canónico de cada sustituto; use include=substitute para incrustar una matriz substitutes en cada canónico.

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/holidays?country=US"

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "country_code": "US",
    "religion_slug": null,
    "type": "public_holiday",
    "scope": "national",
    "region_codes": [],
    "region_names": [],
    "start_date": "2026-07-04",
    "end_date": "2026-07-04",
    "provisional": false,
    "summary": "Independence Day",
    "language": "en"
  }
  // ...más objetos vacacionales en la respuesta completa
]

Devuelve cuántos días hábiles caen en un mes o año calendario completo para un país ISO. Por defecto, la semana laboral es de lunes a viernes (días ISO 1,2,3,4,5); puede sobrescribir con weekdays opcional. De forma predeterminada, sólo se excluyen los días festivos nacionales. Con region opcional, el recuento también excluye los días festivos subnacionales cuyo region_codes contiene este código ISO 3166-2: la misma regla que GET /api/holidays?country=...&region=... (los días nacionales siempre cuentan; region no significa "solo región"). Este punto final requiere la misma clave de API de portador y permisos de token que GET /api/holidays.

El filtrado de subdivisiones requiere un plan que incluya días festivos de subdivisión (Pro/Full), al igual que la API de días festivos.

Parámetros de consulta

Respuesta: Objeto JSON con country_code, region (código normalizado o nulo), weekdays (matriz de números enteros realmente utilizados para contar), year y month (ambos nulos en modo de rango), range (fechas from/to, ventana siempre inclusiva resuelta) y business_days (recuento de enteros). Cuando include es 1 o true, la respuesta también trae holidays: días festivos utilizados en el recuento (solo nacional cuando se omite region; nacional + subnacional correspondiente cuando se ingresa region), con campos completos como ninguna última pestaña de ejemplo.

Si aún no hemos cubierto el calendario de ese país, la API devuelve 404 con error y country_code (no es el mismo cuerpo que "País no encontrado" en GET /api/holidays).

Las primeras cuatro pestañas de ejemplo omiten include (sin holidays en el JSON de ejemplo). La última pestaña muestra include=1 con la matriz holidays.

Los ejemplos siguientes utilizan 2026. Los números en business_days se compararon manualmente con las normas nacionales oficiales: feriados federales de EE. UU. (OPM); Días festivos alemanes observados en todos los estados en esa fecha; Los feriados legales federales de Canadá (julio de 2026 tiene el Día de Canadá en miércoles). Los días festivos fijos de fin de semana no reducen el recuento de días laborables. Los valores de Live API siguen los días festivos almacenados en HolidayDB y deben coincidir con las mismas reglas; Si se agrega o corrige una línea en nuestros datos, los recuentos pueden cambiar ligeramente.

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/business-days?country=US&year=2026&month=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "business_days": 20
}

Devuelve cuántos minutos de trabajo (y un resumen de horas/minutos) corresponden a un mes calendario, un año completo o un rango de fechas inclusive para un país ISO. Utilice las mismas reglas para los días de la semana y feriados que GET /api/business-days, luego multiplíquelas por la duración obligatoria del día laboral (workday).

El filtrado por subdivisión (region) requiere un plan con días festivos de subdivisión (Pro/Full), al igual que la API de días festivos y días hábiles.

Parámetros de consulta

Respuesta: Objeto JSON con los mismos campos base que los días hábiles, más working_days, workday, workday_minutes, working_minutes y working_hours (resumen de horas/minutos).

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/working-hours?country=US&year=2026&month=1&workday=08:00"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "working_days": 20,
  "workday": "08:00",
  "workday_minutes": 480,
  "working_minutes": 9600,
  "working_hours": {
    "hours": 160,
    "minutes": 0
  }
}

Prorratea un monto de salario en función de los días hábiles dentro de un período seleccionado de un período de nómina. Los días laborables se cuentan como días ISO seleccionados (estándar de lunes a viernes) menos los días festivos (y los días festivos regionales opcionales cuando se utiliza region).

Puedes elegir el periodo de nómina por modo calendario (year/month) o por fechas explícitas (period_from/period_to). Opcionalmente, ingrese una ventana de prorrateo personalizada (from/to) dentro de este período; de lo contrario, la ventana es todo el período.

Parámetros de consulta

Respuesta: Objeto JSON con period_working_days, window_working_days, ratio, salary y prorated_salary. Utilice period para los límites del período de hoja y range para la ventana de prorrateo.

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/salary-proration?country=US&year=2026&month=1&salary=5000"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "range": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 20,
  "window_working_days": 20,
  "ratio": "1.000000",
  "salary": "5000.00",
  "salary_scale": 2,
  "prorated_salary": "5000.00"
}

Calcula las vacaciones acumuladas, las vacaciones tomadas (ventana opcional) y el saldo final para un período de cálculo. El tiempo de trabajo se deriva del weekdays seleccionado menos los días festivos para el country seleccionado y el region opcional.

Parámetros de consulta

Respuesta: Objeto JSON con límites de período, totales de trabajo y campos de saldo híbrido: accrued_hours/taken_hours/ending_balance_hours más valores derivados *_days.

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/leave-pto?country=US&year=2026&month=1&workday=08:00&accrual_hours_per_month=8"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": 1,
  "workday": "08:00",
  "workday_minutes": 480,
  "period": {
    "from": "2026-01-01",
    "to": "2026-01-31"
  },
  "period_working_days": 21,
  "accrued_hours": "8.00",
  "taken_hours": "0.00",
  "ending_balance_hours": "8.00"
}

Calcula una fecha de vencimiento agregando días hábiles a una fecha de inicio, excluyendo fines de semana y días festivos para el country seleccionado y el region opcional.

Parámetros de consulta

Los parámetros obligatorios son country, start y sla_business_days.

Respuesta: Objeto JSON con deadline y campos de contexto relacionados (country/region, weekdays y rango de análisis).

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/sla-deadline?country=US&start=2026-01-02&sla_business_days=1"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "sla_business_days": 1,
  "deadline": "2026-01-05"
}

Calcula una fecha de entrega estimada sumando días hábiles a una fecha inicial, excluyendo fines de semana y días festivos para el country seleccionado y el region opcional.

Parámetros de consulta

Los parámetros obligatorios son country, start y delivery_business_days.

Respuesta: Objeto JSON con delivery_date y campos de contexto relacionados (country/region, weekdays y rango de análisis).

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/delivery-date?country=US&start=2026-01-02&delivery_business_days=3"

{
  "country_code": "US",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "start": "2026-01-02",
  "delivery_business_days": 3,
  "delivery_date": "2026-01-07"
}

Devuelve oportunidades de 'día puente' para country y year: secuencias cortas de días laborables entre días no laborables, donde al menos un bloque vecino contiene un día festivo. Cada oportunidad incluye el bloque de tiempo libre consecutivo resultante y un índice de eficiencia para que usted clasifique buenas oportunidades de vacaciones prolongadas.

Parámetros de consulta

Los parámetros obligatorios son country y year.

Respuesta: Objeto JSON con una matriz bridge_opportunities ordenada por eficiencia decreciente. Cada oportunidad expone los días laborables que deben tomarse, el bloque de tiempo libre consecutivo resultante, el número de días libres, el ratio de eficiencia (días libres/días puente) y los feriados ancla.

Ejemplos

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/bridge-days?country=DE&year=2026"

{
  "country_code": "DE",
  "region": null,
  "weekdays": [
    1,
    2,
    3,
    4,
    5
  ],
  "year": 2026,
  "month": null,
  "max_gap": 1,
  "range": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  },
  "bridge_opportunities": [
    {
      "bridge_days": [
        "2026-05-15"
      ],
      "bridge_days_count": 1,
      "off_block": {
        "from": "2026-05-14",
        "to": "2026-05-17"
      },
      "off_days_count": 4,
      "efficiency": 4,
      "anchor_holidays": [
        {
          "uuid": "...",
          "summary": "Christi Himmelfahrt",
          "start_date": "2026-05-14",
          "end_date": "2026-05-14"
        }
      ]
    }
  ]
}

Devuelve la lista de configuraciones regionales admitidas por HolidayDB para los nombres de días festivos traducidos. Este endpoint está disponible para planes que incluyen varios idiomas (Completo). Si su plan solo incluye inglés, la API devuelve `403`.

Parámetros de consulta

Ninguno.

Respuesta

Objeto JSON con una matriz languages. Cada artículo contiene un code (por ejemplo: en, de, pt_BR, en_US) y un name. Pase estos códigos a lang; consulte el parámetro lang para conocer la coincidencia de etiquetas principales y el respaldo.

curl -H "Authorization: Bearer YOUR_API_KEY" \
 "https://api.holidaydb.com/api/languages"

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "de", "name": "German" }
 ]
}

Las páginas de calculadora de este sitio utilizan un punto final de ayuda público GET /api/tools/languages para completar los selectores de idioma sin requerir una clave API.

Cuerpo de respuesta de error

Las respuestas de error son JSON en la API de producto autenticada (GET /api/holidays, endpoints de calculadora, etc.).

Las rutas públicas /api/tools/* usan otro formato de error y no se describen aquí.

{
  "error": "Unauthorized. Provide a valid API key in the Authorization header as Bearer token."
}

El parámetro region (vacaciones de subdivisión) y el parámetro lang (varios idiomas) requieren planes Pro o Full. Básico sólo incluye festivos nacionales en inglés. Consulte precios o sus páginas Facturación y Uso para obtener más detalles.