Eventos

Crea, actualiza y cancela los eventos de tu empresa. Lo recomendable es el upsert por externalId: idempotente y sin duplicados.

Rutas

RutaScopeQué hace
GET /v1/eventsevents:readEventos 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/:externalIdevents:writeUpsert: crea (201) o actualiza (200)
GET /v1/events/external/:source/:externalIdevents:readEvento por tu id
DELETE /v1/events/external/:source/:externalIdevents:writeCancela por tu id
POST /v1/eventsevents:writeCrea. Acepta externalId y source; 409 si ya existen
PATCH /v1/events/:idevents:writeCambia solo los campos que mandes
DELETE /v1/events/:idevents:writeCancela (no borra)
POST /v1/uploadsevents:writeSube un póster (multipart file)

Las respuestas son { "event": EventDTO } o { "events": [EventDTO] }.

Campos obligatorios

CampoRegla
title3 a 120 caracteres
startsAtISO 8601 (ver zonas horarias)
categories1 a 3 categorías de la lista. También vale category con una sola
UbicaciónUna 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

CampoNotas
descriptionHasta 5000 caracteres
endsAtPor defecto startsAt + 3 h. null = sin fin
prices[{ "name": "General", "priceCents": 1850, "capacity": 100 }], hasta 10. Importes en unidad menor de la moneda
currencyISO 4217 (EUR, COP, USD…). Por defecto la del país
countryISO 3166-1 (ES, CO…). Por defecto el de la sede o la empresa
timezoneIANA (Europe/Madrid). Por defecto, la del lugar
capacityAforo total. Sin él, sin límite
subcategorySlug de una subcategoría de la categoría principal (la primera de categories), de `GET /api/categories`. Otra cosa: 422. null la quita
posterUrl / posterKeyPóster por URL o subido (ver abajo)
ticketUrlVenta externa (ver abajo)
externalId, sourceTu 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:

bash
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"
  }'
js
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
}
python
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:

bash
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

Categorías

SlugPara
musicaMúsica: conciertos, festivales, DJ
culturaCultura: teatro, cine, museos, exposiciones
gastronomiaGastronomía: catas, mercados, menús
standupStand-up y comedia
feriasFerias y mercadillos
ocioOcio, fiestas y quedadas
deporteDeporte: 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:

bash
curl https://remolom.com/api/categories
json
{ "categories": [
  { "slug": "musica", "subcategories": [{ "slug": "jazz", "name": { "es": "Jazz", "en": "Jazz", "pt-BR": "Jazz", "fr": "Jazz" } }] }
] }

EventDTO

json
{
  "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.