Guía de automatización de REST API

Las automatizaciones de REST API te permiten exportar automáticamente tus datos de salud a cualquier servicio web que acepte solicitudes HTTP POST. Esto es ideal para integrar con backends personalizados, APIs de terceros o webhooks.

Resumen

Las automatizaciones de REST API envían tus datos de salud a un endpoint de URL especificado usando solicitudes HTTP POST. La automatización puede enviar datos en formato JSON o CSV, con encabezados configurables para autenticación y metadatos personalizados.

Casos de uso:

• Integración con servicios backend personalizados
• Envío de datos a webhooks
• Sincronización con APIs de terceros
• Creación de dashboards personalizados o plataformas de análisis

Características principales:

• Soporta formatos JSON y CSV
• Encabezados HTTP personalizados para autenticación
• Tiempo de espera de solicitud configurable
• Exportación manual de datos históricos

Limitaciones:

• Acceso a datos de salud: Las apps no pueden acceder a los datos de salud mientras el iPhone está bloqueado. Las automatizaciones solo se ejecutan cuando el dispositivo está desbloqueado. Es una limitación impuesta por Apple que no puede eludirse. Más información

• Procesamiento en segundo plano: iOS limita el procesamiento en segundo plano para preservar la batería. Las automatizaciones dependen de la actualización en segundo plano de la app y pueden no ejecutarse de inmediato si:

  • La actualización en segundo plano está desactivada para la app
  • El dispositivo está en modo de bajo consumo
  • El dispositivo ha estado inactivo durante periodos prolongados
  • Los recursos del sistema están restringidos
  • Varias apps compiten por tiempo de ejecución en segundo plano

Rendimiento

Tenga en cuenta que iOS está optimizado para tareas de corta duración en un dispositivo móvil con restricciones de rendimiento muy estrictas. Las tareas en segundo plano suelen tener que completarse en 30 segundos y están limitadas en la memoria que pueden consumir. Health Auto Export ofrece un alto grado de flexibilidad y personalización, lo que a su vez requiere dedicar tiempo a comprender cómo ciertas configuraciones afectarán al rendimiento de la app y a los resultados.

• Configuración: Las automatizaciones que generan grandes cantidades de datos pueden provocar que el sistema finalice el proceso y que las automatizaciones no se ejecuten en segundo plano. Las siguientes configuraciones pueden generar grandes cantidades de datos:
  • Automatizaciones configuradas para exportar todas las métricas de salud.
    • Recomendación: seleccione solo las métricas de salud que tienen datos guardados en Apple Health y solo los datos que realmente planea usar. Incluso los tipos de datos vacíos afectan al rendimiento. También puede considerar dividir las métricas seleccionadas en varias automatizaciones, lo que facilita el trabajo al sistema.
  • Automatizaciones que usan agrupación temporal en segundos o minutos, o con Resumir datos desactivado. Estas consultas tan detalladas pueden tardar mucho en ejecutarse y chocar con las limitaciones del sistema.
    • Recomendación: aunque parezca ideal tener los datos más detallados posible, considere si ese nivel de detalle es necesario para cada métrica o tipo de dato. Valore varias automatizaciones con distintos ajustes.
  • Al exportar entrenamientos al aire libre, como ciclismo, running, senderismo, etc. con datos de ruta, el GPS y las métricas de salud asociadas pueden generar cargas útiles muy grandes.
• Tamaño de la carga útil: Especialmente al usar exportación REST API, tenga en cuenta que cargas grandes pueden provocar errores en el servidor. Asegúrese de que su backend pueda gestionar cargas de posiblemente varios cientos de megabytes para evitar errores.
• Frecuencia de sincronización: Añada el widget de automatizaciones a la pantalla de inicio para ayudar a que las automatizaciones se ejecuten correctamente en segundo plano (consulte Guía de configuración del widget de automatizaciones).

Requisitos previos

• Un endpoint de URL válido que acepte solicitudes HTTP POST
• Credenciales de autenticación (si las requiere tu endpoint)
• Conectividad de red para alcanzar tu endpoint

Solicitudes por lotes y cargas grandes

Al usar formato JSON, activa Solicitudes por lotes para enviar datos en varias solicitudes HTTP en lugar de una sola carga grande.

• ACTIVADO — Reparte los datos en varias solicitudes. Úsalo cuando tu endpoint tenga límites de tamaño, tiempos de espera en cuerpos grandes o proceses datos de forma incremental.
• DESACTIVADO — Envía todos los datos en una sola solicitud. Adecuado para exportaciones pequeñas y webhooks simples.

Cuándo activar lotes:

• Muchas métricas de salud seleccionadas, rangos de fechas largos o agrupación temporal fina (minutos/segundos)
• Resumir datos está DESACTIVADO y exportas métricas de salud desagregadas
• Tu servidor devuelve errores o tiempos de espera en cuerpos POST grandes

Notas:

• Las solicitudes por lotes solo aplican a REST API + JSON (no CSV).
• Los lotes reducen el tamaño de carga por solicitud, pero no eliminan la necesidad de obtener datos en el dispositivo; las consultas lentas de HealthKit pueden seguir apareciendo como advertencias en los registros de actividad. Consulta Consultas lentas en registros de actividad.

Configuración

Navega a la pantalla de Exportaciones automatizadas desde la navegación principal, luego toca "Nueva automatización" y selecciona "REST API" como Tipo de automatización.

Nombre de automatización

Ingresa un nombre descriptivo para tu automatización (por ejemplo, "Mi API backend", "Integración de webhook").

Notificaciones

Configura cuándo deseas recibir notificaciones:

• Notificar en actualización de caché - Recibe una notificación cuando se actualicen los datos en caché
• Notificar cuando se ejecute - Recibe una notificación cada vez que la automatización se ejecute

Configuración de URL

Ingresa la URL completa donde deseas enviar tus datos de salud. Debe ser una URL completa que incluya el protocolo (http:// o https://).

URLs de ejemplo:

• https://api.example.com/health-data
• https://webhook.site/your-unique-id
• http://localhost:3000/api/health

Nota: La URL debe ser válida y accesible desde tu dispositivo. Las URLs inválidas impedirán que la automatización se ejecute.

Tiempo de espera de solicitud

Selecciona un intervalo de tiempo de espera para las solicitudes HTTP. Esto determina cuánto tiempo esperará la aplicación una respuesta antes de considerar que la solicitud falló.

Encabezados HTTP

Agrega encabezados HTTP personalizados para autenticación o metadatos. Los casos de uso comunes incluyen:

• Claves de API: X-API-Key: your-api-key
• Tokens de autorización: Authorization: Bearer your-token
• Anulaciones de tipo de contenido: Content-Type: application/json

Para agregar encabezados:

1. Toca "Agregar encabezados"
2. Ingresa la clave del encabezado en el campo izquierdo
3. Ingresa el valor del encabezado en el campo derecho
4. Repite para encabezados adicionales

Importante: Cada clave de encabezado debe tener un valor correspondiente. Los encabezados vacíos serán ignorados.

Configuración de tipo de datos

Tipo de datos

Selecciona qué tipo de datos de salud exportar:

• Métricas de salud - Pasos, frecuencia cardíaca, sueño y otras mediciones de salud
• Entrenamientos - Actividades de ejercicio y fitness
• Síntomas - Síntomas y condiciones de salud
• ECG - Lecturas de electrocardiograma
• Notificaciones de frecuencia cardíaca - Eventos de frecuencia cardíaca alta/baja
• Estado de ánimo - Entradas de estado de ánimo y estado mental (iOS 18.0+)
• Seguimiento de ciclo - Datos de ciclo menstrual y salud reproductiva
• Medicamentos - Registros de medicamentos y adherencia (iOS 26.0+)

Configuración de métricas de salud

Cuando se selecciona Métricas de salud:

Seleccionar métricas de salud - Elige qué métricas específicas incluir. Puedes seleccionar todas las métricas disponibles o elegir específicas.

Consejo: Seleccionar solo las métricas que necesitas puede mejorar el tiempo de procesamiento y reducir el tamaño de los datos.

Fuentes preferidas - Configura qué fuentes de datos tienen prioridad cuando múltiples fuentes proporcionan la misma métrica.

Configuración de entrenamientos

Cuando se selecciona Entrenamientos:

Incluir datos de ruta - Activa para incluir rutas para entrenamientos que tienen datos de ubicación.

Incluir métricas de entrenamiento - Activa para incluir métricas de salud recopiladas durante los entrenamientos (frecuencia cardíaca, calorías, etc.).

Agrupación de tiempo (métricas de entrenamiento) - Cuando se usa Versión de exportación 2 e Incluir métricas de entrenamiento está habilitado:

• Minutos - Agrupa las métricas de entrenamiento por minuto
• Segundos - Agrupa las métricas de entrenamiento por segundo

Configuración de exportación

Formato de exportación

Selecciona el formato para tus datos exportados:

• Formato JSON - Proporciona estructuras de datos detalladas con objetos anidados. Mejor para APIs, bases de datos y aplicaciones que necesitan datos estructurados. El formato JSON incluye información más detallada para tipos de datos complejos como fases de sueño y lecturas de AFib.

• Formato CSV - Proporciona datos tabulares que se pueden importar fácilmente en aplicaciones de hojas de cálculo. Mejor para análisis de datos simples o cuando tu endpoint espera datos CSV.

Nota: El encabezado Content-Type se establece automáticamente en application/json para exportaciones JSON y multipart/form-data para exportaciones CSV.

Versión de exportación

Selecciona una Versión de exportación. El versionado permite transicionar entre versiones actualizadas de la exportación a tu propio ritmo y minimiza los cambios que rompen los flujos de trabajo.

• Versión 1 - Formato heredado, úsalo si tienes flujos de trabajo existentes que dependen de este formato
• Versión 2 - Formato actual con datos de entrenamiento mejorados y opciones de metadatos más detalladas

Rango de fechas

Selecciona cuándo se deben exportar los datos:

• Predeterminado - Sincroniza datos para el día anterior completo más datos hasta la fecha y hora actuales
• Desde última sincronización - En cada sincronización, exporta todos los datos desde la última vez que se ejecutó la exportación hasta la fecha y hora actuales
• Hoy - Sincroniza todos los datos para la fecha actual hasta la hora actual
• Ayer - Sincroniza todos los datos para el día anterior completo
• Últimos 7 días - Sincroniza datos para los últimos siete días completos

Resumir datos

Cuando uses formato JSON con tipo de datos Métricas de salud, activa o desactiva Resumir datos.

• Activado - Proporciona resúmenes de datos agregados
• Desactivado - Proporciona datos desagregados cuando sea posible, mostrando puntos de datos individuales

Nota: Esta configuración solo se aplica al formato JSON con Métricas de salud. Los datos siempre se agregan cuando se usa formato CSV o cuando se seleccionan múltiples métricas.

Agrupación de tiempo

Cuando uses formato JSON con Resumir datos habilitado, selecciona cómo se deben agregar los datos.

Nota: El formato CSV siempre agrega datos. La agregación a nivel de minuto y segundo puede aumentar significativamente el tiempo de procesamiento y el tamaño de los datos.

Solicitudes por lotes

Cuando uses formato JSON, activa Solicitudes por lotes para enviar datos en lotes a través de múltiples solicitudes en lugar de una sola carga útil.

• Activado - Distribuye datos en múltiples solicitudes para evitar cargas útiles excesivamente grandes
• Desactivado - Envía todos los datos en una sola solicitud

Cadencia de sincronización

Configura con qué frecuencia la automatización debe cargar datos:

Selecciona un número e intervalo.

Pruebas y verificación

Verificar formato de datos

La aplicación incluye automáticamente estos encabezados en cada solicitud:

• Content-Type - Establecido según el formato de exportación
• automation-name - El nombre de tu automatización
• automation-id - Identificador único para la automatización
• automation-aggregation - La agrupación de tiempo seleccionada
• automation-period - El rango de fechas seleccionado
• session-id - Identificador único para cada solicitud

Solución de problemas

Problemas comunes

Datos no recibidos en el endpoint

• Verifica que la URL del endpoint sea correcta
• Verifica que tu endpoint acepte solicitudes POST
• Revisa los encabezados de autenticación
• Verifica los registros del endpoint para solicitudes entrantes
• Verifica la conectividad de red

Consejos y mejores prácticas

1. Sincronización automática:

   • Carga el dispositivo y usa Duplicación del iPhone
     • Al cargar, iOS impone menos restricciones de rendimiento, por lo que los datos pueden sincronizarse con más frecuencia
     • Con Duplicación del iPhone, el dispositivo se comporta como si estuviera desbloqueado. Así Health Auto Export puede acceder a los datos de salud para ejecutar acciones automatizadas

2. Rendimiento:

   • Usa agrupación de tiempo apropiada para equilibrar detalle vs. tamaño de datos
   • Selecciona solo las métricas que necesitas

3. Confiabilidad:

   • Establece valores de tiempo de espera apropiados según el tiempo de respuesta de tu endpoint
   • Monitorea los registros de actividad regularmente

4. Formato de datos:

   • Usa JSON para datos estructurados y APIs
   • Usa CSV para análisis de datos simples o integración con hojas de cálculo
   • Considera solicitudes por lotes para conjuntos de datos grandes o procesamiento separado

Ver registros de actividad

1. Toca Ver registros de actividad en la pantalla de configuración de la automatización.
2. Revisa ejecuciones (agrupadas, las más recientes primero) y expande eventos en cada ejecución.
3. Distingue advertencias (p. ej., consulta lenta de datos de salud) de errores (fallos HTTP, tiempos de espera o errores de lectura de HealthKit)—consulta Resumen de automatizaciones — Registros de actividad.
4. Las subidas REST correctas suelen mostrar un resumen con formato, tipo de datos, periodo de exportación y rango de fechas en la ejecución.
5. Compartir (barra de herramientas) exporta el ZIP de diagnóstico completo de Registros de eventos de la app para soporte (igual que Ajustes → Avanzado).
6. Borrar elimina solo el historial de actividad de esta automatización.