Server-Sent Events (SSE)

SSE ofrece un flujo de larga duración con los mismos eventos que reciben los webhooks. Usa SSE si prefieres una conexión persistente a las llamadas HTTP de retorno.

EndpointCopiar el enlace a esta sección

GET /api/orgs/:orgId/realtime/subscribe

AutenticaciónCopiar el enlace a esta sección

SSE usa la misma autenticación que los demás endpoints de la API:

• x-api-key - Tu clave de API

El ID de la organización va en la ruta de la URL.

Filtrado de eventosCopiar el enlace a esta sección

Usa el parámetro de consulta events para filtrar por tipo de evento:

GET /api/orgs/:orgId/realtime/subscribe?events=invoice:created&events=invoice:paid

Usa events=* para recibir todos los eventos (igual que omitir el parámetro).

Consulta el índice de eventos para ver todos los eventos, el permiso de cada uno y un ejemplo de payload.

Unos pocos eventos tienen su propio canal (logs del controlador y E/S del controlador). Solo los recibes con ?channel=controller-logs o ?channel=controller-io; el índice de eventos indica el canal.

Tillor solo entrega eventos para los que el miembro de la organización con sesión iniciada tiene permiso. Sin bank-transactions:read (o sync), por ejemplo, no recibes eventos bankAccountTransaction:*, ni siquiera si no envías ningún filtro events.

Los datos vinculados de otro dominio siguen las mismas reglas que la API: sin customers:read llega un reservation:updated con customer: null, y sin payments:read un invoice:paid con payment: null. Una lista pasa entonces a ser [].

Formato del eventoCopiar el enlace a esta sección

El payload tiene la misma estructura que las entregas de webhook:

En el flujo SSE, este objeto JSON va en la línea data:; la clave del evento también va en la línea event:. Consulta los ejemplos de SSE para un ejemplo en el cable.

Ejemplo: Node.jsCopiar el enlace a esta sección

const orgId = "org_abc123";
const apiKey = "tkn_xxx";

const url = `https://app.tillor.eu/api/orgs/${orgId}/realtime/subscribe?events=invoice:created&events=customer:updated`;

const response = await fetch(url, {
  headers: {
    "x-api-key": apiKey,
    "Accept": "text/event-stream",
  },
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  for (const line of chunk.split("\n")) {
    if (line.startsWith("data: ")) {
      const payload = JSON.parse(line.slice(6));
      console.log(payload.event, payload.data);
    }
  }
}

Ejemplo: cURLCopiar el enlace a esta sección

curl -N -H "x-api-key: tkn_xxx" \
     -H "Accept: text/event-stream" \
     "https://app.tillor.eu/api/orgs/org_abc123/realtime/subscribe"

ReconexiónCopiar el enlace a esta sección

Si la conexión se interrumpe, vuelve a conectarte con la misma URL y los mismos encabezados. El flujo no admite reanudación; después de reconectar solo recibes eventos nuevos.

RelacionadoCopiar el enlace a esta sección

• OpenAPI - especificación completa de la API
• API HTTP - claves de API y autenticación
• Webhooks - los mismos eventos mediante HTTP POST
• Ejemplos - ejemplos de código y de payload