Docs
Guia

Gerar um token de longa duração

Por padrão, um token de conta vale 14 dias. Para uma integração que roda sozinha (uma ferramenta de BI, uma planilha, um script), gere um token de longa duração definindo uma data de expiração no futuro. Esse token é somente leitura.

(Opcional) Obtenha um token de usuário

A chamada que gera o token de conta é autenticada com um token de usuário. Se você já tem um token de usuário válido, pule para o próximo passo.

Para obtê-lo, chame POST /user-tokens com autenticação HTTP Basic (o e-mail e a senha da conta). A resposta vem no mesmo envelope {"Ok": ...} e traz o token (o token de usuário), o valid_until e o user_email; o token de usuário também vale 14 dias. Esse token de usuário vai no cabeçalho Bearer do passo seguinte. Para detalhes sobre tokens e níveis de acesso, veja autenticação.

O Basic só funciona se a sua conta tem senha. Se você entra só com o Google, defina uma antes deste passo em "Definir senha", no card "Métodos de login" da sua conta.

bash
curl -X POST https://tgsr.com.br/user-tokens \
  -u "voce@exemplo.com:SUA_SENHA"

Gere o token

A chamada cria um token de conta com uma data de validade que você escolhe. Use POST /tokens, autenticado com o token de usuário no cabeçalho Authorization: Bearer, e mande no corpo o account_name e o valid_until (a data até quando o token deve valer, no formato ISO, sem fuso horário, como 2027-06-23T00:00:00).

bash
curl -X POST https://tgsr.com.br/tokens \
  -H "Authorization: Bearer SEU_TOKEN_DE_USUARIO" \
  -H "Content-Type: application/json" \
  -d '{"account_name": "minha-conta", "valid_until": "2027-06-23T00:00:00"}'

Ao informar valid_until, o token passa a valer até aquela data e é sempre somente leitura, qualquer que seja o seu papel na conta. Ele lê relatórios e dados, mas não altera nada. Esse é o nível certo para uma integração de analytics ou BI, e mantém o risco baixo caso o token vaze.

Dica

A janela de risco de um token vazado é o tempo até o valid_until. Se quiser reduzi-la, escolha uma data mais próxima e gere um token novo quando ela chegar.

Guarde o token

A resposta vem dentro do envelope {"Ok": ...} e traz o token e o valid_until até quando ele vale:

json
{"Ok": {"token": "tgsr-acc:KQ7P2-9XM4T-ABCDE-FGHIJ-KLMNO", "valid_until": "2027-06-23T00:00:00"}}

Num script, leia Ok.token, não token na raiz. O token aparece uma única vez. Copie e guarde em local seguro: se perder, não há como recuperar o mesmo token depois, e você terá que gerar outro.

(Opcional) Confira o token

Antes de colar o token em uma integração que roda sozinha, confirme que ele é válido e tem acesso de leitura. Chame GET /tokens/this autenticado com o próprio token no cabeçalho Bearer:

bash
curl https://tgsr.com.br/tokens/this \
  -H "Authorization: Bearer SEU_TOKEN"

Se o token é um token de conta válido com acesso de leitura, a chamada responde HTTP 200 com o corpo {"Ok": null}. Caso contrário, responde HTTP 403 ("Bad token").

Use o token

É um token Bearer normal, somente leitura. Mande no cabeçalho Authorization: Bearer SEU_TOKEN para ler relatórios e dados. Onde a integração só aceita uma URL (uma ferramenta de BI, uma planilha), passe o token no parâmetro ?token= dos relatórios. Para configurar o token em uma ferramenta de BI, veja relatórios no Power BI.

Veja também

AnteriorInício rápidoPróxima Autenticação