# API de caché

> Recachea o borra páginas cuando publicas cambios, desde tu despliegue, tu CMS o un script.

Página original: https://docs.jazui.com/api/cache/es

Cuando cambias tu web, las páginas en caché siguen mostrando la versión anterior hasta el siguiente recaché automático. Con esta API le dices a Jazui que vuelva a renderizarlas (o que las quite) al momento. Las peticiones crean una **tarea** que se procesa en segundo plano y cuyo estado puedes consultar.

> Incluida en los planes con **API de caché** ([Planes y límites](https://docs.jazui.com/llms/es/plans.txt)). Usa el token de render de la cuenta o el de un sitio (con el del sitio, solo puedes tocar ese sitio).

## Direcciones

| Método | Ruta | Qué hace |
|---|---|---|
| `POST` | `/v2/cache/recache` | Vuelve a renderizar las páginas. Las que no estaban en caché se renderizan por primera vez. |
| `POST` | `/v2/cache/purge` | Quita las páginas de la caché (el siguiente bot provocará un render nuevo). |
| `GET` | `/v2/cache/tasks/{id}` | Estado de una tarea. |
| `GET` | `/v2/cache/tasks?limit=20` | Últimas tareas (de 1 a 100). Con un token de sitio, solo las de ese sitio. |

## Qué páginas

El cuerpo lleva **exactamente una** de estas tres opciones:

- `urls`: una lista de hasta 1.000 direcciones completas (se normalizan y se quitan las repetidas).
- `prefix`: todas las páginas en caché que empiezan por esa dirección (también la dirección sin la barra final). Útil para una sección: `/blog/`, `/productos/`…
- `site`: todas las páginas en caché de un sitio.

Con `prefix` y `site` se procesan como mucho 10.000 páginas por tarea.

`urls`:

```json
{ "urls": ["https://misitio.com/", "https://misitio.com/precios"] }
```

`prefix`:

```json
{ "prefix": "https://misitio.com/blog/" }
```

`site`:

```json
{ "site": "misitio.com" }
```

## Ejemplo

```bash
curl -X POST https://api.jazui.com/v2/cache/recache \
  -H "Authorization: Bearer $JAZUI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://misitio.com/","https://misitio.com/precios"]}'
```

`202 Accepted`:

```json
{
  "id": "01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70",
  "action": "Recache",
  "scope": "Urls",
  "target": null,
  "state": "Queued",
  "total": 2,
  "processed": 0,
  "failed": 0,
  "createdAt": "2026-11-03T20:22:17Z",
  "startedAt": null,
  "finishedAt": null,
  "error": null,
  "statusUrl": "https://api.jazui.com/v2/cache/tasks/01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70"
}
```

```bash
curl https://api.jazui.com/v2/cache/tasks/01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70 \
  -H "Authorization: Bearer $JAZUI_TOKEN"
```

```json
{
  "id": "01a1842d-5d0b-4d6e-9a7f-2c3b4d5e6f70",
  "action": "Recache",
  "scope": "Urls",
  "state": "Done",
  "total": 2,
  "processed": 2,
  "failed": 0,
  "createdAt": "2026-11-03T20:22:17Z",
  "startedAt": "2026-11-03T20:22:18Z",
  "finishedAt": "2026-11-03T20:22:31Z",
  "error": null
}
```

## La tarea

| Campo | Descripción |
|---|---|
| `action` | `Recache` o `Purge`. |
| `scope` y `target` | `Urls`, `Prefix` o `Site`, con el prefijo o el sitio. |
| `state` | `Queued` (en cola), `Running`, `Done` o `Failed` (con el motivo en `error`). |
| `total`, `processed`, `failed` | Páginas en total, hechas y con error. El progreso se guarda cada 10 páginas. |
| `statusUrl` | Dirección para consultar la tarea (también en la cabecera `Location`). |

Las tareas se procesan de una en una, por orden de llegada. Recachear **gasta renders** del plan como cualquier otro render; si se acaban, esas páginas cuentan como fallidas.

## Errores

| Código | `code` | Motivo |
|---|---|---|
| `400` | `invalid_request` | No llega exactamente una opción, más de 1.000 direcciones o alguna no es absoluta. |
| `403` | `plan` | Tu plan no incluye la API de caché. |
| `403` | `forbidden` | El dominio no es de tu cuenta (o del sitio del token), o el sitio no está verificado. |
| `429` | `too_many_tasks` | Ya tienes 10 tareas en cola o en marcha: espera a que terminen. |

## Al desplegar

Lo habitual es recachear el sitio entero (o la sección que cambió) al final de tu despliegue. Guarda el token como secreto de tu CI:

`GitHub Actions`:

```bash
# .github/workflows/deploy.yml (después de publicar la web)
- name: Recachear en Jazui
  run: |
    curl -fsS -X POST https://api.jazui.com/v2/cache/recache \
      -H "Authorization: Bearer ${{ secrets.JAZUI_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"site":"misitio.com"}'
```