Server-Sent Events (SSE)

Le SSE fournit un flux de longue durée des mêmes événements que ceux reçus par les webhooks. Utilisez le SSE si vous préférez une connexion persistante aux rappels HTTP.

EndpointCopier le lien vers cette section

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

AuthentificationCopier le lien vers cette section

Le SSE utilise la même authentification que les autres endpoints de l'API :

• x-api-key - votre clé API

L'ID de l'organisation figure dans le chemin de l'URL.

Filtrage des événementsCopier le lien vers cette section

Utilisez le paramètre de requête events pour filtrer par type d'événement :

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

Utilisez events=* pour recevoir tous les événements (comme si vous omettiez le paramètre).

Consultez l'index des événements pour tous les événements, la permission requise par événement et un exemple de payload.

Quelques événements ont leur propre canal (journaux du contrôleur et E/S du contrôleur). Vous ne les recevez qu'avec ?channel=controller-logs ou ?channel=controller-io ; l'index des événements indique le canal.

Tillor ne livre que les événements pour lesquels le membre de l'organisation connecté a la permission. Sans bank-transactions:read (ou sync), vous ne recevez par exemple pas d'événements bankAccountTransaction:*, même sans filtre events.

Les données liées issues d'un autre domaine suivent les mêmes règles que l'API : sans customers:read, un reservation:updated arrive avec customer: null ; sans payments:read, un invoice:paid arrive avec payment: null. Une liste devient alors [].

Format des événementsCopier le lien vers cette section

Le payload a la même structure que les livraisons de webhook :

Dans le flux SSE, cet objet JSON se trouve sur la ligne data: ; la clé de l'événement figure aussi sur la ligne event:. Consultez les exemples SSE pour un exemple brut.

Exemple : Node.jsCopier le lien vers cette section

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

Exemple : cURLCopier le lien vers cette section

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

ReconnexionCopier le lien vers cette section

Si la connexion se coupe, reconnectez-vous avec la même URL et les mêmes en-têtes. Le flux ne permet pas de reprise : après la reconnexion, vous ne recevez que les nouveaux événements.

Voir aussiCopier le lien vers cette section

• OpenAPI - spécification complète de l'API
• API HTTP - clés API et authentification
• Webhooks - mêmes événements via HTTP POST
• Exemples - exemples de code et de payload