# Chiavi di tracciamento API

> Gestisci le chiavi pubbliche che lo script di tracciamento usa per inviare eventi dal tuo sito web.

URL di base: `https://api.emailit.com/v2`. Autenticati con `Authorization: Bearer <API key>`.

## Crea una chiave di tracciamento — POST /tracking-keys

> Crea una chiave di tracciamento pubblica per lo script di tracciamento di Emailit, facoltativamente limitata ai tuoi siti.

# Crea una chiave di tracciamento

Crea una chiave di tracciamento per lo [script di tracciamento](/it/docs/events/tracking-script/). La risposta include la `key` pubblica da inserire nell’URL dello script. Richiede una chiave API con il permesso `full`.

Le chiavi di tracciamento sono pubbliche, quindi chiunque può copiarne una dalla tua pagina. Possono solo inviare eventi di workspace e personalizzati, mai leggere dati, e puoi limitarle ai tuoi siti con `allowed_origins`. Un workspace può avere fino a 25 chiavi di tracciamento.

Il tracciamento del sito web è incluso nei piani Pro, Business e Custom. Le chiavi restano dopo il passaggio a Pay as you go, ma le richieste dello script di tracciamento che le usano restituiscono `403`.

`POST /tracking-keys`

## Parametri del corpo

- `name` (string): Nome che indica dove viene usata la chiave, ad esempio `Online shop`, fino a 100 caratteri.

- `allowed_origins` (string[]): I siti autorizzati a inviare eventi con la chiave, fino a 50. Vuoto o omesso significa qualsiasi sito. Ogni voce è una delle seguenti: - un’origine, come `https://shop.example.com`: solo quello schema, quell’host e quella porta; - un host, come `shop.example.com`: quell’host con qualsiasi schema o porta; - un carattere jolly, come `*.example.com`: `example.com` e tutti i suoi sottodomini. Le voci vengono memorizzate in minuscolo, senza barra finale. Viene accettata anche una stringa con le voci separate da spazi o virgole.

- `enabled` (boolean): `false` crea la chiave disattivata.

## Restituisce

Restituisce `201 Created` con l’[oggetto chiave di tracciamento](/it/docs/api-reference/tracking-keys/get/).

| Stato | Quando |
| --- | --- |
| `403` | La chiave API non ha il permesso `full`, oppure il workspace è su Pay as you go: `error` è `plan_required` e `required_plan` è `pro`. |
| `422` | Un campo non è valido, ad esempio una voce di `allowed_origins` che non è un’origine, un host o un carattere jolly. `errors` ha come chiave il campo e `message` ripete il primo problema. Viene restituito anche con `code: "tracking_keys_limit"` quando il workspace ha già 25 chiavi di tracciamento. |

**Richiesta** `POST /tracking-keys`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Online shop",
    "allowed_origins": ["https://shop.example.com", "*.example.com"]
  }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/tracking-keys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Online shop',
    allowed_origins: ['https://shop.example.com', '*.example.com'],
  }),
});
const trackingKey = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/tracking-keys",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={
        "name": "Online shop",
        "allowed_origins": ["https://shop.example.com", "*.example.com"],
    },
)
tracking_key = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('tracking-keys', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => [
        'name' => 'Online shop',
        'allowed_origins' => ['https://shop.example.com', '*.example.com'],
    ],
]);
$trackingKey = json_decode($response->getBody(), true);
```

**201**

```json
{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "*.example.com"],
  "enabled": true,
  "last_used_at": null,
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T08:05:00.000000+00:00"
}
```

**403**

```json
{
  "error": "plan_required",
  "required_plan": "pro",
  "message": "Website tracking is included with Pro and Business."
}
```

**422**

```json
{
  "error": "allowed_origins \"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)",
  "message": "allowed_origins \"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)",
  "errors": {
    "allowed_origins": ["\"https://shop.example.com/checkout\" is not an origin (https://example.com), a host (example.com) or a wildcard (*.example.com)"]
  }
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/tracking-keys/create/

## Recupera una chiave di tracciamento — GET /tracking-keys/{id}

> Recupera una chiave di tracciamento per lo script di tracciamento di Emailit, con la chiave pubblica, i siti autorizzati e l’ultimo utilizzo.

# Recupera una chiave di tracciamento

Recupera una chiave di tracciamento. Le chiavi di tracciamento sono chiavi pubbliche per lo [script di tracciamento](/it/docs/events/tracking-script/): vanno inserite nelle tue pagine web e possono solo inviare eventi di workspace e personalizzati. Richiede una chiave API con il permesso `full`.

`GET /tracking-keys/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della chiave di tracciamento (`trk_…`) o la chiave stessa (`pub_…`).

## Restituisce

Restituisce l’oggetto chiave di tracciamento.

- `object` (string): Sempre `tracking_key`.

- `id` (string): ID della chiave di tracciamento, con prefisso `trk_`.

- `name` (string): Nome che indica dove viene usata la chiave.

- `key` (string): La chiave pubblica: `pub_` seguito da 32 lettere e cifre. Fa parte dell’URL dello script, quindi viene restituita a ogni lettura.

- `allowed_origins` (string[]): I siti che possono inviare eventi con questa chiave. Vuoto significa qualsiasi sito. Vedi [Siti autorizzati](/it/docs/events/tracking-script/#allowed-sites).

- `enabled` (boolean): `false` quando la chiave è disattivata. Gli eventi inviati con una chiave disattivata vengono rifiutati.

- `last_used_at` (string | null): Quando la chiave ha inviato eventi l’ultima volta, aggiornato al massimo ogni 10 minuti. `null` se non è mai stata usata.

- `created_at, updated_at` (string): Timestamp in UTC.

Restituisce `404` con `error: "Tracking key not found"` se nessuna chiave corrisponde.

**Richiesta** `GET /tracking-keys/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const trackingKey = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
tracking_key = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$trackingKey = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "*.example.com"],
  "enabled": true,
  "last_used_at": "2026-10-19T09:40:00.000000+00:00",
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T08:05:00.000000+00:00"
}
```

**404**

```json
{
  "error": "Tracking key not found"
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/tracking-keys/get/

## Aggiorna una chiave di tracciamento — POST /tracking-keys/{id}

> Rinomina una chiave di tracciamento, modifica i siti autorizzati o disattivala e riattivala. La chiave pubblica resta la stessa.

# Aggiorna una chiave di tracciamento

Aggiorna i campi che passi e lascia invariati gli altri. La `key` pubblica non cambia mai; per sostituire una chiave, creane una nuova, aggiorna le tue pagine ed elimina quella vecchia. Richiede una chiave API con il permesso `full`.

Le modifiche possono richiedere fino a un minuto per essere applicate ovunque.

`POST /tracking-keys/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della chiave di tracciamento (`trk_…`) o la chiave stessa (`pub_…`).

## Parametri del corpo

- `name` (string): Nuovo nome, fino a 100 caratteri. Non può essere vuoto.

- `allowed_origins` (string[]): Sostituisce l’elenco dei siti autorizzati, con le stesse regole valide in [creazione](/it/docs/api-reference/tracking-keys/create/#body-parameters). `[]` consente qualsiasi sito.

- `enabled` (boolean): `false` disattiva la chiave: lo script di tracciamento continua a caricarsi, ma i suoi eventi vengono rifiutati con `403`. `true` la riattiva.

## Restituisce

Restituisce l’[oggetto chiave di tracciamento](/it/docs/api-reference/tracking-keys/get/) aggiornato.

| Stato | Quando |
| --- | --- |
| `404` | Nessuna chiave di tracciamento corrisponde a `id`. |
| `422` | Un campo non è valido. `errors` ha come chiave il campo e `message` ripete il primo problema. |

**Richiesta** `POST /tracking-keys/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_origins": ["https://shop.example.com", "https://www.example.com"] }'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ allowed_origins: ['https://shop.example.com', 'https://www.example.com'] }),
});
const trackingKey = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"allowed_origins": ["https://shop.example.com", "https://www.example.com"]},
)
tracking_key = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['allowed_origins' => ['https://shop.example.com', 'https://www.example.com']],
]);
$trackingKey = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "name": "Online shop",
  "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
  "allowed_origins": ["https://shop.example.com", "https://www.example.com"],
  "enabled": true,
  "last_used_at": "2026-10-19T09:40:00.000000+00:00",
  "created_at": "2026-10-19T08:05:00.000000+00:00",
  "updated_at": "2026-10-19T10:20:00.000000+00:00"
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/tracking-keys/update/

## Elenca le chiavi di tracciamento — GET /tracking-keys

> Elenca le chiavi di tracciamento del workspace per lo script di tracciamento di Emailit, a partire dalla più recente.

# Elenca le chiavi di tracciamento

Restituisce tutte le chiavi di tracciamento del workspace, a partire dalla più recente. Un workspace ne ha al massimo 25, quindi l’elenco non è paginato. Richiede una chiave API con il permesso `full`.

`GET /tracking-keys`

## Parametri di query

- `search` (string): Corrispondenza su una parte del nome, senza distinzione tra maiuscole e minuscole.

- `match`, `order`, `direction`: vedi [Filtri e ordinamento](https://emailit.com/it/docs/api-reference/filtering/).

### Chiavi di filtro

I filtri usano parametri di query `key.condition=value`, ad esempio `enabled.exact=true`. Per le condizioni di ogni tipo, vedi [Filtri e ordinamento](/it/docs/api-reference/filtering/).

| Chiave | Tipo | Note |
| --- | --- | --- |
| `name` | string | |
| `enabled` | boolean | |
| `created_at` | date | |
| `last_used_at` | date | |

Chiavi di ordinamento per `order`: `name`, `enabled`, `created_at`, `last_used_at`. Il valore predefinito è `created_at`, a partire dalla più recente.

## Restituisce

- `data` (object[]): Gli [oggetti chiave di tracciamento](/it/docs/api-reference/tracking-keys/get/), compresa la `key` pubblica di ciascuno.

**Richiesta** `GET /tracking-keys`

**cURL**

```bash
curl https://api.emailit.com/v2/tracking-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/tracking-keys', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const { data } = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/tracking-keys",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
tracking_keys = r.json()["data"]
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('tracking-keys', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$trackingKeys = json_decode($response->getBody(), true)['data'];
```

**200**

```json
{
  "data": [
    {
      "object": "tracking_key",
      "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
      "name": "Online shop",
      "key": "pub_8fK2mQ9xLr4TzW7nB1cV5yH3dJ6sA0pE",
      "allowed_origins": ["https://shop.example.com", "*.example.com"],
      "enabled": true,
      "last_used_at": "2026-10-19T09:40:00.000000+00:00",
      "created_at": "2026-10-19T08:05:00.000000+00:00",
      "updated_at": "2026-10-19T08:05:00.000000+00:00"
    }
  ]
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/tracking-keys/list/

## Elimina una chiave di tracciamento — DELETE /tracking-keys/{id}

> Elimina una chiave di tracciamento. Le pagine che la usano ancora smettono di inviare eventi; gli eventi già registrati vengono conservati.

# Elimina una chiave di tracciamento

Elimina una chiave di tracciamento. Richiede una chiave API con il permesso `full`.

Le pagine che caricano ancora lo script con questa chiave continuano a funzionare, ma i loro eventi vengono rifiutati e non vengono registrati. Gli eventi già registrati con la chiave vengono conservati. Per fermare gli eventi per un po’ senza modificare le tue pagine, disattiva invece la chiave con [Aggiorna una chiave di tracciamento](/it/docs/api-reference/tracking-keys/update/).

`DELETE /tracking-keys/{id}`

## Parametri di percorso

- `id` (string, obbligatorio): L’ID della chiave di tracciamento (`trk_…`) o la chiave stessa (`pub_…`).

## Restituisce

- `object` (string): Sempre `tracking_key`.

- `id` (string): L’ID della chiave eliminata.

- `deleted` (boolean): Sempre `true`.

Restituisce `404` se nessuna chiave di tracciamento corrisponde.

**Richiesta** `DELETE /tracking-keys/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6 \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('tracking-keys/trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

**200**

```json
{
  "object": "tracking_key",
  "id": "trk_2yHn5Pq2WcR7tY4uNs8KdV1bXj6",
  "deleted": true
}
```

---
Fonte: https://emailit.com/it/docs/api-reference/tracking-keys/delete/