API de AirTag y exportación de datos

API de AirTag: exportación de datos de ubicación e integración

TagLogger exporta el historial del AirTag en CSV o JSON y ofrece una API, para que los datos lleguen al ERP, CMMS, TMS o FSM con el que realmente funciona su operación.

Qué exporta TagLogger

  • Ubicación actual e histórica de cada AirTag vinculado (lat/lon + marca de tiempo)
  • Eventos de entrada y salida de geocercas con marca de tiempo
  • Informes de activos inactivos: activos que no se han movido en ventanas de tiempo configurables
  • Metadatos del activo: nombre, color, categoría, equipo asignado
  • Registro de actividad: el registro completo de eventos de cada AirTag en cualquier periodo seleccionado
  • Estado de batería baja y frecuencia de reporte del AirTag

Formatos de exportación

CSV es el formato de exportación más habitual: compatible con Excel, Google Sheets y prácticamente cualquier sistema empresarial. La exportación CSV de TagLogger incluye, por cada AirTag, columnas de marca de tiempo, latitud, longitud, nombre del activo y cualquier evento de geocerca asociado a esa fila.

La exportación JSON conserva la estructura anidada completa de los datos, incluidos los metadatos de geocercas, la categoría del activo y los tipos de evento. JSON resulta útil para la ingesta programática directa en scripts, almacenes de datos e integraciones a medida.

Patrones de integración habituales

  • Instantánea CSV diaria: exportación programada que se deposita en una unidad compartida o en una carpeta del ERP para la conciliación por lotes
  • Informe de auditoría semanal: CSV de activos inactivos más un resumen de actividad para la revisión de operaciones
  • Webhook de geocerca: TagLogger dispara un webhook HTTP cuando ocurre un evento de geocerca y envía los datos a un endpoint del FSM o del TMS
  • Consulta periódica a la API en tiempo real: paneles a medida o herramientas de monitoreo consultan los datos de ubicación con cierta frecuencia (normalmente cada 1–5 minutos)
  • Automatización basada en eventos: el webhook dispara flujos de trabajo posteriores (alertas en Slack, creación de tickets, ajustes de inventario)

Sistemas de destino: ERP, CMMS, TMS, FSM

Los datos de ubicación del AirTag se conectan con cuatro grandes categorías de software operativo. La forma de la integración es parecida en todas: un campo de geolocalización en el registro del activo, actualizado de forma programada o mediante webhook.

ERP: NetSuite, SAP, Oracle, Dynamics

Incorpore el historial de ubicaciones del AirTag como un registro de activo personalizado con un campo de geolocalización, actualizado mediante importaciones CSV diarias o por API. Uso habitual: conciliar la ubicación física del activo con la ubicación registrada en el ERP.

CMMS: Maximo, eMaint, Fiix, UpKeep

Lleve la ubicación del AirTag al atributo de ubicación del activo para apoyar la planificación del mantenimiento preventivo (localizar el activo sin recorrer la planta) y a la vinculación de activos en las órdenes de trabajo, para que los técnicos se desplacen a la ubicación actual.

TMS / WMS: Oracle TM, SAP TM, Blue Yonder, Manhattan

Los eventos de geocerca se registran como actualizaciones de estado de los envíos; la ubicación de remolques y contenedores alimenta los informes de gestión de patio.

FSM: ServiceTitan, Housecall Pro, Jobber, FieldEdge

La ubicación por AirTag de los vehículos de servicio y los juegos de herramientas alimenta las decisiones de asignación de trabajos; los eventos de llegada a una geocerca se convierten en notificaciones automáticas al cliente.

Conceptos básicos del acceso por API

La API de TagLogger ofrece acceso programático a los mismos datos que muestra la interfaz web. La autenticación se basa en claves de API, con alcance por espacio de trabajo. Endpoints habituales: listar los AirTag, obtener la última ubicación de un AirTag, obtener el historial de ubicaciones de un AirTag en un intervalo de tiempo, listar geocercas y eventos de geocerca, y leer las etiquetas de localizador definidas en el espacio de trabajo.

Para consultas de alta frecuencia, la mayoría de las integraciones se quedan en una frecuencia de 1–5 minutos, que coincide con la frecuencia práctica de actualización de la red Find My (la app Buscar o Encontrar). Consultar con más frecuencia no produce más datos, porque el factor limitante es la frecuencia de retransmisión subyacente.

Para integraciones basadas en eventos, las suscripciones a webhooks son más eficientes que las consultas periódicas. Suscríbase a los eventos de entrada y salida de geocercas y TagLogger los enviará a su endpoint en cuanto se produzca un evento relevante.

Inicio rápido de la API de AirTag: instale un SDK y haga su primera solicitud

TagLogger publica dos SDK para su API de datos de AirTag: uno para TypeScript y JavaScript, y otro para Python. Instale uno, cree una clave del espacio de trabajo en Settings → API Keys y liste sus localizadores en unas pocas líneas. El inicio rápido de la API recorre cada paso y la referencia de la API enumera todos los endpoints.

  • TypeScript o JavaScript: npm install @taglogger/sdk (paquete de npm). Funciona en Node 18 o posterior e incluye sus propios tipos.
  • Python: pip install taglogger-sdk (paquete de PyPI). Funciona en Python 3.9 o posterior sin otras dependencias y se importa como taglogger_sdk.
  • Clave de API: defina TAGLOGGER_API_KEY con una clave del espacio de trabajo que tenga el alcance read:tags. La página de autenticación explica los alcances y los encabezados.
Liste sus primeros 50 localizadores con el SDK de Python
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 "")

Leer el inicio rápido de la API

El SDK de TypeScript tiene la misma estructura: new TagLoggerClient({ apiKey }) y luego client.tags.list({ limit: 50 }). Ambos SDK cubren también el historial de ubicaciones, las geocercas, los webhooks y la verificación de firmas de webhooks.

Usos habituales de la exportación y la integración

  • Informes de auditoría: exportaciones mensuales o trimestrales que muestran la custodia y el movimiento de los activos para auditorías internas o externas
  • Documentación para seguros: exportación CSV del historial de ubicaciones para reclamaciones por pérdida y casos de robo
  • Conciliación de facturación: cotejar la ubicación de los activos con las fechas de alquiler contratadas o las visitas de servicio
  • Automatización de recuentos de inventario: instantáneas periódicas de la flota hacia sistemas de gestión de inventario
  • Registros de cumplimiento: historial de ubicaciones con marca de tiempo para requisitos normativos (controles de activos SOX, seguimiento de dispositivos HIPAA)
  • Paneles a medida: vistas unificadas que combinan los datos del AirTag con otros datos operativos (ERP, CRM, telemetría)
  • Flujos de análisis de datos: carga del historial del AirTag en BigQuery/Snowflake/Redshift para analizar la utilización de los activos

Seguridad en las exportaciones y el acceso por API

Los datos de ubicación del AirTag son valiosos: revelan dónde están y dónde han estado los activos (y, a menudo, las personas). Proteja los datos de exportación y de la API con controles de acceso adecuados. Limite las claves de API al alcance de permisos mínimo necesario. Guarde las claves de API en un gestor de secretos, no en archivos de configuración en texto plano. Registre los accesos a la API para auditoría.

En las exportaciones CSV que se comparten con terceros (peritos de seguros, policía, clientes en disputa), comparta solo la ventana de tiempo y los activos necesarios, no un volcado de toda la flota. TagLogger permite exportaciones por activo y acotadas en el tiempo precisamente para esto.

Los clientes de sectores regulados (salud, servicios financieros) suelen pasar los datos de exportación o de la API de TagLogger por su plataforma de cumplimiento en lugar de enviarlos directamente a los sistemas finales. Es un patrón razonable que el formato de exportación de TagLogger admite.

Cómo empezar con las exportaciones y la API

Empiece por la exportación CSV. No requiere desarrollo, funciona en cualquier hoja de cálculo y cubre la mayoría de los casos de auditoría y conciliación. La mayoría de los clientes de TagLogger usan CSV durante sus primeros 3–6 meses y solo pasan a la integración por API cuando surge una necesidad concreta de automatización.

Para la integración por API, el primer objetivo práctico es el webhook de geocerca, porque aporta señales basadas en eventos sin necesidad de una infraestructura de consultas periódicas. Un endpoint de webhook y unas pocas líneas de lógica pueden automatizar una parte importante del flujo de trabajo (alertas en Slack, creación de tickets, actualizaciones de estado) sin una integración a medida completa.

La integración completa con ERP/CMMS es un proyecto más grande y suele llegar después. Para entonces, los patrones operativos del seguimiento con AirTag ya se conocen bien, y la integración se centra en flujos de datos concretos en lugar de "conectarlo todo".

Preguntas frecuentes

Lleve los datos del AirTag a los sistemas que gestionan su operación

Exportación CSV, exportación JSON, acceso por API y webhooks: para que el historial de ubicaciones del AirTag alimente su ERP, CMMS, TMS, FSM y flujos de trabajo a medida sin silos de datos.