Server-Sent Events (SSE)
Transmita eventos em tempo real através de uma ligação de longa duração
Última atualização em
O SSE oferece uma transmissão de longa duração dos mesmos eventos que os webhooks recebem. Utilize o SSE quando preferir uma ligação persistente em vez de chamadas de retorno HTTP.
Endpoint
GET /api/orgs/:orgId/realtime/subscribeAutenticação
O SSE usa a mesma autenticação que os outros endpoints da API:
- x-api-key - A sua chave de API
O ID da organização está no caminho do URL.
Filtragem de eventos
Utilize o parâmetro de consulta events para filtrar por tipo de evento:
GET /api/orgs/:orgId/realtime/subscribe?events=invoice:created&events=invoice:paidUtilize events=* para receber todos os eventos (o mesmo que omitir o parâmetro).
Consulte o Índice de eventos para todos os eventos, a permissão de cada evento e um exemplo de payload.
Alguns eventos estão num canal próprio (registos de controladores e E/S de controladores). Esses só os recebe com ?channel=controller-logs ou ?channel=controller-io; o Índice de eventos indica o canal.
O Tillor só entrega eventos para os quais o membro da organização com sessão iniciada tem permissão. Sem bank-transactions:read (ou sync), por exemplo, não recebe eventos bankAccountTransaction:*, nem mesmo que não envie qualquer filtro events.
Os dados associados de outro domínio seguem as mesmas regras que a API: sem customers:read, um reservation:updated chega com customer: null, e sem payments:read um invoice:paid chega com payment: null. Uma lista passa então a [].
Formato do evento
O payload tem a mesma estrutura que as entregas de webhook:
| Campo | Tipo | Descrição |
|---|---|---|
event | string | Chave do evento (por ex. invoice:created) |
data | object | Payload específico do evento |
timestamp | number | Unix timestamp (ms) em que o evento foi emitido |
traceId | string | ID de trace OpenTelemetry da ação do Tillor que causou este evento (o mesmo que nos webhooks) |
spanId | string (opcional) | Span dentro desse trace |
Na transmissão SSE, este objeto JSON está na linha data:; a chave do evento também está na linha event:. Consulte os exemplos de SSE para um exemplo em formato de transmissão.
Exemplo: Node.js
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);
}
}
}Exemplo: cURL
curl -N -H "x-api-key: tkn_xxx" \
-H "Accept: text/event-stream" \
"https://app.tillor.eu/api/orgs/org_abc123/realtime/subscribe"Religação
Se a ligação cair, volte a ligar com o mesmo URL e cabeçalhos. A transmissão não suporta retoma; depois de religar, só recebe novos eventos.