Referência de integração para terceirosTigerTagFirebase Integration
Ligar o Home Assistant, uma balança ESP32 ou um script Python a uma conta TigerTag.
Este repositório documenta a forma como qualquer cliente inicia sessão com as credenciais TigerTag do próprio utilizador, lê as respetivas bobinas de filamento e prateleiras no Firestore e volta a escrever o peso das bobinas. O que aqui está documentado é o que está implementado, e cada alteração fica registada no changelog.
O seu clienteHome Assistant · ESP32 · Python · Spoolman
email + password
Firebase AuthenticationA conta do próprio utilizador, um idToken de 1 hora
Authorization: Bearer {idToken}
Firestore Security RulesOs proprietários leem e escrevem, os amigos leem
Firestoreusers/{uid}/inventory
0.1.3Versão mais recente publicada do contrato (CHANGELOG, 2 de maio de 2026)
1 hDuração de um idToken: renove-o antes de expirar
5 minIntervalo mínimo de consulta recomendado
3 mesesPré-aviso mínimo de descontinuação antes de um campo ser renomeado ou removido
Como um cliente se liga ao TigerTag
Todos os clientes seguem os mesmos quatro passos: obter a configuração pública do Firebase, iniciar sessão como o utilizador, chamar a API REST do Firestore com o token do utilizador e manter esse token atualizado.
1
Obter a configuração pública
Um único GET devolve a configuração do projeto Firebase. A apiKey é pública por conceção: identifica o projeto, não quem faz o pedido. Guarde-a em cache; basta atualizá-la semanalmente.
O e-mail e a palavra-passe do próprio utilizador devolvem um UID, um idToken de 1 hora e um refreshToken. O Google Sign-In requer um navegador, pelo que os clientes sem interface gráfica usam uma palavra-passe.
Envie o idToken como token Bearer. As bobinas encontram-se em users/{uid}/inventory e as prateleiras em users/{uid}/racks; os pesos são gramas líquidas e as datas milissegundos Unix.
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}
Os valores entre chavetas provêm da chamada anterior: apiKey e projectId da configuração, uid e idToken do início de sessão.
Integrações documentadas neste repositório
Cada guia em docs/clients trata da autenticação, dos dados que lê ou escreve, do mapeamento de campos e do código. Os excertos abaixo foram copiados dos guias.
Esboço de componente
Home Assistant
Um componente personalizado do Home Assistant que disponibiliza um sensor por bobina, tendo como estado o peso restante em gramas. O guia aborda também os inventários dos amigos, a paginação e o armazenamento dos tokens; o config flow e o sensor são esqueletos, e falta ainda escrever um componente totalmente funcional.
Para uma balança ou um dispositivo NFC: procure uma bobina pelo UID RFID lido (uid e, a seguir, twin_uid), calcule o peso líquido e escreva weight_available e last_update com uma update mask. O guia termina com um sketch ESP32 completo (WiFi, ArduinoJson).
Um cliente Python mínimo assente no Pyrebase4: inicia sessão, lista as suas bobinas e indica quantas bobinas tem cada amigo. O guia contém o script completo e um exemplo de execução.
Uma ponte num só sentido do TigerTag para uma instância do Spoolman: as marcas passam a fornecedores, cada combinação de marca, material e cor passa a filamento, e cada documento de inventário passa a bobina, criado ou atualizado através da API REST do Spoolman. Pode ser executado a partir de cron, systemd ou Docker.
O contrato que uma TigerScale ou balança compatível cumpre para surgir online no Tiger Studio Manager e na aplicação móvel TigerTag: um documento de heartbeat a cada 30 segundos, uma atualização de peso em cada leitura estável e etiquetas gémeas escritas num único lote atómico.
users/{uid}/scales/{mac} ← heartbeat, every 30 s
users/{uid}/inventory/{spoolId} ← weight_available + last_update
A desenvolver para outra plataforma? Um novo guia vai para docs/clients e um exemplo executável opcional para examples/. CONTRIBUTING.md
A conta do utilizador, as regras do utilizador
Não há nenhuma chave partilhada a proteger nem nenhum token mestre que possa ser divulgado: um cliente pode fazer exatamente o que o seu utilizador pode fazer, e o Firestore impõe-no no servidor.
Sem conta de serviço
Todos os clientes iniciam sessão com as credenciais do próprio utilizador final. Nunca inclua o SDK firebase-admin nem qualquer chave de administrador num cliente de terceiros.
As Security Rules decidem
As Firestore Security Rules verificam cada pedido face a request.auth.uid: os proprietários leem e escrevem os seus próprios documentos, os amigos podem ler o inventário e as prateleiras, e tudo o que não for permitido é recusado. A cópia pública das regras encontra-se em rules/firestore.rules.
Um vínculo por amizade
Aceitar um pedido de amizade escreve um documento de cada lado. Enquanto users/{friend}/friends/{you} existir, pode ler o inventário e as prateleiras desse amigo, apenas em leitura; eliminá-lo corta o acesso de imediato.
Consulte no máximo a cada 5 minutos, nunca abaixo de 30 segundos, escreva apenas quando um valor mudar e indique um limite nas leituras de listas (200 bobinas, 50 prateleiras). O Firebase App Check não é imposto.
O repositório é tratado como um contrato público: as alterações que afetam os clientes chegam a este repositório na mesma versão, e o changelog regista cada uma como Added, Changed, Deprecated, Removed, Fixed ou Security.
Não muda sem pré-aviso
Caminhos de documentos como users/{uid}/inventory/{spoolId}, users/{uid}/racks/{rackId} e users/{uid}/friends/{friendUid}.
O nome e o significado de cada campo documentado: weight_available está em gramas líquidas, last_update em milissegundos Unix, deleted: true significa eliminação lógica.
O modelo de acesso entre amigos e os endpoints do Firebase Auth com que um cliente inicia sessão.
A apiKey e o projectId, salvo se todo o projeto for migrado, o que será anunciado com pelo menos 6 meses de antecedência.
Pode mudar: programe de forma defensiva
As tabelas de referência recebem novas marcas e materiais; os ids numéricos apenas são acrescentados e nunca reutilizados.
Os endpoints HTTPS de conveniência em cdn.tigertag.io podem alterar o formato dos pedidos e das respostas.
As novas coleções e os novos campos são sempre aditivos: ignore os campos que não conhece e mantenha-se compatível.
Preciso de uma conta de serviço ou de uma chave de administrador?
Não. Todos os clientes iniciam sessão com o e-mail e a palavra-passe TigerTag do próprio utilizador final, e as Firestore Security Rules determinam o que esse utilizador pode ler ou escrever. Não existe nenhuma chave de administrador partilhada, e o SDK firebase-admin nunca deve ser utilizado num cliente de terceiros.
Porque é que a apiKey do Firebase é pública?
A apiKey identifica o projeto Firebase do TigerTag, não quem faz o pedido. Sem um idToken válido, obtido ao iniciar sessão como um utilizador real, não dá acesso a nada; o controlo de acesso é assegurado pela autenticação e pelas Security Rules.
O Home Assistant ou um ESP32 podem iniciar sessão com o Google?
Não diretamente: o Google Sign-In requer um redirecionamento no navegador. Um utilizador que sempre usou apenas o Google define primeiro uma palavra-passe na conta, através da opção de palavra-passe esquecida da aplicação de computador ou móvel, e depois inicia sessão com e-mail e palavra-passe.
Com que frequência pode a minha integração fazer consultas?
No máximo a cada 5 minutos para um sensor, a cada 15 minutos para uma vista geral das prateleiras, e nunca abaixo de 30 segundos. Uma balança só escreve quando um peso muda. As leituras de listas devem indicar um limite: 200 para o inventário, 50 para as prateleiras.
A minha integração pode ler as bobinas de um amigo?
Sim, apenas em leitura. Quando dois utilizadores são amigos, cada um tem um documento relativo ao outro em users/{uid}/friends, e as regras permitem que um amigo leia o inventário e as prateleiras. Qualquer um dos dois pode pôr fim à amizade a qualquer momento, o que corta o acesso de imediato.
E se a produção não coincidir com esta documentação?
Prevalece a documentação: uma diferença significa que foi publicada uma regressão. Abra uma issue no repositório com a página, o caminho que leu ou escreveu e a resposta, depois de retirar os tokens e as chaves privadas.
Ao abrigo de que licença posso reutilizar o código?
As Security Rules e todos os excertos de código da documentação estão sob Apache-2.0, sendo dispensada a atribuição para excertos colados no seu próprio projeto. A documentação propriamente dita está sob CC-BY-4.0. O nome, o logótipo e o serviço TigerTag não estão abrangidos por estas licenças.
Comece a sua integração
Escolha o guia para a sua plataforma nas ligações rápidas do README e siga-o desde o início de sessão até à primeira leitura.
