Integre o SilentShield com segurança no seu formulário

Script de cliente, verificação no servidor, chaves e casos de erro – a integração completa num só lugar.

Início rápido Configurar um domínio de teste

Como o script e a verificação no servidor funcionam em conjunto

Uma integração completa tem duas metades: o script no navegador e uma verificação no seu servidor.

1
O script é carregado
A sua página carrega client.js?k=… com a sua chave do site. O script mede o comportamento no formulário.
2
O formulário é enviado
Ao enviar, o script comunica a medição e adiciona o campo behavior_nonce ao seu formulário.
3
O seu servidor consulta
O seu servidor envia behavior_nonce para POST /api/v1/captcha/verify-nonce, com a sua chave no cabeçalho X-Api-Key.
4
A decisão é sua
A resposta contém ok, verdict, confidence e reason_codes. Aceite o envio se ok for true; caso contrário, rejeite-o.

Sem o passo 3, a integração só protege pela metade: o script sozinho não impede um pedido enviado diretamente para o seu servidor.

Chave do site e chave de servidor

Chave do site (pública)

client.js?k=…

Aparece no código-fonte da sua página e é visível para qualquer pessoa. Associa o script ao seu domínio; subdomínios como www. ou staging. estão incluídos.

Chave de servidor (secreta, opcional)

X-Api-Key

Opcional. Se quiser que as chamadas feitas pelo seu servidor levem um valor que não está no código-fonte da sua página, crie-a no painel, na chave, no separador “Chave de servidor”. Deve ficar apenas no seu servidor, nunca no navegador, e pode ser regenerada a qualquer momento.

A verificação no servidor funciona apenas com a chave do site, pelo que não precisa de alterar nada. Ambas as chaves são aceites. Com a chave de servidor, o código do seu servidor não contém nenhum valor que qualquer pessoa possa ler no código-fonte da sua página.

Início rápido

Instalar e incorporar

Adicione o script e obtenha um token

Verificar no servidor

Valide o token no seu backend

Teste rápido com cURL

Verificar nonce a partir da linha de comando

# Verificar Nonce
curl -X POST https://api.silentshield.io/api/v1/captcha/verify-nonce \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"}'

Frontend Integration

Add the client script with SRI and defer attributes

<!-- In <head> or before </body> of every page with a form -->
<script src="https://api.silentshield.io/client.js?k=YOUR_API_KEY" defer></script>

Segurança e privacidade

Sem cookies – operação totalmente sem cookies
Sem perfis, sem cookies – utilizável em conformidade com o GDPR
Alojamento na EU – verificação e armazenamento nos nossos servidores na Alemanha
Conformidade com WCAG – acessível a todos os utilizadores
Compatível com CSP – use com Content Security Policy:

Content-Security-Policy: script-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; connect-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; worker-src 'self' blob:;

SDKs e Bibliotecas

O pacote corre no seu servidor (Node.js 18 ou superior). No navegador não precisa de pacote nenhum — aí basta o excerto client.js do arranque rápido.

Node.js / Express

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

app.post("/signup", async (req, res) => {
  const { human } = await shield.verify(req.body.behavior_nonce);
  if (!human) return res.status(403).send("Verification failed");
  res.send("ok");
});

NPM

Agentes de IA (Node.js)

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient, enforce } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

// Reports bot candidates only — never blocks, never sees human traffic.
app.use(shield.observe);

// Applies your policy locally from a signed bundle. Fail-open.
app.use(enforce({ apiKey: process.env.SILENTSHIELD_API_KEY }));

NPM

Referência da API

API Version: 2025-10-01 · Base URL: https://api.silentshield.io

POST/api/v1/captcha/verify-nonce

Verificar Nonce SilentShield

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringO Nonce a verificar

Response:

Success (200):

{
  "ok": true,
  "verdict": "human",
  "confidence": 0.95,
  "requested_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"
}

Error:

{
  "ok": false,
  "verdict": "bot",
  "confidence": 0.12,
  "request_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659",
  "reason_codes": ["NO_MOUSE_MOVEMENT"]
}

Status Codes:

200Nonce verificado com sucesso

400Pedido inválido (Nonce ausente ou incorreto)

401Chave API inválida

403Não confirmado como humano (ok: false) – rejeite o envio

429Limite de taxa excedido

500Erro interno do servidor

Tempos limite, falhas e quota

Defina um tempo limite para a verificação no servidor. Os nossos exemplos de código usam 5 segundos.
Se a verificação não responder a tempo, os exemplos tratam isso como “não confirmado” e rejeitam. Se, nesse caso, preferir aceitar, trate o erro por si — a decisão é sua.
Se o primeiro host não responder enquanto o script carrega as suas definições e componentes, passa para o segundo (api.silentshield.io e api-eu.silentshield.io). As chaves com vinculação estrita à UE permanecem no host da UE.
Não existe um host de recurso automático para a verificação no servidor.
Acima da sua quota mensal, a API continua a verificar e responde normalmente. Um 429 significa que o limite de pedidos por minuto da sua chave foi excedido.

Testar localmente e num domínio de teste

A sua chave não funciona em localhost: está associada ao seu domínio e o script é aí rejeitado.
Teste num subdomínio do seu domínio, por exemplo staging.seu-dominio.com. Funciona com a chave do domínio principal e não ocupa outra vaga de domínio.
Se quiser avaliar o teste e a produção separadamente, crie uma segunda chave para o mesmo domínio. Também esta não ocupa outra vaga de domínio.
Envie um formulário de teste e verifique no seu servidor a resposta de verify-nonce: uma entrada escrita à mão deve devolver ok: true; caso contrário, os reason_codes mostram porquê.

Configurar um domínio de teste

Versões e alterações

A API indica a sua versão no caminho: /api/v1. As mesmas rotas estão disponíveis em /api.
O script não tem número de versão: client.js entrega sempre a versão atual, pelo que não precisa de atualizar nada.
Os SDK para PHP, Node, Go e Edge têm números de versão; as alterações constam do registo de alterações de cada pacote.
Publicamos as alterações à API e ao script no registo de alterações.

Recursos

Centro de ajuda

Documentação completa com guias de introdução, tutoriais de integração, referências de configuração e resolução de problemas.

Abrir o Centro de ajuda

Registo de alterações

Mantenha-se a par das mais recentes funcionalidades, melhorias e correções.

Ver o registo de alterações

Pronto para começar?

Crie uma conta gratuita e obtenha a sua chave.

Começar agora