API e exportação de dados do AirTag
API do AirTag: exportação e integração dos dados de localização
A TagLogger exporta o histórico do AirTag em CSV ou JSON e oferece uma API, para que os dados cheguem ao ERP, CMMS, TMS ou FSM que de fato roda a operação.
O que a TagLogger exporta
- Localização atual e histórica de cada AirTag vinculado (lat/lon + data e hora)
- Eventos de entrada e saída de cerca virtual com data e hora
- Relatórios de ativos parados: ativos que não se moveram em janelas de tempo configuráveis
- Metadados do ativo: nome, cor, categoria, equipe responsável
- Feed de atividade: registro completo de eventos de cada AirTag em qualquer período escolhido
- Status de bateria fraca e frequência de atualização do AirTag
Formatos de exportação
CSV é o formato de exportação mais comum. Funciona com Excel, Google Sheets e praticamente qualquer sistema corporativo. A exportação em CSV da TagLogger traz, por AirTag, colunas de data e hora, latitude, longitude, nome do ativo e eventos de cerca virtual ligados a cada linha.
A exportação em JSON preserva toda a estrutura aninhada dos dados, incluindo metadados das cercas virtuais, categoria do ativo e tipos de evento. JSON é útil para a ingestão direta por programas em scripts, data warehouses e integrações sob medida.
Padrões de integração mais comuns
- Snapshot diário em CSV: exportação agendada que cai em uma pasta compartilhada ou do ERP para conciliação em lote
- Relatório semanal de auditoria: CSV de ativos parados mais resumo de atividade para a revisão da operação
- Webhook de cerca virtual: a TagLogger dispara um webhook HTTP quando acontece um evento de cerca virtual e envia para um endpoint do FSM ou TMS
- Consulta à API em tempo real: painéis próprios ou ferramentas de monitoramento puxam dados de localização em intervalos fixos (normalmente a cada 1–5 minutos)
- Automação por eventos: o webhook aciona o fluxo seguinte (alertas no Slack, abertura de chamados, ajustes de estoque)
Sistemas de destino: ERP, CMMS, TMS, FSM
Os dados de localização do AirTag se conectam a quatro grandes categorias de software de operação. O formato da integração é parecido em todas: um campo de geolocalização no cadastro do ativo, atualizado por agendamento ou por webhook.
ERP: NetSuite, SAP, Oracle e Dynamics
Importe o histórico de localização do AirTag como um registro de ativo personalizado com campo de geolocalização, atualizado por importações diárias de CSV ou pela API. Uso comum: conciliar a localização física do ativo com a localização registrada no ERP.
CMMS: Maximo, eMaint, Fiix e UpKeep
Envie a localização do AirTag para o atributo de localização do ativo, apoiando a programação da manutenção preventiva (achar o ativo sem percorrer a planta), e para o vínculo do ativo na ordem de serviço, para que os técnicos sejam enviados à localização atual.
TMS e WMS: Oracle TM, SAP TM, Blue Yonder e Manhattan
Eventos de cerca virtual entram como atualizações de status das cargas; a localização de reboques e contêineres alimenta os relatórios de gestão de pátio.
FSM: ServiceTitan, Housecall Pro, Jobber e FieldEdge
A localização dos veículos de serviço e das caixas de ferramentas pelo AirTag orienta as decisões de despacho; eventos de chegada na cerca virtual viram notificações automáticas para o cliente.
Noções básicas de acesso à API
A API da TagLogger dá acesso programático aos mesmos dados exibidos na interface web. A autenticação é por chave de API, com escopo por espaço de trabalho. Endpoints comuns: listar AirTags, obter a última localização de um AirTag, obter o histórico de localização de um AirTag em um período, listar cercas virtuais e seus eventos e ler os rótulos de tags definidos no espaço de trabalho.
Para consultas frequentes, a maioria das integrações acaba em um intervalo de 1–5 minutos, o mesmo ritmo prático de atualização da rede Buscar (Find My) da Apple. Consultar com mais frequência não gera mais dados, porque o ritmo de retransmissão da rede é o que limita a taxa.
Para integrações por eventos, assinaturas de webhook são mais eficientes que consultas periódicas. Assine os eventos de entrada e saída de cerca virtual e a TagLogger envia para o seu endpoint no momento em que o evento relevante acontece.
Início rápido da API do AirTag: instale um SDK e faça a primeira requisição
A TagLogger publica dois SDKs para a sua API de dados do AirTag: um para TypeScript e JavaScript e outro para Python. Instale um deles, crie uma chave do espaço de trabalho em Settings → API Keys e liste suas tags em poucas linhas. O início rápido da API mostra cada passo, e a referência da API lista todos os endpoints.
- TypeScript ou JavaScript: npm install @taglogger/sdk (pacote npm). Roda no Node 18 ou superior e já traz os próprios tipos.
- Python: pip install taglogger-sdk (pacote PyPI). Roda no Python 3.9 ou superior, sem outras dependências, e é importado como taglogger_sdk.
- Chave de API: defina TAGLOGGER_API_KEY com uma chave do espaço de trabalho que tenha o escopo read:tags. Autenticação explica escopos e cabeçalhos.
import os
from taglogger_sdk import TagLoggerClient
client = TagLoggerClient(api_key=os.environ["TAGLOGGER_API_KEY"])
page = client.tags.list(limit=50)
for tag in page["data"]:
print(tag["id"], tag["name"] or "")O SDK de TypeScript tem o mesmo formato: new TagLoggerClient({ apiKey }) e depois client.tags.list({ limit: 50 }). Os dois SDKs também cobrem histórico de localização, cercas virtuais, webhooks e verificação de assinatura de webhooks.
Casos de uso comuns de exportação e integração
- Relatórios de auditoria: exportações mensais ou trimestrais que mostram a custódia e a movimentação dos ativos para auditorias internas ou externas
- Documentação para seguro: exportação em CSV do histórico de localização para sinistros de perda e casos de furto
- Conciliação de faturamento: comparar a localização do ativo rastreado com as datas de locação contratadas ou as visitas de serviço
- Inventário automatizado: retratos periódicos da frota enviados ao sistema de gestão de estoque
- Registros de conformidade: histórico de localização com data e hora para exigências regulatórias (controles de ativos da SOX, rastreamento de dispositivos sob a HIPAA)
- Painéis próprios: visões unificadas que juntam os dados do AirTag a outros dados da operação (ERP, CRM, telemetria)
- Pipelines de análise: carregar o histórico do AirTag no BigQuery/Snowflake/Redshift para analisar o aproveitamento dos ativos
Segurança na exportação e no acesso à API
Os dados de localização do AirTag são valiosos: revelam onde os ativos (e, muitas vezes, as pessoas) estão e estiveram. Proteja os dados de exportação e da API com controles de acesso adequados. Limite as chaves de API ao menor escopo de permissão necessário. Guarde as chaves em um gerenciador de segredos, não em arquivos de configuração em texto puro. Registre o acesso à API para auditoria.
Em exportações CSV compartilhadas com terceiros (reguladores de sinistro, polícia, clientes em disputa), compartilhe só o período e os ativos necessários, e não uma exportação completa da frota. A TagLogger oferece exportações por ativo e com período definido justamente para isso.
Clientes de setores regulados (saúde, serviços financeiros) costumam passar os dados de exportação e da API da TagLogger pela sua plataforma de conformidade, em vez de enviá-los direto aos sistemas finais. É um padrão razoável, e o formato de exportação da TagLogger o suporta.
Como começar com exportações e API
Comece pela exportação em CSV. Não exige desenvolvimento, funciona em qualquer planilha e cobre a maioria dos casos de auditoria e conciliação. A maioria dos clientes da TagLogger usa CSV nos primeiros 3–6 meses e só passa para a integração via API quando surge uma necessidade específica de automação.
Na integração via API, o primeiro alvo prático é o webhook de cerca virtual, porque ele entrega sinais por evento sem exigir infraestrutura de consulta periódica. Um endpoint de webhook e algumas linhas de lógica automatizam boa parte do fluxo (alertas no Slack, abertura de chamados, atualizações de status) sem precisar de uma integração completa sob medida.
A integração completa com ERP ou CMMS é um projeto maior e costuma vir depois. Quando ela se torna necessária, os padrões da operação com o rastreamento por AirTag já estão bem entendidos, e a integração mira fluxos de dados específicos em vez de “conectar tudo”.
Perguntas frequentes
Leve os dados do AirTag para os sistemas que rodam a sua operação
Exportação em CSV e JSON, acesso à API e webhooks, para que o histórico de localização do AirTag alimente ERP, CMMS, TMS, FSM e fluxos próprios, sem silos de dados.
