# Eventos pelo servidor

Envie eventos de negócio com identidade, data e ID lógico estáveis.

## Enviar um evento

Use analytics:write. O siteId do corpo precisa corresponder ao site da rota, e a URL deve pertencer a um hostname autorizado do site.


### SDK Node.js



```ts
import { Pulsant } from '@pulsant/sdk';

const pulsant = new Pulsant({
  baseUrl: 'https://api.pulsant.app',
  key: process.env.PULSANT_SECRET_KEY!,
  siteId: process.env.PULSANT_SITE_ID!,
});

await pulsant.track({
  id: 'signup_123456',
  name: 'signup',
  url: 'https://seusite.com/cadastro',
  sessionId: 'session_123456',
  properties: { plan: 'basic' },
});
```


### HTTP / fetch



```ts
const siteId = process.env.PULSANT_SITE_ID!;
const response = await fetch(
  `https://api.pulsant.app/v1/account/sites/${siteId}/events`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.PULSANT_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      version: 1, siteId, id: 'signup_123456',
      kind: 'event', name: 'signup',
      occurredAt: new Date().toISOString(),
      url: 'https://seusite.com/cadastro',
      sessionId: 'session_123456',
      properties: { plan: 'basic' },
    }),
  },
);
if (!response.ok) throw new Error(`Evento recusado: ${response.status}`);
```

> Disponibilidade do SDK: @pulsant/sdk é um pacote local do monorepo. Para um backend externo, use HTTP; não há instalação npm pública anunciada neste guia.



## Campos e limites

Nome e propriedades devem representar a ação de negócio, sem dados pessoais ou conteúdo de formulários.


| Campo | Regra |
| --- | --- |
| id | ID lógico estável de 8 a 128 caracteres; reutilize no retry |
| sessionId | Sessão observada; não gere outra por evento |
| occurredAt | ISO 8601; até 72 horas atrás ou 5 minutos no futuro |
| name | Até 80 caracteres |
| properties | Até 32 propriedades primitivas; texto até 500 caracteres |
| Evento completo | Até 8 KiB |



## Eventos no navegador

Para eventos de interface, use o tracker instalado no site. Ele cuida da sessão e envia as informações permitidas pelas configurações do site.


```js
await window.pulsant?.('track', 'signup', { plan: 'basic' }, { id: 'signup_123456' });
```

- [Eventos e navegação SPA](/events)
- [Identidade e privacidade](/privacy)

## Retries sem duplicação

Reenvie o mesmo ID para a mesma ação. A resposta da coleta informa accepted, duplicate e id. Um evento novo deve receber um novo ID.


```json
{
  "accepted": true,
  "duplicate": false,
  "id": "signup_123456"
}
```