# Chaves de rastreamento API

> Gerencie as chaves públicas que o script de rastreamento usa para enviar eventos do seu site.

URL base: `https://api.emailit.com/v2`. Autentique-se com `Authorization: Bearer <API key>`.

## Criar uma chave de rastreamento — POST /tracking-keys

> Crie uma chave de rastreamento pública para o script de rastreamento do Emailit, opcionalmente limitada aos seus próprios sites.

# Criar uma chave de rastreamento

Cria uma chave de rastreamento para o [script de rastreamento](/pt/docs/events/tracking-script/). A resposta inclui a `key` pública que vai na URL do script. Requer uma chave de API com escopo `full`.

As chaves de rastreamento são públicas, então qualquer pessoa pode copiar uma da sua página. Elas só podem enviar eventos do workspace e eventos personalizados, nunca ler dados, e você pode limitá-las aos seus próprios sites com `allowed_origins`. Um workspace pode ter até 25 chaves de rastreamento.

O rastreamento do site está incluído nos planos Pro, Business e Custom. As chaves continuam existindo depois de uma mudança para o Pay as you go, mas as requisições do script de rastreamento com elas retornam `403`.

`POST /tracking-keys`

## Parâmetros do corpo

- `name` (string): Nome que indica onde a chave é usada, como `Online shop`, com até 100 caracteres.

- `allowed_origins` (string[]): Os sites que podem enviar eventos com a chave, até 50. Vazio ou omitido significa qualquer site. Cada entrada é uma destas: - uma origem, como `https://shop.example.com`: apenas esse esquema, host e porta; - um host, como `shop.example.com`: esse host em qualquer esquema ou porta; - um curinga, como `*.example.com`: `example.com` e todos os subdomínios dele. As entradas são armazenadas em minúsculas, sem a barra final. Uma string com entradas separadas por espaços ou vírgulas também é aceita.

- `enabled` (boolean): `false` cria a chave desativada.

## Retorno

Retorna `201 Created` com o [objeto de chave de rastreamento](/pt/docs/api-reference/tracking-keys/get/).

| Status | Quando |
| --- | --- |
| `403` | A chave de API não tem o escopo `full`, ou o workspace está no Pay as you go: `error` é `plan_required` e `required_plan` é `pro`. |
| `422` | Um campo é inválido, por exemplo, uma entrada em `allowed_origins` que não é uma origem, um host nem um curinga. `errors` é indexado por campo e `message` repete o primeiro problema. Também é retornado com `code: "tracking_keys_limit"` quando o workspace já tem 25 chaves de rastreamento. |

**Requisição** `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/pt/docs/api-reference/tracking-keys/create/

## Obter uma chave de rastreamento — GET /tracking-keys/{id}

> Obtenha uma chave de rastreamento do script de rastreamento do Emailit, com a chave pública, os sites permitidos e o último uso.

# Obter uma chave de rastreamento

Obtém uma chave de rastreamento. As chaves de rastreamento são chaves públicas para o [script de rastreamento](/pt/docs/events/tracking-script/): elas vão nas suas páginas web e só podem enviar eventos do workspace e eventos personalizados. Requer uma chave de API com escopo `full`.

`GET /tracking-keys/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID da chave de rastreamento (`trk_…`) ou a própria chave (`pub_…`).

## Retorno

Retorna o objeto de chave de rastreamento.

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

- `id` (string): ID da chave de rastreamento, com o prefixo `trk_`.

- `name` (string): Nome que indica onde a chave é usada.

- `key` (string): A chave pública: `pub_` seguido de 32 letras e dígitos. Ela faz parte da URL do script, então é retornada em toda leitura.

- `allowed_origins` (string[]): Os sites que podem enviar eventos com esta chave. Vazio significa qualquer site. Consulte [Sites permitidos](/pt/docs/events/tracking-script/#allowed-sites).

- `enabled` (boolean): `false` quando a chave está desativada. Os eventos enviados com uma chave desativada são rejeitados.

- `last_used_at` (string | null): Quando a chave enviou eventos pela última vez, atualizado no máximo a cada 10 minutos. `null` se ela nunca foi usada.

- `created_at, updated_at` (string): Timestamps em UTC.

Retorna `404` com `error: "Tracking key not found"` se nenhuma chave corresponder.

**Requisição** `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/pt/docs/api-reference/tracking-keys/get/

## Atualizar uma chave de rastreamento — POST /tracking-keys/{id}

> Renomeie uma chave de rastreamento, altere os sites permitidos dela ou desative-a e ative-a de novo. A chave pública continua a mesma.

# Atualizar uma chave de rastreamento

Atualiza os campos que você enviar e mantém os outros inalterados. A `key` pública nunca muda; para substituir uma chave, crie uma nova, atualize as suas páginas e exclua a antiga. Requer uma chave de API com escopo `full`.

As alterações podem levar até um minuto para valer em todos os lugares.

`POST /tracking-keys/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID da chave de rastreamento (`trk_…`) ou a própria chave (`pub_…`).

## Parâmetros do corpo

- `name` (string): Novo nome, com até 100 caracteres. Não pode ficar vazio.

- `allowed_origins` (string[]): Substitui a lista de sites permitidos, com as mesmas regras da [criação](/pt/docs/api-reference/tracking-keys/create/#body-parameters). `[]` permite qualquer site.

- `enabled` (boolean): `false` desativa a chave: o script de rastreamento continua carregando, mas os eventos dele são rejeitados com `403`. `true` a ativa de novo.

## Retorno

Retorna o [objeto de chave de rastreamento](/pt/docs/api-reference/tracking-keys/get/) atualizado.

| Status | Quando |
| --- | --- |
| `404` | Nenhuma chave de rastreamento corresponde a `id`. |
| `422` | Um campo é inválido. `errors` é indexado por campo e `message` repete o primeiro problema. |

**Requisição** `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/pt/docs/api-reference/tracking-keys/update/

## Listar chaves de rastreamento — GET /tracking-keys

> Liste as chaves de rastreamento do workspace para o script de rastreamento do Emailit, das mais recentes para as mais antigas.

# Listar chaves de rastreamento

Retorna todas as chaves de rastreamento do workspace, das mais recentes para as mais antigas. Um workspace tem no máximo 25, então a lista não é paginada. Requer uma chave de API com escopo `full`.

`GET /tracking-keys`

## Parâmetros de consulta

- `search` (string): Busca sem diferenciar maiúsculas de minúsculas em parte do nome.

- `match`, `order`, `direction`: consulte [Filtragem](https://emailit.com/pt/docs/api-reference/filtering/).

### Chaves de filtro

Os filtros usam parâmetros de consulta `key.condition=value`, por exemplo, `enabled.exact=true`. Consulte [Filtragem](/pt/docs/api-reference/filtering/) para as condições de cada tipo.

| Chave | Tipo | Observações |
| --- | --- | --- |
| `name` | string | |
| `enabled` | boolean | |
| `created_at` | date | |
| `last_used_at` | date | |

Chaves de ordenação para `order`: `name`, `enabled`, `created_at`, `last_used_at`. O padrão é `created_at`, das mais recentes para as mais antigas.

## Retorno

- `data` (object[]): Os [objetos de chave de rastreamento](/pt/docs/api-reference/tracking-keys/get/), incluindo a `key` pública de cada um.

**Requisição** `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/pt/docs/api-reference/tracking-keys/list/

## Excluir uma chave de rastreamento — DELETE /tracking-keys/{id}

> Exclua uma chave de rastreamento. As páginas que ainda a usam param de enviar eventos; os eventos já registrados são mantidos.

# Excluir uma chave de rastreamento

Exclui uma chave de rastreamento. Requer uma chave de API com escopo `full`.

As páginas que ainda carregam o script com esta chave continuam funcionando, mas os eventos delas são rejeitados e não são registrados. Os eventos já registrados com a chave são mantidos. Para interromper os eventos por um tempo sem alterar as suas páginas, desative a chave com [Atualizar uma chave de rastreamento](/pt/docs/api-reference/tracking-keys/update/) em vez de excluí-la.

`DELETE /tracking-keys/{id}`

## Parâmetros de caminho

- `id` (string, obrigatório): O ID da chave de rastreamento (`trk_…`) ou a própria chave (`pub_…`).

## Retorno

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

- `id` (string): ID da chave excluída.

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

Retorna `404` se nenhuma chave de rastreamento corresponder.

**Requisição** `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/pt/docs/api-reference/tracking-keys/delete/