Uso del API

Integración · bop.laplaceta.org

Uso del API del BOLP

Guía para integrar la normativa y, sobre todo, los valores variables (CNIC) del Boletín Oficial de La Placeta en las webs de las organizaciones del Grupo. Lectura pública y sin claves, con valores tipados, revisión de vigencia y un widget oficial que evita publicar datos no garantizados.

Sin claves · lectura pública Dominios autorizados: laplaceta.org y subdominios Valores con revisión y alias históricos

Probar /api/valores Ver el catálogo de valores

Introducción

La base del servicio es https://bop.laplaceta.org. Todos los endpoints responden en JSON UTF-8, son de solo lectura y no requieren clave. Cada respuesta incluye la revisión (fecha) de los datos, para que una web externa pueda comprobar que usa la versión vigente.

GET /api/valores: Valores atómicos tipados para webs de organizaciones (uso recomendado).
GET /api/cnic: Catálogo completo de valores variables (CNIC), con detalle e historial.
GET /api/normativa: Textos normativos (documentos legales completos) en Markdown.
Widget /valores.js: Etiqueta oficial para pintar valores y bloquear la página si fallan.

Regla de uso: los valores (porcentajes, precios en Placetas, límites, plazos) solo deben consumirse desde laplaceta.org o sus subdominios. El resto de dominios recibe un 403.

Endpoints

GET

/api/valores?refs=CNIC-IVA,CNIC-SMI-MENSUAL

Valores oficiales solicitados, tipados (numero + resumen). Opcional &grupo=CNIC-4.5 para expandir un agregado antiguo, y &revision=AAAA-MM-DD para exigir vigencia.

GET

/api/cnic

Catálogo completo de valores (68 canónicos) con revision. Parámetro ?codigo= para un valor concreto, incluyendo alias históricos (p. ej. CNIC-4.4 → CNIC-IVA).

GET

/api/normativa

Listado de documentos normativos. Con ?codigo= devuelve el documento completo (incluye contenido_md, fechas e historial).

GET

/valores.js

Widget oficial (script) para insertar valores en tu web. Se configura con atributos data-*.

Referencias humanas de cada valor: https://bop.laplaceta.org/cnic?codigo=CNIC-IVA.

Valores para tu web (organizaciones)

El endpoint /api/valores devuelve solo lo que pides, con el valor listo para usar en dos formas: numero (para cálculos) y resumen (para mostrar, p. ej. «12 %», «150 Pz»).

refs: Códigos canónicos o alias de un solo valor, separados por coma. Obligatorio.
grupo: Código antiguo agregado (CNIC-4.5) para obtener sus canónicos. Opcional.
revision: Fecha AAAA-MM-DD de la revisión que tu web usa. Si ya no es la vigente responde 409. Opcional pero recomendado.

Petición

curl -H "Origin: https://banco.laplaceta.org" \
  "https://bop.laplaceta.org/api/valores?refs=CNIC-IVA,CNIC-SMI-MENSUAL"

Respuesta (200)

// Resumen de la respuesta
{
  "servicio": "bop.valores",
  "revision": "2026-07-03",
  "total": 2, "encontrados": 2,
  "no_encontrados": [],
  "valores": {
    "CNIC-IVA": {
      "tipo": "porcentaje",
      "valor": "12", "numero": 12,
      "unidad": "%", "resumen": "12 %",
      "articulo": "CNI-BANCO (Art. 4)"
    },
    "CNIC-SMI-MENSUAL": {
      "tipo": "placeta",
      "valor": "150", "numero": 150,
      "unidad": "Pz", "resumen": "150 Pz",
      "articulo": "CNI-BANCO (Art. 7)"
    }
  }
}

Desde JavaScript en una web del dominio laplaceta.org (o subdominio):

const res = await fetch(
  'https://bop.laplaceta.org/api/valores?refs=CNIC-IVA,CNIC-SMI-MENSUAL'
);
const datos = await res.json();
// Si algún valor no se pudo resolver, NO usar la página con datos rotos:
if (datos.no_encontrados.length > 0) { mostrarAviso(datos.no_encontrados); return; }

const iva = datos.valores['CNIC-IVA'];
console.log(iva.numero, iva.resumen); // 12  "12 %"

Widget oficial (valores con fallo a bloqueo)

Para no depender de una integración a medida, incluye el widget del BOP. Rellena los <bop-valor> con el valor oficial y, si alguno falla (red, código sin resolver, revisión obsoleta), muestra un aviso y bloquea la zona (o toda la página) para que nadie use datos que no se puedan garantizar.

<bop-valor data-bop-valor="CNIC-IVA">…</bop-valor>
<bop-valor data-bop-valor="CNIC-SMI-MENSUAL">…</bop-valor>

<script src="https://bop.laplaceta.org/valores.js"
        data-refs="CNIC-IVA,CNIC-SMI-MENSUAL"
        data-bloqueo="area"></script>

data-refs: Valores obligatorios de la página (separados por coma).
data-bloqueo: area (defecto) avisa y desactiva la zona · pagina bloquea toda la web · aviso solo informa.
data-revision: Opcional. Fija la revisión que tu web espera; si cambió, la página se bloquea hasta actualizarse.
data-area: Selector CSS de la zona a bloquear en modo area.

La página escucha los eventos bop:valores-ok y bop:valores-fallo. Los placeholders quedan marcados como data-bop-valor="resuelto".

Catálogo, códigos antiguos y vigencia

El registro canónico tiene 68 valores atómicos con nombre descriptivo (CNIC-IVA, CNIC-SMI-MENSUAL…). Los códigos del antiguo CNI-PDF (CNIC-4.x, CNIC-7-1, CNIC-15-1…) se mantienen como alias de compatibilidad: el servicio los resuelve, pero no deben usarse para cálculos.

Ejemplo	Comportamiento
`CNIC-4.4`	Alias único → se resuelve a `CNIC-IVA`. En `/api/valores` aparece con `alias_de`.
`CNIC-4.5`	Alias de grupo → en `no_encontrados` con motivo `legacy_agrupado` y sus canónicos en `sustitutos`. Usa `?grupo=CNIC-4.5` para obtenerlos.
`CNIC-15-1`	Pendiente → sin equivalente atómico publicado; motivo `pendiente`. No puede usarse en cálculos.
`revision`	Cada respuesta indica la revisión vigente. Si pides una obsoleta con `&revision=`, el API responde `409`.

En la web puedes ver el desglose completo: catálogo de valores. Si una referencia antigua te lleva a un detalle, el BOLP te indica el código canónico que debes usar.

Errores

Código	Significado
`400`	Falta `refs` (`refs_requeridas`) o el `grupo` no existe.
`403`	Origen no permitido: el acceso por navegador está limitado a `laplaceta.org` y subdominios.
`404`	`cnic_no_encontrado`: código desconocido (ni canónico ni alias).
`405`	Método no permitido (solo `GET`).
`409`	`revision_desactualizada`: la revisión pedida ya no es la vigente.
`500`	Error interno.

En /api/valores, los valores que no se pueden resolver no abortan la respuesta: aparecen en no_encontrados con un motivo:

no_existe: Código desconocido.
legacy_agrupado: Es un agregado antiguo; usa sus sustitutos canónicos.
pendiente: Contenido antiguo sin equivalente atómico todavía.
canonico_faltante: El canónico del alias no está publicado.

Dominios permitidos (CORS)

Por ahora el consumo de valores desde navegador está limitado a:

Dominio	Uso
`bop.laplaceta.org`	El propio boletín (mismo origen).
`*.laplaceta.org`	Webs de organizaciones del Grupo.
`laplaceta.org`	Dominio raíz.

Las peticiones sin navegador (servidores, curl) no se bloquean. La ampliación de dominios autorizados se gestiona desde la Administración del sistema (RSP), no desde la web pública.