API Endpoint

API Endpoint est une destination d’export destinée aux utilisateurs qui souhaitent transmettre les données Health.md à leur propre serveur, webhook, base de données, tableau de bord ou automatisation. L’iPhone lit toujours Apple Health ; au lieu d’écrire des fichiers, il envoie le JSON par POST au point de terminaison configuré.

Rappel de confidentialité.

Cette destination envoie volontairement les données de santé sélectionnées à l’URL que vous saisissez. Utilisez un point de terminaison que vous contrôlez ou auquel vous faites confiance, privilégiez HTTPS et limitez les métriques aux seuls besoins de votre service.

Configurer la cible

Ouvrez Health.md sur iPhone.
Accédez à Export.
Dans Export Target, choisissez API Endpoint.
Saisissez une URL comme https://api.example.com/healthmd/ingest.
Facultatif : saisissez un bearer token. Health.md le stocke dans Keychain.
Touchez Done, choisissez votre plage de dates et vos métriques, puis touchez Export.

Si vous saisissez un jeton simple, Health.md l’envoie comme Authorization: Bearer <token>. Si la valeur commence déjà par Bearer ou Basic , Health.md l’envoie telle quelle.

Structure de la charge utile

Health.md envoie une requête POST par export. Le corps est une enveloppe d’API healthmd.api_export, dont la version évolue indépendamment, contenant des enregistrements quotidiens publics healthmd.health_data au schéma v8. L’enveloppe d’API v1 transporte les enregistrements quotidiens ; la v2 peut aussi transporter des fichiers annexes de fournisseurs sans modifier le schéma des enregistrements quotidiens.

records

Objets quotidiens complets au schéma v8 conservés pour la plage demandée, y compris les enregistrements complets mais vides dont le manifeste de requête sert de preuve.

failed_date_details

Dates ayant échoué avant qu’un document quotidien puisse être conservé.

daily_record_schema_version

Version du schéma quotidien contenu dans records. Elle évolue indépendamment de la version de l’enveloppe d’API.

Fichiers annexes de fournisseurs

Enregistrements externes v2 facultatifs, avec leurs propres règles de schéma et d’identité, lorsqu’un fournisseur connecté est activé.

Consultez l’enveloppe d’API v1 complète générée en production et l’enveloppe d’API v2 avec fichier annexe de fournisseur. Le contrat API et CLI documente chaque champ, limite de version et règle d’acceptation.

Exigences du point de terminaison

Méthode

Acceptez POST.

Type de contenu

Acceptez application/json.

Réussite

Renvoyez n’importe quel état 2xx après acceptation sûre de la charge utile.

Échecs

Renvoyez 4xx ou 5xx pour les requêtes rejetées. Health.md affiche un court aperçu de la réponse lorsqu’il est disponible.

Pour fiabiliser l’ingestion, rendez votre point de terminaison idempotent par date. Un utilisateur peut relancer la même plage d’export après avoir modifié les métriques ou corrigé une erreur du serveur.

Conseils

Testez avec une journée avant d’importer un long historique.
Gardez Lossless Health Records activé lorsque l’exhaustivité des sources est importante ; réduisez la plage de dates pour les itinéraires denses, les documents cliniques, les ECG ou les pièces jointes.
Validez le jeton côté serveur avant de stocker une charge utile.
Utilisez records[].date comme clé principale par jour.
Renvoyez un corps d’erreur concis ; Health.md n’affiche qu’un court aperçu.

Dépannage

Problème	Signifie généralement	Correctif
La cible API n’est pas prête	L’URL est vide ou invalide	Rouvrez les réglages API Endpoint et saisissez une URL HTTP(S) valide.
HTTP 401 ou 403	Jeton manquant ou rejeté	Mettez à jour le jeton ou les règles d’authentification du serveur.
HTTP 404	Le chemin d’URL est incorrect	Vérifiez la route sur votre serveur.
HTTP 413	La charge utile est trop volumineuse	Exportez moins de jours ; utilisez une sortie résumé seul uniquement lorsque votre récepteur n’exige pas les enregistrements sources canoniques.
Certaines dates sont manquantes	Aucune donnée HealthKit activée pour ces dates	Vérifiez `failed_date_details` et votre sélection de métriques.