Smart Links
Os endpoints abaixo gerenciam smart links via HTTP. Cada link pertence a um servidor de rastreamento e é endereçado pelo seu slug; o nome reservado global endereça um link de conta, sem servidor. As chamadas autenticadas (listar, upsert, excluir, estatísticas) agem sobre a conta resolvida pelo token (veja Autenticação); o QR e o redirect são públicos e não resolvem conta por token.
Endpoints
| Método | Rota | O que faz | Acesso |
|---|---|---|---|
| GET | /links | Lista todos os links da conta. | ReadOnly |
| PUT | /servers/{server_name}/links | Cria ou atualiza (upsert) um link no servidor. | Standard |
| DELETE | /servers/{server_name}/links/{link_name} | Exclui um link do servidor pelo slug. Retorna { "was_deleted": <bool> }. | Standard |
| GET | /links/stats | Estatísticas de cliques dos links da conta. | ReadOnly |
| GET | /servers/{server_name}/links/qr/{link_with_ext} | Imagem do QR code de um link. O QR aponta para https://{server_name}/l/{link_name}; quando server_name é global, o domínio embutido é o domínio principal do TagServer. | Público, sem token |
| GET | /l/{link_name} | Redirecionamento público que resolve e consome o smart link. O slug é resolvido contra o host da requisição: num domínio principal do TagServer, vale o link de conta (global); em outro host, o próprio host é o nome do servidor de rastreamento. O mesmo slug em hosts diferentes resolve para links diferentes. Registra o clique que alimenta /links/stats e responde 301 com cabeçalho Location. | Público, sem token |
No QR code, o segmento final é o nome do link seguido da extensão do arquivo, por exemplo meulink.png ou meulink.svg. Os formatos servidos são png e svg. Extensão ausente (segmento sem ponto) retorna 400; extensão presente porém não suportada (por exemplo meulink.jpg) retorna 500.
Corpo da escrita (PUT /servers/{server_name}/links)
| Campo | Descrição |
|---|---|
link_name | O slug do link. |
location | A URL de destino. Precisa ser uma URL válida, senão 400. |
O namespace global é compartilhado entre contas. Um upsert sem If-Match de um slug global que já pertence a outra conta não sobrescreve nada e retorna 400 (A link with name '<link_name>' already exists).
Campos do item (GET /links)
| Campo | Descrição |
|---|---|
server_name | O servidor de rastreamento do link. Nulo para um link de conta sem servidor. |
link_name | O slug do link. |
location | A URL de destino. |
created_at | Data e hora de criação. |
etag | O ETag do link, um token opaco. Reenvie como If-Match numa escrita condicional. |
Estatísticas (GET /links/stats)
Todos os parâmetros de query são opcionais.
| Parâmetro | Descrição |
|---|---|
links | Lista de slugs separada por vírgula. Filtra a quais links a estatística se refere. |
since / until | Janela de tempo. Cada valor é um datetime ISO-8601 naive, sem timezone (por exemplo 2026-06-13T00:00:00); não é um unix timestamp. Ausentes, o padrão é dos últimos 7 dias até agora. |
step | Intervalo de agregação temporal. Valores: minute, hour, day, week, year, all. Os nomes em PascalCase (Minute, Hour, Day, ...) ainda são aceitos como alias legado. Padrão (omitido): day. |
O retorno tem o formato { "data": [ { "link_name", "epoch", "count" } ] }, agregado por link e intervalo, ordenado e com no máximo 2000 linhas.
Escrita condicional
A leitura traz um ETag. Reenvie-o como If-Match no PUT: se o link mudou desde a leitura, a resposta é 412 e nada é gravado. O PUT bem-sucedido devolve o cabeçalho ETag do estado gravado, que serve para a próxima escrita condicional sem reler. O mecanismo está descrito em Convenções e erros.
Veja também
- Criando e gerenciando Smart Links: o conceito e a interface dos smart links.
- Parâmetros e rastreamento: parâmetros de rastreamento e estatísticas pelo lado do produto.
- Servidores de rastreamento: a referência irmã da mesma seção.