# Eventos (referencia)

## Rutas (scope)
- `GET /v1/events?from&to&status&branchId&q&limit(≤100)&offset` (`events:read`) → `{ events: EventDTO[] }`, los que no han terminado.
- `PUT /v1/events/external/:source/:externalId` (`events:write`) → 201 creado / 200 actualizado, `{ event }`.
- `GET` (`events:read`) y `DELETE` (`events:write`, cancela) en la misma ruta.
- `POST /v1/events` (409 si el externalId ya existe) · `PATCH /v1/events/:id` (solo lo que cambia) · `DELETE /v1/events/:id` (cancela).
- `POST /v1/uploads` multipart `file` (≤ 10 MB) → `{ posterKey, url }`; luego `posterKey` en el evento.
- `GET /v1/branches` (`events:read`) → `{ branches: [{ id, name, address, city, country, lat, lng }] }`.
- `GET /v1/events/:id/tickets?status=valid|checked_in|voided&limit(≤500)` y `GET /v1/events/:id/stats` (`tickets:read`).

## Cuerpo
```json
{
  "title": "Concierto de jazz",
  "categories": ["musica"],
  "startsAt": "2026-12-05T21:00",
  "endsAt": "2026-12-05T23:30",
  "branchId": "8a6f1c2e-…",
  "isFree": false,
  "prices": [{ "name": "General", "priceCents": 1850, "capacity": 200 }],
  "currency": "EUR",
  "posterUrl": "https://mi-web.com/img/jazz.jpg",
  "ticketUrl": "https://mi-web.com/entradas/jazz",
  "description": "Trío en directo"
}
```

- Sin `branchId`: `venueName` + `address` (se geocodifica) o + `lat` + `lng`. Con `branchId` el lugar se copia de la sede (lo que mandes gana).
- `country` ISO 3166-1, `currency` ISO 4217 (por defecto la del país), `timezone` IANA (por defecto la del lugar).
- Fechas: con offset/`Z` = instante; sin offset = hora local del evento. Respuesta siempre en UTC + `timezone`.
- `posterUrl` igual que la última vez → no se vuelve a descargar. `posterUrl: null` quita el póster.
- `ticketUrl` presente → `sales: null` en el DTO (venta externa, botón «Comprar entradas»).
- Al actualizar, precios con el mismo `name` conservan id y ventas. Quitar un precio con ventas → 409.

## Ejemplo Node
```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 // res.status 201 = creado, 200 = actualizado
}
```

## Ejemplo Python
```python
import os, requests
from urllib.parse import quote

def upsert(source, external_id, event):
    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"]
```

## Sincronizar un catálogo
1. Para cada evento del sistema origen: `upsert(source, id, evento)`.
2. Para los que desaparecieron: `DELETE /v1/events/external/:source/:id`.
3. Respetar 60 peticiones/min: en lotes grandes, espaciar o reintentar 429 con backoff.
