# Invia eventi dal tuo backend

> Registra eventi di workspace e personalizzati dai tuoi server con l’API degli eventi, uno alla volta o in batch, con una chiave API di soli eventi.

Invia gli eventi dai tuoi server per tutto ciò che non deve dipendere dal browser del visitatore, come ordini, pagamenti, modifiche agli abbonamenti o eventi da un back office. Questa pagina mostra come inviare un evento, come inviarne molti e come gestire gli errori.

## Prima di iniziare

- L’invio di eventi è incluso nei piani Pro, Business e Custom. Un workspace Pro può usare 100 tipi di evento e un workspace Business 1000. Vedi [Limiti](/it/docs/events/#limits).
- Crea una chiave API con il permesso **Events Only** in **Email API → API Keys**. Può inviare eventi e nient’altro: non può leggere i tuoi dati, gestire le definizioni degli eventi né inviare email. Funziona anche una chiave con **Full Access**. Vedi [Chiavi API](/it/docs/developers/api-keys/#scopes).
- Per inviare eventi di workspace, prima [definiscili](/it/docs/events/workspace-events/). Gli eventi personalizzati non richiedono configurazione.

## Invia un evento

Chiama [Invia un evento](/it/docs/api-reference/events/send/) con il `type` dell’evento, le sue `properties` e la persona a cui si riferisce:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'
```

- Il campo `email` collega l’evento al contatto con quell’indirizzo. Se conosci già l’ID del contatto, invia invece `contact_id`.
- Il campo `occurred_at` indica quando è avvenuto l’evento, ad esempio quando invii eventi da una coda. Omettilo per usare l’ora attuale.
- La risposta è `201` con l’evento salvato e il suo ID `evt_`. Una chiave di soli eventi riceve l’evento senza `data`.

## Invia più eventi insieme

[Invia eventi in batch](/it/docs/api-reference/events/batch/) accetta fino a 100 eventi in una richiesta, ed è adatto a importazioni e sincronizzazioni programmate:

```bash
curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } }
    ]
  }'
```

Un batch è tutto o niente: se un evento non è valido, non ne viene salvato nessuno. La risposta `422` elenca ogni problema sotto `events.<index>`, così puoi correggere o togliere quegli eventi e inviare di nuovo il batch.

## Gestisci gli errori

| Stato | Significato | Cosa fare |
| --- | --- | --- |
| `201` | Salvato. | Niente. |
| `400` | Il corpo non è un oggetto JSON, oppure il batch è vuoto o ha più di 100 eventi. | Correggi la richiesta. |
| `401` | La chiave API manca o è sbagliata. | Controlla la chiave. |
| `403` | Il permesso della chiave non consente di inviare eventi, oppure il workspace è su Pay as you go (`"error": "plan_required"`). | Usa una chiave di soli eventi o con accesso completo, oppure passa a Pro o Business. |
| `422` | Un evento non è valido: un evento `w:` non definito, una proprietà del tipo sbagliato, un `contact_id` sconosciuto, una data oltre 24 ore nel futuro o un nuovo tipo di evento quando il workspace usa già il numero di tipi previsto dal piano. L’oggetto `errors` indica ogni campo. | Correggi l’evento, oppure passa a un piano superiore per avere più tipi di evento. Se lo ritenti senza modifiche, non riesce di nuovo. |
| `5xx` | Un problema temporaneo da parte di Emailit. | Ritenta con backoff. |

Gli eventi non hanno una chiave di idempotenza, quindi ritentare una richiesta andata a buon fine salva l’evento due volte. Metti un tuo ID nelle proprietà, come `order_id`, così chi legge gli eventi può riconoscere i duplicati.

## Controlla che gli eventi arrivino

Apri **Email API → Events**. La scheda **Log** elenca in alto i nuovi eventi; imposta **Scope** su **Custom** o **Workspace** per nascondere gli eventi di sistema. Seleziona un evento per vederne le proprietà, il contatto a cui appartiene e la provenienza. Gli eventi collegati a un contatto compaiono anche nella sezione **Activity log** del contatto.

## Vedi anche

  - [Tracciamento degli eventi](/it/docs/events/): Ambiti, nomi e dove finiscono gli eventi.
  - [Script di tracciamento](/it/docs/events/tracking-script/): Invia eventi dal tuo sito web.
  - [Invia un evento](/it/docs/api-reference/events/send/): Tutti i parametri e le risposte.
  - [Chiavi API](/it/docs/developers/api-keys/): Crea una chiave di soli eventi.

---
Fonte: https://emailit.com/it/docs/events/send-events/