API di Natom

Integra le push nei tuoi sistemi: invio campagne, gestione siti e statistiche via HTTP. Disponibili dal piano Pro.

Autenticazione

Genera la tua chiave dalla dashboard: Piano → API → Genera chiave. Ogni richiesta la passa come bearer token:

Authorization: Bearer nk_live_xxxxxxxx...

Base URL: https://api.natom.app. Tutte le richieste e risposte sono JSON. La chiave dà accesso alle risorse del tuo account (siti, campagne, audience, statistiche); non può toccare fatturazione o impostazioni account.

Tratta la chiave come una password: se compromessa, rigenerala dalla dashboard (quella vecchia smette di funzionare subito).

Endpoint principali

GET /api/sites

I tuoi siti con il conteggio iscritti attivi.

curl https://api.natom.app/api/sites \
  -H "Authorization: Bearer nk_live_..."

POST /api/campaigns

Crea (e opzionalmente invia) una campagna. Il caso d'uso tipico: il tuo CMS pubblica un articolo e chiama questo endpoint.

curl -X POST https://api.natom.app/api/campaigns \
  -H "Authorization: Bearer nk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "siteIds": [12],
    "title": "Titolo della push",
    "body": "Testo della notifica",
    "url": "https://tuosito.com/articolo",
    "imageUrl": "https://tuosito.com/cover.jpg",
    "segmentId": 34,
    "send": true
  }'

Campo	Tipo	Note
siteIds	int[]	uno o più siti (stessa push su tutti). Con più siti, niente segmentId
title, body, url	string	obbligatori
iconUrl, imageUrl	string	opzionali
segmentId	int	invia solo a un'audience (un solo sito)
scheduledAt	ISO 8601	programmazione futura; esclude send:true
ttlSeconds	int	scadenza consegna, default 86400
send	bool	true = parte subito; false = bozza

POST /api/campaigns/:id/send

Invia una bozza o anticipa una campagna schedulata.

GET /api/campaigns/:id

Stato e statistiche di una campagna: impressions_est (stima da campionamento), clicks, status.

GET /api/campaigns

Le ultime 200 campagne dell'account, con dominio e statistiche.

GET /api/sites/:id/segments

Le audience del sito con il conteggio membri (per trovare il segmentId da usare negli invii mirati).

GET /api/stats?days=30

Andamento iscritti giorno per giorno, tile riassuntive, ripartizioni per paese, dispositivo, browser e OS, membri per audience.

WordPress

Il plugin Natom Push usa due endpoint dedicati, pensati per chi lavora dentro l'editor e non conosce gli ID interni: il sito viene riconosciuto dal dominio.

Il plugin non usa la chiave API di questa pagina, ma una chiave dedicata (nw_...) inclusa in tutti i piani, che vale solo per i due endpoint qui sotto. La generi dalla dashboard: Siti › Codice › riquadro WordPress, dove scarichi anche il plugin.

GET /api/wp/context

Elenca i siti dell'account con le rispettive audience. Serve alla pagina impostazioni del plugin per verificare la chiave e popolare i menu.

POST /api/wp/push

Invia subito una notifica. Il sito si ricava dal campo domain o, se assente, dall'host dell'URL (il prefisso www. viene ignorato).

{
  "title": "Titolo della notifica",
  "body": "Testo della notifica",
  "url": "https://tuosito.it/articolo",
  "domain": "tuosito.it",
  "imageUrl": "https://tuosito.it/immagine.jpg",
  "segment": "Cronaca"
}

L'audience si indica con segmentId oppure con segment (il nome, senza distinzione fra maiuscole e minuscole). Senza audience la push va a tutti gli iscritti del sito.

Risposte ed errori

Codici standard: 200 ok, 400 parametri non validi, 401 chiave mancante o revocata, 403 risorsa non tua o endpoint non disponibile via API, 404 non trovato. Il corpo d'errore è {"error": "descrizione"}.

Buone pratiche

Idempotenza degli invii: crea la campagna con send:false, verifica la risposta, poi chiama /send. Eviti doppi invii in caso di retry.
Per le push automatiche da CMS valuta prima l'RSS automatico: zero codice, stesso risultato.
Le statistiche delle impression sono campionate per design: usa impressions_est, non il campo grezzo.

Serve un endpoint che non c'è? Scrivi a support@natom.app.