Endpoint de API

O Endpoint de API é um destino de exportação para usuários que desejam que os dados do Health.md sejam enviados ao próprio servidor, webhook, banco de dados, painel ou automação. O iPhone continua lendo o Apple Health; em vez de gravar arquivos, ele envia o JSON por POST ao endpoint configurado.

Lembrete de privacidade.

Este destino envia intencionalmente os dados de saúde selecionados para a URL informada. Use um endpoint que você controle ou no qual confie, dê preferência a HTTPS e limite as métricas ao que seu serviço realmente precisa.

Configure o destino

Abra o Health.md no iPhone.
Acesse Exportar.
Em Destino da exportação, escolha Endpoint de API.
Insira uma URL, como https://api.example.com/healthmd/ingest.
Opcional: insira um token bearer. O Health.md o armazena nas Chaves.
Toque em Concluído, escolha o intervalo de datas e as métricas e toque em Exportar.

Se você inserir um token simples, o Health.md o enviará como Authorization: Bearer <token>. Se o valor já começar com Bearer ou Basic , o Health.md o enviará exatamente como foi inserido.

Estrutura do payload

O Health.md envia uma solicitação POST por ação de exportação. O corpo é um envelope healthmd.api_export com versionamento independente, que contém registros diários públicos healthmd.health_data do schema v8. O envelope de API v1 transporta os registros diários; a v2 também pode transportar sidecars de provedores sem alterar o schema dos registros diários.

records

Objetos diários completos do schema v8 mantidos para o intervalo solicitado, incluindo registros completos e vazios cujo manifesto de consulta serve como evidência.

failed_date_details

Datas que apresentaram falha antes que um documento diário pudesse ser mantido.

daily_record_schema_version

A versão do schema diário em records. Ela avança independentemente da versão do envelope da API.

Sidecars de provedores

Registros externos condicionais da v2, com regras próprias de schema e identidade, quando um provedor conectado está ativado.

Consulte o envelope de API v1 completo gerado em produção e o envelope de sidecar de provedor da API v2. O contrato da API e da CLI documenta todos os campos, limites de versão e regras de aceitação.

Requisitos do endpoint

Método

Aceite POST.

Tipo de conteúdo

Aceite application/json.

Sucesso

Retorne qualquer status 2xx depois que o payload for aceito com segurança.

Falhas

Retorne 4xx ou 5xx para solicitações rejeitadas. O Health.md mostra uma breve prévia da resposta quando disponível.

Para uma ingestão confiável, torne seu endpoint idempotente por data. Um usuário pode repetir a exportação do mesmo intervalo depois de alterar as métricas ou corrigir um erro do servidor.

Dicas

Teste com um dia antes de enviar um preenchimento retroativo longo.
Mantenha os Registros de Saúde sem Perdas ativados quando a completude da fonte for importante; reduza o intervalo de datas para rotas densas, documentos clínicos, ECGs ou anexos.
Valide o token no servidor antes de armazenar qualquer payload.
Use records[].date como chave principal de cada dia.
Retorne um corpo de erro conciso; o Health.md exibe apenas uma breve prévia.

Solução de problemas

Problema	Geralmente significa	Correção
O destino da API não está pronto	A URL está vazia ou é inválida	Reabra as configurações do Endpoint de API e insira uma URL HTTP(S) válida.
HTTP 401 ou 403	O token está ausente ou foi rejeitado	Atualize o token ou as regras de autenticação do servidor.
HTTP 404	O caminho da URL está incorreto	Verifique a rota no servidor.
HTTP 413	O payload é grande demais	Exporte menos dias; use uma saída somente de resumo apenas quando o receptor não precisar dos registros canônicos da fonte.
Algumas datas estão ausentes	Não há dados do HealthKit ativados para essas datas	Verifique `failed_date_details` e sua seleção de métricas.