Documentación

Visión general

La integración API de Ciudad Viva es un sistema de extracción automática (pull): Ciudad Viva consulta periódicamente tu API, obtiene los eventos y los publica en la plataforma. Tu sistema no necesita saber que Ciudad Viva existe ni enviar nada por iniciativa propia.

Cómo funciona

El proceso tiene dos actores: tu sistema (que ya existe y no cambia) y Ciudad Viva (que lo consulta).

Requisitos de tu API

Tu API puede tener cualquier estructura, siempre que cumpla estos requisitos básicos:

• ✓Responde con JSON (Content-Type: application/json).
• ✓Devuelve un array de eventos, ya sea en la raíz de la respuesta o dentro de algún campo.
• ✓Cada evento tiene al menos un título y una fecha de inicio.
• ✓La URL es accesible desde internet (no puede ser localhost ni una red interna privada).
• ✓Acepta GET o POST como método HTTP.

Configuración paso a paso

Accede al panel de tu organización en Ciudad Viva y sigue estos pasos:

1. 1

   Ve a Mi organización → Integraciones → Nueva integración.

2. 2

   Ingresa un nombre descriptivo (ej: "API de eventos municipales").

3. 3

   Ingresa la URL de tu API.

4. 4

   Selecciona el método HTTP (GET o POST).

5. 5

   Si tu API devuelve los eventos dentro de un campo (ej: data.results), ingresa esa ruta en Ruta al array de eventos. Si el array está en la raíz, deja este campo vacío.

6. 6

   Configura la autenticación si tu API lo requiere (ver sección Autenticación).

7. 7

   Configura el mapeo de campos indicando qué campo de tu API corresponde a cada campo de Ciudad Viva (ver sección Mapeo de campos).

8. 8

   Haz clic en Probar conexión para verificar que todo funciona.

9. 9

   Si la prueba es exitosa, haz clic en Activar.

Autenticación

Ciudad Viva soporta cuatro métodos de autenticación. Elige el que usa tu API. Las credenciales se almacenan cifradas con AES-256-GCM y nunca se exponen en logs ni respuestas.

{
  "auth": {
    "type": "none"
  }
}

{
  "auth": {
    "type": "api_key",
    "apiKeyHeader": "X-API-Key",
    "apiKey": "tu-clave-secreta"
  }
}

{
  "auth": {
    "type": "bearer",
    "bearerToken": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

{
  "auth": {
    "type": "basic",
    "basicUsername": "mi-usuario",
    "basicPassword": "mi-contraseña"
  }
}

Formato de respuesta

Tu API puede devolver los eventos en cualquiera de estas estructuras. El campo Ruta al array le indica a Ciudad Viva dónde encontrar el array de eventos.

[
  {
    "title": "Festival de Verano",
    "date": "2026-02-15",
    "location": "Parque O'Higgins"
  },
  {
    "title": "Obra de Teatro",
    "date": "2026-02-20",
    "location": "Teatro Municipal"
  }
]

{
  "status": "ok",
  "total": 2,
  "events": [
    {
      "title": "Festival de Verano",
      "date": "2026-02-15"
    }
  ]
}

{
  "meta": { "page": 1 },
  "data": {
    "results": [
      {
        "content": {
          "title": "Festival de Verano",
          "start": "2026-02-15T20:00:00"
        }
      }
    ]
  }
}

Mapeo de campos

El mapeo le dice a Ciudad Viva qué campo de tu API corresponde a cada campo de la plataforma. Puedes usar notación de punto para acceder a campos anidados (ej: content.title, meta.date.start).

{
  "fieldMap": {
    "title": "content.name",
    "startDate": "meta.startAt",
    "endDate": "meta.endAt",
    "description": "content.body",
    "imageUrl": "content.coverImage",
    "venue": "location.name",
    "address": "location.address",
    "district": "location.commune",
    "price": "ticket.description",
    "eventUrl": "permalink",
    "externalId": "id"
  }
}

Prueba de conexión

Antes de activar la integración, puedes probar la conexión desde el formulario de configuración. Ciudad Viva consultará tu API en ese momento y mostrará:

• →El código HTTP de respuesta de tu API.
• →Cuántos eventos encontró en la respuesta.
• →Una vista previa de los primeros 3 eventos con el mapeo aplicado.
• →El mensaje de error si algo falla (URL incorrecta, autenticación rechazada, campo no encontrado, etc.).

Solo puedes activar la integración si la prueba de conexión fue exitosa. Si modificas la configuración después de activarla, la integración vuelve a estado borrador y deberás probarla nuevamente.

Webhook (opcional)

Además de la sincronización diaria automática, puedes configurar un webhook para que Ciudad Viva sincronice tus eventos en el momento en que tú lo necesites. Cuando creas un nuevo evento en tu sistema, tu sistema puede notificar a Ciudad Viva inmediatamente y el evento aparecerá en la plataforma sin esperar hasta el día siguiente.

https://server.ciudad-viva.cl/api/webhooks/{tu-webhook-key}

curl -X POST \
  "https://server.ciudad-viva.cl/api/webhooks/{tu-webhook-key}"

# Respuesta exitosa (HTTP 202):
{ "queued": true }

# Si superas el límite:
HTTP 429 Too Many Requests
{ "error": "rate_limit_exceeded", "retryAfterMs": 8500 }

Sincronización

Cada sincronización sigue este proceso:

Próximamente