Início rápido

Em poucos minutos você sai de uma conta TagServer e chega a um Smart Link criado via API. O caminho tem quatro chamadas: você troca e-mail e senha por um token de usuário, gera um token da conta, cria o link e confirma que ele existe. Cada passo é um curl.

Antes de começar

Uma conta TagServer, com e-mail e senha (se você criou a conta só com o Google, defina uma senha antes em "Definir senha", no card "Métodos de login" da conta).
O account_name da conta sobre a qual você vai trabalhar.
A base da API, https://tgsr.com.br: é o mesmo host que o dashboard chama, e os comandos abaixo já usam esse endereço (o modelo de host está explicado na introdução).
O curl disponível no terminal.

Toda resposta de sucesso chega no formato {"Ok": <valor>} e toda falha chega como {"Err": "<mensagem>"}; o envelope completo está em convenções e erros.

1. Obtenha um token de usuário

A primeira chamada troca suas credenciais por um token de usuário. Ela usa HTTP Basic: você manda e-mail e senha no cabeçalho Authorization: Basic, e o curl monta isso para você com a opção -u.

bash

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

A resposta traz o token, sua data de validade e o e-mail da conta de usuário:

json

{"Ok": {"token": "<token-de-usuario>", "valid_until": "<timestamp>", "user_email": "voce@exemplo.com"}}

Esse token prova quem você é; ele ainda não escolhe uma conta. A validade padrão é de 14 dias.

2. Gere um token da conta

Agora você diz sobre qual conta vai agir. Envie o token de usuário em Authorization: Bearer e passe o account_name no corpo JSON:

bash

curl -X POST https://tgsr.com.br/tokens \
  -H "Authorization: Bearer <token-de-usuario>" \
  -H "Content-Type: application/json" \
  -d '{"account_name": "minha-conta"}'

A resposta traz o token da conta e sua validade:

json

{"Ok": {"token": "<token-da-conta>", "valid_until": "<timestamp>"}}

Se o nome não existir ou você não tiver permissão sobre ele, a resposta é {"Err": "Error 400: No such account (or not authorized): <nome>"}.

Esse token da conta age sobre uma única conta, e é ele que você usa nas chamadas seguintes.

3. Crie um Smart Link

Com o token da conta em mãos, crie o Smart Link. Use o servidor global, que já está disponível, então você não precisa registrar um servidor antes. A rota é PUT /servers/global/links, e o corpo informa o nome do link e o destino:

bash

curl -X PUT https://tgsr.com.br/servers/global/links \
  -H "Authorization: Bearer <token-da-conta>" \
  -H "Content-Type: application/json" \
  -d '{"link_name": "promo-verao", "location": "https://seusite.com.br/promo"}'

O location precisa ser uma URL absoluta e completa, com https://. A API não completa o esquema por você, e uma URL inválida retorna um erro 400 cuja mensagem começa com Error 400: bad URL.

Em caso de sucesso, a resposta é o envelope {"Ok": ...} sem campos, e vem com um cabeçalho ETag que carrega a versão do link recém-criado. O cabeçalho ETag e o formato completo das mensagens de erro estão descritos em convenções e erros.

4. Confirme o link

Para confirmar que o link foi criado, liste os links da conta com GET /links:

bash

curl https://tgsr.com.br/links \
  -H "Authorization: Bearer <token-da-conta>"

A resposta é uma lista, e o link que você acabou de criar está lá:

json

{"Ok": [
  {
    "server_name": null,
    "link_name": "promo-verao",
    "location": "https://seusite.com.br/promo",
    "created_at": "<timestamp>",
    "etag": "<etag>"
  }
]}

Para links do servidor global, server_name vem null. Pronto: o Smart Link existe e responde.

Próximos passos

Para os tipos de token, níveis de acesso e validade que este tutorial só tocou, veja a referência de autenticação. Todos os campos e operações de Smart Links via API (criar, listar, excluir, gerar QR) estão na referência de links. O envelope completo, os códigos de status e a escrita condicional com ETag e If-Match ficam em convenções e erros. E se você ainda decide entre a API REST e o MCP, a introdução explica quando usar cada um.