¿Cómo dejo que mis usuarios conecten sus datos de salud con un código QR?

Muestra a cada usuario un código QR que lleve tu dirección de webhook y un secreto para ese usuario. Lo escanea con la app Life Dashboard, toca Vincular, y a partir de ahí su teléfono envía los datos de Health Connect, o los de Apple Health desde un iPhone, a tu servicio como JSON firmado. Nadie escribe una URL ni copia un secreto, y sabes que funcionó porque la app envía enseguida un ping de prueba firmado. La integración Life Dashboard para Home Assistant funciona exactamente así, y el formato es abierto, así que cualquier servicio puede hacer lo mismo.

Tu servicio muestra un código QR, el teléfono lo abre en la página de vinculación y, después de Vincular, tu servicio recibe un ping de prueba firmado

Por Owen Vogelaar, que mantiene Life Dashboard 5 min de lectura

Referencia de vinculación

Qué puede hacer un código

  • Rellenar una dirección y su secreto. En las secciones que permitas: Salud, Tiempo de pantalla o las dos. El usuario todavía puede desactivar una sección en la página de vinculación.
  • Nunca elegir los tipos de datos ni un horario. Qué datos se envían, y con qué frecuencia, sigue siendo decisión del usuario en el teléfono. Un código no puede empezar a enviar a escondidas la frecuencia cardíaca de alguien a ningún sitio.
  • Nunca tocar otros receptores. Cada una de las demás direcciones mantiene su propio secreto y sus encabezados, y una dirección agregada por vinculación empieza sin encabezados personalizados.
  • No guardar nada antes de Vincular. La página de vinculación muestra tu nombre y el host al que van los datos, tomado de la propia dirección.

Un código es un enlace https con todo lo demás después del #:

https://owen282000.github.io/life-dashboard-companion-app/pair#v=1&url=<address>&secret=<secret>&name=<name>
CampoValor
v1, la versión del formato. Obligatorio.
urlTu dirección de webhook, como máximo 2048 caracteres, sin espacios ni comas. Obligatorio.
secretEl secreto de firma HMAC de este usuario, como máximo 512 caracteres, sin espacios. Obligatorio.
nameEl nombre que la página de vinculación le da a tu servicio, hasta 64 caracteres. Opcional.
sourceshealth_connect, screen_time o los dos, separados por una coma. Omítelo para aceptar los dos.

Codifica cada valor por completo con codificación por ciento, con el espacio como %20. quote(value, safe="") de Python y encodeURIComponent de JavaScript lo hacen; la codificación de formularios, que escribe el espacio como +, no. El secreto va en el fragmento a propósito: un navegador nunca envía a un servidor la parte que sigue al #, así que cuando alguien escanea el código sin tener la app instalada, la página de destino se carga pero el secreto se queda en su teléfono.

Crea un código en Python

import secrets
from urllib.parse import quote, urlencode

import segno

PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair"


def pairing_link(webhook_url, secret, name=None, sources=None):
    fields = {"v": "1", "url": webhook_url, "secret": secret}
    if name:
        fields["name"] = name
    if sources:
        fields["sources"] = ",".join(sources)
    return PAIR_PAGE + "#" + urlencode(fields, quote_via=quote, safe="")


secret = secrets.token_urlsafe(32)  # store this with the user
link = pairing_link("https://health.example.com/webhook/u/42", secret, name="Example Health")
segno.make(link, error="m").save("pairing.svg", scale=6, border=4)

Crea un código en Node.js

import crypto from "node:crypto";
import QRCode from "qrcode";

const PAIR_PAGE = "https://owen282000.github.io/life-dashboard-companion-app/pair";

function pairingLink(webhookUrl, secret, { name, sources } = {}) {
  const fields = [["v", "1"], ["url", webhookUrl], ["secret", secret]];
  if (name) fields.push(["name", name]);
  if (sources) fields.push(["sources", sources.join(",")]);
  return PAIR_PAGE + "#" + fields.map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
}

const secret = crypto.randomBytes(32).toString("base64url"); // store this with the user
const link = pairingLink("https://health.example.com/webhook/u/42", secret, { name: "Example Health" });
const dataUrl = await QRCode.toDataURL(link, { errorCorrectionLevel: "M", margin: 4 });

Los dos dan exactamente el vector de prueba conocido que comprueban los tests de la propia app, y que está en la referencia de vinculación. Úsalo como test unitario de tu generador.

Qué ve el usuario

Escanea tu código en la app, con Escanear un código de vinculación, o con la cámara del teléfono, que en Android abre la app directamente. Una página dice "Example Health quiere recibir tus datos en: health.example.com", con un interruptor para cada sección y las demás direcciones que mantienen su propio secreto. No se guarda nada hasta que toca Vincular.

El ping de prueba después de Vincular

Justo después de Vincular, la app envía un ping de prueba a tu dirección, firmado con el secreto del código:

POST /webhook/u/42
Content-Type: application/json; charset=utf-8
X-Signature: sha256=<hex of HMAC-SHA256(secret, raw body)>

{
  "test": true,
  "message": "Test ping from Life Dashboard",
  "timestamp": "2026-10-04T12:00:00Z",
  "app_version": "1.29.0",
  "source": "health_connect"
}

Comprueba la firma sobre el cuerpo sin procesar antes de analizarlo, responde con cualquier 2xx, y el usuario ve "Conectado." en la página después de Vincular, o un mensaje corto que dice "ping de prueba entregado" durante la configuración inicial de la app. Responde 401 a una firma incorrecta, igual que en todas las peticiones posteriores. Un ping no lleva datos, así que es un buen momento para marcar al usuario como conectado, no algo que guardar. Cada sincronización posterior usa el mismo secreto y el mismo payload, descrito en la guía del webhook.

iPhone

Life Dashboard para iPhone lee los mismos códigos. Solo envía Apple Health, así que un código tiene que aceptar health_connect u omitir sources. El http:// sin cifrar solo funciona ahí hacia una dirección de la red doméstica, así que usa https. La cámara del iPhone abre primero la página de destino, que pasa el código a la app con un botón Open in the app.

Mantenlo seguro

  • Un secreto por usuario, de un generador aleatorio criptográfico, de al menos 32 bytes.
  • Muestra el código solo a ese usuario, después de que haya iniciado sesión. Cualquiera que lo vea puede firmar datos en su nombre.
  • Nunca registres el enlace en los logs. Contiene el secreto.
  • Deja que los usuarios roten el secreto. Un secreto nuevo significa un código nuevo; al escanearlo se sustituye el secreto anterior en el teléfono.

Life Dashboard

Crea un código para un usuario de prueba y escanéalo con la app. La referencia de vinculación tiene cada regla, el vector de prueba y las diferencias en iPhone.

Disponible en Google Play

4,99 €, pago único, en Google Play: la forma más cómoda, con actualizaciones automáticas, y así apoyas el desarrollo.

O gratis, la misma app con la misma clave de firma: APK en GitHub · Obtainium · F‑Droid

Descárgala en App Store

6,99 €, pago único, en App Store, sin suscripción.

Compilar con Xcode

Referencia de vinculación Referencia del payload

Las apps de código abierto que usa esta guía, para Android y iPhone. Sin cuenta y sin nube. Más sobre Android y iPhone.

Preguntas frecuentes

¿Necesitan mis usuarios una cuenta de Life Dashboard?

No. No hay ningún servidor ni cuenta de Life Dashboard. El teléfono envía directamente a la dirección de tu código.

¿Puede un código elegir qué datos de salud recibe mi servicio?

No. Un código solo rellena la dirección y el secreto. El usuario elige los tipos de datos y el horario en el teléfono, y así el consentimiento sigue en sus manos.

¿Puedo recibir el payload en mi propio formato?

No. Todos los receptores reciben el mismo JSON firmado, descrito por un JSON Schema, y tu servicio lo adapta a su propio modelo. Un único formato documentado es lo que permite que cualquier receptor funcione sin un plugin.

¿Y si el usuario escanea sin tener la app instalada?

El enlace abre una página que dice dónde conseguir la app, para Android o iPhone. El secreto del enlace nunca llega al servidor de esa página.