# Contrato del endpoint de ingesta de eventos (para el agente de scraping)

> Versión del contrato: **2026-10-10**. Reescrito al estado real del endpoint
> (`src/routes/api/admin/eventos/ingest/+server.ts`). Este documento explica las reglas; los catálogos
> vigentes y la huella NO viven aquí sino en el contrato vivo (sección 1), porque los catálogos cambian
> sin avisar y este texto se queda viejo.

## 1. Paso previo obligatorio: pedir el contrato vivo

Al empezar CADA corrida, antes de enviar nada:

```
GET https://eco.lpdi.co/api/admin/eventos/ingest/contrato
Authorization: Bearer <INGEST_SECRET>
```

- Misma autenticación que la ingesta. Sin el bearer correcto responde `401`.
- Responde `Cache-Control: no-store`, no escribe nada y devuelve: `contrato { version, huella }`,
  `codigo_evento`, `estados`, `campos`, `avisos_tema`, `catalogos` (`paises`, `tematicas`,
  `actividades`, `modalidades`, `costo_inscripcion`, `industrias`), `cambios` y `generado_en`.
- Cada catálogo sale de las MISMAS fuentes con que la ingesta valida ese campo (hay una prueba que lo
  ata). Valide y clasifique contra ese catálogo, no contra copias guardadas.
- `huella` es un sha256 (16 caracteres) de todo el contrato salvo `generado_en`. No cambia entre dos
  llamadas seguidas; cambia si cambia una regla o un valor de un catálogo.

En el `POST` de ingesta mande la huella que acaba de leer:

```json
{ "fuente": "luma", "contrato_huella": "<huella del GET>", "eventos": [ ... ] }
```

- Si `contrato_huella` no coincide con la vigente, la ingesta responde **`409`** sin procesar ningún
  evento:

  ```json
  {
    "ok": false,
    "error": "contrato_desactualizado",
    "huella_enviada": "...",
    "huella_actual": "...",
    "version_actual": "2026-10-10",
    "cambios": [ { "fecha": "2026-10-10", "que": "..." } ],
    "contrato_url": "https://eco.lpdi.co/api/admin/eventos/ingest/contrato"
  }
  ```

  Ante un `409`: vuelva a pedir el contrato, adapte sus catálogos y reglas, y reenvíe el lote con la
  huella nueva.
- Si no manda `contrato_huella`, el lote se procesa como siempre (compatibilidad), pero usted no se
  entera de que el contrato cambió. Mandarla es lo que garantiza el aviso.
- Si `contrato_huella` viene y no es texto, responde `400`.
- TODA respuesta `200` trae `contrato: { version, huella }`; si difiere de la que usted tiene, vuelva a
  pedir el contrato en la siguiente corrida.

## 2. Endpoint y autenticación

```
POST https://eco.lpdi.co/api/admin/eventos/ingest
Authorization: Bearer <INGEST_SECRET>
Content-Type: application/json
```

- Sin el header correcto responde `401`. Cuerpo que no es JSON responde `400`.
- Falta `fuente` o `eventos` vacío: `400`. Máximo **500 eventos por lote**.
- Un evento inválido NO tumba el lote: se marca `error` con su motivo y los demás se procesan.

Estructura:

```json
{ "fuente": "nombre-de-la-fuente", "contrato_huella": "<huella>", "eventos": [ { }, { } ] }
```

`fuente` (texto, requerido; se guarda en minúsculas) junto con `id_fuente` forma la llave de upsert.

## 3. Campos de un evento

La lista vigente y sus notas están en `campos` del contrato vivo. Resumen al 2026-10-10:

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `id_fuente` | texto | Sí | Identificador estable en la fuente. |
| `nombre` | texto | Sí | |
| `fecha_inicio` | `YYYY-MM-DD` | Sí | |
| `fecha_finalizacion` | `YYYY-MM-DD` | No | Por defecto igual a `fecha_inicio`. |
| `modalidad` | texto cerrado | No | `presencial`, `online`, `hibrido`, `dual`. Ausente o vacía: `presencial`. Presente y fuera de la lista: el evento se rechaza (sección 7). |
| `zona_horaria` | texto | No | Por defecto `America/Bogota`. |
| `horarios` | lista | No | Cada fecha dentro de las fechas del evento (sección 6). |
| `pais_code` | texto | Sí salvo `online` | Nombre en español del catálogo, ISO alpha-2/3 o alias común en inglés. Si no resuelve, el evento se rechaza. |
| `estado_provincia`, `ciudad` | texto | No | La ciudad se recomienda en presenciales. |
| `ubicacion_texto` | texto | No | Dirección exacta; ver sección 8. |
| `ubicacion_lat`, `ubicacion_lng` | número | No | |
| `ubicacion_por_confirmar`, `ubicacion_solo_registrados` | booleano | No | Excluyentes entre sí. |
| `tematicas` | lista de `{ categoria, subcategoria, principal? }` | No | Sección 5. |
| `actividades` | lista de `{ categoria, subcategoria }` | No | Sección 4. |
| `organizadores_raw` | lista de `{ nombre, rol }` | No | `rol` es el rol en el ecosistema de la organización, no su papel en el evento. Sección 9. |
| `hosts_speakers` | lista | No | |
| `costo_inscripcion` | texto cerrado | No | `ENTRADA_LIBRE_SIN_REGISTRO` (por defecto), `ENTRADA_LIBRE_CON_REGISTRO`, `POR_INVITACION`, `SI`. Presente y fuera de la lista: el evento se rechaza con los valores válidos (CHECK de la base, `supabase/migrations/049_eventos_schema.sql:86`, sin cambios posteriores). |
| `link_registro`, `link_evento`, `link_sesion`, `mas_informacion`, `url_fuente` | texto | No | |
| `super_evento_id` | uuid | No | Asocia el evento a un super evento (agrega su sigla al código). |

## 4. Actividades: lista de objetos `{ categoria, subcategoria }`

Desde 2026-10-10 `actividades` se valida. Antes se guardaba lo que llegara; y el documento anterior
mostraba textos sueltos (`["conferencia","networking"]`), que era un defecto: en la base cada actividad
es un objeto.

```json
"actividades": [
  { "categoria": "networking", "subcategoria": "networking-session" },
  { "categoria": "tech-weeks", "subcategoria": "tech-week" }
]
```

- Ausente o lista vacía: se acepta (igual que `tematicas`).
- Cada ítem debe ser un objeto cuyo PAR `categoria` + `subcategoria` exista en el catálogo.
- Si no, ese evento se rechaza con `status: "error"` y un motivo que dice qué llegó:
  - `actividad no reconocida: {"categoria":"x","subcategoria":"y"}`
  - `actividades debe ser una lista de { categoria, subcategoria }; llego el item "conferencia"`
  - `actividades debe ser una lista de { categoria, subcategoria }; llego: "conferencia"` (cuando no es una lista)
- Nada se convierte en silencio: un texto suelto no se transforma en objeto.

Catálogo completo al 2026-10-10 (27 subcategorías en 5 categorías; el vigente está en
`catalogos.actividades` del contrato):

| Categoría | Subcategorías |
|-----------|---------------|
| `academica` (Académica) | `capacitacion` (Capacitación), `clase` (Clase), `conferencia` (Conferencia), `conversatorio` (Conversatorio), `curso` (Curso), `debate` (Debate), `foro` (Foro), `masterclass` (Masterclass), `taller` (Taller), `webinar` (Webinar), `workshop` (Workshop) |
| `networking` (Networking) | `actividad-bienestar` (Actividad de bienestar), `actividad-deportiva` (Actividad deportiva), `after-party` (After party), `almuerzo` (Almuerzo), `cena` (Cena), `coctel` (Cóctel), `desayuno` (Desayuno), `networking-session` (Networking session) |
| `matchmaking` (Matchmaking) | `demo-day` (Demo Day), `muestra-comercial` (Muestra Comercial), `pitch-practice` (Pitch Practice), `reverse-pitch` (Reverse Pitch), `rueda-de-negocios` (Rueda de Negocios), `sesion-informativa` (Sesión Informativa) |
| `tech-weeks` (Tech Weeks) | `tech-week` (Tech Weeks) |
| `otro` (Otro tipo de actividad) | `otro` (Otro) |

## 5. Temáticas y código del evento

Cada ítem de `tematicas` es `{ "categoria": "<slug>", "subcategoria": "<slug>" }`; uno puede llevar
`"principal": true`. La principal es la marcada o, si ninguna, la primera.

- `categoria` debe ser uno de los 9 slugs: `emprendimiento`, `innovacion`, `inversion`, `economia`,
  `estrategia-gestion`, `marketing-ventas`, `desarrollo-profesional`, `otros-temas`, `sectorial`.
- `subcategoria` debe existir en el catálogo (`catalogos.tematicas`, con su `codigo_tema`).
- Categoría o subcategoría fuera del catálogo: el evento se rechaza (`categoria de tematica no
  reconocida` o `subcategoria de tematica no reconocida`). No hay código de relleno silencioso.
- Cada ítem debe traer `categoria` Y `subcategoria`, las dos no vacías; si falta una, el evento se rechaza con `cada tematica debe traer categoria y subcategoria: llego {"subcategoria":"fintech"}`.
- Traer temáticas no es obligatorio (ausente o lista vacía se acepta), pero si vienen deben ser válidas. Sin ellas el código queda en
  `999999` y la respuesta trae aviso (más abajo).
- La subcategoría debe pertenecer a la categoría que envía (el PAR del catálogo). Un par cruzado se
  rechaza, por ejemplo `la subcategoria "fintech" no pertenece a la categoria "emprendimiento"
  (pertenece a "sectorial")`. El slug `ecommerce` existe en dos categorías y las dos combinaciones son
  válidas, cada una con su código: `marketing-ventas` + `ecommerce` da `500001`, `sectorial` +
  `ecommerce` da `801001`.

### Código del evento

Formato `M-CC-TTTTTT-AA-NNNNN(-SIGLA)`, que se genera solo en el alta (una actualización no lo cambia):

| Segmento | Significado |
|----------|-------------|
| `M` | Modalidad: presencial `P`, online `V`, hibrido `H`, dual `D`. |
| `CC` | ISO alpha-2 del país; online o país sin coincidencia: `00`. |
| `TTTTTT` | Código de 6 dígitos de la temática principal (estructura CC-SS-SS). Sin temáticas: `999999`. |
| `AA` | Dos últimos dígitos del año de `fecha_inicio`. |
| `NNNNN` | Consecutivo de 5 dígitos por año, asignado por el servidor. |
| `SIGLA` | Opcional: sigla del super evento. |

Convención «Otra»: un `99` en el segundo o tercer par del tema (por ejemplo `990099`, `809999`,
`909999`) es la temática «Otra». El primer par `99` es la categoría «Otros temas» (por ejemplo
Educación, `990001`) y no cuenta como «Otra».

Ejemplos reales medidos en producción el 2026-10-10:

| Caso | Código |
|------|--------|
| Fintech sectorial | `P-CO-800401-26-00011` |
| Sin temáticas | `P-CO-999999-26-00012` (con `advertencia_tema`) |
| Temática `otros-temas` / `otra` | `P-CO-990099-26-00013` (sin aviso en ese momento; desde este contrato lleva aviso de tipo `otra`) |

### Los dos avisos de temática

En las respuestas `created` y `updated` aparece `advertencia_tema` junto con `advertencia_tema_tipo`.
NO son rechazos: el evento se crea o actualiza igual.

| `advertencia_tema_tipo` | Cuándo | Qué hacer |
|-------------------------|--------|-----------|
| `sin_tematica` | El código de tema es `999999`. Texto: `segmento de tema 999999: el evento no trae una tematica reconocida y quedo sin clasificar por tema. Revisa la tematica antes de publicar.` | Mande una `tematicas` válida. |
| `otra` | La temática principal quedó clasificada como «Otra» (segmento 99 en la subcategoría). Texto: `la tematica principal quedo clasificada como "Otra" (codigo de tema con segmento 99): no encontro una tematica especifica del catalogo. Revisa la tematica antes de publicar.` | Busque una temática específica del catálogo; si no existe, déjela para curaduría. |

En una actualización el código no se regenera: el aviso se calcula sobre el código que el evento ya tiene.

## 6. Horarios dentro del rango (desde 2026-10-05)

Cada fecha de `horarios` debe estar dentro de `[fecha_inicio, fecha_finalizacion]`. Si no, el evento se
rechaza con `El horario del 05-nov-2026 no está dentro de las fechas del evento.` (fecha del primer
horario fuera de rango). Es la misma regla del formulario y de la edición.

## 7. Países y modalidades

- `pais_code`: valores en `catalogos.paises` (`nombre`, `iso_alpha2`). Se acepta además el ISO como
  texto y algunos alias en inglés (por ejemplo `Brazil`, `Spain`); se guarda el nombre en español del
  catálogo. Fuera de `online`, un país que no resuelve rechaza el evento con `país no reconocido en el
  catálogo`.
- `modalidad`: valores en `catalogos.modalidades`. Ausente o vacía se toma como `presencial`. Si viene y no está en el catálogo, el evento se rechaza con `modalidad no reconocida: "x" (valores validos: presencial, online, hibrido, dual)`; ya no se guarda `presencial` en silencio.
- `costo_inscripcion`: valores en `catalogos.costo_inscripcion`. Si viene y no es uno de ellos, el evento se rechaza con `costo_inscripcion no reconocido: "x" (valores validos: ...)`.

## 8. Reglas de ubicación

1. Presencial con dirección exacta (`ubicacion_texto`, sin banderas): la plataforma geocodifica la
   dirección (precisión `venue`, o `city` si solo resuelve el centro).
2. Presencial sin dirección exacta y sin banderas: se marca sola `ubicacion_por_confirmar = true` y se
   conservan las coordenadas de la CIUDAD (precisión `city`).
3. `ubicacion_por_confirmar = true`: conserva las coordenadas de la ciudad.
4. `ubicacion_solo_registrados = true`: `lat/lng` quedan nulos, precisión `none`.
5. Las dos banderas son excluyentes: ambas en `true` rechaza el evento.
6. No mande el texto «Por confirmar» como dirección. Los placeholders tipo «Registrarse para ver...» se
   descartan.
7. Las banderas ganan sobre cualquier `lat/lng` que mande.
8. Geocodificación: en presencial, híbrido o dual sin `solo_registrados`, sin `lat/lng` y con ciudad o
   país, la plataforma geocodifica restringiendo por país. Es best-effort: si falla, el evento no se
   rechaza.

## 9. Organizadores

`organizadores_raw` es `[{ "nombre": "...", "rol": "..." }]`. Tras cada alta o actualización cada
organizador se asocia por nombre normalizado a una ficha existente o se crea una nueva. Los parecidos
quedan marcados para revisión del superadmin; no hay fusión automática. Envíe el nombre limpio.

### Qué es `rol`

`rol` es el **rol en el ecosistema** de la organización, es decir, qué tipo de actor es (Universidad,
Startup, Asociación, Comunidad...). **No es su papel en el evento**: no envíe «Organizador»,
«Patrocinador», «Aliado» ni «Anfitrión». Es el mismo dato que el formulario de eventos pide como «Rol en
el ecosistema».

- Valores admitidos: los de `catalogos.roles_organizador` del contrato vivo (`GET .../ingest/contrato`),
  campo `valor`. Son 45 en 10 categorías (por ejemplo `Universidad`, `Startup`, `PyME`, `Comunidad`,
  `Fundacion`, `Centro de Innovacion`, `Hub de Innovacion`, `Empresa Privada`, `Otro`).
- Se envía el `valor` **exacto**, no la `etiqueta`: sin tildes (`Asociacion`, no «Asociación»;
  `Camara de Comercio`, no «Cámara de Comercio») y respetando mayúsculas. Solo se recortan los espacios
  de los extremos.
- Si una organización no encaja en ninguno, use `Otro`; si no sabe, deje `rol` vacío o sin enviar.

### Qué pasa con cada caso

La ingesta **nunca rechaza un evento por el rol** y la respuesta **no trae ningún aviso** sobre él.

| Caso | Qué se guarda |
|------|---------------|
| Rol del catálogo | El texto queda en el vínculo evento y organizador. Si la ficha del directorio es nueva, o existe sin rol y sin entidad registrada vinculada, la ficha toma ese rol (solo la primera vez). Si la ficha ya tiene un rol, no se cambia. |
| Vacío o sin enviar | El vínculo queda sin rol y la ficha no se toca. |
| Fuera del catálogo (por ejemplo `Organizador` o «Asociación» con tilde) | El texto queda tal cual en el vínculo del evento, pero **no llega a la ficha** del directorio: la organización queda sin rol en el directorio. |

Si una misma organización aparece dos veces en el evento, a la ficha le sirve el primer rol no vacío y el vínculo del evento conserva la primera aparición. Para una
organización que ya es una entidad registrada en el sistema, su rol lo define su perfil, no el evento.

En el panel de curaduría, la tabla y el resumen del evento muestran solo el nombre del organizador. El
modal de edición avisa «Hay organizadores sin rol indicado.» cuando el rol está vacío; un rol fuera del
catálogo no genera ese aviso, pero el selector lo muestra como sin elegir. Por eso conviene enviar
siempre un valor del catálogo.

## 10. Estados y flujo del evento

Cada afirmación cita el código que la sostiene.

- **Estados guardados:** `DRAFT`, `PENDING`, `APPROVED`, `REJECTED`, `CAMBIOS`, `INACTIVO`
  (`src/routes/api/admin/eventos/[id]/+server.ts:44`; etiquetas en `src/lib/utils/eventoStatus.ts:10-17`).
- **La ingesta siempre crea en `PENDING`** (`src/routes/api/admin/eventos/ingest/+server.ts:324`).
- **Una actualización por la ingesta no toca `status` ni `evento_codigo`**
  (`ingest/+server.ts:281`, el `update` usa solo `rowCommon`). Consecuencia: un evento ya aprobado que
  el scraper vuelve a enviar se actualiza y sigue aprobado, sin volver a curaduría.
- **Transiciones del curador** (rol `curador` o superadmin, `[id]/+server.ts:626`), tabla en
  `[id]/+server.ts:47-53`:
  - `aprobar`: desde `PENDING` o `CAMBIOS` hacia `APPROVED`.
  - `solicitar_cambios`: desde `PENDING` hacia `CAMBIOS` (el comentario es obligatorio).
  - `rechazar`: desde `PENDING` o `CAMBIOS` hacia `REJECTED`.
  - `desactivar`: desde `APPROVED` hacia `INACTIVO`.
  - `reactivar`: desde `INACTIVO` o `REJECTED` hacia `APPROVED`.
- **Un evento es público solo si está `APPROVED` y fuera de la papelera:** el catálogo público filtra
  `status = APPROVED` y `deleted_at` nulo (`src/lib/server/eventosPublicos.ts:297-298`), igual que la
  ficha por código (`eventosPublicos.ts:353-355`). Su cabecera lo dice: la visibilidad depende
  exclusivamente de la aprobación, no de la fecha (`eventosPublicos.ts:277-283`).
- **`publish_at` ya no condiciona nada público para eventos:** `[id]/+server.ts:649-659` lo indica
  (desde el acuerdo #6 de Frank, 2026-07-27, un evento `APPROVED` con fecha futura es público de
  inmediato). Se sigue guardando solo como marca interna del panel de aprobación, y el cron diario
  `publish-scheduled` (`vercel.json:5`, `0 5 * * *`) lo limpia cuando vence
  (`src/routes/api/cron/publish-scheduled/+server.ts:64-70`). La ingesta no lo escribe ni lo lee.
- **«Finalizado» no es un estado guardado, es derivado:** `esEventoFinalizado`
  (`src/lib/utils/eventoStatus.ts:51-58`) lo calcula como `APPROVED` con `fecha_finalizacion` anterior a
  hoy, o `INACTIVO` siempre; ningún otro estado cuenta como finalizado. «Mis eventos» lo usa en
  `src/routes/dashboard/eventos/mios/+page.svelte:167-169`. La edición administrativa de un evento ya
  terminado por fecha queda solo para el superadmin (`[id]/+server.ts:292-302`).
- **Aprobar un evento de la ingesta no envía correo:** su `contact_email` es el buzón de sistema
  `ingesta@lpdi.co`, que no existe (`[id]/+server.ts:691-695`; `ingest/+server.ts:33`).

## 11. Comportamiento general

- **Upsert** por `(fuente, id_fuente)`: si existe, se actualiza; si no, se crea.
- **Un descarte se respeta.** Si una persona rechazó el evento o lo envió a la papelera, la ingesta lo
  reconoce por `(fuente, id_fuente)` y lo **omite**: no lo actualiza, no lo vuelve a crear y no valida ni
  geocodifica sus datos. La papelera no borra del todo los eventos de la ingesta, así que vale sin límite de
  tiempo. El resultado de ese evento es `status: "omitido"` con `motivo` (por ejemplo `descartado previamente:
  el evento fue rechazado el 2026-10-02. ...`), `estado` y `en_papelera`, y `summary.omitidos` los cuenta:
  lo que se filtra queda a la vista en cada lote.
- **La vuelta atrás es de una persona.** Un curador puede restaurar el evento desde la papelera o reactivar
  un rechazado en el panel de eventos; desde la corrida siguiente se actualiza con normalidad.
- **Un evento desactivado no es un descarte.** Con `estado: "INACTIVO"` sigue actualizándose (`updated`) y
  conserva su estado: está fuera del catálogo público hasta que un curador lo reactive.
- El registrante es la cuenta de sistema; no se crea ningún usuario.
- La respuesta incluye siempre `contrato { version, huella }`.

## 12. Respuesta

```json
{
  "ok": true,
  "fuente": "luma",
  "contrato": { "version": "2026-10-10", "huella": "..." },
  "summary": { "total": 5, "created": 2, "updated": 1, "omitidos": 1, "errors": 1 },
  "results": [
    { "id_fuente": "abc", "status": "created", "evento_id": "uuid", "evento_codigo": "P-CO-800401-26-00011" },
    { "id_fuente": "def", "status": "created", "evento_id": "uuid", "evento_codigo": "P-CO-990099-26-00013",
      "advertencia_tema": "la tematica principal quedo clasificada como \"Otra\" ...", "advertencia_tema_tipo": "otra" },
    { "id_fuente": "ghi", "status": "updated", "evento_id": "uuid", "evento_codigo": "P-CO-999999-26-00012",
      "estado": "PENDING", "en_papelera": false,
      "advertencia_tema": "segmento de tema 999999: ...", "advertencia_tema_tipo": "sin_tematica" },
    { "id_fuente": "jkl", "status": "error", "error": "actividad no reconocida: {\"categoria\":\"x\",\"subcategoria\":\"y\"}" },
    { "id_fuente": "mno", "status": "omitido", "evento_id": "uuid", "evento_codigo": "P-CO-800401-26-00020",
      "estado": "REJECTED", "en_papelera": false,
      "motivo": "descartado previamente: el evento fue rechazado el 2026-10-02. No se actualiza ni se vuelve a crear; un curador puede reactivarlo en el panel de eventos." }
  ]
}
```

Motivos de `error` posibles: `id_fuente requerido`, `nombre requerido`, `fecha_inicio requerida
(YYYY-MM-DD)`, el de horarios fuera de rango, `país no reconocido en el catálogo`, `cada tematica debe traer categoria y subcategoria`, `categoria de
tematica no reconocida`, `subcategoria de tematica no reconocida`, `la subcategoria "x" no pertenece a la categoria "y"`, `modalidad no reconocida`, `costo_inscripcion no reconocido`, `actividad no reconocida` /
`actividades debe ser una lista de { categoria, subcategoria }`, `ubicacion_por_confirmar y
ubicacion_solo_registrados son excluyentes`, y los de la base (`consecutivo: ...`).

## 13. Ejemplo de request

```json
{
  "fuente": "luma",
  "contrato_huella": "<huella del GET .../ingest/contrato>",
  "eventos": [
    {
      "id_fuente": "ev-98211",
      "nombre": "Cumbre de Innovación Abierta 2026",
      "fecha_inicio": "2026-11-12",
      "fecha_finalizacion": "2026-11-12",
      "modalidad": "presencial",
      "pais_code": "Colombia",
      "ciudad": "Medellín",
      "estado_provincia": "Antioquia",
      "ubicacion_texto": "Plaza Mayor, Calle 41 55-80",
      "horarios": [{ "fecha": "2026-11-12", "hora_inicio": "09:00", "hora_fin": "17:00" }],
      "tematicas": [{ "categoria": "innovacion", "subcategoria": "gestion-innovacion", "principal": true }],
      "actividades": [
        { "categoria": "academica", "subcategoria": "conferencia" },
        { "categoria": "networking", "subcategoria": "networking-session" }
      ],
      "organizadores_raw": [{ "nombre": "Ruta N", "rol": "Centro de Innovacion" }],
      "url_fuente": "https://lu.ma/ev-98211"
    }
  ]
}
```

## 14. Checklist para el scraper

- [ ] Al empezar la corrida: `GET .../ingest/contrato`; guardar la `huella` y validar contra sus catálogos.
- [ ] Mandar `contrato_huella` en cada lote; ante `409`, volver a leer el contrato y reenviar.
- [ ] `id_fuente`, `nombre`, `fecha_inicio` presentes en cada evento.
- [ ] `pais_code` resoluble (no `online`); `ciudad` en presenciales.
- [ ] `tematicas` con pares del catálogo (la subcategoría dentro de su categoría); vigilar `advertencia_tema_tipo` en las respuestas.
- [ ] `actividades` como objetos `{ categoria, subcategoria }` del catálogo, nunca textos.
- [ ] `modalidad` y `costo_inscripcion` solo con valores del catálogo (o ausentes).
- [ ] Horarios dentro de las fechas del evento.
- [ ] No mandar «Por confirmar» como dirección.
- [ ] `organizadores_raw[].rol` con un `valor` de `catalogos.roles_organizador` (rol en el ecosistema, no papel en el evento), o vacío.
- [ ] Reintentar solo los eventos con `status: error` tras corregir el motivo (`created` y `updated` son idempotentes por `fuente` + `id_fuente`).

## 15. Registro de cambios

| Fecha | Cambio |
|-------|--------|
| 2026-10-10 | `organizadores_raw[].rol` se aclara: es el rol en el ecosistema de la organización (no su papel en el evento) y su catálogo se publica en `catalogos.roles_organizador`. Un rol vacío o fuera del catálogo no rechaza el evento ni avisa. |
| 2026-10-10 | Un descarte se respeta: el evento rechazado o en la papelera se reconoce por `(fuente, id_fuente)` y se **omite** sin escribir nada; resultado `omitido` con `motivo`, `estado` y `en_papelera`; `summary.omitidos`; la vuelta atrás la hace un curador (restaurar o reactivar). `updated` trae `estado`. |
| 2026-10-10 | Nada entra en silencio: cada ítem de `tematicas` trae `categoria` y `subcategoria` (las dos no vacías); la subcategoría de cada temática debe pertenecer a su categoría (par del catálogo); una modalidad presente fuera del catálogo se rechaza (ausente o vacía sigue siendo `presencial`); `costo_inscripcion` presente debe ser uno de los valores del catálogo. |
| 2026-10-10 | Contrato vivo `GET .../ingest/contrato` con huella; `contrato_huella` en el lote y `409 contrato_desactualizado`; `contrato { version, huella }` en toda respuesta `200`. |
| 2026-10-10 | `actividades` validada como lista de `{ categoria, subcategoria }` del catálogo; el contrato de agosto las mostraba como textos sueltos por error. |
| 2026-10-10 | Aviso de temática «Otra» y campo `advertencia_tema_tipo` (`sin_tematica` u `otra`). El texto del aviso de `999999` no cambió. |
| 2026-10-05 | Los horarios deben estar dentro de `[fecha_inicio, fecha_finalizacion]`. |
| 2026-09-26 | Segmento de tema de 6 dígitos (CC-SS-SS); «sin temática» pasa de `999` a `999999`. |
| 2026-08-24 / 25 | Contrato inicial: validación de temáticas, banderas de ubicación, geocodificación server-side y sincronización de organizadores. |
