rafa/feadulta
1
0
Fork 0
Code Issues 71 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

docs: guía de publicación de la carta semanal para Inma (REST API)

Browse Source 
Guía para el asistente de Inma: conexión por REST API, modelo
carta->portada, categorías, flujo de publicación y qué es automático.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
rafa
2026-06-27 11:18:50 -04:00
parent 8ea4d51fd2
commit 6c0e366b03
1 changed files with 319 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guia-publicacion-carta-inma.md
+319
View File
@@ -0,0 +1,319 @@
# Guía para publicar la carta semanal en Fe Adulta (WordPress)
> **Para quién es este documento:** para el asistente (Claude Code / Cowork) que ayuda a
> **Inma** a publicar la carta semanal y los artículos en el WordPress nuevo de Fe Adulta.
>
> **Reparto de responsabilidades:**
> - **Inma** aporta el contenido editorial: cómo se redacta y compone la carta y los artículos.
> - **Este documento** aporta la infraestructura y la estructura del sitio: cómo conectarse,
> dónde va cada cosa, qué categorías usar, qué se publica automáticamente y qué hay que
> hacer a mano.
> - **Inma sube siempre en ESPAÑOL.** Las traducciones (EN/FR/IT/PT) y el audio (TTS) los
> genera un proceso automático en el servidor (ver §7). No hay que traducir a mano.
---
## 1. El sitio y cómo conectarse
### 1.1 Entornos
| Entorno | URL | Estado |
|---------|-----|--------|
| **Beta (actual)** | `https://wp-nuevo.feadulta.com` | Es donde se trabaja **ahora** |
| Producción final | `https://feadulta.com` | Tras el "cutover" de DNS (cambiará la URL base) |
Mientras no se avise, **todo va a `wp-nuevo.feadulta.com`**. Cuando se haga el cambio de
dominio, solo hay que sustituir la URL base en los ejemplos de abajo.
### 1.2 Acceso recomendado: API REST de WordPress + contraseña de aplicación
No hace falta SSH ni tocar la base de datos. WordPress trae una API REST y un sistema de
**"Contraseñas de aplicación"** (Application Passwords) pensado exactamente para esto.
**Cómo obtener la credencial (lo hace Inma una sola vez):**
Inma **ya tiene usuario con rol Editor** en el sitio (suficiente para crear, editar,
publicar y programar entradas). Con ese usuario:
1. Entrar en `https://wp-nuevo.feadulta.com/wp-admin`.
2. Ir a **Usuarios → Perfil** → bajar hasta **"Contraseñas de aplicación"**.
3. Escribir un nombre (p. ej. `cowork-cartas`) y pulsar **Añadir**.
4. WordPress muestra una contraseña de 24 caracteres con espacios
(formato `xxxx xxxx xxxx xxxx xxxx xxxx`). **Se copia y se guarda**: solo se ve una vez.
**Cómo la usa el asistente:** autenticación HTTP Basic sobre HTTPS, con
`usuario:contraseña_de_aplicación`. Ejemplo de prueba (debe responder con los datos del
usuario):
```bash
curl -s -u "USUARIO:xxxx xxxx xxxx xxxx xxxx xxxx" \
https://wp-nuevo.feadulta.com/wp-json/wp/v2/users/me
```
Base de la API para todo lo demás: `https://wp-nuevo.feadulta.com/wp-json/wp/v2/`
> **⚠️ Pendiente de configurar en Cloudflare (bloqueante).** Comprobado el **27/06/2026**: el
> sitio está tras Cloudflare y devuelve **403 "Attention Required"** a **cualquier** petición
> que no sea un navegador real con JavaScript — afecta a la API REST, a la home y a
> `wp-login.php`, incluso enviando un User-Agent de navegador. Es el reto de navegador de
> Cloudflare, **no** un problema de la credencial.
>
> Para que el asistente pueda usar la API hay que crear una **excepción en el panel de
> Cloudflare** (lo hace Inma). Opciones, de más simple a más limpia:
> 1. **Allowlist por IP de origen:** WAF → Tools → permitir la IP pública desde la que se
> conecta el asistente. Simple, pero requiere IP fija/conocida.
> 2. **Regla WAF con token secreto:** una Custom Rule que haga *Skip / Bypass* cuando la
> petición vaya a `/wp-json/*` **y** lleve una cabecera secreta (p. ej.
> `X-FEA-Key: <secreto>`). El asistente añade esa cabecera en cada llamada.
> 3. **Subdominio "solo DNS"** (sin proxy naranja), p. ej. `api.feadulta.com`, apuntando al
> mismo origen para servir la API sin pasar por el reto de Cloudflare.
>
> Hasta que se aplique una de estas, las llamadas a la API fallarán con 403. Coordinar con
> Rafa/Inma cuál se elige.
---
## 2. La idea clave: **la carta de la semana ES la portada**
Esto es lo más importante de entender. La portada de Fe Adulta **no** muestra "los últimos
artículos por categoría". Muestra **exactamente lo que enlaza la carta de la semana actual**,
agrupado por las secciones internas de esa carta.
Es decir: la carta semanal es un artículo largo en HTML, con secciones marcadas por
encabezados, y dentro de cada sección hay enlaces a otros artículos. La portada lee la carta
vigente, detecta esas secciones y coloca cada grupo de enlaces en su bloque correspondiente.
**Consecuencia práctica:** para que la portada se rellene bien, la carta tiene que estar
escrita con unos **encabezados de sección concretos** (§5) y enlazar a artículos que ya
existan en el sitio (§4).
---
## 3. Categorías del sitio
Las categorías se asignan por su **ID numérico** vía API (campo `categories: [..]`).
### 3.1 Categorías de la carta (estado de cada carta)
| ID | Nombre | Slug | Significado |
|----|--------|------|-------------|
| **6** | Carta de la semana | `cartasemana` | La carta **vigente**. Debe estar solo la actual. |
| **22** | La semana pasada | `carta-semana-pasada` | La carta de la semana anterior. |
| **21** | Cartas de otras semanas | `cartas-de-otras-semanas` | Histórico (todas las anteriores). |
### 3.2 Categorías temáticas (para los artículos de dentro de la carta)
| ID | Nombre | Uso |
|----|--------|-----|
| 1645 | Lecturas bíblicas | Lecturas del domingo |
| 1646 | Comentario editorial | Comentario editorial de la semana |
| 1647 | Comentarios al evangelio | Artículos que comentan el evangelio |
| 1648 | Eucaristía | Material para la eucaristía |
| 1649 | Multimedia | Vídeos / audios / material multimedia |
| 1650 | Artículos | Artículos generales seleccionados |
> Cada artículo de la semana va en su categoría temática. **La carta** (el texto largo) va
> en la categoría **6**.
---
## 4. Cómo se publica una carta nueva (flujo completo)
Una "carta" no es un solo artículo: es **un artículo-carta que enlaza a varios artículos**.
El orden correcto es: primero los artículos, luego la carta que los enlaza.
### Paso 1 — Crear los artículos de la semana
Cada pieza de contenido (cada comentario al evangelio, cada artículo seleccionado, etc.) es
un **post** propio. Se crean vía API y conviene crearlos primero **como borrador** y, cuando
estén listos, publicarlos.
```bash
curl -s -u "USUARIO:APP_PASSWORD" \
-X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts \
-H "Content-Type: application/json" \
-d '{
"title": "Título del artículo",
"content": "<p>Cuerpo en HTML…</p>",
"status": "draft",
"categories": [1647]
}'
```
De la respuesta JSON interesan dos campos:
- `id` → identificador del post.
- `link` → la **URL pública** del artículo. **Guardar esta URL**: es la que se usa para
enlazar desde la carta.
Repetir para cada artículo, usando la categoría temática que corresponda (§3.2).
### Paso 2 — Componer el artículo-carta
La carta es un post HTML con:
1. Texto editorial libre (introducción).
2. Una sección por cada bloque, **encabezada con una de las frases exactas de §5**.
3. Dentro de cada sección, **enlaces (`<a href>`) a las URLs** de los artículos del Paso 1.
Ver §5 para el formato exacto de los encabezados y un ejemplo completo.
### Paso 3 — Publicar (o programar) la carta
La carta va en la categoría **6** (`cartasemana`).
- **Publicar ya:** `"status": "publish"`.
- **Programar:** `"status": "future"` + `"date"` con la fecha/hora local del sitio en
formato ISO 8601, p. ej. `"2026-06-29T08:00:00"`. WordPress la publicará sola a esa hora.
```bash
curl -s -u "USUARIO:APP_PASSWORD" \
-X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts \
-H "Content-Type: application/json" \
-d '{
"title": "Carta de la semana — 29 de junio",
"content": "<p>…cuerpo de la carta con sus secciones y enlaces…</p>",
"status": "future",
"date": "2026-06-29T08:00:00",
"categories": [6]
}'
```
### Paso 4 — Rotar la carta anterior (IMPORTANTE, manual)
Al entrar una carta nueva en la categoría **6**, hay que **degradar la anterior** para que la
categoría "Carta de la semana" contenga **solo una** carta:
1. A la carta que **dejaba** de ser actual: quitarle la categoría **6** y ponerle la **22**
("La semana pasada").
2. A la que estaba en **22**: pasarla a la **21** ("Cartas de otras semanas").
Vía API se actualiza el array `categories` del post (sustituye al anterior):
```bash
curl -s -u "USUARIO:APP_PASSWORD" \
-X POST https://wp-nuevo.feadulta.com/wp-json/wp/v2/posts/ID_DE_LA_CARTA_VIEJA \
-H "Content-Type: application/json" \
-d '{"categories": [22]}'
```
> Si se programa la carta nueva con `future`, esta rotación puede hacerse el mismo día en que
> se publique. Si surge duda sobre qué carta está en qué categoría, consultar:
> `GET /wp-json/wp/v2/posts?categories=6` (debe devolver solo una).
---
## 5. Formato de la carta para que la portada la "entienda"
La portada parsea el HTML de la carta buscando **encabezados con estas frases** (no distingue
mayúsculas/acentos, pero el texto debe coincidir). Cada encabezado abre una sección; todos los
enlaces que vayan **después** de ese encabezado (hasta el siguiente) se muestran en el bloque
de portada indicado:
| Frase del encabezado en la carta | Bloque de portada |
|----------------------------------|-------------------|
| **Evangelio y comentarios al Evangelio** | Evangelio |
| **Artículos seleccionados para la semana** | Artículos de la semana |
| **Para unas eucaristías más participativas y actuales** | Eucaristía |
| **Material multimedia** | Multimedia |
| **Escuela EFFA** | EFFA |
**Reglas:**
- Los encabezados se suelen marcar en rojo/negrita (es el estilo histórico), pero lo que
importa es que **el texto coincida** con la frase de la tabla.
- Los enlaces dentro de cada sección deben apuntar a **artículos que existan** en el sitio
(las URLs del Paso 1). Enlaces a páginas externas se ignoran.
- Si una sección no tiene enlaces, ese bloque de la portada queda vacío.
**Ejemplo mínimo de cuerpo de carta:**
```html
<p>Texto editorial de introducción de la semana…</p>
<p><strong style="color:red">Evangelio y comentarios al Evangelio</strong></p>
<ul>
<li><a href="https://wp-nuevo.feadulta.com/comentario-evangelio-domingo/">Comentario al evangelio</a></li>
</ul>
<p><strong style="color:red">Artículos seleccionados para la semana</strong></p>
<ul>
<li><a href="https://wp-nuevo.feadulta.com/articulo-uno/">Primer artículo</a></li>
<li><a href="https://wp-nuevo.feadulta.com/articulo-dos/">Segundo artículo</a></li>
</ul>
<p><strong style="color:red">Para unas eucaristías más participativas y actuales</strong></p>
<ul>
<li><a href="https://wp-nuevo.feadulta.com/eucaristia-domingo/">Material para la eucaristía</a></li>
</ul>
<p><strong style="color:red">Material multimedia</strong></p>
<ul>
<li><a href="https://wp-nuevo.feadulta.com/video-semana/">Vídeo de la semana</a></li>
</ul>
```
> La portada cachea el resultado **15 minutos**. Al guardar/editar la carta se refresca sola,
> pero si un cambio no se ve al momento, esperar unos minutos.
---
## 6. Qué es automático y qué hay que tocar a mano
### Automático — NO hay que hacer nada
- **Portada (home):** se construye sola a partir de la carta vigente (la más reciente en la
categoría 6) y sus secciones (§5).
- **Página "Carta de la semana"** (`/carta-de-la-semana/`): redirige automáticamente a la
carta más reciente de la categoría 6.
- **Página "La semana pasada"** (`/la-semana-pasada/`): redirige a la carta más reciente de la
categoría 22.
- **Menús, avatares de autores, multiidioma, etc.:** gestionados por el tema/plugins.
- **Traducciones (EN/FR/IT/PT) y audio (TTS):** las genera el proceso del servidor (§7).
### Manual — lo que hace Inma / su asistente
- Crear los **artículos** de la semana (§4, Paso 1).
- Componer y **publicar/programar la carta** (§4, Pasos 2-3).
- **Rotar** la carta anterior de categoría (§4, Paso 4).
- Subir **imagen destacada** del artículo si se quiere (campo `featured_media` con el ID de
un adjunto previamente subido a la biblioteca de medios).
---
## 7. Traducción y audio automáticos (lado servidor — informativo)
**Inma no tiene que traducir ni generar audio.** En el servidor hay (o habrá) un proceso
programado (cron) que:
1. Detecta cartas y artículos nuevos publicados **en español** sin traducción.
2. Los **traduce** a EN/FR/IT/PT y los enlaza como traducciones (Polylang).
3. Genera el **audio TTS** (voz, MiniMax) de la carta y sus artículos.
Por eso es importante: **subir siempre el contenido en español** y dejar que el proceso haga
el resto. Si una carta urgente necesita traducción inmediata, avisar a Rafa.
> *Este punto es responsabilidad de Rafa (infraestructura). Se incluye aquí solo para que el
> asistente de Inma sepa que no debe duplicar ese trabajo.*
---
## 8. Resumen rápido (checklist por carta)
- [ ] Crear cada artículo de la semana (borrador → publicado). Guardar su URL.
- [ ] Componer la carta en HTML con los **encabezados exactos** de §5 y los enlaces a esos artículos.
- [ ] Publicar o programar la carta en la categoría **6**.
- [ ] Rotar la carta anterior: 6 → 22, y la de 22 → 21.
- [ ] Comprobar que la portada muestra las secciones (esperar hasta 15 min si hace falta).
- [ ] No traducir ni generar audio: lo hace el servidor.
---
## 9. Referencia rápida de la API
| Acción | Método y endpoint |
|--------|-------------------|
| Probar credencial | `GET /wp-json/wp/v2/users/me` |
| Listar categorías | `GET /wp-json/wp/v2/categories?per_page=100` |
| Crear artículo/carta | `POST /wp-json/wp/v2/posts` |
| Editar artículo/carta | `POST /wp-json/wp/v2/posts/{id}` |
| Ver carta vigente | `GET /wp-json/wp/v2/posts?categories=6` |
| Subir imagen | `POST /wp-json/wp/v2/media` (cabecera `Content-Disposition`) |
Campos útiles del post: `title`, `content` (HTML), `status` (`draft`/`publish`/`future`),
`date` (ISO 8601 para programar), `categories` (array de IDs), `featured_media` (ID de adjunto).