---
name: remolom-api
description: Integrar Remolom (red social de eventos geolocalizada): publicar o sincronizar eventos por API REST o feeds, recibir webhooks firmados de eventos y entradas, conectar una plataforma por OAuth con PKCE o usar el MCP. Úsala cuando el usuario quiera publicar eventos en Remolom desde su web, CMS, ticketing o agenda, leer entradas vendidas, verificar webhooks de Remolom o depurar errores de la API de Remolom.
---

# Integrar la API de Remolom

Base: `https://remolom.com/api/v1`. JSON. Cabecera `Authorization: Bearer <token>`. Errores: `{ "error": "mensaje" }` con código HTTP estable. Documentación completa: https://remolom.com/llms-full.txt · OpenAPI: https://remolom.com/api/v1/openapi.json

## Elige el camino

- **Una empresa publica sus propios eventos** → clave de API (`rk_live_…`) creada en https://remolom.com/dashboard/company?tab=integrations. Va en el servidor, nunca en el navegador.
- **Una plataforma publica para muchas empresas** → OAuth authorization code + PKCE S256. Ver [oauth.md](oauth.md).
- **La agenda ya existe en iCal, CSV o una web con schema.org/Event** → feed en el panel (Mi empresa → Importar → Sincronización automática). Sin código. CSV con columna `id`; iCal con `UID`.
- **El usuario quiere hablarle a un asistente** → MCP en `https://remolom.com/api/mcp` con la misma cabecera.

## Publicar eventos: usa siempre el upsert

`PUT /v1/events/external/:source/:externalId` crea (201) o actualiza (200). Idempotente: reintentar no duplica. Si estaba cancelado, lo reactiva. `source` = sistema de origen (`mi-web`), `externalId` = id del evento en ese sistema (URL-encode). Manda el evento completo cada vez.

No uses `POST /v1/events` para sincronizar: da 409 si el `externalId` ya existe.

Campos obligatorios (detalle en [eventos.md](eventos.md)):
- `title` (3–120)
- `startsAt` ISO 8601. **Sin offset = hora local del lugar** (`2026-12-05T21:00`), lo normal.
- `categories`: 1–3 de `musica`, `cultura`, `gastronomia`, `standup`, `ferias`, `ocio`, `deporte` (o `category` con una).
- Ubicación: `branchId` (de `GET /v1/branches`), o `venueName` + `address` (se geocodifica), o ambos + `lat` + `lng`.
- Precio: `"isFree": true`, o `"isFree": false` + `prices: [{ "name": "General", "priceCents": 1850 }]`. **Importes en unidad menor** (EUR 1850 = 18,50 €; COP 15000 = 15.000). `currency` por defecto la del país.

Opcionales útiles: `endsAt` (por defecto +3 h), `posterUrl` (se descarga; JPG/PNG/WebP ≤ 10 MB), `ticketUrl` (https; venta externa, desactiva la venta en Remolom), `timezone` (IANA), `description`, `capacity`.

Cancelar: `DELETE /v1/events/external/:source/:externalId` (cancela, no borra).

## Probar sin riesgo: claves rk_test_

Crea la clave en modo **Prueba** (`rk_test_…`). Sus eventos llevan `"test": true`, no son públicos y se borran a los 7 días. Una clave test solo ve eventos test (y una live solo reales): un evento del otro modo da 404. Webhooks en modo Prueba reciben solo sucesos test. Recomienda empezar siempre así.

## Webhooks

`POST` a la URL del cliente con `Remolom-Signature: t=<unix>,v1=<hex>`. Verificar: `hex(hmac_sha256(secret_whsec, t + "." + cuerpo_crudo))`, comparación en tiempo constante, rechazar si `t` tiene más de 5 min. **Firmar el cuerpo crudo, antes de parsear JSON** (en Express: `express.raw`). Deduplicar por `id` del cuerpo. Responder 2xx en < 10 s. Código en Node, Python y PHP y payloads en [webhooks.md](webhooks.md).

## Errores comunes

| Síntoma | Causa | Arreglo |
|---|---|---|
| 401 | Falta `Bearer`, clave revocada, o quien la creó ya no es owner/admin | Revisar cabecera o crear otra clave |
| 403 `La clave no tiene el permiso events:write` | Clave de solo lectura | Crear clave con "Puede crear, editar y cancelar eventos" |
| 404 en un evento que existe | Es de otra empresa o del otro modo (live/test) | Usar la clave del mismo modo |
| 400 `prices es obligatorio si el evento no es gratis` | `isFree: false` sin `prices` | Añadir `prices` o `isFree: true` |
| 400 `Un evento gratis no lleva precios` | `isFree: true` con `prices` | Quitar `prices` |
| 422 `No encontramos esa dirección` | Dirección no geocodificable | Mandar `lat`/`lng` o `branchId` |
| 422 `No se pudo descargar el póster` | URL privada, no imagen o > 10 MB | URL pública o `POST /v1/uploads` |
| 409 en `POST /v1/events` | `externalId` repetido | Usar `PUT /v1/events/external/…` |
| Precio x100 mal | Importes en unidades normales | Convertir a unidad menor según la moneda |
| Hora desplazada | Mandó `Z` con la hora del cartel | Mandar sin offset (hora local) |
| Firma de webhook no valida | Se firmó el JSON re-serializado | Usar el cuerpo crudo |
| 429 | Más de 60 peticiones/min por clave | Backoff exponencial |
