Integre SilentShield de forma segura en su formulario

Script de cliente, verificación en el servidor, claves y casos de error – la integración completa en un solo lugar.

Inicio rápido Configurar un dominio de prueba

Cómo funcionan juntos el script y la comprobación en el servidor

Una integración completa tiene dos mitades: el script en el navegador y una comprobación en su servidor.

1
El script se carga
Su página carga client.js?k=… con su clave de sitio. El script mide el comportamiento en el formulario.
2
Se envía el formulario
Al enviarlo, el script comunica la medición y añade el campo behavior_nonce a su formulario.
3
Su servidor consulta
Su servidor envía behavior_nonce a POST /api/v1/captcha/verify-nonce, con su clave en la cabecera X-Api-Key.
4
Usted decide
La respuesta contiene ok, verdict, confidence y reason_codes. Acepte el envío si ok es true; de lo contrario, recházelo.

Sin el paso 3, la integración solo protege a medias: el script por sí solo no detiene una solicitud enviada directamente a su servidor.

Clave de sitio y clave de servidor

Clave de sitio (pública)

client.js?k=…

Aparece en el código fuente de su página y es visible para cualquiera. Vincula el script a su dominio; los subdominios como www. o staging. están incluidos.

Clave de servidor (secreta, opcional)

X-Api-Key

Opcional. Si quiere que las llamadas que hace su servidor lleven un valor que no figure en el código fuente de su página, créela en el panel, en la clave, en la pestaña «Clave de servidor». Debe estar solo en su servidor, nunca en el navegador, y puede regenerarse en cualquier momento.

La comprobación en el servidor funciona solo con la clave de sitio, por lo que no necesita cambiar nada. Se aceptan ambas claves. Con la clave de servidor, el código de su servidor no contiene ningún valor que cualquiera pueda leer en el código fuente de su página.

Inicio rápido

Instalar e incrustar

Añada el script y obtenga un token

Verificar en el servidor

Valide el token en su backend

Prueba rápida con cURL

Verificar nonce desde la línea de comandos

# 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>

Seguridad y privacidad

Sin cookies – funcionamiento completamente sin cookies
Sin perfiles, sin cookies – utilizable conforme al GDPR
Alojamiento en la EU – verificación y almacenamiento en nuestros servidores en Alemania
Conforme a WCAG – accesible para todos los usuarios
Compatible con CSP – usar con 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 y Bibliotecas

El paquete se ejecuta en su servidor (Node.js 18 o superior). En el navegador no necesita ningún paquete: allí basta con el fragmento client.js del inicio 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

Referencia de la 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:

noncestringEl 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 con éxito

400Solicitud no válida (nonce faltante o incorrecto)

401Clave API no válida

403No confirmado como humano (ok: false): rechace el envío

429Límite de tasa excedido

500Error interno del servidor

Tiempos de espera, caídas y cuota

Establezca un tiempo de espera para la comprobación en el servidor. Nuestros ejemplos de código usan 5 segundos.
Si la comprobación no responde a tiempo, los ejemplos lo tratan como «no confirmado» y rechazan. Si en ese caso prefiere aceptar, capture usted mismo el error: la decisión es suya.
Si el primer host no responde mientras el script carga su configuración y sus componentes, recurre al segundo (api.silentshield.io y api-eu.silentshield.io). Las claves con vinculación estricta a la UE permanecen en el host de la UE.
No hay un host de respaldo automático para la comprobación en el servidor.
Por encima de su cuota mensual, la API sigue comprobando y responde como de costumbre. Un 429 significa que se ha superado el límite de solicitudes por minuto de su clave.

Pruebas en local y en un dominio de prueba

Su clave no funciona en localhost: está vinculada a su dominio y allí se rechaza el script.
Haga las pruebas en un subdominio de su dominio, por ejemplo staging.su-dominio.es. Funciona con la clave del dominio principal y no ocupa otra plaza de dominio.
Si quiere evaluar por separado las pruebas y producción, cree una segunda clave para el mismo dominio. Tampoco ocupa otra plaza de dominio.
Envíe un formulario de prueba y compruebe en su servidor la respuesta de verify-nonce: una entrada escrita a mano debería devolver ok: true; si no, los reason_codes muestran por qué.

Configurar un dominio de prueba

Versiones y cambios

La API lleva su versión en la ruta: /api/v1. Las mismas rutas están disponibles en /api.
El script no tiene número de versión: client.js siempre entrega la versión actual, así que no tiene que actualizar nada.
Los SDK para PHP, Node, Go y Edge tienen números de versión; los cambios figuran en el registro de cambios de cada paquete.
Publicamos los cambios de la API y del script en el registro de cambios.

Recursos

Centro de ayuda

Documentación completa con guías de primeros pasos, tutoriales de integración, referencias de configuración y solución de problemas.

Abrir el Centro de ayuda

Registro de cambios

Manténgase al día de las últimas funciones, mejoras y correcciones.

Ver el registro de cambios

¿Listo para empezar?

Cree una cuenta gratuita y obtenga su clave.

Empezar