Publica Datos Personales en Tu Web: El Patrón del Endpoint Firmado

Apple Health no tiene API. Ni Spotify te deja leer sin OAuth, ni tus otros proyectos pueden escribir en tu web sin más. El patrón que resuelve las tres cosas: un endpoint firmado al que tus dispositivos empujan datos.

Publicado el 22 de agosto de 2026


Views

264 views

Tiempo de lectura:8 min

Quería enseñar mis pasos diarios en mi web. Pensaba que sería mirar la documentación de la API de Apple Health, sacar un token y listo.

No existe esa API. Y descubrir por qué me llevó a un patrón que ahora uso para cuatro cosas distintas en este mismo sitio.

El malentendido de partida

Apple Health no tiene API de servidor. Ninguna. Los datos viven en el iPhone, iCloud los sincroniza cifrados de extremo a extremo, y no hay endpoint al que tu backend pueda llamar para preguntar "¿cuántos pasos dio hoy este usuario?". HealthKit es un framework on-device: solo una app instalada en el teléfono, con permiso explícito, puede leerlos.

Esto invierte la arquitectura entera. No es tu web la que lee de tu teléfono:

iPhone ──(empuja)──► tu endpoint ──► tu base de datos ──► tu web

Y en cuanto lo dibujas así, te das cuenta de que ya has resuelto ese problema antes. Es el mismo esquema que un webhook de GitHub, o que un side project mandando eventos a tu web principal. El dispositivo, o el proyecto, o el servicio, empuja. Tú recibes, validas y publicas.

Lo llamo el patrón del endpoint firmado, y tiene tres piezas.

Pieza 1: un endpoint que no se fía de nadie

Si algo de fuera va a escribir en tu web, ese endpoint es superficie de ataque. Como mínimo necesita:

Autenticación por secreto compartido, comparada en tiempo constante. Un === sobre strings filtra información por el tiempo que tarda en fallar:

import { timingSafeEqual } from "node:crypto"

export const safeCompare = (left: string | null, right: string): boolean => {
  if (!left) return false
  const a = Buffer.from(left)
  const b = Buffer.from(right)
  if (a.length !== b.length) return false
  return timingSafeEqual(a, b)
}

Validación estricta con rangos. No basta con "es un número": un número plausible. Nadie da 4 millones de pasos ni tiene 900 pulsaciones en reposo:

const bodySchema = z.object({
  steps: metric(0, 200_000),
  restingHeartRate: metric(25, 220),
}).strict()

Ese .strict() importa: rechaza campos que no has declarado, así nadie te llena la base de datos de basura arbitraria.

Un tope de tamaño en el cuerpo de la petición, y rate limiting si el endpoint es público. El mío es privado (solo lo llama mi teléfono), así que con el token basta.

Pieza 2: el dispositivo que empuja

Aquí es donde Apple te obliga a ser creativo. Las opciones reales para sacar datos de Health:

VíaCosteFiabilidad
Atajos (Shortcuts)GratisBuena, con matices
App con HealthKit propia99 $/año de cuenta de desarrolladorMáxima
Apps tipo Health Auto ExportPago único o suscripciónBuena
Wearable con API (Oura, Whoop, Garmin, Strava)DependeMáxima: es servidor a servidor
Exportar el XML de HealthGratisSolo una foto fija, no sirve para datos vivos

Elegí Atajos: cero código, cero coste, y una automación diaria que lee Health y hace el POST. Si tienes un wearable con API propia, ese camino es mejor — es servidor a servidor y no depende de que el teléfono esté despierto.

El campo de minas de Atajos

Aquí es donde perdí el tiempo, así que te ahorro los tropiezos:

"Buscar muestras médicas" no te da un número, te da una lista. Los pasos son cientos de muestras a lo largo del día. Necesitas una acción "Calcular estadísticas → Suma" después. Si mandas la lista directamente, tu endpoint recibe cualquier cosa menos un entero.

Para la frecuencia cardiaca en reposo, la muestra no es el valor. Hay que añadir "Obtener detalles de muestra médica → Valor" para quedarte con el número pelado. Sin eso te llega el texto con unidades.

Ordena y limita. "Límite 1" sin ordenar te devuelve una muestra arbitraria de la ventana. Ordena por fecha de inicio, descendente, y coge una.

Amplía la ventana temporal para lo que no es diario. Los pasos son de hoy, pero la frecuencia en reposo la calcula el reloj una vez al día y a veces tarde. Yo la busco en los últimos 7 días y me quedo con la más reciente.

Los tipos de dato salen en inglés aunque tengas el sistema en español. Buscas "Frecuencia cardíaca en reposo" y en el selector aparece Resting Heart Rate.

Las automaciones no se sincronizan entre dispositivos. Puedes crear el atajo en el Mac (se sincroniza por iCloud), pero el disparador de "cada día a las 23:45" solo se crea en el iPhone. Y ojo: las acciones de Health no existen en el Shortcuts de macOS, porque el Mac no tiene base de datos de salud. Lo comprobé buscando los identificadores en el framework del sistema y no hay ni uno.

Pieza 3: tolerancia, porque el mundo real es sucio

Este es el detalle que separa un juguete de algo que aguanta meses sin que lo toques.

Atajos serializa los valores como texto o con decimales según la acción que uses. Y cuando una muestra no existe todavía, no omite el campo: manda una cadena vacía. Mi primera versión validaba enteros estrictos, así que:

  • "8123" → rechazado.
  • 8123.7 → rechazado.
  • "" → convertido a 0 → fuera de rango → el envío completo fallaba, y perdía también los pasos por no tener el dato de pulsaciones.

Ese último caso es el peor, porque es silencioso y solo pasa algunos días. La versión que aguanta:

const metric = (min: number, max: number) =>
  z.union([z.number(), z.string(), z.null()])
    .optional()
    .transform((value) => {
      // Vacío significa "esa muestra no existe hoy", no cero.
      if (value === undefined || value === null || value === "") return
      return Math.round(Number(value))
    })
    .refine((value) =>
      value === undefined ||
      (Number.isFinite(value) && value >= min && value <= max)
    )

Y en el guardado, fusiona en vez de sobrescribir: un envío solo con pasos no debe borrar las pulsaciones de ayer.

La otra decisión que agradecerás: el widget se esconde solo si el dato tiene más de 36 horas. Una automación fallará antes o después — las de Atajos que leen Health pueden fallar con el móvil bloqueado — y es mucho mejor no mostrar nada que mostrar los pasos del martes pasado como si fueran de hoy.

Dejarlo abierto a más métricas

Si el endpoint tiene los nombres de las métricas incrustados en el código, añadir "horas de sueño" toca cuatro archivos. Un registro pequeño lo convierte en una línea:

export const HEALTH_METRICS = {
  restingHeartRate: { max: 220, min: 25 },
  steps: { max: 200_000, min: 0 },
  // sleepHours: { max: 24, min: 0 },
} as const

El esquema de validación se genera de ahí, y la UI recorre las métricas presentes. Añadir una es: entrada en el registro, su etiqueta en los archivos de traducción, y leerla en el atajo con ese mismo nombre de campo.

Lo mismo, cuatro veces

Cuando el patrón está montado, aparece por todas partes. En esta web hay ahora cuatro instancias del mismo esquema:

  • Visitas de mis side projects. Seis proyectos (SmoothUI, SparkBites, TheGridCN, UI Craft, Codevator y la doc de Mallard) firman con HMAC en su servidor y mandan cada visita al feed de actividad de aquí. Nunca desde el navegador: el secreto se filtraría en el primer view source.
  • PRs y estrellas de GitHub, por webhook con firma verificada.
  • Los datos de salud de este artículo.
  • Las preguntas del AMA, que aterrizan en una base de datos de Notion y se publican cuando las respondo.

Distintas fuentes, distintos transportes, misma forma: alguien de fuera empuja, yo valido con rangos y secreto, guardo en Redis y publico solo lo grueso.

Lo que no publicaría

Un aviso, porque es fácil emocionarse: esto acaba en una web pública, indexada y archivada.

Yo publico pasos y pulsaciones en reposo. No publico peso, variabilidad cardiaca, ni nada que huela a historial médico. La geolocalización de las visitas la guardo a nivel de ciudad y sin IPs — ni siquiera las almaceno para calcularla, uso las cabeceras que ya trae el CDN. Y en el AMA, la pregunta no aparece en el feed hasta que está respondida.

La regla que aplico: si un desconocido con ese dato en la mano puede hacer algo con él, no va. Si solo le sirve para saber que estoy vivo y ando bastante, va.

Merece la pena

El widget dice "Hoy — 7.949 pasos, 70 ppm en reposo" en una esquina, y casi nadie va a fijarse.

Pero el camino hasta ahí me dejó tres cosas: entender por qué HealthKit es on-device y no un descuido de Apple, un patrón que ya reutilicé para seis proyectos empujando a un mismo sitio, y la costumbre de preguntarme, antes de publicar cualquier dato personal, si lo querría en manos de un desconocido.

Para una web personal, que es un sitio donde enseñas quién eres, eso último es la parte importante.