# API: link di tracciamento, domini, pixel e statistiche

_API · 9 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-tracking/_

Un **link di tracciamento** invia un visitatore a una creator su Telegram e conta ciò che segue: clic, conversazioni, primi messaggi, acquirenti e ricavi. I link possono risiedere sul tuo **dominio** personale, attivare **pixel** pubblicitari (Meta, TikTok, Snap) e inviare **eventi** server. Questi endpoint corrispondono alla pagina **Tracking**.

## Endpoints

| Method | Path | Description | Permission | Status |
|---|---|---|---|---|
| GET | `/links` | Elenca i link (`creator_id=`, `archived=false`) con i loro contatori | `can_tracking` o `can_sales_read` | Planned |
| POST | `/links` | Crea un link | `can_tracking` | Planned |
| GET | `/links/{id}` | Un link | `can_tracking` o `can_sales_read` | Planned |
| PUT | `/links/{id}` | Sostituisce un link (nome, slug, dominio, destinazione, UTM, pixel) | `can_tracking` | Planned |
| DELETE | `/links/{id}` | Archivia un link (`permanent=1` lo elimina) | `can_tracking` | Planned |
| GET | `/domains` | I tuoi domini (`status=active,inactive`, `q=`) | `can_tracking` | Planned |
| POST | `/domains` | Aggiungi un dominio (stato `pending`) | `can_tracking` | Planned |
| POST | `/domains/{host}/verify` | Verifica ora i suoi record DNS | `can_tracking` | Planned |
| PATCH | `/domains/{host}` | Imposta un dominio verificato come predefinito, o cambia la sua etichetta | `can_tracking` | Planned |
| DELETE | `/domains/{host}` | Rimuovi un dominio non usato da link attivi | `can_tracking` | Planned |
| GET | `/pixels` | Le connessioni Meta, TikTok e Snap e la modalità consenso | `can_tracking` | Planned |
| PUT | `/pixels/{provider}` | Connetti o sostituisci un pixel (`meta`, `tiktok`, `snap`) | `owner` | Planned |
| DELETE | `/pixels/{provider}` | Disconnetti un pixel | `owner` | Planned |
| POST | `/pixels/{provider}/test` | Invia un evento di test e restituisce la risposta della piattaforma | `can_tracking` | Planned |
| PUT | `/pixels/consent` | Modalità consenso: `page` o `implicit_by_country` | `owner` | Planned |
| GET | `/events` | Eventi integrati e personalizzati, con conteggi di consegna a 7 giorni | `can_tracking` | Planned |
| POST | `/events` | Crea un evento personalizzato | `owner` | Planned |
| PATCH | `/events/{id}` | Attiva o disattiva un evento per rete | `owner` | Planned |
| DELETE | `/events/{id}` | Elimina un evento personalizzato | `owner` | Planned |
| GET | `/stats` | Totali giornalieri, per link e per fonte (`from=`, `to=`, `creator_id=`) | `can_sales_read` | Planned |
| GET | `/stats/export.csv` | Gli stessi numeri in CSV | `can_sales_read` | Planned |

## L'oggetto link

```json
{
  "id": "lnk_3",
  "name": "TikTok · Lea night",
  "slug": "lea-tiktok-night",
  "creator_id": "cr_lea",
  "source": "tiktok",
  "campaign": "Autumn",
  "domain": "go.mia-links.com",
  "public_url": "https://go.mia-links.com/r/lea-tiktok-night",
  "destination": "pool",
  "account_id": null,
  "utm": { "source": "tiktok", "medium": "social", "campaign": "autumn" },
  "pixels": { "meta": false, "tiktok": true, "snap": false },
  "counters": { "clicks": 640, "conversations": 97, "first_messages": 76, "buyers": 14, "revenue_stars": 6200 },
  "archived": false,
  "created_at": "2026-09-12T08:00:00Z"
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | Inizia con `lnk_` |
| `name` | string | Il nome visibile al tuo team |
| `slug` | string | La parte finale dell'URL pubblico |
| `creator_id` | string | La creator a cui il link indirizza |
| `source`, `campaign` | string | Da dove proviene il traffico e il nome della tua campagna |
| `domain` | string | Un dominio verificato dello workspace, o il dominio LanaChat |
| `public_url` | string | `https://<domain>/r/<slug>`: l'URL da mettere in bio o in un annuncio |
| `destination` | string | `pool` o `account` |
| `account_id` | string o null | L'account fisso quando `destination` è `account` |
| `utm` | object | `source`, `medium`, `campaign` |
| `pixels` | object | Quali pixel connessi si attivano su questo link |
| `counters` | object | `clicks`, `conversations`, `first_messages`, `buyers`, `revenue_stars` |
| `archived` | boolean | I link archiviati sono esclusi dalle statistiche |
| `created_at` | string | ISO 8601, UTC |

- `destination` è `pool` (l'account viene scelto al clic tra il pool della creator, vedi [pools](https://lanachat.ai/guides/it/api-telegram-accounts/)) o `account` (sempre lo stesso `account_id`).
- `slug`: lettere minuscole, cifre e trattini, da 1 a 48 caratteri, inizia e finisce con lettera o cifra, unico tra i link attivi dello stesso dominio.
- `domain` deve essere un dominio verificato dello workspace; senza di esso si usa il dominio LanaChat.
- Valori `utm`: fino a 80 lettere, cifre, punti, trattini o underscore. Sono applicati a ogni clic e inoltrati agli eventi pixel.

## L'oggetto dominio

```json
{
  "host": "go.mia-links.com",
  "builtin": false,
  "status": "pending",
  "error": null,
  "ssl": "none",
  "is_default": false,
  "label": "Lea TikTok",
  "token": "8be03d5f19a2",
  "checks": 0,
  "added_at": "2026-10-05T10:00:00Z",
  "verified_at": null,
  "last_check_at": null
}
```

| Field | Type | Description |
|---|---|---|
| `host` | string | Un sottodominio in minuscolo (almeno 3 etichette), unico nello workspace |
| `builtin` | boolean | `true` per il dominio LanaChat, che non può mai essere rimosso |
| `status` | string | `verified`, `pending` o `error` |
| `error` | string o null | Una frase semplice quando `status` è `error` |
| `ssl` | string | `none`, `issuing` o `active` |
| `is_default` | boolean | Esattamente un dominio verificato è quello predefinito |
| `label` | string o null | Un nome per il tuo team, fino a 60 caratteri |
| `token` | string | Il valore del record TXT di verifica |
| `checks` | number | Controlli DNS effettuati finora |
| `added_at`, `verified_at`, `last_check_at` | string o null | ISO 8601, UTC |

## L'oggetto connessione pixel

```json
{ "connected": true, "pixel_id": "123456789012345", "token_last4": "x9Qa", "token_status": "valid", "token_error": null, "test_event_code": "TEST4821", "connected_at": "2026-10-06T14:30:00Z" }
```

| Field | Type | Description |
|---|---|---|
| `connected` | boolean | Il pixel è connesso |
| `pixel_id` | string | Meta: 15 o 16 cifre. TikTok: 20 lettere maiuscole o cifre. Snap: un UUID |
| `token_last4` | string | Ultimi 4 caratteri del token di accesso, mai il token completo |
| `token_status` | string | `valid`, `expired` o `invalid` |
| `token_error` | string o null | Una frase semplice, per esempio "Access token expired on 3 Oct. Replace it to resume delivery." |
| `test_event_code` | string o null | Il codice di test del gestore eventi della piattaforma |
| `connected_at` | string | ISO 8601, UTC |

## L'oggetto evento

```json
{
  "id": "evt_purchase",
  "name": "Purchase",
  "builtin": true,
  "trigger": { "type": "purchase" },
  "networks": { "meta": true, "tiktok": true, "snap": false }
}
```

| Field | Type | Description |
|---|---|---|
| `id` | string | L'id dell'evento |
| `name` | string | Nome integrato, o tuo nome personalizzato: una lettera, poi fino a 39 lettere, cifre o underscore, unico nello workspace |
| `builtin` | boolean | `true` per Lead, Contact, Purchase, Subscribe e InitiateCheckout |
| `trigger` | object | `type`, e un `value` per i trigger che ne hanno bisogno |
| `networks` | object | Attivo o no per `meta`, `tiktok` e `snap` |

## L'oggetto statistiche

```json
{
  "days":    [ { "date": "2026-10-05", "clicks": 54, "conversations": 9, "first_messages": 7, "buyers": 2, "revenue_stars": 950 } ],
  "links":   [ { "link_id": "lnk_3", "clicks": 640, "conversations": 97, "first_messages": 76, "buyers": 14, "revenue_stars": 6200 } ],
  "sources": [ { "source": "instagram", "clicks": 1210, "conversations": 160, "first_messages": 131, "buyers": 22, "revenue_stars": 9100 } ]
}
```

| Field | Type | Description |
|---|---|---|
| `days` | array | Una riga per ogni giorno UTC del periodo |
| `links` | array | Una riga per ogni link, su tutto il periodo |
| `sources` | array | Una riga per ogni gruppo di fonte: `instagram`, `tiktok`, `snapchat`, `meta`, `x` e `other` |
| `clicks` | number | Reindirizzamenti serviti |
| `conversations` | number | Conversazioni Telegram iniziate con il link |
| `first_messages` | number | Fans che hanno scritto almeno una volta |
| `buyers` | number | Fans distinti con acquisto Stars verificato nel periodo |
| `revenue_stars` | number | Acquisti Stars verificati di quei fans nel periodo |

## Link

### Elenca link

`GET /links` · `can_tracking` o `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `creator_id` | string | No | Solo i link di questa creator |
| `archived` | boolean | No | `false` (vista predefinita) nasconde i link archiviati |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/links?creator_id=cr_lea&archived=false" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta è una lista paginata di oggetti link, ciascuno con i suoi `counters`.

### Crea un link

`POST /links` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Sì | Il nome visibile al tuo team |
| `slug` | string | Sì | Lettere minuscole, cifre e trattini, da 1 a 48 caratteri |
| `creator_id` | string | Sì | La creator a cui il link indirizza |
| `source` | string | No | `instagram`, `tiktok`, `snapchat`, `meta`, `x` o altra fonte |
| `campaign` | string | No | Il nome della tua campagna |
| `destination` | string | No | `pool` o `account` |
| `account_id` | string | Quando `destination` è `account` | L'account Telegram fisso |
| `domain` | string | No | Un dominio verificato; senza di esso il dominio LanaChat |
| `utm` | object | No | `source`, `medium`, `campaign` |
| `pixels` | object | No | `meta`, `tiktok`, `snap`: `true` per attivare quel pixel |

```bash
curl -X POST https://api.lanachat.ai/v1/links \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Insta bio · Lea", "slug": "lea-bio", "creator_id": "cr_lea", "source": "instagram", "destination": "pool", "domain": "go.mia-links.com"}'
```

```json
{
  "id": "lnk_9",
  "name": "Insta bio · Lea",
  "slug": "lea-bio",
  "creator_id": "cr_lea",
  "source": "instagram",
  "campaign": null,
  "domain": "go.mia-links.com",
  "public_url": "https://go.mia-links.com/r/lea-bio",
  "destination": "pool",
  "account_id": null,
  "utm": { "source": null, "medium": null, "campaign": null },
  "pixels": { "meta": false, "tiktok": false, "snap": false },
  "counters": { "clicks": 0, "conversations": 0, "first_messages": 0, "buyers": 0, "revenue_stars": 0 },
  "archived": false,
  "created_at": "2026-10-06T14:40:00Z"
}
```

- Uno slug già usato risponde `409` con `The slug /lea-bio is already used by "Insta bio · Mia".`
- Un dominio non verificato risponde `400` ("Pick a verified domain…").

### Ottieni un link

`GET /links/{id}` · `can_tracking` o `can_sales_read`

```bash
curl https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta è l'oggetto link. Un id sconosciuto risponde `404`.

### Sostituisci un link

`PUT /links/{id}` · `can_tracking`

Stesso corpo di **Crea un link**; `PUT` sostituisce tutto il link, quindi invia tutti i campi da mantenere.

```bash
curl -X PUT https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "TikTok · Lea night", "slug": "lea-tiktok-night", "creator_id": "cr_lea", "source": "tiktok", "campaign": "Autumn", "destination": "pool", "domain": "go.mia-links.com", "utm": {"source": "tiktok", "medium": "social", "campaign": "autumn"}, "pixels": {"meta": false, "tiktok": true, "snap": false}}'
```

La risposta è il link aggiornato. Stessi errori di quando crei un link.

### Archivia o elimina un link

`DELETE /links/{id}` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `permanent` | number | No | `1` elimina il link definitivamente invece di archiviarlo |

```bash
curl -X DELETE https://api.lanachat.ai/v1/links/lnk_3 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Un link archiviato è escluso dalle statistiche.

## Domini

Per usare un dominio tuo, aggiungilo, crea due record DNS, poi verificane la proprietà:

- `CNAME go.mia-links.com → links.lanachat.app`
- `TXT _lanachat.go.mia-links.com = lanachat-verify=8be03d5f19a2`

I domini in pending sono controllati ogni 10 minuti per 72 ore, poi ogni giorno. Lo `status` diventa `verified` e `ssl` passa da `issuing` a `active`.

### Elenca domini

`GET /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | string | No | `active` (verificati) o `inactive` (pending o error) |
| `q` | string | No | Parte dell'host o dell'etichetta |

```bash
curl "https://api.lanachat.ai/v1/domains?status=active" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta elenca oggetti dominio, incluso il dominio LanaChat (`builtin: true`).

### Aggiungi un dominio

`POST /domains` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `host` | string | Sì | Un sottodominio, per esempio `go.mia-links.com` |

```bash
curl -X POST https://api.lanachat.ai/v1/domains \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"host": "go.mia-links.com"}'
```

La risposta è il nuovo dominio con `status: "pending"` e il suo `token` per il record TXT. L'host viene pulito (minuscolo, senza `https://`, senza path). I domini root, `*.lanachat.app` e un dominio già aggiunto rispondono `400` con una frase.

### Verifica un dominio

`POST /domains/{host}/verify` · `can_tracking`

```bash
curl -X POST https://api.lanachat.ai/v1/domains/go.mia-links.com/verify \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "host": "go.mia-links.com", "builtin": false, "status": "verified", "error": null, "ssl": "issuing", "is_default": false, "label": null, "token": "8be03d5f19a2", "checks": 3, "added_at": "2026-10-05T10:00:00Z", "verified_at": "2026-10-06T14:45:00Z", "last_check_at": "2026-10-06T14:45:00Z" }
```

Quando un record è errato, `status` è `error` e `error` indica quale, per esempio "The CNAME record points to another service." Il dominio LanaChat non può essere verificato (il suo DNS è gestito da LanaChat).

### Modifica un dominio

`PATCH /domains/{host}` · `can_tracking`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `is_default` | boolean | No | `true` lo imposta come dominio predefinito; il precedente predefinito non lo sarà più |
| `label` | string o null | No | Un nome per il tuo team, fino a 60 caratteri |

```bash
curl -X PATCH https://api.lanachat.ai/v1/domains/go.mia-links.com \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_default": true}'
```

Solo un dominio verificato può essere predefinito. Il dominio LanaChat rifiuta un'etichetta (`403`).

### Rimuovi un dominio

`DELETE /domains/{host}` · `can_tracking`

```bash
curl -X DELETE https://api.lanachat.ai/v1/domains/go.mia-links.com \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Rimuovere il dominio LanaChat, il dominio predefinito ("Set another default domain first") o un dominio usato da link attivi ("Used by N active links across all creators") risponde `409`.

## Pixel

Gli eventi sono inviati server to server, deduplicati con il pixel browser tramite lo stesso `event_id`, con l'id Telegram del fan hashato (SHA-256), mai in chiaro. Senza consenso nessun evento è mai inviato. Un pixel si attiva solo per i link che lo abilitano.

### Leggi connessioni pixel

`GET /pixels` · `can_tracking`

```bash
curl https://api.lanachat.ai/v1/pixels \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta contiene una connessione pixel per ciascuno di `meta`, `tiktok` e `snap`, e la `mode` del consenso.

### Connetti un pixel

`PUT /pixels/{provider}` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `pixel_id` | string | Sì | Meta: 15 o 16 cifre. TikTok: 20 lettere maiuscole o cifre. Snap: un UUID |
| `access_token` | string | Sì | Il token API Conversions della piattaforma |
| `test_event_code` | string | No | Il codice di test della piattaforma |

```bash
curl -X PUT https://api.lanachat.ai/v1/pixels/meta \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pixel_id": "123456789012345", "access_token": "EAAG…", "test_event_code": "TEST4821"}'
```

```json
{ "connected": true, "pixel_id": "123456789012345", "token_last4": "x9Qa", "token_status": "valid", "token_error": null, "test_event_code": "TEST4821", "connected_at": "2026-10-06T14:30:00Z" }
```

Il token di accesso è memorizzato criptato e mai restituito: solo `token_last4`. Un pixel id in formato errato o un token vuoto rispondono `400`.

### Disconnetti un pixel

`DELETE /pixels/{provider}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/pixels/meta \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

### Invia un evento di test

`POST /pixels/{provider}/test` · `can_tracking`

```bash
curl -X POST https://api.lanachat.ai/v1/pixels/meta/test \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "ok": true, "status": 200, "body": "{\"events_received\":1}" }
```

`status` e `body` sono la risposta diretta della piattaforma, così vedi esattamente cosa hanno risposto Meta, TikTok o Snap.

### Imposta la modalità consenso

`PUT /pixels/consent` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `mode` | string | Sì | `page`: schermata consenso per ogni fan prima che Telegram si apra. `implicit_by_country`: schermata solo in UE, SEE, UK e Svizzera |

```bash
curl -X PUT https://api.lanachat.ai/v1/pixels/consent \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "implicit_by_country"}'
```

## Eventi

Eventi integrati: Lead (conversazione iniziata da un link), Contact (primo messaggio fan), Purchase (vendita verificata), Subscribe, InitiateCheckout. Eventi personalizzati hanno un trigger: `sale_over` (vendita sopra una certa somma in dollari), `tag_added` (un tag), `nth_message` (il N-esimo messaggio fan, 2 o più) o `offer_viewed`.

### Elenca eventi

`GET /events` · `can_tracking`

```bash
curl https://api.lanachat.ai/v1/events \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta elenca oggetti evento con le consegne accettate e fallite in 7 giorni, per rete.

### Crea un evento personalizzato

`POST /events` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Sì | Una lettera, poi fino a 39 lettere, cifre o underscore; unico nello workspace |
| `trigger` | object | Sì | `type`: `sale_over`, `tag_added`, `nth_message` o `offer_viewed`; `value` per i primi tre |
| `networks` | object | No | `meta`, `tiktok`, `snap`: `true` per inviarlo lì |

```bash
curl -X POST https://api.lanachat.ai/v1/events \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "BigSpender", "trigger": {"type": "sale_over", "value": 50}, "networks": {"meta": true, "tiktok": true, "snap": false}}'
```

La risposta è il nuovo evento (`201`). Un nome già usato risponde `409`.

### Attiva o disattiva un evento

`PATCH /events/{id}` · `owner`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `networks` | object | Sì | `meta`, `tiktok`, `snap`: `true` o `false` |

```bash
curl -X PATCH https://api.lanachat.ai/v1/events/evt_purchase \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"networks": {"meta": true, "tiktok": true, "snap": true}}'
```

### Elimina un evento personalizzato

`DELETE /events/{id}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/events/evt_bigspender \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Gli eventi integrati non possono essere eliminati; disattivali invece.

## Statistiche

### Leggi statistiche

`GET /stats` · `can_sales_read`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `from` | string | Sì | Primo giorno UTC, `YYYY-MM-DD`, incluso |
| `to` | string | Sì | Ultimo giorno UTC, `YYYY-MM-DD`, incluso |
| `creator_id` | string | No | Solo questa creator; senza, tutte le creators |

```bash
curl "https://api.lanachat.ai/v1/stats?from=2026-09-06&to=2026-10-05&creator_id=cr_lea" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta è l'oggetto statistiche. I giorni sono UTC; i link archiviati sono esclusi.

### Esporta statistiche in CSV

`GET /stats/export.csv` · `can_sales_read`

Stessi parametri di `GET /stats`.

```bash
curl "https://api.lanachat.ai/v1/stats/export.csv?from=2026-09-06&to=2026-10-05" \
  -H "Authorization: Bearer $LANACHAT_TOKEN" -o stats.csv
```

```text
date,link,slug,domain,creator,source,clicks,conversations,first_messages,buyers,revenue_stars
2026-10-05,TikTok · Lea night,lea-tiktok-night,go.mia-links.com,Lea,tiktok,54,9,7,2,950
```

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Tracciamento: link, domini e analisi](https://lanachat.ai/guides/it/tracking-links/)
- [API: Account Telegram, pool e stories](https://lanachat.ai/guides/it/api-telegram-accounts/)