Eventos
Crea, actualiza y cancela los eventos de tu empresa. Lo recomendable es el upsert por externalId: idempotente y sin duplicados.
Rutas
| Ruta | Scope | Qué hace |
|---|---|---|
GET /v1/events | events:read | Eventos que no han terminado. Filtros: from, to (ISO), status (published o cancelled), branchId, q, limit (máx. 100, por defecto 50), offset |
PUT /v1/events/external/:source/:externalId | events:write | Upsert: crea (201) o actualiza (200) |
GET /v1/events/external/:source/:externalId | events:read | Evento por tu id |
DELETE /v1/events/external/:source/:externalId | events:write | Cancela por tu id |
POST /v1/events | events:write | Crea. Acepta externalId y source; 409 si ya existen |
PATCH /v1/events/:id | events:write | Cambia solo los campos que mandes |
DELETE /v1/events/:id | events:write | Cancela (no borra) |
POST /v1/uploads | events:write | Sube un póster (multipart file) |
Las respuestas son { "event": EventDTO } o { "events": [EventDTO] }.
Campos obligatorios
| Campo | Regla |
|---|---|
title | 3 a 120 caracteres |
startsAt | ISO 8601 (ver zonas horarias) |
categories | 1 a 3 categorías de la lista. También vale category con una sola |
| Ubicación | Una de estas: branchId (se copia el lugar de la sede); venueName + address (se geocodifica la dirección); o venueName + address + lat + lng |
| Precio | "isFree": true sin precios, o "isFree": false con prices (y currency, por defecto la del país) |
Campos opcionales
| Campo | Notas |
|---|---|
description | Hasta 5000 caracteres |
endsAt | Por defecto startsAt + 3 h. null = sin fin |
prices | [{ "name": "General", "priceCents": 1850, "capacity": 100 }], hasta 10. Importes en unidad menor de la moneda |
currency | ISO 4217 (EUR, COP, USD…). Por defecto la del país |
country | ISO 3166-1 (ES, CO…). Por defecto el de la sede o la empresa |
timezone | IANA (Europe/Madrid). Por defecto, la del lugar |
capacity | Aforo total. Sin él, sin límite |
subcategory | Slug de una subcategoría de la categoría principal (la primera de categories), de `GET /api/categories`. Otra cosa: 422. null la quita |
posterUrl / posterKey | Póster por URL o subido (ver abajo) |
ticketUrl | Venta externa (ver abajo) |
externalId, source | Tu id del evento y su origen |
Si falta un dato obligatorio o tiene mal formato la respuesta es 422; si incumple una regla (de pago sin precios, fin antes del inicio, cupo de un precio mayor que el aforo), 400.
Upsert por externalId
PUT /v1/events/external/:source/:externalId es la forma recomendada de sincronizar tu sistema con Remolom:
externalIdes el id del evento en tu sistema (hasta 200 caracteres).sourceidentifica de dónde viene (hasta 50 caracteres):mi-web,taquilla,wordpress… Así el mismo id en dos sistemas no choca.- Si no existe, se crea y responde 201. Si existe, se actualiza y responde 200. Si estaba cancelado, se reactiva.
- Al actualizar, los precios con el mismo nombre conservan su id y sus ventas.
- Manda siempre el evento completo: es lo más sencillo y evita estados a medias.
curl -X PUT https://remolom.com/api/v1/events/external/taquilla/obra-123 \
-H "Authorization: Bearer $REMOLOM_KEY" -H "Content-Type: application/json" \
-d '{
"title": "La vida es sueño",
"categories": ["cultura"],
"startsAt": "2026-12-12T20:30",
"branchId": "8a6f1c2e-…",
"isFree": false,
"prices": [{ "name": "Platea", "priceCents": 2500 }, { "name": "Anfiteatro", "priceCents": 1500 }],
"posterUrl": "https://mi-web.com/img/vida-es-sueno.jpg"
}'async function upsert(source, externalId, event) {
const res = await fetch(`https://remolom.com/api/v1/events/external/${source}/${encodeURIComponent(externalId)}`, {
method: 'PUT',
headers: { Authorization: `Bearer ${process.env.REMOLOM_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(event),
})
const body = await res.json()
if (!res.ok) throw new Error(`${res.status} ${body.error}`)
return body.event
}import os, requests
from urllib.parse import quote
def upsert(source: str, external_id: str, event: dict) -> dict:
r = requests.put(
f"https://remolom.com/api/v1/events/external/{source}/{quote(external_id, safe='')}",
headers={"Authorization": f"Bearer {os.environ['REMOLOM_KEY']}"},
json=event,
)
if not r.ok:
raise RuntimeError(f"{r.status_code} {r.json()['error']}")
return r.json()["event"]POST /v1/events también acepta externalId y source (por defecto "default"), pero devuelve 409 si ya existen: úsalo solo si quieres que falle ante un duplicado.
Pósters
Dos formas:
- Por URL: manda
posterUrl. Remolom descarga la imagen (JPG, PNG o WebP, hasta 10 MB) y la guarda. Si la URL no cambia, no se vuelve a descargar."posterUrl": nullquita el póster. Si la descarga falla: 422No se pudo descargar el póster: …. - Subida:
POST /v1/uploadscon el archivo en el campofile(multipart, hasta 10 MB). Devuelve{ posterKey, url }; manda eseposterKeyen el evento.
curl -X POST https://remolom.com/api/v1/uploads \
-H "Authorization: Bearer $REMOLOM_KEY" -F [email protected]
# { "posterKey": "…", "url": "https://media.remolom.com/…" }Venta de entradas externa (ticketUrl)
Si vendes las entradas en tu web o en otra plataforma, manda ticketUrl (solo https://, hasta 500 caracteres). La ficha del evento muestra el botón Comprar entradas con ese enlace y la venta en Remolom se desactiva ("sales": null en el EventDTO). Sin ticketUrl, un evento de pago se vende en Remolom.
Zonas horarias
- Con offset o `Z` (
2026-12-05T21:00:00+01:00,2026-12-05T20:00:00Z): es un instante exacto. - Sin offset (
2026-12-05T21:00): es la hora local del lugar del evento. Es lo más cómodo: manda la hora que pone en el cartel. - La zona del evento es
timezonesi la mandas (IANA, por ejemploAmerica/Bogota); si no, la del país del lugar (Canarias se detecta por coordenadas). - La API siempre devuelve las fechas en UTC (
…Z) y el EventDTO traetimezonepara mostrarlas en hora local.
Categorías
| Slug | Para |
|---|---|
musica | Música: conciertos, festivales, DJ |
cultura | Cultura: teatro, cine, museos, exposiciones |
gastronomia | Gastronomía: catas, mercados, menús |
standup | Stand-up y comedia |
ferias | Ferias y mercadillos |
ocio | Ocio, fiestas y quedadas |
deporte | Deporte: partidos, carreras, torneos |
Subcategorías
Cada categoría tiene subcategorías (jazz, teatro, fútbol…) que mantiene Remolom. La lista es pública, sin clave:
curl https://remolom.com/api/categories{ "categories": [
{ "slug": "musica", "subcategories": [{ "slug": "jazz", "name": { "es": "Jazz", "en": "Jazz", "pt-BR": "Jazz", "fr": "Jazz" } }] }
] }subcategorylleva elslugy debe ser de la categoría principal del evento; si no, la respuesta es 422.- Si al editar cambias la categoría principal sin mandar
subcategory, se quita la que ya no encaja. - El EventDTO trae
subcategory(slug) ysubcategoryName(nombre por idioma; si falta uno, usaes).
EventDTO
{
"event": {
"id": "3f0b…", "title": "Concierto de jazz", "description": "",
"category": "musica", "categories": ["musica"], "subcategory": null, "subcategoryName": null,
"isFree": false, "priceCents": 1850, "currency": "EUR", "country": "ES",
"prices": [{ "id": "…", "name": "General", "priceCents": 1850, "capacity": null, "remaining": null, "soldOut": false }],
"timezone": "Europe/Madrid",
"startsAt": "2026-12-05T20:00:00.000Z", "endsAt": "2026-12-05T23:00:00.000Z",
"venueName": "Sala Clamores", "address": "Calle Alburquerque 14, Madrid", "lat": 40.4316, "lng": -3.7003,
"posterUrl": "https://media.remolom.com/…",
"status": "published", "sales": null, "ticketUrl": "https://mi-web.com/entradas/jazz",
"externalId": "jazz-2026-12-05", "source": "mi-web", "test": false,
"createdAt": "2026-11-14T10:00:00.000Z"
}
}El EventDTO trae más campos (empresa, sede, aforo restante…). La lista completa está en el OpenAPI.