API per il monitoraggio del bebè: registra dal tuo codice

Il biberon è tiepido e il bambino si è finalmente sistemato sulla tua spalla. Il telefono con l'app di monitoraggio, ovviamente, è in carica nell'altra stanza. Intanto in uno sgabuzzino del corridoio ronza un Raspberry Pi, e una parte testarda del tuo cervello sta già pensando: potrei semplicemente mandare una richiesta POST.

Puoi farlo davvero. nappi ha un'API REST pubblica che qualsiasi famiglia con nappi Premium può usare con i propri dati. Crei una chiave personale, la invii con ogni richiesta e i tuoi script possono registrare pannolini, biberon, allattamento, tiralatte, sonno, attività e crescita, avviare e fermare i timer e leggere le ultime registrazioni. La specifica completa è pubblica su https://api.nappi.app/v1/openapi.json.

nappi ha un'API?

Sì. L'URL di base è https://api.nappi.app/v1, e ogni chiamata è un normale HTTPS con JSON in entrata e in uscita.

L'API è descritta da un documento OpenAPI 3.1, il formato standard e indipendente dal linguaggio per descrivere le API HTTP.¹ Dai la specifica in pasto a un generatore di codice o a Postman e ottieni un client funzionante, senza tirare a indovinare i nomi dei campi.

Se preferisci cliccare invece di leggere JSON, il riferimento interattivo dell'API mostra ogni endpoint con esempi. Per leggerlo non serve un account. Accedendo, il pannello di prova elenca le tue chiavi, così puoi inviare richieste vere direttamente dalla pagina.

L'API è ancora in beta, quindi il formato delle richieste potrebbe cambiare man mano che vediamo come la usano le famiglie. Il riferimento viene generato dall'API in produzione, perciò corrisponde sempre a quello che è online.

Come si ottiene una chiave per l'API di nappi?

Le chiavi si creano sul web, non nell'app:

1. Accedi a nappi.app/app/connections, meglio da un computer.
2. Dai alla chiave un nome che riconoscerai ("Pi della cameretta", "schermo in cucina") e scegli quanto deve durare: 30 giorni, 90 giorni o 1 anno.
3. Copiala. Inizia con nappi_ e la vedrai una volta sola.

Ogni richiesta la invia nell'intestazione Authorization come Bearer nappi_YOUR_KEY, il formato dei token bearer definito dalla RFC 6750.² Chi possiede un token bearer può usarlo, quindi tratta il tuo come una password.

Qualche regola prima di costruire qualcosa:

• L'API fa parte di nappi Premium. Un abbonamento copre tutta la famiglia, e le chiavi smettono di funzionare finché la famiglia non ha Premium.
• Solo chi si prende cura del bambino può creare chiavi. Osservatori e ospiti no.
• Puoi avere fino a 10 chiavi contemporaneamente.
• Ti mandiamo un'email una settimana prima che scada una chiave che stai usando.

Cosa può fare l'API di nappi?

Otto endpoint, tutti limitati ai bambini della tua famiglia:

Metodo	Percorso	Cosa fa
GET	/v1/babies	Elenca i tuoi bambini e i loro ID
GET	/v1/babies/{babyId}/entries/latest	L'ultima registrazione di ogni tipo
GET	/v1/babies/{babyId}/entries/latest/{type}	L'ultima registrazione di un tipo
POST	/v1/babies/{babyId}/entries	Salva una registrazione conclusa
GET	/v1/babies/{babyId}/timers	I timer di sonno, allattamento e tiralatte attivi ora
GET	/v1/babies/{babyId}/status	Timer e ultime registrazioni in una sola lettura
POST	/v1/babies/{babyId}/timers/{timerType}/start	Avvia un timer
POST	/v1/babies/{babyId}/timers/{timerType}/stop	Ferma un timer e salva la registrazione

Anche quello che manca conta. Non puoi ancora registrare farmaci o cibi solidi, anche se puoi leggere l'ultimo di ciascuno. E l'API restituisce solo la registrazione più recente per tipo, non tutto lo storico, senza un modo per modificare o eliminare le registrazioni.

La prima registrazione con curl

Per prima cosa trova l'ID del tuo bambino:

curl https://api.nappi.app/v1/babies \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Ricevi un array:

[
  {
    "id": "BABY_ID",
    "name": "Phoebe",
    "birth_date": "2026-05-02",
    "timezone": "America/New_York"
  }
]

Poi registra un pannolino bagnato:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/entries \
  -H "Authorization: Bearer nappi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "diaper", "diaper_type": "wet"}'

Un 201 vuol dire che è registrato, e il corpo della risposta ti dice cosa è stato creato:

{ "id": "ENTRY_ID", "type": "diaper", "duplicate": false }

L'intestazione Idempotency-Key è facoltativa. Noi però non la toglieremmo mai da un'automazione. Se la connessione cade e lo script riprova con la stessa chiave, la seconda richiesta restituisce 200 con "duplicate": true e non viene scritto niente di nuovo, così non ti ritrovi con due pannolini.

Una registrazione fatta dall'API è una normale registrazione di nappi. Tutti in famiglia la vedono nell'app, ed è attribuita a te, cioè a chi ha creato la chiave.

Gli orari sono in formato ISO 8601 con lo scostamento da UTC, come 2026-10-21T14:30:00-04:00, e se mancano si usa l'ora attuale. Le quantità sono in millilitri, a meno che tu non invii "unit": "oz".

Quali tipi di registrazione puoi salvare?

POST /entries accetta un type più i campi che servono a quel tipo:

type	Obbligatorio	Facoltativo
diaper	diaper_type: wet, poo, mixed o dry	time
potty	outcome: potty, accident o sat_dry	time
bottle	nient'altro	amount, unit (ml o oz), bottle_type (per esempio breast_milk o formula), time
nursing	nient'altro	side, left_minutes, right_minutes, duration_minutes, time
pumping	nient'altro	amount, left_amount, right_amount, unit, duration_minutes, time
sleep	start_time, end_time	sleep_type (nap o night)
activity	activity_type (per esempio bath o tummy_time)	duration_minutes, time
growth	nient'altro	weight, weight_unit (kg o lb), length, head, length_unit (cm o in), time

Un biberon da 4 once di latte artificiale si scrive così:

{ "type": "bottle", "amount": 4, "unit": "oz", "bottle_type": "formula" }

Se ometti sleep_type, nappi decide tra pisolino e notte in base agli orari diurni del bambino, come fa l'app. Per qualcosa che è ancora in corso, come un pisolino iniziato da poco, usa un timer.

Avviare e fermare il timer del sonno da uno script

I timer sono gli stessi condivisi che tutta la famiglia vede nell'app. Per avviare un pisolino:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start \
  -H "Authorization: Bearer nappi_YOUR_KEY"

Fermarlo salva la registrazione del sonno, esattamente come quando lo fermi dal telefono:

curl -X POST https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop \
  -H "Authorization: Bearer nappi_YOUR_KEY"

timerType può essere sleep, nursing o pumping. Avviare un timer già in corso non cambia nulla e te lo restituisce con "status": "already_running". Fermarlo quando non c'è niente in corso restituisce 409 con il codice timer_not_running, il che rende facile costruire un unico pulsante on/off.

Funziona nei due sensi. GET /timers restituisce anche i timer che qualcuno ha avviato da un telefono, da un orologio o con Alexa. Quelli dell'allattamento accettano un side facoltativo, e con start_time puoi retrodatare l'inizio fino a 48 ore.

Un piccolo script: quanto tempo dall'ultima poppata

Questo script Node (Node 18 o successivo, nessun pacchetto) stampa quanto tempo è passato dall'ultima volta che il bambino ha mangiato, contando biberon e allattamento. Salvalo come last-feed.mjs ed eseguilo con node last-feed.mjs:

const KEY = "nappi_YOUR_KEY";
const BABY = "BABY_ID";

const res = await fetch(
  `https://api.nappi.app/v1/babies/${BABY}/status?types=bottle,nursing`,
  { headers: { Authorization: `Bearer ${KEY}` } },
);
if (!res.ok) throw new Error(`nappi returned ${res.status}`);
const { timers, latest } = await res.json();

const feeds = [latest.bottle, latest.nursing].filter(Boolean);
if (timers.some((t) => t.type === "nursing")) {
  console.log("Nursing right now");
} else if (feeds.length === 0) {
  console.log("No feeds logged yet");
} else {
  const last = Math.max(...feeds.map((f) => new Date(f.time).getTime()));
  const min = Math.round((Date.now() - last) / 60000);
  console.log(`Last feed ${Math.floor(min / 60)}h ${min % 60}m ago`);
}

Collegalo a un cron e a uno schermo e-ink sul frigo, e nessuno dovrà sbloccare il telefono alle 3 di notte per capire quando è stato l'ultimo biberon.

Interrogare l'API senza superare i limiti

Ogni chiave ha 12 letture e 30 scritture al minuto. Se le superi ricevi 429 Too Many Requests, con un'intestazione Retry-After che indica quanti secondi aspettare.³⁴

Per una dashboard, interroga /status al massimo una volta al minuto. Le sue risposte includono un ETag. Rimandalo come If-None-Match e ricevi 304 Not Modified, senza corpo, finché qualcosa non cambia.⁴

C'è un'eccezione. Mentre un timer è in corso il tempo trascorso cambia ogni secondo, quindi /status restituisce sempre un 200 completo.

Comandi Rapidi su iPhone: un biberon con un tocco

Qui il computer non serve. Nell'app Comandi Rapidi aggiungi l'azione Ottieni contenuti dell'URL e impostala così:

• URL: https://api.nappi.app/v1/babies/BABY_ID/entries
• Metodo: POST
• Intestazioni: Authorization con valore Bearer nappi_YOUR_KEY
• Richiedi corpo: JSON, con type su bottle, amount su 120 (come Numero) e unit su ml

È passando il metodo a POST che compare il campo "Richiedi corpo", e JSON è una delle sue opzioni.⁵ Metti il comando nella schermata Home, oppure aggiungi prima un passaggio "Richiedi input" per scrivere la quantità ogni volta.

L'app nappi registra già a voce con Siri. Questa strada serve per le cose su misura, come un pulsante "120 ml di latte artificiale" da un tocco o un'automazione che parte quando il telefono sfiora un'etichetta NFC attaccata allo scolabiberon.

Home Assistant: l'integrazione o semplici comandi REST

Se Home Assistant gestisce la tua casa, parti dall'integrazione. È open source con licenza MIT (nappi-app/nappi-home-assistant su GitHub) e la trovi nello store predefinito di HACS cercando "nappi". Interroga /status una volta ogni 2 minuti per bambino e ti dà pulsanti di registrazione, interruttori per i timer e sensori dell'ultima registrazione senza toccare YAML. La nostra guida a Home Assistant spiega l'installazione passo passo, insieme ad alcune automazioni da copiare.

Preferisci YAML? L'integrazione RESTful Command di Home Assistant può chiamare l'API direttamente, con le tue intestazioni e un corpo JSON.⁶ Questi due comandi avviano e fermano un pisolino:

# secrets.yaml
nappi_auth: "Bearer nappi_YOUR_KEY"

# configuration.yaml
rest_command:
  nappi_sleep_start:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/start"
    method: post
    headers:
      Authorization: !secret nappi_auth
  nappi_sleep_stop:
    url: "https://api.nappi.app/v1/babies/BABY_ID/timers/sleep/stop"
    method: post
    headers:
      Authorization: !secret nappi_auth

Richiama rest_command.nappi_sleep_start da un pulsante accanto alla culla e il timer del pisolino parte sui telefoni di tutta la famiglia. La pagina sulla casa smart elenca gli altri modi per collegarsi, tra cui Alexa e Google Home.

È sicuro dare a uno script accesso ai dati del mio bambino?

Niente può leggere i dati della tua famiglia tramite l'API finché non crei una chiave. Ogni chiave appartiene a una persona che si prende cura del bambino, in una sola famiglia, e nappi ne conserva solo un hash SHA-256. Per questo la vedi una volta e poi mai più.

Puoi revocare una chiave quando vuoi su nappi.app/app/connections, oppure nell'app in Opzioni → Collegamenti → Casa smart. Una chiave smette di funzionare anche quando scade, o se esci dalla famiglia o diventi osservatore.

Una chiave può registrare e leggere per la tua famiglia come fai tu nell'app, timer compresi. Non può modificare il tuo account né vedere la tua password. Tienila lontana dai repository Git pubblici e dagli screenshot, e revocala appena finisce in giro.

Provalo stasera: crea una chiave da 30 giorni, lancia il curl su /babies e registra un pannolino di prova. Quando compare sul telefono del tuo partner, eliminalo da lì, perché l'API non può farlo.

Domande frequenti

L'API di nappi costa qualcosa in più?

Non ha un costo a parte, ma l'API fa parte di nappi Premium. Un abbonamento copre tutti in famiglia. Leggere la documentazione e la specifica OpenAPI è gratis per chiunque.

Posso esportare tutto lo storico tramite l'API?

No. L'API restituisce l'ultima registrazione di ogni tipo e i timer in corso. Per lo storico completo usa l'esportazione CSV nell'app nappi.

Funziona con gemelli o fratelli?

Sì. GET /v1/babies restituisce tutti i bambini della tua famiglia, e ogni altra chiamata indica un bambino tramite il suo ID. Esegui lo script una volta per ogni bambino.

Posso registrare i farmaci tramite l'API?

Non ancora. Puoi leggere l'ultima registrazione di un farmaco, ma registrare farmaci o cibi solidi non è supportato, quindi per quelli continua a usare l'app.