Esplora la documentazioneAPI REST

API REST

L'API REST è ciò che Zapier, Make, n8n e il tuo codice chiamano per leggere gli eventi del tuo account e per iscriversi ad essi. Parla JSON su HTTPS e ogni richiesta porta una chiave API.

10 min

In questa pagina

Panoramica
Autenticazione
Errori
Limiti di frequenza
Endpoint
REST hook per le integrazioni
E adesso?

Panoramica

Ogni endpoint vive sotto l'URL di base qui sotto, seguito dalla versione, per esempio /v1/me.

Gli esempi in questa pagina leggono l'URL di base da KADENS_API_URL e la tua chiave da KADENS_API_KEY, così puoi incollarli così come sono.

Richieste e risposte sono in JSON. Invia Content-Type: application/json con ogni richiesta che ha un corpo.

La versione fa parte del percorso. Ogni evento porta anche la versione del proprio formato nel campo version, attualmente 2026-10-01, così il tuo codice può capire quale forma ha ricevuto.

Autenticazione

Ogni richiesta ha bisogno di una chiave API nell'intestazione Authorization come token Bearer. Ogni endpoint elenca il permesso di cui ha bisogno.

Chiavi API e permessi

Errori

Gli errori usano i codici di stato HTTP standard e un corpo JSON con lo stato, un messaggio, il percorso e un id di richiesta che puoi citare all'assistenza.

Stato	Significato
`400`	La query o il corpo non hanno superato la validazione. Controlla i campi rispetto a questo riferimento.
`401`	La chiave manca, è formattata male, è stata revocata o è scaduta.
`403`	La chiave è valida ma non ha il permesso necessario per questo endpoint.
`429`	Troppe richieste. Attendi il tempo indicato nell'intestazione Retry-After, poi riprova.

Risposta di errore

1
2
3
4
5
6
7
{
  "statusCode": 401,
  "message": "Missing or invalid API key",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "path": "/api/v1/events",
  "requestId": "req_7c1e0b"
}

Limiti di frequenza

I limiti sono conteggiati per chiave API. Superarne uno restituisce 429 finché la finestra non si azzera.

Finestra	Limite
`Al secondo`	40 richieste
`Ogni 10 secondi`	250 richieste
`Al minuto`	800 richieste

Gestire un 429

Leggi l'intestazione Retry-After, attendi quel numero di secondi e riprova. Il corpo porta errorCode: RATE_LIMITED così il tuo codice non deve analizzare il messaggio.

Endpoint

GET/v1/me

Testa la chiave: restituisce l'account a cui appartiene e i suoi permessi. Funziona con qualsiasi chiave valida.

Bash

1
2
curl "$KADENS_API_URL/v1/me" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Risposta di esempio

1
2
3
4
5
6
7
8
9
10
11
{
  "entity": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "name": "Barcelona Salsa Studio"
  },
  "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "scopes": [
    "webhooks.read",
    "webhooks.write"
  ]
}

GET/v1/event-typesPermesso: webhooks.read

Elenca ogni tipo di evento a cui puoi iscriverti, con un esempio di ciascuno e i campi che contengono dati personali.

Bash

1
2
curl "$KADENS_API_URL/v1/event-types" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Risposta di esempio

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "apiVersion": "2026-10-01",
  "data": [
    {
      "type": "order.paid",
      "family": "orders",
      "descriptionKey": "Webhooks.events.order_paid",
      "sample": {
        "order": {
          "id": "ord_91ac04",
          "status": "paid",
          "created_at": "2026-10-01T09:58:02Z",
          "paid_at": "2026-10-01T10:00:00Z",
          "event": {
            "id": "evt_7f3c2a",
            "name": "Salsa Congress Barcelona 2026"
          },
          "totals": {
            "gross": {
              "amount": 12000,
              "currency": "EUR"
            },
            "fees": {
              "amount": 600,
              "currency": "EUR"
            },
            "net": {
              "amount": 11400,
              "currency": "EUR"
            },
            "tax": {
              "amount": 2083,
              "currency": "EUR"
            }
          },
          "buyer": {
            "entity_id": "ent_5b21",
            "name": "Lucia Martin",
            "email": "lucia@example.com"
          },
          "lines": [
            {
              "ticket_type_id": "tt_full_pass",
              "name": "Full pass",
              "quantity": 1,
              "unit_price": {
                "amount": 12000,
                "currency": "EUR"
              }
            }
          ]
        }
      },
      "personalDataPaths": [
        "order.buyer.name",
        "order.buyer.email"
      ]
    }
  ]
}

GET/v1/eventsPermesso: webhooks.read

Elenca gli eventi recenti, dal più nuovo, nella stessa busta delle consegne webhook. Le integrazioni lo usano per mostrare dati di esempio.

Bash

1
2
curl "$KADENS_API_URL/v1/events?type=order.paid&limit=10" \
  -H "Authorization: Bearer $KADENS_API_KEY"

Risposta di esempio

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "data": [
    {
      "id": "msg_2f8a1c7e",
      "type": "order.paid",
      "version": "2026-10-01",
      "occurred_at": "2026-10-01T10:00:00Z",
      "account": {
        "id": "ent_1a0f",
        "name": "Barcelona Salsa Studio"
      },
      "subject": {
        "type": "order",
        "id": "ord_91ac04",
        "sequence": 2
      },
      "correlation_id": null,
      "livemode": true,
      "data": {
        "order": {
          "id": "ord_91ac04",
          "status": "paid",
          "created_at": "2026-10-01T09:58:02Z",
          "paid_at": "2026-10-01T10:00:00Z",
          "event": {
            "id": "evt_7f3c2a",
            "name": "Salsa Congress Barcelona 2026"
          },
          "totals": {
            "gross": {
              "amount": 12000,
              "currency": "EUR"
            },
            "fees": {
              "amount": 600,
              "currency": "EUR"
            },
            "net": {
              "amount": 11400,
              "currency": "EUR"
            },
            "tax": {
              "amount": 2083,
              "currency": "EUR"
            }
          },
          "buyer": {
            "entity_id": "ent_5b21"
          },
          "lines": [
            {
              "ticket_type_id": "tt_full_pass",
              "name": "Full pass",
              "quantity": 1,
              "unit_price": {
                "amount": 12000,
                "currency": "EUR"
              }
            }
          ]
        }
      }
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Parametro	Tipo	Descrizione
`type`	string	Solo eventi di questo tipo.
`limit`	integer	Quanti eventi restituire, da 1 a 100. Il valore predefinito è 25.
`cursor`	string	Il nextCursor della pagina precedente, per leggere quella successiva.

I dati personali sono nascosti per impostazione predefinita

Nomi, email e altri campi personali vengono rimossi dagli eventi a meno che la chiave non abbia anche il permesso people.read.

POST/v1/webhooks/subscriptionsPermesso: webhooks.write

Crea un endpoint gestito dall'integrazione. Appare come sola lettura nella dashboard. Restituisce 201 quando crea l'iscrizione, e 200 con quella esistente quando la stessa iscrizione esiste già.

Bash

1
2
3
4
curl -X POST "$KADENS_API_URL/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $KADENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl":"https://hooks.example.com/kadens","eventTypes":["order.paid","attendee.checked_in"],"integration":"zapier","externalRef":"zap_812734"}'

Risposta di esempio

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "id": "3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14",
  "created": true,
  "targetUrl": "https://hooks.example.com/kadens",
  "eventTypes": [
    "order.paid",
    "attendee.checked_in"
  ],
  "integration": "zapier",
  "externalRef": "zap_812734",
  "apiVersion": "2026-10-01",
  "secret": "whsec_Zk3v9QmT1rX8bLp2Wc6yHn4s",
  "createdAt": "2026-10-01T10:00:00.000Z"
}

Campo	Tipo	Descrizione
`targetUrl`Obbligatorio	string	L'indirizzo HTTPS a cui Kadens consegna gli eventi.
`eventTypes`Obbligatorio	string[]	I tipi di evento da consegnare, da 1 a 50. Leggi l'elenco da /v1/event-types.
`integration`Obbligatorio	string	Chi gestisce l'iscrizione: zapier, make, n8n o other.
`externalRef`	string	Il tuo id per questa iscrizione, fino a 255 caratteri.

DELETE/v1/webhooks/subscriptions/:idPermesso: webhooks.write

Rimuove un endpoint creato dall'integrazione. Restituisce 204 senza corpo.

Bash

1
2
curl -X DELETE "$KADENS_API_URL/v1/webhooks/subscriptions/3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14" \
  -H "Authorization: Bearer $KADENS_API_KEY"

REST hook per le integrazioni

Gli strumenti di automazione si collegano a Kadens con il pattern REST hook: si iscrivono quando un workflow viene attivato e si disiscrivono quando viene disattivato.

Iscriviti
Lo strumento chiama POST /v1/webhooks/subscriptions con l'indirizzo a cui consegnare e i tipi di evento che vuole. Conserva l'id e il segreto di firma dalla risposta.
Ricevi eventi
Kadens invia ogni evento corrispondente a quell'indirizzo come POST firmato. Verifica la firma con il segreto prima di fidarti del payload.
Disiscriviti
Quando il workflow viene disattivato, lo strumento chiama DELETE /v1/webhooks/subscriptions/:id con l'id che ha conservato.

Le iscrizioni create in questo modo appaiono come sola lettura nella tua dashboard, contrassegnate con l'integrazione che le gestisce.

Come verificare le firme

E adesso?

Apri nella dashboard

È stato utile?

Non trovi quello che cerchi?Cerca di nuovoParla con noi

Stato

Significato

400

La query o il corpo non hanno superato la validazione. Controlla i campi rispetto a questo riferimento.

401

La chiave manca, è formattata male, è stata revocata o è scaduta.

403

La chiave è valida ma non ha il permesso necessario per questo endpoint.

429

Troppe richieste. Attendi il tempo indicato nell'intestazione Retry-After, poi riprova.

Finestra

Limite

Al secondo

40 richieste

Ogni 10 secondi

250 richieste

Al minuto

800 richieste

{ "entity": { "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f", "name": "Barcelona Salsa Studio" }, "apiKeyId": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d", "scopes": [ "webhooks.read", "webhooks.write" ] }

{ "apiVersion": "2026-10-01", "data": [ { "type": "order.paid", "family": "orders", "descriptionKey": "Webhooks.events.order_paid", "sample": { "order": { "id": "ord_91ac04", "status": "paid", "created_at": "2026-10-01T09:58:02Z", "paid_at": "2026-10-01T10:00:00Z", "event": { "id": "evt_7f3c2a", "name": "Salsa Congress Barcelona 2026" }, "totals": { "gross": { "amount": 12000, "currency": "EUR" }, "fees": { "amount": 600, "currency": "EUR" }, "net": { "amount": 11400, "currency": "EUR" }, "tax": { "amount": 2083, "currency": "EUR" } }, "buyer": { "entity_id": "ent_5b21", "name": "Lucia Martin", "email": "lucia@example.com" }, "lines": [ { "ticket_type_id": "tt_full_pass", "name": "Full pass", "quantity": 1, "unit_price": { "amount": 12000, "currency": "EUR" } } ] } }, "personalDataPaths": [ "order.buyer.name", "order.buyer.email" ] } ] }

{ "data": [ { "id": "msg_2f8a1c7e", "type": "order.paid", "version": "2026-10-01", "occurred_at": "2026-10-01T10:00:00Z", "account": { "id": "ent_1a0f", "name": "Barcelona Salsa Studio" }, "subject": { "type": "order", "id": "ord_91ac04", "sequence": 2 }, "correlation_id": null, "livemode": true, "data": { "order": { "id": "ord_91ac04", "status": "paid", "created_at": "2026-10-01T09:58:02Z", "paid_at": "2026-10-01T10:00:00Z", "event": { "id": "evt_7f3c2a", "name": "Salsa Congress Barcelona 2026" }, "totals": { "gross": { "amount": 12000, "currency": "EUR" }, "fees": { "amount": 600, "currency": "EUR" }, "net": { "amount": 11400, "currency": "EUR" }, "tax": { "amount": 2083, "currency": "EUR" } }, "buyer": { "entity_id": "ent_5b21" }, "lines": [ { "ticket_type_id": "tt_full_pass", "name": "Full pass", "quantity": 1, "unit_price": { "amount": 12000, "currency": "EUR" } } ] } } } ], "nextCursor": null, "hasMore": false }

Parametro

Tipo

Descrizione

type

string

Solo eventi di questo tipo.

limit

integer

Quanti eventi restituire, da 1 a 100. Il valore predefinito è 25.

cursor

string

Il nextCursor della pagina precedente, per leggere quella successiva.

curl -X POST "$KADENS_API_URL/v1/webhooks/subscriptions" \ -H "Authorization: Bearer $KADENS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"targetUrl":"https://hooks.example.com/kadens","eventTypes":["order.paid","attendee.checked_in"],"integration":"zapier","externalRef":"zap_812734"}'

{ "id": "3d9f2b71-8c4e-4a6f-9b1d-5e7a0c2f8d14", "created": true, "targetUrl": "https://hooks.example.com/kadens", "eventTypes": [ "order.paid", "attendee.checked_in" ], "integration": "zapier", "externalRef": "zap_812734", "apiVersion": "2026-10-01", "secret": "whsec_Zk3v9QmT1rX8bLp2Wc6yHn4s", "createdAt": "2026-10-01T10:00:00.000Z" }

Campo

Tipo

Descrizione

targetUrlObbligatorio

string

L'indirizzo HTTPS a cui Kadens consegna gli eventi.

eventTypesObbligatorio

string[]

I tipi di evento da consegnare, da 1 a 50. Leggi l'elenco da /v1/event-types.

integrationObbligatorio

string

Chi gestisce l'iscrizione: zapier, make, n8n o other.

externalRef

string

Il tuo id per questa iscrizione, fino a 255 caratteri.

Gestire un 429

I dati personali sono nascosti per impostazione predefinita

Iscriviti

Ricevi eventi

Disiscriviti

E adesso?

Gestire un 429

I dati personali sono nascosti per impostazione predefinita

Iscriviti

Ricevi eventi

Disiscriviti

E adesso?