API de QueUsan

En preparación. La API REST todavía no está disponible: esta página es un anticipo de cómo funcionará para que puedas planificar tu integración. Te avisaremos en cuanto se active. Mientras tanto, trabaja desde el panel web.

Una API REST simple para automatizar escaneos, consultar resultados y vigilar dominios desde tu propia infraestructura. Pensada para agencias que integran QueUsan en su pipeline de prospección.

Índice 1. Autenticación 2. Rate limits 3. Crear un escaneo 4. Consultar un escaneo 5. Watchlist 6. Export 7. Webhooks 8. Errores

1. Autenticación

Toda llamada a https://queusan.com/api/... requiere un header Authorization: Bearer <tu-api-key>. Las API keys se generan desde el dashboard y son exclusivas del plan Agencia.

curl -H "Authorization: Bearer qu_xxxxxxxxxxxxxxxxxxxx" \
     https://queusan.com/api/scan/14

Rotación

Las API keys no caducan automáticamente. Puedes revocar una key en cualquier momento desde el dashboard; tendrás que generar una nueva si lo haces.

2. Rate limits

El plan Agencia incluye 5000 peticiones diarias (rolling 24h). Si lo sobrepasas, recibes HTTP 429 con header Retry-After indicando segundos hasta el siguiente reset. Para volúmenes mayores, escribe a soporte@queusan.com.

3. Crear un escaneo

POST/api/v1/scan

Lanza un escaneo nuevo. Si la URL ya fue escaneada en las últimas 24h, devuelve el resultado cacheado salvo que pases force=1.

curl -X POST https://queusan.com/api/v1/scan \
  -H "Authorization: Bearer qu_..." \
  -d "url=https://ejemplo.com"

Respuesta (HTTP 200):

{
  "ok": true,
  "id": 1234,
  "url": "https://ejemplo.com",
  "domain": "ejemplo.com",
  "score": 78,
  "duration_ms": 1240
}

4. Consultar un escaneo

GET/api/v1/scan/{id}

Devuelve la estructura completa del escaneo, igual a la que verías en /scan/{id}.

{
  "id": 1234,
  "url": "https://ejemplo.com",
  "domain": "ejemplo.com",
  "score": 78,
  "cms":      { "name": "WordPress", "version": "6.4.2", "confidence": 95, "theme": "Astra" },
  "hosting":  { "provider": "Cloudflare", "country_iso": "US", "ip": "104.21.x.x", "https": true },
  "plugins":  [ { "name": "Yoast SEO", "slug": "wordpress-seo", "version": "21.7", "tier": "free" } ],
  "analytics":[ { "name": "Google Analytics 4", "id": "G-XXXX" } ],
  "fonts":    [ "Inter", "JetBrains Mono" ],
  "emails":   [ { "addr": "info@ejemplo.com", "source": "html", "protected": false } ],
  "social":   [ { "net": "twitter", "handle": "ejemplo" } ],
  "technologies": [ ... ],
  "security": { "score": 84, "grade": "B", "findings": [ ... ] },
  "scanned_at": 1714000000
}

5. Watchlist

GET/api/v1/watchlist

Lista los dominios en vigilancia.

POST/api/v1/watchlist

Añade un dominio. Body: domain=ejemplo.com.

6. Export

GET/api/export/scans

CSV con tus escaneos. También disponible /api/export/json y /api/export/emails.

7. Webhooks

Configura webhooks desde tu dashboard para recibir notificaciones POST de eventos. QueUsan firma cada payload con HMAC-SHA256 usando el secret que se te muestra al crearlo.

Eventos disponibles

watchlist.diff — un dominio vigilado cambió de stack.
scan.created — se ha guardado un nuevo escaneo en tu cuenta.
subscription.changed — cambio de plan o estado de suscripción.

Verificar la firma

// Node.js
const crypto = require("crypto");
const signature = req.headers["x-queusan-signature"];
const expected  = crypto.createHmac("sha256", SECRET)
                        .update(req.rawBody)
                        .digest("hex");
if (signature !== expected) return res.status(401).send("invalid signature");

8. Errores

La API devuelve siempre JSON con ok: false y error en caso de fallo. Códigos:

400 — petición mal formada
401 — API key inválida o no proporcionada
402 — operación requiere plan Agencia
404 — recurso no encontrado
419 — sesión expirada o token CSRF inválido (solo dashboard)
429 — rate limit excedido
5xx — error en QueUsan; reintenta con backoff exponencial

¿Algo no funciona o falta? Escribe a soporte@queusan.com.