Server-Sent Events (SSE)

SSE bietet einen langlaufenden Stream derselben Events, die Webhooks erhalten. Verwenden Sie SSE, wenn Sie eine dauerhafte Verbindung HTTP-Callbacks vorziehen.

EndpunktLink zu diesem Abschnitt kopieren

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

AuthentifizierungLink zu diesem Abschnitt kopieren

SSE verwendet dieselbe Authentifizierung wie die anderen API-Endpunkte:

• x-api-key - Ihr API-Schlüssel

Die Organisations-ID steht im Pfad der URL.

Event-FilterungLink zu diesem Abschnitt kopieren

Verwenden Sie den Query-Parameter events, um nach Event-Typ zu filtern:

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

Verwenden Sie events=*, um alle Events zu erhalten (wie wenn Sie den Parameter weglassen).

Alle Events, die Berechtigung pro Event und eine Beispiel-Payload finden Sie im Event-Index.

Einige Events liegen auf einem eigenen Kanal (Controller-Logs und Controller-I/O). Diese erhalten Sie nur mit ?channel=controller-logs oder ?channel=controller-io; der Event-Index nennt den Kanal.

Tillor liefert nur Events, für die das angemeldete Organisationsmitglied die Berechtigung hat. Ohne bank-transactions:read (oder Sync) erhalten Sie zum Beispiel keine bankAccountTransaction:*-Events, auch nicht, wenn Sie keinen events-Filter mitsenden.

Verknüpfte Daten aus einem anderen Bereich folgen denselben Regeln wie die API: Ohne customers:read kommt ein reservation:updated mit customer: null an, ohne payments:read ein invoice:paid mit payment: null. Eine Liste wird dann zu [].

Event-FormatLink zu diesem Abschnitt kopieren

Die Payload hat dieselbe Struktur wie Webhook-Zustellungen:

Im SSE-Stream steht dieses JSON-Objekt auf der data:-Zeile; der Event-Key steht auch auf der event:-Zeile. Ein Beispiel auf Protokollebene finden Sie unter SSE-Beispiele.

Beispiel: Node.jsLink zu diesem Abschnitt kopieren

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);
    }
  }
}

Beispiel: cURLLink zu diesem Abschnitt kopieren

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

WiederverbindenLink zu diesem Abschnitt kopieren

Wenn die Verbindung abbricht, verbinden Sie sich mit derselben URL und denselben Headern erneut. Der Stream unterstützt kein Wiederaufsetzen; nach dem Wiederverbinden erhalten Sie nur neue Events.

VerwandtLink zu diesem Abschnitt kopieren

• OpenAPI - Vollständige API-Spezifikation
• HTTP API - API-Schlüssel und Authentifizierung
• Webhooks - Dieselben Events über HTTP POST
• Beispiele - Code- und Payload-Beispiele