Incrustar el widget del changelog

Objetivo

Renderizar el changelog de MexCep dentro de cualquier sitio de terceros (página de status, wiki interno, portal de partners) sin escribir JavaScript. El endpoint devuelve un documento HTML autocontenido con CSS inline; incrústalo en un <iframe> y funciona en cualquier lado.

Prerrequisitos

Ninguno para el request mismo. El widget soporta tráfico anónimo y sirve entradas de audiencia public.

Pasos

1. Insertar el iframe en tu página

<iframe
  src="https://api.example.com/v1/public/changelog/embed?lang=es"
  width="100%"
  height="600"
  frameborder="0"
  title="MexCep Changelog">
</iframe>

El widget renderiza una lista con scroll de entradas recientes con título, fecha, resumen y badge de categoría. Un enlace en el pie "Ver todo" apunta a la página completa del changelog.

2. Personalizar via query params

Todos los parámetros son opcionales.

Parámetro	Default	Descripción
`lang`	`en`	Idioma de visualización. Aceptados: `en`, `es`.
`limit`	`10`	Número de entradas a mostrar (1–30; valores fuera del rango se limitan).
`audience`	`public`	Filtro de audiencia. Aceptados: `public`, `admin` (admin requiere cookie + `docs:read`).

<!-- Español, últimas 5 entradas -->
<iframe src="https://api.example.com/v1/public/changelog/embed?lang=es&limit=5"
        width="100%" height="400" frameborder="0"></iframe>

<!-- Audiencia public, últimas 20 entradas -->
<iframe src="https://api.example.com/v1/public/changelog/embed?audience=public&limit=20"
        width="100%" height="800" frameborder="0"></iframe>

3. Estilos

El widget incluye CSS inline mínimo. Layout de una columna responsive. La tipografía hereda del propio stylesheet del widget, no de la página padre — comportamiento esperado de aislamiento de iframe.

El stylesheet reacciona a la preferencia del sistema operativo del visitante via prefers-color-scheme:

Modo claro: fondo blanco, texto oscuro.
Modo oscuro: fondo casi negro, texto claro.

No se exponen nombres de clases, variables CSS ni tokens de tema para override externo. Si necesitas control visual total, llama GET /v1/public/changelog directamente y renderiza tu propio HTML.

4. Headers iframe + CORS

El endpoint sirve en cada respuesta:

Content-Security-Policy: frame-ancestors *
X-Frame-Options: ALLOWALL

El widget puede ser incrustado desde cualquier dominio, incluyendo localhost, file:// y sitios de terceros. No hay allowlist que configurar.

5. Caché

Las respuestas se cachean por 5 minutos (Cache-Control: public, max-age=300, must-revalidate). Tras publicar un nuevo release, el iframe se refresca en la siguiente recarga dentro de los 5 minutos.

Errores

Estado	Código	Causa
400	`invalid_lang` / `invalid_audience`	Valor de param fuera del enum.
401	`unauthorized`	Pediste `audience=admin` sin auth por cookie.
403	`forbidden`	Cookie presente pero sin `docs:read`.
429	`rate_limited`	Demasiados requests al widget desde la misma IP.

Notas

El widget es un documento HTML completo, no un fragmento — incrústalo con <iframe>, no con dangerouslySetInnerHTML.
Ver Suscribir al feed Atom o Suscribir al feed JSON si prefieres integración push con un lector RSS en lugar de iframe.
ADR-0090 (Convención de URL) explica el movimiento al namespace /v1/public/*.

Nuevo en v1.49.6 — ver ADR-0090.