Guia de automatização do 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 apps não podem aceder a dados de saúde enquanto o iPhone está bloqueado. As automatizações só são executadas quando o dispositivo está desbloqueado. É uma limitação imposta pela Apple que não pode ser contornada. Mais informações

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

  • A Atualização em segundo plano estiver desativada para a app
  • O dispositivo estiver no Modo de pouca energia
  • O dispositivo esteve inativo durante períodos prolongados
  • Os recursos do sistema estiverem restritos
  • Várias apps estiverem a competir por tempo de execução em segundo plano

Desempenho

Tenha em conta que o iOS está otimizado para tarefas de curta duração num dispositivo móvel com restrições de desempenho muito apertadas. As tarefas em segundo plano normalmente têm de ser concluídas em 30 segundos e são limitadas na memória que podem consumir. O Health Auto Export oferece grande flexibilidade e personalização, pelo que é importante compreender como determinadas configurações afetam o desempenho da app e os resultados.

• Configuração: Automatizações que produzem grandes volumes de dados podem fazer com que o sistema termine o processo e impedir que as automatizações sejam executadas em segundo plano. As seguintes configurações podem produzir grandes volumes de dados:
  • Automatizações configuradas para exportar todas as métricas de saúde.
    • Recomendação: selecione apenas métricas de saúde que tenham dados guardados no Apple Health e apenas os dados que realmente pretende utilizar. Mesmo tipos de dados vazios têm impacto no desempenho. Também pode dividir as métricas selecionadas por várias automatizações, o que facilita o processamento pelo sistema.
  • Automatizações com agrupamento temporal em segundos ou minutos, ou com Resumir dados desativado. Consultas tão detalhadas podem demorar muito e colidir com as limitações do sistema.
    • Recomendação: embora pareça ideal ter o máximo de detalhe, considere se esse nível de detalhe é necessário para cada métrica ou tipo de dados. Considere várias automatizações com definições diferentes.
  • Ao exportar treinos ao ar livre, como ciclismo, corrida, caminhadas, etc. com dados de rota, o GPS e as métricas de saúde associadas podem produzir payloads grandes.
• Tamanho do payload: Especialmente ao usar exportação REST API, tenha em conta que payloads grandes podem causar erros no servidor. Certifique-se de que o seu backend está configurado para lidar com payloads de possivelmente várias centenas de megabytes para evitar erros.
• Frequência de sincronização: Adicione o widget de automatizações ao Ecrã principal para ajudar a garantir que as automatizações são executadas com sucesso em segundo plano (consulte o Guia de configuração do widget de automatizações).

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

Pedidos em lote e cargas grandes

Ao usar o formato JSON, ative Pedidos em lote para enviar dados em vários pedidos HTTP em vez de uma única carga grande.

• ATIVADO — Distribui os dados por vários pedidos. Use quando o endpoint tiver limites de tamanho, timeouts em corpos grandes ou processar dados de forma incremental.
• DESATIVADO — Envia todos os dados num único pedido. Adequado para exportações mais pequenas e webhooks simples.

Quando ativar lote:

• Muitas métricas de saúde selecionadas, intervalos longos de datas ou agrupamento temporal fino (minutos/segundos)
• Resumir dados está DESATIVADO e exporta métricas de saúde desagregadas
• O servidor devolve erros ou timeouts em corpos POST grandes

Notas:

• Os pedidos em lote aplicam-se apenas a REST API + JSON (não CSV).
• O lote reduz o tamanho da carga por pedido, mas não elimina a necessidade de obter dados no dispositivo; consultas lentas do HealthKit podem ainda aparecer como avisos nos registos de atividade. Consulte Consultas lentas nos registos de atividade.

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

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. Sincronização automática:

   • Carregue o dispositivo e utilize Espelhamento do iPhone
     • Durante o carregamento, o iOS impõe menos restrições de desempenho, pelo que os dados podem sincronizar com mais frequência
     • Com o Espelhamento do iPhone, o dispositivo comporta-se como desbloqueado. Assim o Health Auto Export pode aceder a dados de saúde para executar ações automatizadas

2. Desempenho:

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

3. Confiabilidade:

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

4. 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

Ver registos de atividade

1. Toque em Ver registos de atividade no ecrã de configuração da automatização.
2. Reveja execuções (agrupadas, as mais recentes primeiro) e expanda eventos em cada execução.
3. Distinga avisos (p. ex., consulta lenta de dados de saúde) de erros (falhas HTTP, timeouts ou falhas de leitura do HealthKit)—veja Visão geral das automatizações — Registos de atividade.
4. Carregamentos REST bem-sucedidos mostram frequentemente um resumo com formato, tipo de dados, período de exportação e intervalo de datas na execução.
5. Partilhar (barra de ferramentas) exporta o ZIP de diagnóstico completo dos Registos de eventos da app para suporte (o mesmo que Definições → Avançado).
6. Limpar remove apenas o histórico de atividade desta automatização.