# Eventos do workspace

> Defina eventos do workspace e o tipo de cada propriedade, para que todos os sistemas que os enviam continuem consistentes. Aborda os tipos de propriedade, a validação e a alteração de uma definição.

Um evento do workspace é um evento que o seu workspace declara antes que alguém o envie: o nome, um título opcional e as propriedades que ele traz, cada uma com um tipo. Os eventos desse tipo são enviados como `w:<name>`, e o Emailit rejeita os que não correspondem à definição. Esta página explica como defini-los e como funciona a validação.

Se você não quiser declarar uma estrutura, envie um [evento personalizado](/pt/docs/events/#three-scopes-of-events) (`c:<name>`) no lugar. Os eventos do workspace e os eventos personalizados estão incluídos nos planos Pro, Business e Custom.

## Definir um evento do workspace

**Painel**

  1. **Abra os eventos do workspace.** Acesse **Email API → Events**, selecione a aba **Workspace events** e depois **Define workspace event**.

  2. **Dê um nome ao evento.** Em **Name**, digite um nome como `customer.type`. Ele é enviado como `w:customer.type`. Se quiser, adicione um título em **Title**, exibido em linhas do tempo e seletores, e uma descrição para a sua equipe em **Description**.

  3. **Adicione as propriedades.** Selecione **Add property** para cada valor que os sistemas que enviam o evento devem ou podem incluir. Dê um nome à propriedade, escolha o tipo em **Type** e ative **Required** se todo evento precisar tê-la. Um título e uma descrição são opcionais.

  4. **Crie o evento.** Selecione **Create**. Para testá-lo, selecione **Send test** na definição: isso abre **Send event** com o evento já escolhido.

**API**

  Chame [Criar um evento do workspace](/pt/docs/api-reference/workspace-events/create/) com uma chave de API **Full Access**:

```bash
curl -X POST https://api.emailit.com/v2/workspace/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer.type",
    "title": "Customer type",
    "properties": [
      { "name": "segment", "type": "string", "required": true },
      { "name": "since", "type": "date" }
    ]
  }'
```

Depois, envie-o como qualquer outro evento, com o script de rastreamento ou com a API:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "w:customer.type", "email": "jane@example.com", "properties": { "segment": "b2b", "since": "2026-10-01" } }'
```

## Tipos de propriedade

| Tipo | Aceita | Armazenado como |
| --- | --- | --- |
| `string` | Uma string JSON, com até 2.000 caracteres. | A string |
| `number` | Um número JSON. Números entre aspas, como `"42"`, são rejeitados. | O número |
| `date` | Uma data ISO 8601 (`2026-10-01`) ou uma data e hora (`2026-10-01T12:00:00Z`), ou um timestamp em milissegundos. Anos anteriores a 1900 são rejeitados. | Uma data e hora ISO 8601 em UTC |
| `boolean` | `true` ou `false`. | O booleano |

## Como os eventos são verificados

Quando um evento `w:` chega, o Emailit compara as `properties` dele com a definição:

- Toda propriedade precisa estar na definição. Propriedades desconhecidas são rejeitadas, então um erro de digitação não passa despercebido.
- As propriedades obrigatórias precisam estar presentes e não podem ser `null`.
- Uma propriedade opcional pode ser omitida ou enviada como `null` para indicar que está vazia.
- Cada valor precisa corresponder ao seu tipo.

Um evento `w:` cujo nome não está definido também é rejeitado. A API responde com `422` e cada problema identificado pelo caminho, como `properties.since`. O script de rastreamento descarta os eventos inválidos e, com a [depuração](/pt/docs/events/tracking-script/#debug) ativada, registra o motivo.

## Alterar ou excluir uma definição

Na aba **Workspace events**, selecione **Edit** ou **Delete** em uma definição. Pela API, use [Atualizar um evento do workspace](/pt/docs/api-reference/workspace-events/update/) e [Excluir um evento do workspace](/pt/docs/api-reference/workspace-events/delete/).

- Uma definição só verifica eventos novos. Os eventos já armazenados mantêm as propriedades que tinham.
- Alterar as propriedades substitui a lista inteira. Os sistemas que ainda enviarem uma propriedade removida recebem erros, então atualize-os antes ou ao mesmo tempo.
- Renomear muda o tipo a enviar. Os eventos armazenados mantêm o tipo antigo, e os eventos novos com o nome antigo são rejeitados.
- Excluir mantém os eventos armazenados, e os eventos novos desse tipo são rejeitados até que você o defina de novo.

## Limites

Um workspace pode definir tantos eventos do workspace quantos forem os [tipos de evento](/pt/docs/events/#limits) do plano: 100 no Pro e 1.000 no Business, sem limite no Custom. Um evento a mais retorna `422` com `code` `workspace_events_limit`. Cada evento do workspace tem até 50 propriedades. Os nomes têm até 100 caracteres, os nomes de propriedades até 64, os títulos até 120 e as descrições até 1.000.

## Veja também

  - [Rastreamento de eventos](/pt/docs/events/): Escopos, nomes e para onde vão os eventos.
  - [API de eventos do workspace](/pt/docs/api-reference/workspace-events/): Crie, liste, atualize e exclua definições.

---
Fonte: https://emailit.com/pt/docs/events/workspace-events/