API de seguimiento del bebé: registra desde tu código

El biberón está tibio y el bebé por fin se acomodó en tu hombro. El celular con la app de seguimiento, cómo no, está cargando en el otro cuarto. Mientras tanto hay una Raspberry Pi zumbando en el clóset del pasillo, y una parte terca de tu cerebro ya está pensando: podría mandar un POST y listo.

Puedes hacerlo. nappi tiene una API REST pública que cualquier familia con nappi Premium puede usar con sus propios datos. Creas una clave personal, la mandas en cada solicitud y tus scripts pueden registrar pañales, biberones, lactancia, extracción, sueño, actividades y crecimiento, iniciar y detener temporizadores y leer los registros más recientes. La especificación completa es pública en https://api.nappi.app/v1/openapi.json.

¿nappi tiene una API?

Sí. La URL base es https://api.nappi.app/v1, y cada llamada es HTTPS normal, con JSON de ida y de vuelta.

La API está descrita en un documento OpenAPI 3.1, el formato estándar e independiente del lenguaje para describir APIs HTTP.¹ Le pasas la especificación a un generador de código o a Postman y obtienes un cliente que funciona, sin adivinar nombres de campos.

Si prefieres hacer clic en vez de leer JSON, la referencia interactiva de la API muestra cada endpoint con ejemplos. Para leerla no necesitas cuenta. Iniciar sesión solo agrega tus claves al panel de pruebas, para que puedas mandar solicitudes reales desde la misma página.

La API todavía está en beta, así que el formato de las solicitudes puede cambiar a medida que vemos cómo la usan las familias. La referencia se genera a partir de la API en vivo, por lo que siempre coincide con lo que está publicado.

¿Cómo consigo una clave de la API de nappi?

Las claves se crean en la web, no en la app:

1. Inicia sesión en nappi.app/app/connections, mejor desde una computadora.
2. Ponle a la clave un nombre que reconozcas después ("Pi del cuarto del bebé", "panel de la cocina") y elige cuánto dura: 30 días, 90 días o 1 año.
3. Cópiala. Empieza con nappi_ y solo la vas a ver una vez.

Cada solicitud la manda en el encabezado Authorization como Bearer nappi_YOUR_KEY, el formato de token bearer que define el RFC 6750.² Quien tenga un token bearer puede usarlo, así que trata el tuyo como una contraseña.

Algunas reglas antes de construir cualquier cosa:

• La API es parte de nappi Premium. Una suscripción cubre a todo el hogar, y las claves dejan de funcionar mientras la familia no tenga Premium.
• Solo los cuidadores pueden crear claves. Los observadores e invitados no.
• Puedes tener hasta 10 claves a la vez.
• Te mandamos un correo una semana antes de que venza una clave que estás usando.

¿Qué puede hacer la API de nappi?

Ocho endpoints, todos limitados a los bebés de tu hogar:

Método	Ruta	Qué hace
GET	/v1/babies	Lista tus bebés y sus IDs
GET	/v1/babies/{babyId}/entries/latest	El registro más reciente de cada tipo
GET	/v1/babies/{babyId}/entries/latest/{type}	El registro más reciente de un tipo
POST	/v1/babies/{babyId}/entries	Guarda un registro terminado
GET	/v1/babies/{babyId}/timers	Temporizadores de sueño, lactancia y extracción en curso
GET	/v1/babies/{babyId}/status	Temporizadores y registros recientes en una sola lectura
POST	/v1/babies/{babyId}/timers/{timerType}/start	Inicia un temporizador
POST	/v1/babies/{babyId}/timers/{timerType}/stop	Detiene un temporizador y guarda el registro

Lo que falta también importa. Todavía no puedes registrar medicamentos ni sólidos, aunque sí puedes leer el más reciente de cada uno. Y la API solo devuelve el registro más nuevo de cada tipo, no todo tu historial, y no tiene forma de editar ni borrar registros.

Tu primer registro con curl

Empieza por buscar el ID de tu bebé:

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

Recibes un arreglo:

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

Después registra un pañal mojado:

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 significa que quedó registrado, y el cuerpo te dice qué se creó:

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

El encabezado Idempotency-Key es opcional. Aun así, nosotros nunca lo dejaríamos fuera de una automatización. Si se corta la conexión y tu script reintenta con la misma clave, la segunda solicitud devuelve 200 con "duplicate": true y no se escribe nada nuevo, así que no terminas con dos pañales.

Un registro hecho desde la API es un registro normal de nappi. Todos en tu hogar lo ven en la app, y queda a tu nombre, como la persona que creó la clave.

Las horas van en ISO 8601 con desfase respecto a UTC, como 2026-10-21T14:30:00-04:00, y si no mandas ninguna se usa la hora actual. Las cantidades van en mililitros, salvo que mandes "unit": "oz".

¿Qué tipos de registro puedes guardar?

POST /entries recibe un type más los campos que ese tipo necesite:

type	Obligatorio	Opcional
diaper	diaper_type: wet, poo, mixed o dry	time
potty	outcome: potty, accident o sat_dry	time
bottle	nada más	amount, unit (ml u oz), bottle_type (por ejemplo breast_milk o formula), time
nursing	nada más	side, left_minutes, right_minutes, duration_minutes, time
pumping	nada más	amount, left_amount, right_amount, unit, duration_minutes, time
sleep	start_time, end_time	sleep_type (nap o night)
activity	activity_type (por ejemplo bath o tummy_time)	duration_minutes, time
growth	nada más	weight, weight_unit (kg o lb), length, head, length_unit (cm o in), time

Un biberón de 4 onzas de fórmula se ve así:

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

Si no mandas sleep_type, nappi decide si fue siesta o noche según el horario de día del bebé, igual que la app. Para algo que todavía está pasando, como una siesta en curso, usa un temporizador.

Iniciar y detener un temporizador de sueño desde un script

Los temporizadores son los mismos compartidos que todo tu hogar ve en la app. Para iniciar una siesta:

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

Al detenerlo se guarda el registro de sueño, exactamente como si lo detuvieras en el celular:

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

timerType puede ser sleep, nursing o pumping. Iniciar un temporizador que ya está corriendo no cambia nada y te lo devuelve con "status": "already_running". Detenerlo cuando no hay nada corriendo devuelve 409 con el código timer_not_running, lo que facilita armar un solo botón que funcione como interruptor.

Funciona en ambas direcciones. GET /timers también devuelve los temporizadores que alguien inició en un celular, en un reloj o con Alexa. Los de lactancia aceptan un side opcional, y con start_time puedes poner un inicio hasta 48 horas atrás.

Un script pequeño: cuánto pasó desde la última toma

Este script de Node (Node 18 o más reciente, sin paquetes) muestra hace cuánto comió el bebé por última vez, contando biberones y lactancia. Guárdalo como last-feed.mjs y córrelo 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`);
}

Conéctalo a un cron y a una pantalla de tinta electrónica en el refrigerador, y nadie tiene que desbloquear el celular a las 3 de la mañana para averiguar cuándo fue el último biberón.

Consultar sin chocar con el límite de solicitudes

Cada clave tiene 12 lecturas y 30 escrituras por minuto. Si te pasas, recibes 429 Too Many Requests con un encabezado Retry-After que dice cuántos segundos esperar.³⁴

Para un panel, consulta /status como máximo una vez por minuto. Sus respuestas traen un ETag. Mándalo de vuelta como If-None-Match y vas a recibir 304 Not Modified, sin cuerpo, hasta que algo cambie.⁴

Hay una excepción. Mientras corre un temporizador, su tiempo transcurrido cambia cada segundo, así que /status siempre devuelve un 200 completo.

Atajos de iPhone: registra un biberón con un toque

Para esto no necesitas computadora. En la app Atajos, agrega la acción Obtener contenido de URL y configúrala así:

• URL: https://api.nappi.app/v1/babies/BABY_ID/entries
• Método: POST
• Encabezados: Authorization con el valor Bearer nappi_YOUR_KEY
• Solicitar cuerpo: JSON, con type en bottle, amount en 120 (como Número) y unit en ml

Al cambiar el método a POST aparece el campo "Solicitar cuerpo", y JSON es una de sus opciones.⁵ Pon el atajo en tu pantalla de inicio, o agrega antes un paso "Solicitar entrada" para escribir la cantidad cada vez.

La app de nappi ya permite registrar por voz con Siri. Este camino es para lo personalizado, como un botón de un toque para "120 ml de fórmula" o una automatización que se activa cuando el celular toca una etiqueta NFC pegada en el escurridor de biberones.

Home Assistant: la integración o comandos REST simples

Si Home Assistant maneja tu casa, empieza por la integración. Es de código abierto con licencia MIT (nappi-app/nappi-home-assistant en GitHub), y la encuentras en la tienda predeterminada de HACS buscando "nappi". Consulta /status una vez cada 2 minutos por bebé y te da botones de registro, interruptores de temporizador y sensores del último registro sin tocar YAML. Nuestra guía de Home Assistant explica la instalación paso a paso, junto con algunas automatizaciones que vale la pena copiar.

¿Prefieres YAML? La integración RESTful Command de Home Assistant puede llamar a la API directamente, con tus propios encabezados y un cuerpo JSON.⁶ Estos dos comandos inician y detienen una siesta:

# 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

Llama a rest_command.nappi_sleep_start desde un botón junto a la cuna y el temporizador de siesta arranca en todos los celulares de la familia. La página de hogar inteligente reúne las otras formas de conectarte, incluidas Alexa y Google Home.

¿Es seguro darle a un script acceso a los datos de mi bebé?

Nada puede leer los datos de tu familia a través de la API hasta que crees una clave. Cada clave pertenece a un cuidador en un hogar, y nappi solo guarda un hash SHA-256 de ella. Por eso la ves una vez y nunca más.

Puedes revocar una clave cuando quieras en nappi.app/app/connections, o en la app en Ajustes → Conexiones → Hogar inteligente. Una clave también deja de funcionar cuando vence, o si sales del hogar o pasas a ser observador.

Una clave puede registrar y leer para tu familia igual que tú en la app, temporizadores incluidos. No puede cambiar tu cuenta ni ver tu contraseña. No la subas a repositorios públicos de Git ni la muestres en capturas de pantalla, y revócala apenas se filtre.

Pruébalo esta noche: crea una clave de 30 días, corre el curl de /babies y registra un pañal de prueba. Cuando aparezca en el celular de tu pareja, bórralo desde ahí, porque la API no puede.

Preguntas frecuentes

¿La API de nappi cuesta extra?

No tiene un cobro aparte, pero la API es parte de nappi Premium. Una suscripción cubre a todos en tu hogar. Leer la documentación y la especificación OpenAPI es gratis para cualquiera.

¿Puedo exportar todo mi historial con la API?

No. La API devuelve el registro más reciente de cada tipo y los temporizadores en curso. Para tu historial completo, usa la exportación CSV de la app de nappi.

¿Funciona con gemelos o hermanos?

Sí. GET /v1/babies devuelve todos los bebés de tu hogar, y cada una de las demás llamadas indica un bebé por su ID. Corre tu script una vez por bebé.

¿Puedo registrar medicamentos con la API?

Todavía no. Puedes leer el registro de medicamento más reciente, pero registrar medicamentos o sólidos no está disponible, así que sigue usando la app para eso.