API ServerDo.in v2

Integrações seguras para cache e otimização de conteúdo.

Disponibilidade controlada. As credenciais e os recursos são habilitados por projeto. Para integrar ou migrar uma versão anterior, entre em contato com o suporte da ServerDo.in.

Primeiros passos

A API v2 permite renovar objetos de cache e controlar a geração de WebP sem expor credenciais na aplicação cliente. Todas as requisições usam HTTPS e retornam JSON.

Não envie tokens, assinaturas ou chaves pelo navegador. As chamadas devem partir do servidor autorizado do projeto.

Autenticação

A API pública usa credenciais provisionadas por projeto, assinatura HMAC e proteção contra repetição. A API local usa um token armazenado no próprio servidor.

Headers da API pública

Header	Finalidade
`Idempotency-Key`	Identifica a operação e evita execução duplicada.
`X-ServerDo-Key-Id`	Identifica a credencial do projeto.
`X-ServerDo-Timestamp`	Horário Unix usado na validação.
`X-ServerDo-Nonce`	Valor aleatório de uso único.
`X-ServerDo-Signature`	Assinatura HMAC-SHA256 da requisição.

A string canônica é formada por horário, nonce e SHA-256 do corpo JSON, separados por quebra de linha. O segredo nunca deve ser enviado na requisição ou gravado em logs.

String canônica

TIMESTAMP + "\n" + NONCE + "\n" + SHA256(CORPO_JSON)

POST

Renovar cache público

/api/v2/cache/purge

Renova uma URL específica nos servidores de CDN associados ao projeto. Publicações e atualizações devem usar purge_url.

purge_site é uma ação excepcional, manual e sujeita a permissão específica. Nunca use limpeza completa como fallback para erro, chave desconhecida ou falha parcial.

Corpo JSON

{
  "operation": "purge_url",
  "domain": "portal.exemplo",
  "url": "https://portal.exemplo/noticia/",
  "key_profile": "serverdoin-v3",
  "reason": "publish"
}

Resposta

Sucesso ou conclusão parcial

{
  "status": "success",
  "operation_id": "ID_DA_OPERACAO",
  "objects_found": 2,
  "objects_deleted": 2,
  "nodes": [
    {
      "status": "success",
      "objects_found": 1,
      "objects_deleted": 1
    }
  ]
}

A resposta pública não informa nomes internos de servidores, IPs, caminhos de arquivos ou comandos executados.

POST

Renovar Cache Local

/_serverdoin/v2/cache/purge

Remove as variantes site e mobile da URL no cache do publicador. O endpoint é local ao projeto e requer Bearer token provisionado no servidor.

Exemplo

curl -X POST \
  "https://controle.portal.exemplo/_serverdoin/v2/cache/purge" \
  -H "Authorization: Bearer TOKEN_LOCAL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ID_UNICO" \
  --data '{
    "operation": "purge_url",
    "url": "https://portal.exemplo/noticia/",
    "key_profile": "serverdoin-v3"
  }'

Perfil de chave serverdoin-v3

O perfil atual separa páginas HTML para desktop e mobile. Arquivos estáticos não variam por dispositivo.

HTML no CDN$mobile_request$uri$c_uri

HTML no Cache Local$mobile_request$cache_uri$c_uri

Arquivos estáticossite$uri$c_uri

Variantessite, mobile

$cache_uri preserva o caminho original antes do processamento interno do WordPress. $c_uri preserva parâmetros funcionais e remove parâmetros de campanha conhecidos que não devem criar cópias extras do cache. A API rejeita perfis desconhecidos; ela não converte esse caso em limpeza completa.

POST

Controlar WebP

/_serverdoin/v2/webp

Ativa ou desativa a conversão e a entrega de WebP no projeto. A operação é processada em segundo plano e o estado deve ser consultado até a conclusão.

Ativar

curl -X POST \
  "https://controle.portal.exemplo/_serverdoin/v2/webp" \
  -H "Authorization: Bearer TOKEN_LOCAL" \
  -H "Content-Type: application/json" \
  --data '{"action":"enable"}'

Consultar estado

curl \
  "https://controle.portal.exemplo/_serverdoin/v2/webp" \
  -H "Authorization: Bearer TOKEN_LOCAL"

Códigos de erro

HTTP	Significado	Ação recomendada
`400`	Corpo ou operação inválida.	Revise o JSON e o tipo da operação.
`401`	Credencial ou assinatura ausente.	Confira os headers sem registrar o segredo.
`403`	Projeto sem permissão para o recurso.	Solicite a habilitação ao suporte.
`409`	Nonce ou operação repetida.	Consulte a operação original.
`422`	Domínio, URL ou perfil incompatível.	Não faça fallback para `purge_site`.
`429`	Limite temporário atingido.	Respeite `Retry-After`.
`5xx`	Falha temporária ou parcial.	Preserve o cache e tente novamente com a mesma idempotência.