Sincronizar dados do Apple Health para REST API

As automações REST API permitem-lhe exportar automaticamente os seus dados de saúde para qualquer serviço web que aceite pedidos HTTP POST. Isto é ideal para integrar com backends personalizados, APIs de terceiros ou webhooks.

Visão geral

As automações REST API enviam os seus dados de saúde para um endpoint de URL especificado utilizando pedidos HTTP POST. A automação pode enviar dados em formato JSON ou CSV, com cabeçalhos configuráveis para autenticação e metadados personalizados.

Casos de utilização:

• Integração com serviços backend personalizados
• Envio de dados para webhooks
• Sincronização com APIs de terceiros
• Criação de dashboards personalizados ou plataformas de análise

Características principais:

• Suporta formatos JSON e CSV
• Cabeçalhos HTTP personalizados para autenticação
• Timeout de pedido configurável
• Exportação manual de dados históricos

Limitações

• Acesso a dados de saúde: As aplicações não têm permissão para aceder a dados de saúde enquanto o iPhone está bloqueado. As automações serão executadas apenas durante os períodos em que o seu dispositivo está desbloqueado. Isto pode afetar a atualidade dos dados. Consulte as instruções para sincronização manual para manter os dados atualizados.

• Processamento em segundo plano: O iOS limita o processamento em segundo plano para preservar a vida da bateria. As automações dependem da Atualização de aplicação em segundo plano e podem não ser executadas imediatamente se:

  • A Atualização de aplicação em segundo plano está desativada para a aplicação
  • O dispositivo está em Modo de poupança de energia
  • O dispositivo esteve inativo durante períodos prolongados
  • Os recursos do sistema estão limitados
  • Múltiplas aplicações estão a competir por tempo de execução em segundo plano

Pré-requisitos

• Um endpoint de URL válido que aceita pedidos HTTP POST
• Credenciais de autenticação (se exigidas pelo seu endpoint)
• Conectividade de rede para alcançar o seu endpoint

Configuração

Navegue até ao ecrã Exportações automatizadas na navegação principal, depois toque em "Nova automação" e selecione "REST API" como Tipo de automação.

Nome da automação

Introduza um nome descritivo para a sua automação (por exemplo, "A minha API backend", "Integração webhook").

Notificações

Configure quando deseja receber notificações:

• Notificar na atualização da cache - Receba uma notificação quando os dados em cache forem atualizados
• Notificar quando executar - Receba uma notificação sempre que a automação for executada

Configuração de URL

Introduza o URL completo onde deseja enviar os seus dados de saúde. Isto deve ser um URL completo incluindo o protocolo (http:// ou https://).

URLs de exemplo:

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

Nota: O URL deve ser válido e acessível do seu dispositivo. URLs inválidos impedirão que a automação seja executada.

Timeout de pedido

Selecione um intervalo de timeout para pedidos HTTP. Isto determina quanto tempo a aplicação aguardará uma resposta antes de considerar que o pedido falhou.

Cabeçalhos HTTP

Adicione cabeçalhos HTTP personalizados para autenticação ou metadados. Casos de utilização comuns incluem:

• Chaves de API: X-API-Key: your-api-key
• Tokens de autorização: Authorization: Bearer your-token
• Substituições de tipo de conteúdo: Content-Type: application/json

Para adicionar cabeçalhos:

1. Toque em "Adicionar cabeçalhos"
2. Introduza a chave do cabeçalho no campo esquerdo
3. Introduza o valor do cabeçalho no campo direito
4. Repita para cabeçalhos adicionais

Importante: Cada chave de cabeçalho deve ter um valor correspondente. Cabeçalhos vazios serão ignorados.

Configurações de tipo de dados

Tipo de dados

Selecione qual tipo de dados de saúde exportar:

• Métricas de saúde - Passos, frequência cardíaca, sono e outras medições de saúde
• Treinos - Atividades de exercício e fitness
• Sintomas - Sintomas e condições de saúde
• ECG - Leituras de eletrocardiograma
• Notificações de frequência cardíaca - Eventos de frequência cardíaca alta/baixa
• Estado mental - Entradas de humor e estado mental (iOS 18.0+)
• Acompanhamento de ciclo - Dados de ciclo menstrual e saúde reprodutiva
• Medicamentos - Registos de medicamentos e aderência (iOS 26.0+)

Configuração de métricas de saúde

Quando Métricas de saúde está selecionado:

Selecionar métricas de saúde - Escolha quais métricas específicas incluir. Pode selecionar todas as métricas disponíveis ou escolher específicas.

Dica: Selecionar apenas as métricas de que precisa pode melhorar o tempo de processamento e reduzir o tamanho dos dados.

Fontes preferidas - Configure quais fontes de dados têm prioridade quando múltiplas fontes fornecem a mesma métrica.

Configuração de treinos

Quando Treinos está selecionado:

Incluir dados de rota - Ative para incluir rotas para treinos que têm dados de localização.

Incluir métricas de treino - Ative para incluir métricas de saúde recolhidas durante os treinos (frequência cardíaca, calorias, etc.).

Agrupamento de tempo (métricas de treino) - Ao utilizar Versão de exportação 2 e Incluir métricas de treino está ativado:

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

Configurações de exportação

Formato de exportação

Selecione o formato para os seus dados exportados:

• Formato JSON - Fornece estruturas de dados detalhadas com objetos aninhados. Melhor para APIs, bases de dados e aplicações que precisam de dados estruturados. O formato JSON inclui informações mais detalhadas para tipos de dados complexos como fases do sono e leituras de AFib.

• Formato CSV - Fornece dados tabulares que podem ser facilmente importados em aplicações de folha de cálculo. Melhor para análise de dados simples ou quando o seu endpoint espera dados CSV.

Nota: O cabeçalho Content-Type é automaticamente definido como application/json para exportações JSON e multipart/form-data para exportações CSV.

Versão de exportação

Selecione uma Versão de exportação. O versionamento permite transicionar entre versões atualizadas da exportação ao seu próprio ritmo e minimiza mudanças que quebram fluxos de trabalho.

• Versão 1 - Formato legado, use se tem fluxos de trabalho existentes que dependem deste formato
• Versão 2 - Formato atual com dados de treino melhorados e opções de metadados mais detalhadas

Intervalo de datas

Selecione quando os dados devem ser exportados:

• Padrão - Sincroniza dados para o dia anterior completo mais dados até à data e hora atuais
• Desde última sincronização - Em cada sincronização, exporta todos os dados desde a última vez que a exportação foi executada até à data e hora atuais
• Hoje - Sincroniza todos os dados para a data atual até à hora atual
• Ontem - Sincroniza todos os dados para o dia anterior completo
• Últimos 7 dias - Sincroniza dados para os últimos sete dias completos

Resumir dados

Ao utilizar formato JSON com tipo de dados Métricas de saúde, ative ou desative Resumir dados.

• ATIVADO - Fornece resumos de dados agregados
• DESATIVADO - Fornece dados desagregados quando possível, mostrando pontos de dados individuais

Nota: Esta configuração aplica-se apenas ao formato JSON com Métricas de saúde. Os dados são sempre agregados ao utilizar formato CSV ou quando múltiplas métricas são selecionadas.

Agrupamento de tempo

Ao utilizar formato JSON com Resumir dados ativado, selecione como os dados devem ser agregados.

Nota: O formato CSV sempre agrega dados. A agregação em nível de minuto e segundo pode aumentar significativamente o tempo de processamento e o tamanho dos dados.

Pedidos em lote

Ao utilizar formato JSON, ative Pedidos em lote para enviar dados em lotes em múltiplos pedidos em vez de uma única carga útil.

• ATIVADO - Distribui dados em múltiplos pedidos para evitar cargas úteis excessivamente grandes
• DESATIVADO - Envia todos os dados num único pedido

Frequência de sincronização

Configure com que frequência a automação deve fazer upload dos dados:

Selecione um número e intervalo.

Testes e verificação

Testes manuais

1. Toque em "Exportação manual" no ecrã de configuração da automação
2. Selecione um intervalo de datas
3. Toque em "Exportar" para enviar um pedido de teste
4. Verifique o seu endpoint para confirmar que os dados foram recebidos

Visualizar registos de atividade

1. Toque em "Visualizar registos de atividade" no ecrã de configuração da automação
2. Revise as execuções recentes da automação
3. Verifique se há erros ou avisos
4. Verifique timestamps de pedido e estado de resposta

Verificar formato de dados

A aplicação inclui automaticamente estes cabeçalhos em cada pedido:

• Content-Type - Definido com base no formato de exportação
• automation-name - O nome da sua automação
• automation-id - Identificador único para a automação
• automation-aggregation - O agrupamento de tempo selecionado
• automation-period - O intervalo de datas selecionado
• session-id - Identificador único para cada pedido

Resolução de problemas

Problemas comuns

Dados não recebidos no endpoint

• Verifique se o URL do endpoint está correto
• Verifique se o seu endpoint aceita pedidos POST
• Revise os cabeçalhos de autenticação
• Verifique os registos do endpoint para pedidos recebidos
• Verifique a conectividade de rede

Dicas e melhores práticas

1. Desempenho:

   • Utilize agrupamento de tempo apropriado para equilibrar detalhe vs. tamanho dos dados
   • Selecione apenas as métricas de que precisa

2. Confiabilidade:

   • Defina valores de timeout apropriados com base no tempo de resposta do seu endpoint
   • Monitore os registos de atividade regularmente

3. Formato de dados:

   • Utilize JSON para dados estruturados e APIs
   • Utilize CSV para análise de dados simples ou integração com folhas de cálculo
   • Considere pedidos em lote para grandes conjuntos de dados ou processamento separado