Recuperare gli eventi

Quando recuperare invece di ricevere#

• Cassa senza indirizzo pubblico: un programma nel locale dietro un router non può ricevere webhook. Recupera gli eventi da sé.
• Rimettersi in pari: dopo un guasto, un webhook disattivato o un errore nella tua elaborazione.
• Riconciliazione: come seconda strada accanto al webhook, che garantisce che non manchi nulla.

Gli eventi vengono generati per ogni collegamento attivo, anche se la tua app non ha alcun webhook.

Recuperare#

GET /events restituisce gli eventi del locale che il tuo collegamento può vedere, più gli eventi app.* di questo collegamento, in ordine crescente, il più vecchio per primo, fino a 30 giorni indietro. app.disconnected non arriva mai qui: con lo scollegamento i token del collegamento smettono di valere. Riconosci uno scollegamento da un 401 seguito da invalid_grant nel rinnovo.

La risposta è un elenco con data, has_more, next_after e gap. next_after è il valore per after con cui continuare a leggere da lì; c'è sempre, anche quando non ci sono eventi. gap: true indica che il tuo after non era più conservato: possono mancare eventi, risincronizza con GET /orders?updated_since=… e gli altri elenchi che usi.

{
  "object": "list",
  "data": [
    {
      "id": "evt_2bf5a9b06b75442a9244e884a1acfc57",
      "object": "event",
      "type": "reservation.updated",
      "created_at": "2026-10-04T17:45:10.410Z",
      "api_version": "2026-10-08",
      "livemode": true,
      "tenant_id": "7d0e5b8a-3c41-4f2e-9a6b-1e2d3c4b5a69",
      "connection_id": "4b3f7c1e-9a2d-4e8b-b5f6-0c1d2e3f4a5b",
      "data": {
        "object": {
          "object": "reservation",
          "id": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
          "code": "R7K2Q9",
          "status": "confirmed",
          "starts_at": "2026-10-10T17:30:00.000Z",
          "duration_minutes": 120,
          "party_size": 4,
          "table_ids": [
            "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
          ],
          "source": "staff",
          "guest_name": "Alex Example",
          "note": "Window seat if possible",
          "created_at": "2026-10-04T12:00:00.000Z",
          "updated_at": "2026-10-04T12:00:00.000Z"
        },
        "previous_status": "pending",
        "changed": [
          "status"
        ]
      }
    }
  ],
  "has_more": false,
  "next_after": "evt_2bf5a9b06b75442a9244e884a1acfc57",
  "gap": false
}

Il ciclo di interrogazione#

1. 1

   Dove sei arrivato

   Leggi il valore after che hai salvato per questo collegamento. Per un nuovo collegamento usa latest: senza after riceveresti gli ultimi 30 giorni, anche eventi precedenti al collegamento.

2. 2

   Recupera ed elabora

   Recupera gli eventi ed elabora ciascuno. L'elaborazione riconosce i duplicati dall'id.

3. 3

   Avanza

   Solo dopo aver elaborato l'intera pagina, salva next_after in modo permanente, per ogni collegamento.

4. 4

   Continua o aspetta

   Se has_more è vero, recupera subito la pagina successiva. Altrimenti aspetta qualche secondo.

# A new connection starts now: no events, only next_after. Store it for this connection.
# (Without after you would get the last 30 days, also events from before the connection.)
curl "https://api.flavoso.com/v1/events?after=latest" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Then always from where you stopped: after = next_after of the previous page.
# "gap": true means that after was no longer kept: resync with GET /orders.
curl "https://api.flavoso.com/v1/events?types=order.*,menu.*,store.*,app.*&limit=100&after=evt_2bf5a9b06b75442a9244e884a1acfc57" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Interrogare a intervalli da 5 a 30 secondi rientra comodamente nel limite di 120 richieste al minuto per collegamento.

Un singolo evento#

GET /events/{id} restituisce un evento, per esempio per controllare un identificativo dal registro dei webhook.

curl https://api.flavoso.com/v1/events/evt_2bf5a9b06b75442a9244e884a1acfc57 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

La stessa busta#

Un evento recuperato è la stessa busta del webhook: lo stesso id, gli stessi campi, lo stesso data, congelato alla prima lettura o al primo invio. Se usi entrambi, riconosci i duplicati dall'id. La firma c'è solo nel webhook; nel recupero è il token a provare chi chiede.

Conservazione#

Gli eventi vengono conservati per 30 giorni. Ciò che è più vecchio lo recuperi tramite gli elenchi, per esempio GET /orders con updated_since. Un after più vecchio non è un errore: la risposta riprende dall'evento conservato più vecchio e imposta gap: true.