# Claves de seguimiento API

> Gestiona las claves públicas que usa el script de seguimiento para enviar eventos desde tu sitio web.

URL base: `https://api.emailit.com/v2`. Autentícate con `Authorization: Bearer <API key>`.

## Crear una clave de seguimiento — POST /tracking-keys

> Crea una clave de seguimiento pública para el script de seguimiento de Emailit, limitada opcionalmente a tus propios sitios.

# Crear una clave de seguimiento

Crea una clave de seguimiento para el [script de seguimiento](/es/docs/events/tracking-script/). La respuesta incluye la `key` pública que va en la URL del script. Requiere una clave de API con el permiso `full`.

Las claves de seguimiento son públicas, así que cualquiera puede copiar una de tu página. Solo pueden enviar eventos de espacio de trabajo y personalizados, nunca leer datos, y puedes limitarlas a tus propios sitios con `allowed_origins`. Un espacio de trabajo puede tener hasta 25 claves de seguimiento.

El seguimiento de tu web está incluido en los planes Pro, Business y Custom. Las claves se conservan después de cambiar a Pay as you go, pero las peticiones del script de seguimiento con ellas devuelven `403`.

`POST /tracking-keys`

## Parámetros del cuerpo

- `name` (string): Un nombre que indique dónde se usa la clave, como `Online shop`, de hasta 100 caracteres.

- `allowed_origins` (string[]): Los sitios que pueden enviar eventos con la clave, hasta 50. Si está vacío o se omite, se admite cualquier sitio. Cada entrada es una de estas: - un origen, como `https://shop.example.com`: solo ese esquema, ese host y ese puerto; - un host, como `shop.example.com`: ese host con cualquier esquema o puerto; - un comodín, como `*.example.com`: `example.com` y todos sus subdominios. Las entradas se guardan en minúsculas, sin barra final. También se acepta una cadena con las entradas separadas por espacios o comas.

- `enabled` (boolean): `false` crea la clave desactivada.

## Devuelve

Devuelve `201 Created` con el [objeto de clave de seguimiento](/es/docs/api-reference/tracking-keys/get/).

| Código | Cuándo |
| --- | --- |
| `403` | La clave de API no tiene el permiso `full`, o el espacio de trabajo está en Pay as you go: `error` es `plan_required` y `required_plan` es `pro`. |
| `422` | Un campo no es válido, por ejemplo una entrada de `allowed_origins` que no es un origen, un host ni un comodín. `errors` usa el campo como clave y `message` repite el primer problema. También se devuelve con `code: "tracking_keys_limit"` cuando el espacio de trabajo ya tiene 25 claves de seguimiento. |

**Petición** `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)"]
  }
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/tracking-keys/create/

## Obtener una clave de seguimiento — GET /tracking-keys/{id}

> Obtén una clave de seguimiento del script de seguimiento de Emailit, con su clave pública, sus sitios permitidos y su último uso.

# Obtener una clave de seguimiento

Obtiene una clave de seguimiento. Las claves de seguimiento son claves públicas para el [script de seguimiento](/es/docs/events/tracking-script/): van en tus páginas web y solo pueden enviar eventos de espacio de trabajo y personalizados. Requiere una clave de API con el permiso `full`.

`GET /tracking-keys/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la clave de seguimiento (`trk_…`) o la propia clave (`pub_…`).

## Devuelve

Devuelve el objeto de clave de seguimiento.

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

- `id` (string): El ID de la clave de seguimiento, con el prefijo `trk_`.

- `name` (string): El nombre que indica dónde se usa la clave.

- `key` (string): La clave pública: `pub_` seguido de 32 letras y dígitos. Forma parte de la URL del script, así que se devuelve en cada lectura.

- `allowed_origins` (string[]): Los sitios que pueden enviar eventos con esta clave. Si está vacío, se admite cualquier sitio. Consulta [Sitios permitidos](/es/docs/events/tracking-script/#allowed-sites).

- `enabled` (boolean): `false` cuando la clave está desactivada. Los eventos enviados con una clave desactivada se rechazan.

- `last_used_at` (string | null): Cuándo envió eventos la clave por última vez; se actualiza como máximo cada 10 minutos. `null` si no se ha usado nunca.

- `created_at, updated_at` (string): Las marcas de tiempo en UTC.

Devuelve `404` con `error: "Tracking key not found"` si ninguna clave coincide.

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/tracking-keys/get/

## Actualizar una clave de seguimiento — POST /tracking-keys/{id}

> Cambia el nombre de una clave de seguimiento o sus sitios permitidos, o desactívala y vuelve a activarla. La clave pública no cambia.

# Actualizar una clave de seguimiento

Actualiza los campos que pasas y deja los demás sin cambios. La `key` pública no cambia nunca; para sustituir una clave, crea una nueva, actualiza tus páginas y elimina la anterior. Requiere una clave de API con el permiso `full`.

Los cambios pueden tardar hasta un minuto en aplicarse en todas partes.

`POST /tracking-keys/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la clave de seguimiento (`trk_…`) o la propia clave (`pub_…`).

## Parámetros del cuerpo

- `name` (string): El nombre nuevo, de hasta 100 caracteres. No puede estar vacío.

- `allowed_origins` (string[]): Sustituye la lista de sitios permitidos, con las mismas reglas que al [crearla](/es/docs/api-reference/tracking-keys/create/#body-parameters). `[]` admite cualquier sitio.

- `enabled` (boolean): `false` desactiva la clave: el script de seguimiento se sigue cargando, pero sus eventos se rechazan con `403`. `true` vuelve a activarla.

## Devuelve

Devuelve el [objeto de clave de seguimiento](/es/docs/api-reference/tracking-keys/get/) actualizado.

| Código | Cuándo |
| --- | --- |
| `404` | Ninguna clave de seguimiento coincide con `id`. |
| `422` | Un campo no es válido. `errors` usa el campo como clave y `message` repite el primer problema. |

**Petición** `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"
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/tracking-keys/update/

## Listar claves de seguimiento — GET /tracking-keys

> Lista las claves de seguimiento del espacio de trabajo para el script de seguimiento de Emailit, de la más reciente a la más antigua.

# Listar claves de seguimiento

Devuelve todas las claves de seguimiento del espacio de trabajo, de la más reciente a la más antigua. Un espacio de trabajo tiene como máximo 25, así que la lista no está paginada. Requiere una clave de API con el permiso `full`.

`GET /tracking-keys`

## Parámetros de consulta

- `search` (string): Una búsqueda sin distinguir mayúsculas y minúsculas en una parte del nombre.

- `match`, `order`, `direction`: consulta [Filtrado](https://emailit.com/es/docs/api-reference/filtering/).

### Claves de filtro

Los filtros usan parámetros de consulta `key.condition=value`, por ejemplo `enabled.exact=true`. Para las condiciones de cada tipo, consulta [Filtrado y ordenación](/es/docs/api-reference/filtering/).

| Clave | Tipo | Notas |
| --- | --- | --- |
| `name` | string | |
| `enabled` | boolean | |
| `created_at` | date | |
| `last_used_at` | date | |

Claves de orden para `order`: `name`, `enabled`, `created_at`, `last_used_at`. Por defecto, `created_at`, de la más reciente a la más antigua.

## Devuelve

- `data` (object[]): Los [objetos de clave de seguimiento](/es/docs/api-reference/tracking-keys/get/), incluida la `key` pública de cada clave.

**Petición** `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"
    }
  ]
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/tracking-keys/list/

## Eliminar una clave de seguimiento — DELETE /tracking-keys/{id}

> Elimina una clave de seguimiento. Las páginas que todavía la usan dejan de enviar eventos; los eventos ya registrados se conservan.

# Eliminar una clave de seguimiento

Elimina una clave de seguimiento. Requiere una clave de API con el permiso `full`.

Las páginas que todavía cargan el script con esta clave siguen funcionando, pero sus eventos se rechazan y no se registran. Los eventos ya registrados con la clave se conservan. Si quieres detener los eventos durante un tiempo sin cambiar tus páginas, desactiva la clave con [Actualizar una clave de seguimiento](/es/docs/api-reference/tracking-keys/update/) en lugar de eliminarla.

`DELETE /tracking-keys/{id}`

## Parámetros de ruta

- `id` (string, obligatorio): El ID de la clave de seguimiento (`trk_…`) o la propia clave (`pub_…`).

## Devuelve

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

- `id` (string): El ID de la clave eliminada.

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

Devuelve `404` si ninguna clave de seguimiento coincide.

**Petición** `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
}
```

---
Fuente: https://emailit.com/es/docs/api-reference/tracking-keys/delete/