Servidores de rastreamento

Um servidor de rastreamento é o domínio do cliente (metrics.seu-site.com.br, por exemplo) sob o qual os Smart Links, pixels e eventos são servidos. Cada endpoint abaixo age sobre a conta resolvida pelo token Bearer (veja Autenticação para o cabeçalho).

Endpoints

Método	Rota	O que faz	Acesso
`GET`	`/servers`	Lista todos os servidores de rastreamento da conta. Retorna `{ "servers": [ ... ] }`, cada item no formato de Campos do servidor.	ReadOnly
`GET`	`/servers/{server_name}`	Obtém um servidor pelo domínio. Retorna o objeto do servidor e o cabeçalho `ETag` (é a única rota de leitura que devolve esse cabeçalho). Servidor inexistente: `404`.	ReadOnly
`PUT`	`/servers`	Registra ou atualiza um servidor. Corpo: `{ "server_name": "<dominio>" }`. Antes de pedir o certificado, roda a mesma verificação de `check-dns`; se o domínio ainda não aponta só para o TagServer, responde `400` ("DNS is not ready") sem contatar a autoridade certificadora. Com o DNS correto, emite/instala o certificado TLS e grava a linha. Um servidor sem nenhuma regra recebe as regras de rastreamento padrão; um servidor que já tem regras não é alterado, e uma falha nessa etapa não faz o `PUT` falhar. Aceita `If-Match` e retorna o cabeçalho `ETag`. Falha de DNS ou ao criar/instalar o certificado: `400`. `If-Match` que não bate: `412`.	Standard
`DELETE`	`/servers/{server_name}`	Exclui um servidor pelo domínio e remove na hora o certificado do domínio, que deixa de ser servido via TLS imediatamente. Retorna `{ "was_deleted": true \| false }` (`false` quando não havia linha para excluir).	Standard
`GET`	`/servers/dns-config`	Retorna os registros DNS que você cria para apontar um domínio ao TagServer: `{ "cname": "<dominio>", "a": "<IPv4>", "aaaa": "<IPv6>" }`. Use o par `a` + `aaaa` ou o `cname` (o destino CNAME resolve para os mesmos `a` e `aaaa`).	Não exige token
`GET`	`/servers/check-dns`	Verifica se um domínio aponta para o TagServer, por registros A/AAAA ou por CNAME. Parâmetro de query obrigatório: `domain`.	Não exige token
`POST`	`/servers/{server_name}/force-renew`	Dispara uma rodada de renovação do certificado TLS. Responde `NotYetDue` quando nenhuma renovação foi executada nesta chamada; caso contrário, `Success` ou `Error`. Servidor inexistente: `404`.	Standard

Campos do servidor

Campo	Descrição
`server_name`	O domínio do servidor de rastreamento.
`created_at`	Data/hora de criação.
`renewed_at`	Data/hora da última renovação do certificado.
`expires_at`	Data/hora de expiração do certificado (pode ser nulo).
`last_error`	Última mensagem de erro do servidor (nulo quando não há erro).
`last_error_at`	Data/hora do último erro (pode ser nulo).
`etag`	O token de mudança da linha; reenvie como `If-Match` numa escrita condicional. A forma serializada difere por rota: em `GET /servers/{server_name}` vem como o ETag forte, entre aspas e igual ao cabeçalho `ETag`; em `GET /servers` (listagem) vem como o token cru, sem aspas. Os dois valem como `If-Match`.

Verificação de DNS

check-dns resolve todos os endereços A e AAAA do domínio, seguindo CNAMEs, e compara com os endereços do TagServer (a e aaaa de dns-config). Passa só quando todo endereço encontrado é do TagServer: um único endereço estranho (um AAAA antigo ao lado de um A correto, por exemplo) basta para falhar. A resposta é { "issue": <null | objeto> }; o objeto traz o estado no campo type.

Resultado	Significado
`null`	DNS correto.
`NoRecords`	O domínio não resolve para nenhum endereço A ou AAAA, nem direto, nem via CNAME.
`WrongAddress`	Pelo menos um endereço do domínio não é do TagServer. O objeto traz `found` (os endereços encontrados) e `valid` (os endereços do TagServer), ambos listas de IPs.

O passo a passo para configurar os registros está em Referência de DNS e SSL.

Renovação forçada

Tipo	Significado
`NotYetDue`	Nenhuma renovação foi executada nesta chamada: a rodada de renovação não rodou.
`Success`	A rodada de renovação foi concluída com sucesso.
`Error`	A renovação foi tentada e falhou. O objeto traz a mensagem de erro.

Escrita condicional

GET /servers/{server_name} retorna o cabeçalho ETag (a listagem traz só o campo etag de cada item); reenvie-o como If-Match num PUT /servers condicional. Se a linha mudou desde a leitura, a resposta é 412. O mecanismo está descrito em Convenções e erros.

Veja também

Smart Links na API: os Smart Links ficam sob um servidor de rastreamento.
Referência de DNS e SSL: o que significam o CNAME e o SSL do lado do usuário.
Convenções e erros: envelope de resposta, status e escrita condicional.
Referência do MCP: as ferramentas MCP equivalentes a estas rotas.