Referencia de integración para tercerosTigerTagFirebase Integration
Conecta Home Assistant, una báscula ESP32 o un script de Python a una cuenta TigerTag.
Este repositorio documenta cómo cualquier cliente inicia sesión con las credenciales TigerTag del propio usuario, lee sus bobinas de filamento y sus estanterías en Firestore y vuelve a escribir el peso de las bobinas. Lo que se documenta aquí es lo que está desplegado, y cada cambio queda registrado en el changelog.
Tu clienteHome Assistant · ESP32 · Python · Spoolman
email + password
Firebase AuthenticationLa cuenta del propio usuario, un idToken de 1 hora
Authorization: Bearer {idToken}
Firestore Security RulesLos propietarios leen y escriben, los amigos leen
Firestoreusers/{uid}/inventory
0.1.3Última versión publicada del contrato (CHANGELOG, 2 de mayo de 2026)
1 hDuración de un idToken: renuévalo antes de que caduque
5 minIntervalo mínimo de sondeo recomendado
3 mesesPreaviso mínimo de obsolescencia antes de renombrar o eliminar un campo
Cómo se conecta un cliente a TigerTag
Todos los clientes siguen los mismos cuatro pasos: obtener la configuración pública de Firebase, iniciar sesión como el usuario, llamar a la API REST de Firestore con el token del usuario y mantener ese token vigente.
1
Obtener la configuración pública
Un solo GET devuelve la configuración del proyecto Firebase. El apiKey es público por diseño: identifica el proyecto, no a quien llama. Guárdalo en caché; basta con renovarlo una vez por semana.
El correo y la contraseña del propio usuario devuelven un UID, un idToken de 1 hora y un refreshToken. Google Sign-In necesita un navegador, así que los clientes sin interfaz usan una contraseña.
Envía el idToken como token Bearer. Las bobinas están en users/{uid}/inventory y las estanterías en users/{uid}/racks; los pesos son gramos netos y las fechas, milisegundos Unix.
Renueva el idToken antes de que pase la hora y sustituye los dos tokens guardados. Ante un permission-denied, renueva una vez y reintenta la lectura una vez.
GET https://tigertag-cdn.web.app/__/firebase/init.json
POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key={apiKey}
{ "email": "user@example.com", "password": "…", "returnSecureToken": true }
GET https://firestore.googleapis.com/v1/projects/{projectId}/databases/(default)/documents/users/{uid}/inventory
Authorization: Bearer {idToken}
Los valores entre llaves proceden de la llamada anterior: apiKey y projectId de la configuración, uid e idToken del inicio de sesión.
Integraciones documentadas en este repositorio
Cada guía de docs/clients cubre la autenticación, los datos que lee o escribe, la correspondencia de campos y el código. Los fragmentos siguientes están copiados de las guías.
Esbozo de componente
Home Assistant
Un componente personalizado de Home Assistant que expone un sensor por bobina, con el peso restante en gramos como estado. La guía también cubre los inventarios de los amigos, la paginación y el almacenamiento de tokens; el config flow y el sensor son esqueletos, y aún falta escribir un componente completamente funcional.
Para una báscula o un dispositivo NFC: busca una bobina por el UID RFID escaneado (uid y luego twin_uid), calcula el peso neto y escribe weight_available y last_update con una máscara de actualización. La guía termina con un sketch completo para ESP32 (WiFi, ArduinoJson).
Un cliente mínimo en Python basado en Pyrebase4: inicia sesión, lista tus bobinas y muestra cuántas bobinas tiene cada amigo. La guía contiene el script completo y un ejemplo de ejecución.
Un puente unidireccional de TigerTag a una instancia de Spoolman: las marcas se convierten en vendors, cada combinación de marca, material y color en un filament, y cada documento del inventario en un spool, creado o actualizado mediante la API REST de Spoolman. Se ejecuta desde cron, systemd o Docker.
El contrato que sigue una TigerScale o una báscula compatible para aparecer en línea en Tiger Studio Manager y en la aplicación móvil TigerTag: un documento de latido cada 30 segundos, una actualización de peso en cada lectura estable y las etiquetas gemelas escritas en un único lote atómico.
users/{uid}/scales/{mac} ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId} ← weight_available + last_update
¿Desarrollas para otra plataforma? Una guía nueva va en docs/clients, y un ejemplo ejecutable opcional en examples/. CONTRIBUTING.md
La cuenta del usuario, las reglas del usuario
No hay ninguna clave compartida que proteger ni ningún token maestro que pueda filtrarse: un cliente puede hacer exactamente lo que puede hacer su usuario, y Firestore lo aplica en el servidor.
Sin cuenta de servicio
Cada cliente inicia sesión con las credenciales del propio usuario final. Nunca incluyas el SDK firebase-admin ni ninguna clave de administrador en un cliente de terceros.
Las Security Rules deciden
Las Firestore Security Rules comprueban cada solicitud frente a request.auth.uid: los propietarios leen y escriben sus propios documentos, los amigos pueden leer el inventario y las estanterías, y todo lo que no está permitido se deniega. La copia pública de las reglas está en rules/firestore.rules.
Un vínculo por amistad
Aceptar una solicitud de amistad escribe un documento en cada lado. Mientras exista users/{friend}/friends/{you}, puedes leer el inventario y las estanterías de ese amigo, en solo lectura; eliminarlo corta el acceso de inmediato.
Sondea como máximo cada 5 minutos, nunca por debajo de 30 segundos, escribe solo cuando un valor cambie y pasa un límite en las lecturas de listas (200 bobinas, 50 estanterías). Firebase App Check no se aplica.
El repositorio se trata como un contrato público: los cambios que afectan a los clientes llegan a este repositorio en la misma versión, y el changelog registra cada uno como Added, Changed, Deprecated, Removed, Fixed o Security.
No cambiará sin previo aviso
Las rutas de documentos como users/{uid}/inventory/{spoolId}, users/{uid}/racks/{rackId} y users/{uid}/friends/{friendUid}.
El nombre y el significado de cada campo documentado: weight_available son gramos netos, last_update son milisegundos Unix, deleted: true indica un borrado lógico.
El modelo de acceso de los amigos y los endpoints de Firebase Auth con los que inicia sesión un cliente.
El apiKey y el projectId, salvo que se traslade el proyecto entero, lo que se anunciaría con al menos 6 meses de antelación.
Puede cambiar: programa a la defensiva
Las tablas de referencia incorporan nuevas marcas y materiales; los identificadores numéricos solo se añaden y nunca se reutilizan.
Los endpoints HTTPS de conveniencia en cdn.tigertag.io pueden cambiar la forma de sus solicitudes y respuestas.
Las nuevas colecciones y los nuevos campos siempre se añaden sin romper nada: ignora los campos que no conozcas y seguirás siendo compatible.
¿Necesito una cuenta de servicio o una clave de administrador?
No. Cada cliente inicia sesión con el correo y la contraseña TigerTag del propio usuario final, y las Firestore Security Rules deciden qué puede leer o escribir ese usuario. No existe ninguna clave de administrador compartida, y el SDK firebase-admin nunca debe usarse en un cliente de terceros.
¿Por qué es público el apiKey de Firebase?
El apiKey identifica el proyecto Firebase de TigerTag, no a quien llama. Sin un idToken válido, obtenido al iniciar sesión como un usuario real, no da acceso a nada; el control de acceso lo realizan la autenticación y las Security Rules.
¿Puede Home Assistant o un ESP32 iniciar sesión con Google?
No directamente: Google Sign-In necesita una redirección en el navegador. Un usuario que solo ha usado Google establece primero una contraseña en la cuenta, mediante la función de contraseña olvidada de la aplicación de escritorio o móvil, y después inicia sesión con correo y contraseña.
¿Con qué frecuencia puede sondear mi integración?
Como máximo cada 5 minutos para un sensor, cada 15 minutos para una vista general de estanterías, y nunca por debajo de 30 segundos. Una báscula solo escribe cuando cambia un peso. Las lecturas de listas deben pasar un límite: 200 para el inventario, 50 para las estanterías.
¿Puede mi integración leer las bobinas de un amigo?
Sí, en solo lectura. Cuando dos usuarios son amigos, cada uno tiene un documento del otro en users/{uid}/friends, y las reglas permiten a un amigo leer el inventario y las estanterías. Cualquiera de los dos puede eliminar la amistad en cualquier momento, lo que corta el acceso de inmediato.
¿Y si la producción no coincide con esta documentación?
Prevalece la documentación: una diferencia significa que se ha publicado una regresión. Abre una issue en el repositorio con la página, la ruta que leíste o escribiste y la respuesta, sin tokens ni claves privadas.
¿Bajo qué licencia puedo reutilizar el código?
Las Security Rules y todos los fragmentos de código de la documentación están bajo Apache-2.0, y no se exige atribución para los fragmentos que pegues en tu propio proyecto. La documentación en sí está bajo CC-BY-4.0. El nombre, el logotipo y el servicio TigerTag no están cubiertos por estas licencias.
Empieza tu integración
Elige la guía de tu plataforma en los enlaces rápidos del README y síguela desde el inicio de sesión hasta tu primera lectura.
