# Plantilla n8n: LicitaIA → Google Sheets

La plantilla [`licitaia-licitaciones-google-sheets.json`](./licitaia-licitaciones-google-sheets.json) hace una búsqueda manual en la API pública v1 de LicitaIA y guarda cada resultado con `appendOrUpdate` de Google Sheets, usando `id` como columna de coincidencia. Una segunda ejecución actualiza la fila existente.

## Configuración

1. En n8n, importa el JSON y deja el workflow inactivo (`active=false`).
2. Crea una clave de lectura (`licitaciones:read`) desde [Equipo · API](https://licitaia.org/equipo/api/). En n8n, crea una credencial **Header Auth** con cabecera `x-api-key` y el valor de tu clave, y selecciónala en el nodo `LicitaIA API (Header Auth)`. La clave no está en el JSON ni en expresiones.
3. Crea una credencial **Google Sheets OAuth2** con acceso al documento que elijas y selecciónala en el nodo `Google Sheets: upsert por id`.
4. En `Configuración (editar filtros)`, cambia `query`, `cpv`, `provincia`, `organismo`, `page`, `limit`, `spreadsheetId` y `sheetName`. `limit` queda acotado a 20 y `page` a 1..2 para respetar el alcance Free documentado. `organismo` sí está admitido por el endpoint Free actual.
5. En el nodo de Google Sheets selecciona el documento/hoja del usuario, o sustituye los valores de marcador de `Configuración`; el nodo los lee mediante expresiones. La primera fila debe tener estas cabeceras: `id`, `titulo`, `organismo`, `presupuesto`, `plazo`, `enlaceOficial`, `enlaceLicitaIA`, `cpv`, `provincia`, `pagina`, `totalPaginas`, `alerta`, `actualizadoEn`.
6. Ejecuta el nodo manual. La programación periódica es opcional: si se añade, debe permanecer desactivada hasta que el usuario elija una frecuencia que pueda asumir la cuota.

La URL de destino está fijada literalmente en el nodo HTTP: `https://api.licitaia.org/api/v1/licitaciones`. Los filtros vacíos se omiten de la petición; por ejemplo, enviar `cpv=` sería inválido. El workflow no admite una URL de API procedente de una entrada externa, no usa LLM ni envía alertas.

## Límites y comportamiento seguro

- La plantilla solicita una página de hasta 20 resultados. Si `totalPages` es mayor que la página guardada, cada fila incluye una alerta de truncación. El mensaje recuerda que la página no es exhaustiva y no promete vigilancia completa.
- Un resultado vacío deja un registro `RESUMEN` visible en la ejecución n8n y no crea filas en Sheets. Un 401/403/429/5xx deja un registro de error visible y no escribe filas falsas; se debe corregir credencial, permisos o cuota antes de reintentar.
- Los campos de texto que empiezan por espacio, control o `=`, `+`, `-` o `@` se anteponen con `'` antes de llegar a Sheets para evitar inyección de fórmulas. El nodo usa `cellFormat=RAW`, por lo que ese apóstrofo protector puede quedar visible en la celda; es deliberado. `presupuestoBase` solo se guarda si la API entrega un número finito; los nulos se convierten en celda vacía. Un id que no sea UUID se descarta con error visible y nunca hace upsert.
- El upsert se hace por `id` devuelto por LicitaIA. No se usa memoria de ejecución ni una lista estática para deduplicar.
- La API Free comparte 200 operaciones/mes y 10 por minuto por organización; el hospedaje n8n tiene su propio coste y límites. Cada ejecución de esta plantilla hace una llamada HTTP. Google Sheets tiene cuotas propias. Revisa `Retry-After` y las cabeceras `X-RateLimit-*` cuando n8n las muestre.
- La API puede cambiar campos opcionales. Se conservan los campos principales `id`, título, organismo, presupuesto, plazo, enlace oficial y enlace LicitaIA cuando el contrato los aporta; el resto queda vacío.

Para el contrato actual, consulta `docs/25-api-publica.md`, `backend/src/public-api/public-mcp.service.ts` y la documentación pública de `/api/v1/docs`. En Free se consume `{data, meta}` de la allowlist: `title`, `organismo`, `presupuestoBase`, `fechaLimite`, `cpv`, `lugar` y `enlaces.oficial/licitaia`. En Pro/Team la API devuelve `{data, total, page, limit, totalPages}` y entidades con importes normalizados; el nodo adapta explícitamente ambos envelopes sin aliases adivinados. No se sustituye `presupuestoBase` por `valorEstimado`.

## Dependencias pendientes de la instancia

La importación no crea credenciales, documentos ni hojas reales. El usuario debe configurar la API key en Header Auth, autorizar Google Sheets, seleccionar el documento y compartirlo con esa credencial. Una prueba con Google Sheets real es E2E de la instancia y no forma parte de los fixtures locales.

## Pruebas y compatibilidad

Probada el 11/10/2026 con n8n 1.123.0: importación y ejecución del motor con Header Auth, respuestas Free/Pro, vacío, UUID inválido y errores 401/403/429/500. El código real del nodo Google Sheets se probó con un transporte HTTP simulado: dos ejecuciones con el mismo id conservan una fila y actualizan sus datos. La API Free también se consultó en producción con una clave temporal de QA que se revocó al terminar.

No se ha probado OAuth ni escritura en una cuenta Google real, ni se ha validado n8n 2.42.6. Ejecuta primero con una hoja de prueba y revisa sus resultados antes de añadir una programación. Esta es una plantilla publicada por licitaIA, no una integración oficial aprobada por n8n.
