Crawlux para desarrolladores y plataformas.
Documentación de referencia para la salida JSON de auditoría Crawlux (en vivo hoy), payloads de webhooks (en vivo hoy) y la API REST Crawlux planeada (enviándose Q4 2026). Más patrones de integración para agencias, plataformas SEO y sistemas CRM.
Estado actual y roadmap
Tres categorías de funcionalidad cara-al-desarrollador. Dos están en vivo hoy. Una se envía Q4 2026.
Cada auditoría produce una salida JSON descargable desde el dashboard. Los tiers Free, Pro y Team todos incluyen JSON. Estructura documentada en la sección 2.
Configura una URL de webhook en el dashboard. Crawlux hace POST del JSON completo de la auditoría a la URL al completar. Solo tiers Pro y Team. Documentado en la sección 3.
Disparo programático de auditorías, polling de estado, recuperación de resultados y configuración de webhooks. Referencia documentada en las secciones 4 a 8 abajo.
Wrappers SDK tipados para la API REST. Node.js (npm: crawlux-sdk), Python (pip: crawlux). Documentado en la sección 8.
Waitlist de acceso temprano
La API se lanza en el Q4 2026, pero el acceso anticipado abre unas 2 semanas antes del lanzamiento público. Escribe a [email protected] con el asunto "API Waitlist" para unirte. El acceso anticipado es gratis e incluye revisión de la documentación de la API.
Estructura de salida JSON de auditoría
Cada auditoría Crawlux produce un archivo JSON descargable desde el dashboard. La estructura es estable y versionada. Abajo: la forma top-level y los campos clave.
"audit_id": "aud_8f3k29vJ7nQ",
"version": "v3",
"domain": "example-protocol.io",
"tier": "team",
"started_at": "2026-04-29T08:14:22Z",
"completed_at": "2026-04-29T08:16:47Z",
"site_category": "defi_protocol",
// Overall score and grade
"score": {
"overall": 67,
"grade": "C+",
"percentile": 58
},
// Per-check-group breakdown
"groups": [
{ "id": "technical", "score": 82, "weight": 0.15 },
{ "id": "schema", "score": 45, "weight": 0.20 },
{ "id": "ymyl", "score": 71, "weight": 0.15 },
{ "id": "ai_visibility", "score": 58, "weight": 0.20 },
{ "id": "authority", "score": 76, "weight": 0.15 },
{ "id": "on_chain", "score": 74, "weight": 0.15 }
],
// Findings array (truncated, full audit returns all 23 analyzers)
"findings": [
{
"analyzer": "B01",
"severity": "high",
"title": "Token page uses generic Product schema",
"recommendation": "Migrate to FinancialProduct schema",
"reference": "crawlux.com/guides/token-schema/"
}
]La salida JSON es el sistema de registro. Tanto la vista del dashboard como el reporte PDF white-label son generados desde este JSON. Guardar el JSON junto con tu dominio te da historial completo de auditorías.
Campos clave explicados
Identificador único de auditoría. Formato: aud_ seguido por 12 caracteres alfanuméricos. Úsalo para recuperar la auditoría después vía dashboard o (cuando la API se envíe) el endpoint GET /audits.
Versión de metodología usada para esta auditoría. Revisada trimestralmente. El pinning permite auditorías históricas reproducibles a través de actualizaciones de versión.
Categoría auto-detectada. Valores: defi_protocol, exchange, wallet, nft_platform, infrastructure, identity, generic_crypto. Determina qué set de prompts corre para pruebas AEO.
Código de analizador (A01 a F03, mira la página de metodología). Mapea a los 23 analizadores a través de 6 grupos de verificación. Cada hallazgo cita el analizador específico que se disparó.
Payloads de webhooks
Configura una URL de webhook en el dashboard. Cuando una auditoría se completa, Crawlux hace POST del JSON completo de la auditoría a la URL configurada. Útil para disparar automatización aguas abajo, poblar registros CRM o alertar equipos de agencia.
// Headers
Content-Type: application/json
X-Crawlux-Event: audit.completed
X-Crawlux-Signature: sha256=a4b8c92e...
X-Crawlux-Audit-Id: aud_8f3k29vJ7nQ
X-Crawlux-Delivery: del_2HxJ4nP3kqM
// Body (full audit JSON, structure as shown in section 2)
{ "audit_id": "aud_8f3k29vJ7nQ", ... }La firma del webhook es HMAC-SHA256 computada usando un secreto compartido configurado en el dashboard. Siempre verifica la firma antes de procesar el payload.
Disparado cuando una auditoría termina exitosamente. El payload contiene el JSON completo de la auditoría. El evento más común para automatización aguas abajo.
Disparado cuando una auditoría no puede completarse. El payload contiene el audit_id, el código de error y el mensaje de error. Causas comunes: dominio inalcanzable, disallow de robots.txt, rate limit alcanzado.
Disparado cuando una auditoría fallida es reintentada automáticamente. Hasta 3 reintentos con backoff exponencial. La falla final produce audit.failed en su lugar.
Garantías de entrega de webhooks
Crawlux reintenta la entrega del webhook hasta 5 veces durante 24 horas si tu endpoint devuelve un estado distinto de 2xx. Devuelve siempre un estado 2xx rápidamente (en menos de 5 segundos) y procesa el payload de forma asíncrona.
Endpoints API planeados
La API REST de Crawlux se lanza en el Q4 2026. A continuación: la superficie de endpoints planificada. Sujeta a ajustes durante el periodo de acceso anticipado. URL base: https://api.crawlux.com/v1/.
Dispara una nueva auditoría para un dominio. El body acepta domain (requerido), tier (free/pro/team), webhook_url (opcional). Devuelve el audit_id y el estado de la auditoría.
Recupera una auditoría específica por ID. Devuelve el JSON completo de la auditoría si está completada, o el objeto de estado (queued, running, failed) si aún no está completa.
Lista todas las auditorías en tu workspace. Soporta paginación vía parámetros limit y cursor. Filtra por estado, dominio, rango de fechas. Devuelve resúmenes de auditorías.
Recupera solo el array de hallazgos para una auditoría. Respuesta más liviana que el JSON completo de la auditoría. Útil para exponer hallazgos específicos en dashboards.
Descarga el reporte PDF white-label (solo tiers Pro y Team). Devuelve una URL firmada válida por 60 minutos. Las auditorías de tier gratis no tienen reportes PDF.
Configura un endpoint de webhook. El body acepta url (requerido), events (array de tipos de eventos a los que suscribirse), secret (para firma HMAC).
Remueve una configuración de webhook. Las finalizaciones de auditoría subsecuentes no harán POST a la URL de webhook removida. Las auditorías existentes no son afectadas.
Recupera el uso del periodo actual. Devuelve auditorías usadas este periodo, auditorías restantes, fecha de reset del periodo y límites del tier. Útil para dashboards de uso.
Autenticación
La API usará autenticación Bearer token. Las API keys se generan por workspace desde el dashboard de Crawlux. Cada key se scopea a un workspace y a rate limits configurables.
Authorization: Bearer crl_live_8f3k29vJ7nQa4b8c92eP3kqM
Content-Type: application/jsonLas API keys vienen en dos entornos: crl_test_ para pruebas en sandbox sin consumir cuota de auditorías y crl_live_ para auditorías en producción que consumen la cuota del plan. Las firmas de webhooks usan un secreto de firma aparte, configurado por webhook.
El modo de prueba es gratis
Las keys de modo de prueba (crl_test_) devuelven datos de auditoría realistas pero sintéticos sin consumir cuota. Útil para construir integraciones sin pagar auditorías reales durante el desarrollo.
Límites de uso
Los rate limits escalan con el tier. La cuota de auditoría es la restricción vinculante; las llamadas de recuperación de resultados son ilimitadas dentro de lo razonable.
| Tier | Auditorías / mes | Obtención de resultados | Use case |
|---|---|---|---|
| Gratis | 5 | Ilimitado | Proyectos personales, evaluación, equipos de un solo dominio |
| Pro | 50 | Ilimitado | Agencias individuales, responsables de SEO in-house, consultores multiproyecto |
| Team | 200 | Ilimitado | Agencias de marketing, plataformas multi-tenant, equipos de SEO más grandes |
| Enterprise | Personalizado | Ilimitado | Infraestructura dedicada, SLA, soporte de integración personalizado |
Los headers de límite de uso se devuelven en cada respuesta de la API. X-RateLimit-Limit muestra el límite de tu plan. X-RateLimit-Remaining muestra las auditorías restantes. X-RateLimit-Reset es el timestamp Unix en que se reinicia el límite (inicio del mes siguiente).
Códigos de error
Los errores devuelven JSON con un code, un message y un request_id para solicitudes de soporte. Los códigos de estado HTTP siguen las convenciones REST estándar.
{
"error": {
"code": "audit_quota_exceeded",
"message": "Tier quota exceeded for the current period",
"request_id": "req_2HxJ4nP3kqM8f3k",
"docs_url": "https://www.crawlux.com/docs/#errors"
}
}Formato de dominio inválido o dominio inalcanzable. Causas comunes: protocolo faltante, typo, DNS no propagado, dominio bloqueado por el registrar.
API key faltante, malformada o revocada. Revisa el formato del header Authorization. Regenera la key desde el dashboard si está comprometida.
La feature solicitada requiere un tier más alto. Caso común: configuración de webhook en tier gratis (Pro o Team requerido), descarga de PDF en tier gratis (Pro o Team requerido).
Cuota mensual de auditoría agotada para el tier actual. Espera hasta que el periodo se resetee o sube de tier. Las llamadas de recuperación de resultados no son afectadas.
Un proveedor upstream de data requerido no está disponible (DataForSEO, CoinGecko, DefiLlama, PageSpeed). La auditoría será reintentada automáticamente. La página de estado cubre las caídas de proveedores.
SDKs y librerías cliente
Dos SDKs oficialmente soportadas se envían con el lanzamiento de la API en Q4 2026. Las SDKs de comunidad en otros idiomas son bienvenidas y serán enlazadas desde esta página.
import { Crawlux } from 'crawlux-sdk';
const crawlux = new Crawlux({ apiKey: process.env.CRAWLUX_API_KEY });
// Trigger an audit and wait for completion
const audit = await crawlux.audits.run({
domain: 'example-protocol.io',
tier: 'team',
waitForCompletion: true
});
console.log(audit.score.overall); // 67
console.log(audit.findings.length); // 23from crawlux import Crawlux
client = Crawlux(api_key=os.environ["CRAWLUX_API_KEY"])
# Trigger an audit and wait for completion
audit = client.audits.run(
domain="example-protocol.io",
tier="team",
wait_for_completion=True
)
print(audit.score.overall) # 67
print(len(audit.findings)) # 23Ambos SDKs proveen wrappers tipados alrededor de la API REST más helpers para patrones comunes: polling para finalización de auditoría, verificación de firma en webhooks entrantes, disparadores de auditorías por lote a través de múltiples dominios.
Patrones comunes de integración
Seis patrones de integración que vemos más a menudo cuando los equipos discuten el acceso temprano a la API. Cada patrón tiene una secuencia de endpoints recomendada.
Integración con dashboard de agencia
Dispara auditorías por dominio de cliente bajo demanda. POST /audits con webhook_url apuntando a tu dashboard. Procesa el webhook audit.completed para poblar vistas de reportes de cliente.
Automatización de cadencia trimestral
Un cron job dispara auditorías cada 90 días por dominio manejado. POST /audits con webhook_url para disparar alertas aguas abajo en regresión de score. Compara el actual con el previo vía el JSON de auditoría guardado.
CRM enrichment
Cuando un nuevo lead entra al CRM, dispara una auditoría de tier gratis en su dominio. Pobla el registro del lead con el score y los 3 hallazgos top. Úsalo como starter de conversación para llamadas de ventas.
Slack alerting
El endpoint de webhook postea en Slack cuando la auditoría se completa. Formatea el score y los 3 hallazgos top en un mensaje Block Kit. Útil para canales cara-al-cliente y leads SEO internos.
Embed para plataformas SEO
Auditorías Crawlux white-label dentro de tu propia UI de plataforma SEO. Usa la API key de prueba (crl_test_) durante el build. Muestra los hallazgos en tu propia UI codificados por código de analizador.
Monitoreo masivo de dominios
Dispara auditorías a través de cientos de dominios manejados durante la noche. Batchea las llamadas POST /audits con sleep entre ellas para respetar los rate limits. Agrega resultados vía tu propia capa de reportes.
Preguntas comunes de desarrolladores
Seis preguntas cubriendo el roadmap de la API, salida JSON, autenticación, SDKs y rate limits.
¿Cuándo se lanza la API de Crawlux?
La API de Crawlux está planeada para Q4 2026. Actualmente las auditorías corren vía el dashboard web de Crawlux con salida JSON descargable por auditoría. La API permitirá disparo programático de auditorías, polling de estado, callbacks de webhook y recuperación de resultados. Suscríbete vía la waitlist de acceso temprano de docs para ser notificado cuando el acceso a la API se abra.
¿Puedo obtener el JSON de la auditoría hoy?
Sí. Cada auditoría Crawlux produce una salida JSON descargable desde el dashboard de auditoría. La estructura JSON está documentada en esta página. Las auditorías de tier Pro y Team también producen un reporte PDF white-label. Las auditorías de tier gratis producen una salida JSON y un reporte HTML de resumen.
¿Qué autenticación usará la API?
La API usará autenticación con API key vía Bearer tokens. Las API keys serán generadas desde el dashboard de Crawlux. Cada API key se scopea a un workspace y tiene rate limits configurables. Los callbacks de webhook serán autenticados vía firmas HMAC-SHA256 usando un secreto compartido.
¿Habrá SDKs disponibles?
Dos SDKs están planeadas para el lanzamiento de Q4 2026. Una SDK Node.js publicada en npm bajo el nombre de paquete crawlux-sdk. Una SDK Python publicada en PyPI bajo el nombre de paquete crawlux. Ambas SDKs proveerán wrappers tipados alrededor de la API REST más helpers para patrones comunes como polling para finalización de auditoría.
¿Qué límites de uso tendrá la API?
Los rate limits escalarán con el tier. Tier gratis: 5 auditorías por mes. Tier Pro: 50 auditorías por mes. Tier Team: 200 auditorías por mes. Tier Enterprise (precios personalizados): auditorías ilimitadas con infraestructura dedicada. Todos los tiers incluyen llamadas ilimitadas de recuperación de resultados. Los callbacks de webhook cuentan por separado y no tienen rate-limit.
¿Cómo me entero cuando se lance la API?
Tres formas. Primero, envía email a [email protected] con asunto API Waitlist para unirte a la lista de acceso temprano. Segundo, sigue la página de changelog para actualizaciones de producto. Tercero, corre una auditoría gratis y responde a cualquiera de los follow-ups por email confirmando interés de desarrollador. El acceso temprano se abre aproximadamente 2 semanas antes del lanzamiento público de la API.
Corre una auditoría gratis y descarga el JSON
La forma más rápida de evaluar el JSON de auditoría para integración: corre una auditoría real en tu propio dominio e inspecciona la salida. Primera auditoría gratis por dominio.
Salida JSON disponible · Webhooks disponibles · API Q4 2026 · Acceso anticipado de 2 semanas