Servicio: Calendario

El tercer dominio del servicio: el calendario formal de feriados nacionales con el que el propio servicio decide qué día es hábil, con la norma legal de cada feriado y, desde el 2026-09-17, con el contrato de sincronización que un sistema cliente usa para tomar el calendario como propio: cobertura declarada por año, declaraciones con su revisión y retiros explícitos. Es público — se consulta sin token — y es la única parte del servicio que un cliente puede llamar hoy, aunque el servicio siga en desarrollo y no ofrezca acceso a terceros. Esta página da la forma exacta de cada principio de la plataforma en este dominio.

Qué es y qué no

• Es la lista de feriados nacionales del Perú que el servicio usa para contar días hábiles: en la frescura y la cobertura del tipo de cambio (el cierre existe solo en días hábiles) y en toda regla que diga "día hábil". Cada feriado lleva su fuente legal literal (fuente):

  fuente	feriados por año (2026 y 2027)
  Decreto Legislativo 713, art. 6	12 (Año Nuevo, Jueves y Viernes Santo, Día del Trabajo, San Pedro y San Pablo, Fiestas Patrias, Santa Rosa de Lima, Combate de Angamos, Todos los Santos, Inmaculada Concepción, Navidad)
  Ley 31381	3 (Batalla de Arica y Día de la Bandera, Batalla de Junín, Batalla de Ayacucho)
  Ley 31788	1 (Día de la Fuerza Aérea del Perú)

  Las dos fechas móviles (Jueves y Viernes Santo) tienen una fuente más larga que las demás, porque el Decreto Legislativo 713 las hace feriado sin fijar su fecha: la fecha sale del calendario litúrgico del año, y la fuente de esas dos filas dice de qué documento (identificado por su SHA-256), cómo se deriva (Pascua menos 3 y menos 2) y contra qué se cotejó (el histórico 2022-2026 de la Plataforma del Estado).

• El calendario peruano tiene tres cosas distintas y aquí entra una sola. (1) Feriados nacionales, por ley: son este dominio. (2) Días no laborables del sector público, por decreto supremo de cada año (en 2026, el 2 de enero y el 27 de julio): no entran. No son feriados; al sector privado se aplican solo previo acuerdo con el empleador, suelen ser compensables, y el decreto sale sobre el fin del año anterior. (3) Feriados regionales, por ordenanza (once departamentos en 2026): no entran. Consecuencia práctica: quien mire gob.pe/feriados verá fechas que este servicio no trae, y es a propósito. Si una empresa necesita descansar uno de esos días, lo carga como feriado manual, por compañía, en su propio sistema — el módulo base de Eurekia lo prevé —, porque esa decisión es de la empresa y no del Estado.

• No es un calendario laboral: sin jornadas ni horarios.

• El request, sin token, con year:

curl -s 'https://api.eurekia.pe/v1/calendario/feriados?year=2026'

Respuesta real (2026-09-28, revisión 4414): extracto, los primeros tres de los 16 feriados de 2026, en las dos listas.

{
  "feriados": [
    {
      "fecha": "2026-01-01",
      "nombre": "Año Nuevo",
      "fuente": "Decreto Legislativo 713, art. 6"
    },
    {
      "fecha": "2026-04-02",
      "nombre": "Jueves Santo",
      "fuente": "Decreto Legislativo 713, art. 6"
    },
    {
      "fecha": "2026-04-03",
      "nombre": "Viernes Santo",
      "fuente": "Decreto Legislativo 713, art. 6"
    },
    {
      "…": "13 feriados más"
    }
  ],
  "criterio": "feriados nacionales del calendario formal del servicio, con su norma legal; los días no laborables decretados ad hoc no entran",
  "zona": "America/Lima",
  "contract_version": 1,
  "year": 2026,
  "coverage": "complete",
  "declarations": [
    {
      "fecha": "2026-01-01",
      "nombre": "Año Nuevo",
      "fuente": "Decreto Legislativo 713, art. 6",
      "dataset_revision": 3953
    },
    {
      "fecha": "2026-04-02",
      "nombre": "Jueves Santo",
      "fuente": "Decreto Legislativo 713, art. 6",
      "dataset_revision": 3953
    },
    {
      "fecha": "2026-04-03",
      "nombre": "Viernes Santo",
      "fuente": "Decreto Legislativo 713, art. 6",
      "dataset_revision": 3953
    },
    {
      "…": "13 declaraciones más"
    }
  ],
  "tombstones": [],
  "dataset_revision": 4414,
  "request_id": "5e6a2778-ebb6-4f94-937f-9c29422a873f",
  "schema_version": "1.0"
}

Campos de la respuesta con year:

criterio y zona viajan en cada respuesta y no cambian; dataset_revision del sobre es la revisión del registro con la que se respondió, como en todo dominio. Sin year la respuesta es la de siempre — todas las declaraciones vigentes de todos los años en feriados — sin year, coverage, declarations ni tombstones, porque no hay un año al que referirlos; un cliente que sincroniza manda year siempre.

Cobertura

La cobertura es por año y declarada, nunca deducida de si hay filas. El servicio declara cada año como un acto, con la fuente que respalda el conjunto, y la respuesta lo dice en coverage. Años declarados hoy:

Tres estados que conviene distinguir, todos coherentes:

• complete con lista vacía: año cubierto sin feriados. No ocurre en el Perú, pero el contrato lo soporta porque este calendario es el molde de otros catálogos donde sí ocurre.
• unsupported sin nada: el servicio no dice nada del año. El cliente conserva intacto lo que tenía y no inventa declaraciones ni retiros.
• unsupported con declaraciones: año en carga. Las declaraciones se sirven como dato (y el propio servicio ya las usa para contar días hábiles), pero el cliente no debe tratar el año como completo hasta que la cobertura se declare.

Un año nuevo se carga antes de que empiece por actos de declaración (cobertura primero, luego cada feriado con su norma) y se anuncia en el registro de cambios. Huecos: no aplica — un calendario no tiene fechas esperadas sin dato; lo que puede faltar es un año, y eso lo dice coverage: unsupported, nunca una lista vacía.

Frescura

No aplica, y por qué: el calendario no se captura de una fuente cada día, se declara desde la norma legal, así que no tiene "fecha esperada" ni frescura. La expectativa que sí existe es de vigencia: el año N+1 debe estar cargado y declarado complete antes del 1 de enero (2027 lo está desde el 2026-09-17). Mientras el servicio esté en desarrollo, esa carga es una tarea del calendario de operación y queda fechada en el registro de cambios.

Consulta histórica

No aplica en la forma de los otros dominios: /v1/calendario/feriados no acepta as_of_revision, porque un feriado no se observa — se legisla. Lo que sí existe, y desde el 2026-09-17 viaja en la propia respuesta, es el rastro de actos: el calendario es un registro append-only de declaraciones y retiros, cada uno con la revisión en que se hizo. Nada se edita ni se borra; una norma que mueve o deroga un feriado ya cargado es un retiro (queda como tombstone) más, si corresponde, una declaración nueva. Cada acto queda además fechado en el registro de cambios.

Las cuatro revisiones de una respuesta, y para qué sirve cada una. Una respuesta con un retiro trae cuatro números de revisión distintos; ninguno sobra:

Ejemplo, con el caso que hace falta el cuarto número — una norma derogada y después repuesta: el 23 de julio de 2027 se declaró en la revisión 6611; una norma lo deroga en la revisión 7000 y otra lo repone en la 7300. La respuesta del año trae en declarations el 23 de julio con dataset_revision: 7300 y en tombstones un retiro con dataset_revision: 7000 y retira_revision: 6611. Un cliente que aplique los actos por orden de revisión llega al estado correcto (vigente); uno que hubiera sincronizado entre la 7000 y la 7300 lo tiene retirado, y al volver a sincronizar recibe la declaración nueva. Sin retira_revision, ese cliente no podría distinguir "retiro de la declaración vieja" de "retiro de la nueva".

Los tombstones se sirven sin plazo: el endpoint es público y el servicio no sabe qué cliente vio qué declaración, y el volumen es de unas filas por año.

Integridad

El control de integridad de este dominio es la fuente legal por acto: cada declaración cita la norma que crea el feriado (fuente) y cada retiro cita la que lo quita, verificables en el diario oficial; para las dos fechas móviles, el documento litúrgico identificado por su hash. Ninguna declaración ni retiro real del servicio lleva una fuente inventada (las fuentes ficticias que aparecen en los tests del servicio viven solo en transacciones que se revierten). No hay cotejo (no existe una segunda fuente oficial que publique el calendario como dato) ni verificación exhaustiva (no hay artefacto que reconstruir).

Del lado del registro, la integridad es estructural: el calendario se escribe solo por tres actos (declarar cobertura, declarar feriado, retirar feriado), ejecutados por funciones de la base que rechazan un feriado en un año sin cobertura declarada, una fecha que ya está vigente y un retiro de una fecha que no lo está; ningún rol de la aplicación puede modificar ni borrar una fila. Alcance declarado: el servicio garantiza que cada fecha servida tiene su norma citada y que todo retiro es explícito; no garantiza que un feriado decretado después de la carga del año ya esté — eso lo dice el registro de cambios.

Evidencia

No aplica bajo el contrato de /v1/evidence, y por qué: la evidencia de un feriado no son bytes capturados de una fuente sino la norma legal citada en fuente, pública y verificable por su número. Por eso el calendario no crea observaciones ni evidencias (no viaja observacion_id) y ninguna respuesta suya cuenta en la cuota de descarga.

Restricciones y límites

• Solo feriados nacionales; sin regionales, sin días no laborables por decreto supremo, sin jornadas ni horarios (Qué es y qué no).
• Años declarados: 2026 y 2027 (Cobertura); cualquier otro responde unsupported.
• Público y sin token, pero no es un servicio abierto: forma parte del servicio en desarrollo y puede cambiar de forma con su registro de cambios; no hay compromiso de disponibilidad hacia terceros mientras el servicio no abra acceso (Empezar).
• El único error propio es INVALID_PARAMS con un year no entero (Errores y límites).

Qué guardar

Por año sincronizado: contract_version y coverage con los que se sincronizó y el dataset_revision del sobre. Por feriado que su sistema tome: fecha, nombre, fuente y su dataset_revision. Por retiro aplicado: fecha, fuente, dataset_revision y retira_revision. Con eso y el registro de cambios se reconstruye qué calendario regía cuando su sistema lo sincronizó y por qué una fecha dejó de ser feriado.