Server-Sent Events (SSE)

SSE udostępnia długotrwały strumień tych samych zdarzeń, które otrzymują webhooki. Użyj SSE, gdy wolisz trwałe połączenie od wywołań zwrotnych HTTP.

EndpointKopiuj link do tej sekcji

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

UwierzytelnianieKopiuj link do tej sekcji

SSE używa tego samego uwierzytelniania co pozostałe endpointy API:

• x-api-key - Twój klucz API

ID organizacji znajduje się w ścieżce URL.

Filtrowanie zdarzeńKopiuj link do tej sekcji

Użyj parametru zapytania events, aby filtrować według typu zdarzenia:

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

Użyj events=*, aby otrzymywać wszystkie zdarzenia (tak samo jak przy pominięciu parametru).

Wszystkie zdarzenia, uprawnienie dla każdego zdarzenia i przykładowy payload znajdziesz w indeksie zdarzeń.

Kilka zdarzeń ma własny kanał (logi kontrolerów i I/O kontrolerów). Otrzymasz je tylko z ?channel=controller-logs lub ?channel=controller-io; indeks zdarzeń podaje kanał.

Tillor dostarcza tylko zdarzenia, do których zalogowany członek organizacji ma uprawnienie. Bez bank-transactions:read (lub sync) nie dostaniesz na przykład zdarzeń bankAccountTransaction:*, także gdy nie wysyłasz filtra events.

Powiązane dane z innej domeny podlegają tym samym regułom co API: bez customers:read zdarzenie reservation:updated przychodzi z customer: null, bez payments:read zdarzenie invoice:paid przychodzi z payment: null. Lista staje się wtedy [].

Format zdarzeniaKopiuj link do tej sekcji

Payload ma taką samą strukturę jak dostarczenia webhooków:

W strumieniu SSE ten obiekt JSON znajduje się w wierszu data:; klucz zdarzenia jest też w wierszu event:. Przykład na poziomie protokołu znajdziesz w przykładach SSE.

Przykład: Node.jsKopiuj link do tej sekcji

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

Przykład: cURLKopiuj link do tej sekcji

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

Ponowne łączenieKopiuj link do tej sekcji

Gdy połączenie zostanie przerwane, połącz się ponownie z tym samym URL i nagłówkami. Strumień nie obsługuje wznawiania; po ponownym połączeniu otrzymujesz tylko nowe zdarzenia.

PowiązaneKopiuj link do tej sekcji

• OpenAPI - Pełna specyfikacja API
• HTTP API - Klucze API i uwierzytelnianie
• Webhooki - Te same zdarzenia przez HTTP POST
• Przykłady - Przykłady kodu i payloadów