Eventos

Cada hecho económico de una cuadra tiene su evento (un objeto event): se crea un cargo, se hace una corrección, llega un cobro, se emite o se anula un recibo, cambian los datos de un cliente. Los eventos los escribe la base de datos en la misma transacción que el hecho, y se numeran en el orden en que se hacen visibles.

GET /events?after=<cursor>&limit=100

La garantía

Si un evento es visible, todos los eventos anteriores de la misma cuadra ya son visibles, o no existirán nunca.

Así, leer «todo lo que viene después de mi cursor» nunca se salta nada: ningún evento anterior puede aparecer más tarde. Puede haber huecos en la numeración (una transacción cancelada), y son inofensivos, porque nunca pides «el número siguiente».

Cómo leer

1. La primera vez, llama a GET /events sin after: empiezas desde el primer evento de la cuadra, historia incluida.
2. Procesa cada evento en orden: lee el objeto al que apunta (data.url) y haz tu trabajo.
3. Cuando la página esté procesada, guarda next_cursor.
4. Llama de nuevo con after=<next_cursor>. Repite mientras has_more sea true; cuando sea false, espera y vuelve a preguntar más tarde (por ejemplo, cada pocos minutos).

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "6f1d1e0c-…",
      "type": "adjustment.created",
      "data": { "object": "adjustment", "id": "8d0c2f6e-…", "url": "/api/v1/adjustments/8d0c2f6e-…" },
      "occurred_at": "2026-12-05T09:14:03.512Z",
      "recorded_at": "2026-12-05T09:14:03.540Z",
      "historical": false
    }
  ],
  "has_more": false,
  "next_cursor": "6f1d1e0c-…"
}

• Los eventos son ligeros: dicen qué objeto se creó o cambió, nunca los importes. Lee el objeto.
• Al menos una vez: tras una interrupción vuelves a empezar desde el último cursor guardado, y puede que leas una página dos veces. Procesar de nuevo un evento no hace daño — apunta a un hecho que no cambia, o a los datos actuales de un cliente — y el id del evento te permite reconocer los que ya procesaste. Los id de los eventos son únicos entre todas las cuadras.
• next_cursor puede ser el id de un evento que no se te muestra: guárdalo siempre tal cual.
• has_more: true con menos de limit eventos — incluso ninguno — significa que algunos eventos no eran para ti y el registro sigue: vuelve a preguntar.
• Un cursor que no es un evento de esta cuadra es un 400 en after.

Tipos de evento

Cada evento se muestra solo con el permiso del objeto al que apunta. Solo se muestra el lado por cobrar, es decir, lo que los clientes deben a la cuadra, pagado o no: los pagos al personal nunca aparecen. No existe customer.created: un cliente nace con su primer cargo, y charge.created lleva su customer_id. La lista de tipos es abierta: acepta un tipo que aún no conozcas. Los nombres en cada idioma están en /codes (event_type).

Si tu clave obtiene un permiso nuevo, los eventos que antes no veía están detrás de tu cursor: vuelve a leer desde el principio (sin after) para obtenerlos.

La historia

Cuando una cuadra empieza a usar la API, toda su historia ya está en el registro: los eventos de hechos anteriores llevan historical: true, están ordenados por la fecha del hecho y van antes que cualquier evento del presente. occurred_at es siempre la fecha del hecho; recorded_at es cuándo se escribió el evento.

Mientras se carga la historia de una cuadra, /events responde 503 con type: …/events-not-ready y Retry-After. Tarda unos segundos.

Un solo evento

GET /events/{id} devuelve un evento, con las mismas reglas. Un evento de otra cuadra, de un tipo que tu clave no puede leer, o que no existe: 404.