Festivos municipales y entidades locales: elige el ámbito correcto

Un código de municipio no siempre resuelve todo el ámbito

Seleccionar un municipio es un paso necesario para consultar su calendario, pero no siempre es el último. El modelo de Toddle Plazos contempla entidades locales: determinadas consultas necesitan identificar también la entidad a la que corresponde el calendario.

Para quien integra la API, la consecuencia es práctica. Una fecha publicada para una entidad no debe extenderse automáticamente a todas las ubicaciones del municipio. Y disponer de un calendario de entidad no equivale a disponer de un calendario municipal común para todas ellas.

Qué significa cada parte de la cobertura

En la web, el desglose distingue calendario municipal, cobertura solo mediante entidad local y pendientes reales. La cobertura local reúne las dos primeras categorías, pero eso no elimina la necesidad de seleccionar el ámbito correcto al realizar una petición.

Por ejemplo, que un municipio figure cubierto mediante entidad no significa que cualquier entidad de ese municipio tenga un calendario disponible. El indicador agregado permite describir la cobertura; la consulta concreta exige comprobar la ubicación y las condiciones del contrato de la API.

La cobertura utilizable tiene además en cuenta las capas necesarias para calcular. Por eso conviene leer la información del año seleccionado y no trasladar un porcentaje de un año a otro. Consulta la cobertura vigente en lugar de conservar una cifra estática en tu integración.

Cómo resolver la ubicación en tu aplicación

Utiliza el código INE como identificador del municipio y consulta las entidades admitidas mediante los mecanismos descritos en la documentación. No construyas códigos de entidad a partir del nombre que escribe el usuario.

Cuando tu producto disponga de dirección, localidad o centro de trabajo, define cómo va a seleccionar el ámbito correspondiente. No presupongas que una coincidencia textual basta para asignar una entidad: puede haber nombres parecidos o denominaciones que no sean intercambiables.

Una vez resuelta la ubicación, conserva los identificadores necesarios junto a la petición. Esto permite revisar por qué dos consultas que parecen próximas geográficamente utilizan calendarios diferentes.

Trata los errores como decisiones de integración

El contrato distingue situaciones que no deben mezclarse:

• ENTIDAD_LOCAL_REQUERIDA: la petición necesita identificar una entidad.
• ENTIDAD_LOCAL_NO_VALIDA: el código no existe o no pertenece al municipio indicado.
• ENTIDAD_LOCAL_NO_ADMITIDA: ese municipio utiliza exclusivamente calendario municipal.

Ante el primer caso, tu aplicación necesita obtener el dato que falta. Ante el segundo, revisar la selección. Ante el tercero, ajustar la petición al modelo admitido. Ninguno justifica sustituir silenciosamente la entidad por otra ni continuar con fechas supuestas.

Los códigos y respuestas completos están en la referencia de errores. Mantén esa referencia como contrato y evita convertir esta guía en una copia que pueda quedar desactualizada.

Un caso de producto: varias sedes en un municipio

Imagina un software que calcula vencimientos para varias sedes. Agrupar todos sus calendarios únicamente por municipio puede perder la distinción de entidad local cuando sea relevante. Antes de compartir un calendario o un resultado entre sedes, verifica que la petición utiliza el mismo ámbito y las mismas reglas.

Si mantienes una caché propia, su clave debe representar los parámetros que afectan a la consulta. La estrategia de caducidad e invalidación es una decisión de tu producto; no presupongas que un calendario guardado seguirá siendo válido indefinidamente ante correcciones oficiales.

Qué comprobar antes de lanzar

Prueba un municipio con calendario municipal, un caso que requiera entidad y las combinaciones inválidas que describe el contrato. Revisa que la interfaz pida información cuando falte y explique los errores sin inventar una fecha alternativa.

Las entidades TEST ayudan a ensayar los flujos documentados. Después, verifica la disponibilidad del territorio y año reales. El objetivo es que tu aplicación conserve la precisión territorial desde la selección de ubicación hasta la presentación del vencimiento.