Server-Sent Events (SSE)

SSE oferă un flux de lungă durată cu aceleași evenimente pe care le primesc webhookurile. Folosiți SSE când preferați o conexiune persistentă în locul apelurilor HTTP inverse.

EndpointCopiază linkul către această secțiune

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

AutentificareCopiază linkul către această secțiune

SSE folosește aceeași autentificare ca celelalte endpointuri API:

• x-api-key - cheia dumneavoastră API

ID-ul organizației se află în calea URL-ului.

Filtrarea evenimentelorCopiază linkul către această secțiune

Folosiți parametrul de interogare events pentru a filtra după tipul evenimentului:

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

Folosiți events=* pentru a primi toate evenimentele (la fel ca omiterea parametrului).

Consultați Indexul de evenimente pentru toate evenimentele, permisiunea pentru fiecare eveniment și un exemplu de payload.

Câteva evenimente se află pe un canal propriu (jurnalele controlerelor și I/O al controlerelor). Le primiți doar cu ?channel=controller-logs sau ?channel=controller-io; Indexul de evenimente menționează canalul.

Tillor livrează doar evenimentele pentru care membrul autentificat al organizației are permisiune. Fără bank-transactions:read (sau sync) nu primiți, de exemplu, evenimente bankAccountTransaction:*, nici dacă nu trimiteți niciun filtru events.

Datele asociate dintr-un alt domeniu urmează aceleași reguli ca API-ul: fără customers:read, un reservation:updated sosește cu customer: null, iar fără payments:read, un invoice:paid cu payment: null. O listă devine atunci [].

Formatul evenimentuluiCopiază linkul către această secțiune

Payloadul are aceeași structură ca livrările webhook:

În fluxul SSE, acest obiect JSON se află pe linia data:; cheia evenimentului se află și pe linia event:. Consultați exemplele SSE pentru un exemplu la nivel de rețea.

Exemplu: Node.jsCopiază linkul către această secțiune

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

Exemplu: cURLCopiază linkul către această secțiune

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

ReconectareCopiază linkul către această secțiune

Dacă se pierde conexiunea, reconectați-vă cu același URL și aceleași antete. Fluxul nu acceptă reluarea; după reconectare primiți doar evenimente noi.

Legate de acest subiectCopiază linkul către această secțiune

• OpenAPI - specificația completă a API-ului
• API HTTP - chei API și autentificare
• Webhookuri - aceleași evenimente prin HTTP POST
• Exemple - exemple de cod și de payload