Guia de automação do REST API

As automações REST API permitem que você exporte automaticamente seus dados de saúde para qualquer serviço web que aceita solicitações HTTP POST. Isso é ideal para integrar com backends personalizados, APIs de terceiros ou webhooks.

Visão geral

As automações REST API enviam seus dados de saúde para um endpoint de URL especificado usando solicitações 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 uso:

• 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

Recursos principais:

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

Limitações:

• Acesso a dados de saúde: Os apps não podem acessar dados de saúde enquanto o iPhone está bloqueado. As automaçõ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 automações dependem da Atualização em segundo plano do app e podem não ser executadas imediatamente se:

  • A Atualização em segundo plano estiver desativada para o app
  • O dispositivo estiver no Modo de baixa energia
  • O dispositivo ficou inativo por longos períodos
  • Os recursos do sistema estiverem restritos
  • Vários apps estiverem competindo por tempo de execução em segundo plano

Desempenho

Lembre-se de que o iOS é otimizado para tarefas de curta duração em um dispositivo móvel com restrições de desempenho muito rígidas. Tarefas em segundo plano normalmente precisam ser concluídas em até 30 segundos e têm limite de memória que podem consumir. O Health Auto Export oferece grande flexibilidade e personalização, e isso exige entender como certas configurações afetam o desempenho do app e os resultados.

• Configuração: Automações que produzem grandes volumes de dados podem fazer o sistema encerrar o processo e impedir que automações sejam executadas em segundo plano. As configurações a seguir podem produzir grandes volumes de dados:
  • Automações configuradas para exportar todas as métricas de saúde.
    • Recomendação: selecione apenas métricas de saúde que tenham dados salvos no Apple Health e apenas os dados que você realmente pretende usar. Mesmo tipos de dados vazios afetam o desempenho. Você também pode dividir as métricas selecionadas em várias automações, o que facilita o processamento pelo sistema.
  • Automações que usam agrupamento temporal em segundos ou minutos, ou com Resumir dados desativado. Consultas tão detalhadas podem demorar muito e entrar em conflito com as limitações do sistema.
    • Recomendação: embora pareça ideal ter o máximo de detalhes, considere se esse nível de detalhe é necessário para cada métrica ou tipo de dado. Considere várias automações com configurações diferentes.
  • Ao exportar treinos ao ar livre, como ciclismo, corrida, trilha etc. com dados de rota, GPS e métricas de saúde associadas podem gerar payloads grandes.
• Tamanho do payload: Especialmente ao usar exportação por REST API, lembre-se de que payloads grandes podem causar erros no servidor. Certifique-se de que seu backend está configurado para lidar com payloads de possivelmente centenas de megabytes para evitar erros.
• Frequência de sincronização: Adicione o widget de automações à Tela de início para ajudar a garantir que as automações sejam executadas com sucesso em segundo plano (consulte o Guia de configuração do widget de automações).

Pré-requisitos

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

Solicitações em lote e cargas grandes

Ao usar o formato JSON, ative Solicitações em lote para enviar dados em várias solicitações HTTP em vez de uma única carga grande.

• ATIVADO — Distribui os dados em várias solicitações. Use quando o endpoint tiver limites de tamanho, timeouts em corpos grandes ou processar dados incrementalmente.
• DESATIVADO — Envia todos os dados em uma única solicitação. Adequado para exportações menores 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 você exporta métricas de saúde desagregadas
• O servidor retorna erros ou timeouts em corpos POST grandes

Observações:

• Solicitações em lote aplicam-se apenas a REST API + JSON (não CSV).
• O lote reduz o tamanho da carga por solicitação, mas não elimina a necessidade de buscar dados no dispositivo; consultas lentas do HealthKit ainda podem aparecer como avisos nos registros de atividade. Veja Consultas lentas nos registros de atividade.

Configuração

Navegue até a tela 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

Digite um nome descritivo para sua automação (por exemplo, "Minha API backend", "Integração webhook").

Notificações

Configure quando deseja receber notificações:

• Notificar na atualização do 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

Digite a URL completa onde deseja enviar seus dados de saúde. Isso deve ser uma URL completa 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: A URL deve ser válida e acessível do seu dispositivo. URLs inválidas impedirão que a automação seja executada.

Timeout de solicitação

Selecione um intervalo de timeout para solicitações HTTP. Isso determina quanto tempo o aplicativo aguardará uma resposta antes de considerar que a solicitação falhou.

Cabeçalhos HTTP

Adicione cabeçalhos HTTP personalizados para autenticação ou metadados. Casos de uso 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. Digite a chave do cabeçalho no campo esquerdo
3. Digite 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 - Registros 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. Você pode selecionar todas as métricas disponíveis ou escolher específicas.

Dica: Selecionar apenas as métricas que você 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 coletadas durante os treinos (frequência cardíaca, calorias, etc.).

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

• 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 seus dados exportados:

• Formato JSON - Fornece estruturas de dados detalhadas com objetos aninhados. Melhor para APIs, bancos de dados e aplicativos 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 aplicativos de planilha. Melhor para análise de dados simples ou quando 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 no seu próprio ritmo e minimiza mudanças que quebram fluxos de trabalho.

• Versão 1 - Formato legado, use se você tem fluxos de trabalho existentes que dependem deste formato
• Versão 2 - Formato atual com dados de treino aprimorados 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é a 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é a data e hora atuais
• Hoje - Sincroniza todos os dados para a data atual até a 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 usar 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 se aplica apenas ao formato JSON com Métricas de saúde. Os dados são sempre agregados ao usar formato CSV ou quando múltiplas métricas são selecionadas.

Agrupamento de tempo

Ao usar formato JSON com Resumir dados habilitado, 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.

Solicitações em lote

Ao usar formato JSON, ative Solicitações em lote para enviar dados em lotes em múltiplas solicitações em vez de uma única carga útil.

• ATIVADO - Distribui dados em múltiplas solicitações para evitar cargas úteis excessivamente grandes
• DESATIVADO - Envia todos os dados em uma única solicitação

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

O aplicativo inclui automaticamente estes cabeçalhos em cada solicitação:

• 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 solicitação

Solução de problemas

Problemas comuns

Dados não recebidos no endpoint

• Verifique se a URL do endpoint está correta
• Verifique se seu endpoint aceita solicitações POST
• Revise os cabeçalhos de autenticação
• Verifique os logs do endpoint para solicitações recebidas
• Verifique a conectividade de rede

Dicas e melhores práticas

1. Sincronização automática:

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

2. Desempenho:

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

3. Confiabilidade:

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

4. Formato de dados:

   • Use JSON para dados estruturados e APIs
   • Use CSV para análise de dados simples ou integração com planilhas
   • Considere solicitações em lote para grandes conjuntos de dados ou processamento separado

Visualizar registros de atividade

1. Toque em Ver registros de atividade na tela de configuração da automação.
2. Revise execuções (agrupadas, as mais recentes primeiro) e expanda eventos em cada execução.
3. Diferencie avisos (por exemplo, consulta lenta de dados de saúde) de erros (falhas HTTP, timeouts ou falhas de leitura do HealthKit)—veja Visão geral das automações — Registros de atividade.
4. Envios REST bem-sucedidos costumam mostrar um resumo com formato, tipo de dados, período de exportação e intervalo de datas na execução.
5. Compartilhar (barra de ferramentas) exporta o ZIP de diagnóstico completo de Registros de eventos do app para suporte (o mesmo que Ajustes → Avançado).
6. Limpar remove apenas o histórico de atividade desta automação.