API REST e Integraciones

Última actualización: 2026-11-04

¿Qué permite hacer la API de SEOdiag?

La API REST de SEOdiag permite integrar el motor de rastreo técnico SEO y análisis GEO directamente dentro de tus propios flujos de trabajo, pipelines de CI/CD, CRMs o motores de prospección comercial B2B.

Mediante la API puedes disparar auditorías bajo demanda, consultar el estado de avance en tiempo real, extraer el Score de Salud SEO, el GEO Score de Citabilidad IA, los problemas detectados por severidad y la lista priorizada de tareas para desarrolladores (dev_tasks).

Requisitos y Planes Habilitados

Exclusivo para Tiers Superiores: El acceso programático mediante tokens Bearer está disponible únicamente para cuentas con un Workspace activo en los planes Agency (US$ 99) o Enterprise (US$ 159). Las peticiones por API realizadas sobre Workspaces en tiers inferiores (Freelance o Growth) devolverán HTTP 403 Forbidden.

Plan (Tier) Acceso al Dashboard Web Acceso Programático API REST Concurrencia por Workspace
Freelance (US$ 9) Incluido No incluido 1 auditoría simultánea
Growth (US$ 29) Incluido No incluido 1 auditoría simultánea
Agency (US$ 99) Incluido Habilitado Hasta 2 simultáneas
Enterprise (US$ 159) Incluido Habilitado Hasta 5 simultáneas

1. Autenticación (Bearer JWT)

Para autenticarte contra la API en https://seodiag.com, realiza una petición POST /auth/login con formato application/x-www-form-urlencoded enviando tu email (username) y contraseña (password).

  • Si tu cuenta pertenece a un Workspace Agency o Enterprise, la respuesta incluye el campo access_token tanto en el cuerpo JSON como en la cookie access_token.
  • El token tiene una validez de 12 horas. Te recomendamos almacenarlo en caché durante su vigencia para no abrir sesiones innecesarias en cada llamada.
curl -X POST "https://seodiag.com/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=tu-email@agencia.com&password=TuPasswordSeguro"

Respuesta JSON (planes Agency y Enterprise):

{
  "message": "Login successful",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

En todas las peticiones subsiguientes debes enviar las cabeceras: - Authorization: Bearer <access_token> - X-Workspace-ID: <id_del_workspace> (obligatorio si tu usuario participa en múltiples Workspaces)

2. Consultar Workspaces y Créditos (GET /workspaces/me)

Antes de lanzar auditorías, puedes consultar el listado de Workspaces asociados a tu usuario, verificar su id, el tier activo (subscription_tier) y el saldo de créditos disponibles (available_credits):

curl -s "https://seodiag.com/workspaces/me" \
  -H "Authorization: Bearer $TOKEN"

3. Lanzar una Auditoría (POST /audit)

Inicia un rastreo asíncrono indicando la URL objetivo y el tope máximo de páginas (max_pages). El sistema reserva preventivamente max_pages créditos y reembolsa de forma automática la diferencia si el sitio tiene menos URLs internas, o el 100% si el sitio bloquea el rastreo.

curl -X POST "https://seodiag.com/audit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: 23" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ejemplo.com",
    "max_pages": 100,
    "lang": "es",
    "industry": "saas",
    "slow_mode": false
  }'

Respuesta:

{
  "message": "Auditoría iniciada correctamente en entorno seguro",
  "task_id": "3de6f41a-2170-49e0-9047-8263ad05f1fb"
}

4. Monitorear Estado y Obtener Resultados

Consultar progreso de la tarea (GET /tasks/{task_id})

Consulta cada 10–15 segundos hasta que status sea SUCCESS, ERROR o CANCELED:

curl -s "https://seodiag.com/tasks/3de6f41a-2170-49e0-9047-8263ad05f1fb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: 23"

Listar auditorías y recuperar el reporte (GET /audits y GET /audits/{id})

  1. Obtén el listado de auditorías del Workspace con GET /audits (o filtra por task_id).
  2. Recupera el resumen ejecutivo, puntajes y conteo de problemas con GET /audits/{audit_id}?include_urls=false.
  3. Recupera las tareas técnicas priorizadas con GET /audits/{audit_id}/dev_tasks?limit=50.
Endpoint Método Descripción
/auth/login POST Emite el token JWT (access_token) válido por 12 horas
/workspaces/me GET Lista tus Workspaces, id, tier y créditos disponibles
/audit POST Encola una nueva auditoría técnica SEO + GEO
/tasks/{task_id} GET Devuelve el estado (PENDING, RUNNING, SUCCESS, ERROR)
/audits GET Lista el historial de auditorías del Workspace
/audits/{id} GET Devuelve el reporte completo (score, geo_score_avg, issues)
/audits/{id}/dev_tasks GET Devuelve la lista paginada de hallazgos accionables para desarrollo

¿Necesitas más ayuda con tu integración? Contáctanos

¿Necesitas más ayuda? Contáctanos