Datos estructurados e Intelligence Tokens

15 min de lectura

TLDR

Cada informe de Surmado incluye JSON estructurado para acceso programático. Los tokens de AI Visibility contienen métricas de visibilidad y datos de competidores. Los tokens de Site Audit incluyen puntuaciones de rendimiento y problemas técnicos. Los tokens de Strategy tienen recomendaciones estratégicas y modelado financiero. Intégralos con Notion, Airtable, Google Sheets, Zapier o herramientas personalizadas. Sigue métricas a lo largo del tiempo, automatiza informes, crea paneles o activa alertas cuando baje tu visibilidad.

¿Buscas la API REST? Consulta la Guía de integración de la API para crear informes, gestionar marcas y recibir webhooks de forma programática.

Cada informe de Surmado incluye JSON estructurado para acceso programático.

¿Qué son los Intelligence Tokens?

Los Intelligence Tokens son identificadores únicos de cada informe completado (p. ej. SIG-2025-11-A7K3Q). El token se devuelve en la respuesta de la API REST cuando un informe se completa y, en los informes de AI Visibility y Site Audit, desbloquea un payload JSON estructurado public_intelligence que puedes integrar en:

Paneles (Notion, Airtable, Retool, apps React personalizadas)
Flujos de automatización (Zapier, Make, n8n)
Herramientas internas (CRM, gestión de proyectos, plataformas de BI)
Agentes personalizados (asistentes de IA, bots de monitoreo, integraciones con Slack)

Dónde encontrarlos: Llama a GET /v1/reports/{report_id} cuando tu informe esté completed. Las respuestas de AI Visibility y Site Audit incluyen un objeto public_intelligence con campos seleccionados y legibles por máquina. Los informes de Strategy devuelven el token al completarse, pero por ahora no exponen public_intelligence – usa el PDF generado para el resultado de Strategy. Consulta la Guía de integración de la API para ver la autenticación y los detalles de los endpoints.

Formato: JSON estándar. Se pueden agregar campos con el tiempo; buscamos mantener estables los campos existentes.

Intelligence Token de AI Visibility

Prefijo del token: SIG-* (slug del producto en las rutas de la API: signal) Propósito: Métricas de visibilidad en IA, posicionamiento competitivo y medición del Ghost Influence.

Estructura del esquema (AI Visibility)

{
  "token": "SIG-2025-11-A7K3Q",
  "schema_type": "signal",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "summary": {
    "business_name": "Acme Coffee Roasters",
    "industry": "Food & Beverage",
    "location": "Portland, OR",
    "presence_score": 34.2,
    "authority_score": 42.7,
    "competitive_rank": 4,
    "total_competitors": 12,
    "top_competitor": "Blue Bottle",
    "insights_summary": [
      "Presence score: 34.2 (↑5.5 from last report)",
      "Ghost influence: 48.3% of relevant mentions don't name you",
      "Competitive rank: #4 of 12 in category"
    ]
  },
  "data": {
    "entity_context": {
      "entity_name": "Acme Coffee Roasters",
      "category": "Food & Beverage",
      "location": "Portland, OR",
      "value_proposition": "Single-origin, small-batch specialty coffee",
      "competitive_set": ["Starbucks", "Blue Bottle", "Intelligentsia"]
    },
    "visibility_metrics": {
      "presence_score": 34.2,
      "ghost_influence_percentage": 48.3,
      "attributed_mentions": 12,
      "unattributed_mentions": 17,
      "category_share": 8.1
    },
    "competitive_position": {
      "rank": 4,
      "total_competitors": 12,
      "tier": "challenger",
      "top_competitor": "Blue Bottle"
    },
    "platform_variance": {
      "chatgpt": {
        "presence_score": 42.1,
        "attributed_mentions": 5,
        "unattributed_mentions": 7,
        "sample_responses": ["..."]
      },
      "claude": {
        "presence_score": 38.5,
        "attributed_mentions": 3,
        "unattributed_mentions": 4
      },
      "gemini": { "...": "..." },
      "deepseek": { "...": "..." },
      "meta_ai": { "...": "..." },
      "grok": { "...": "..." }
    },
    "perception_analysis": {
      "primary_associations": ["specialty coffee", "local roasting", "sustainable sourcing"],
      "sentiment_distribution": {
        "positive": 67.4,
        "neutral": 28.3,
        "negative": 4.3
      },
      "strength_signals": ["ethical sourcing", "small batch quality"],
      "weakness_signals": ["limited retail presence", "higher price point"]
    },
    "strategic_signals": {
      "visibility_opportunities": [
        {
          "platform": "chatgpt",
          "gap": "Location-based queries underrepresented",
          "recommendation": "Optimize Google Business Profile with neighborhood keywords",
          "estimated_impact": "high"
        }
      ],
      "competitive_threats": [
        {
          "competitor": "Blue Bottle",
          "platform": "claude",
          "advantage": "Brand recognition in 'premium coffee' queries",
          "mitigation": "Emphasize direct trade relationships and roast-date freshness"
        }
      ]
    },
    "evidence_samples": [
      {
        "platform": "chatgpt",
        "query": "best specialty coffee roasters in Portland",
        "response_excerpt": "...",
        "attribution_type": "named",
        "rank": 3
      }
    ],
    "market_context": {
      "industry_trends": ["direct trade transparency", "micro-lot offerings"],
      "seasonal_factors": "Testing conducted during peak holiday gifting season",
      "competitive_intensity": "high",
      "total_competitors_found": 12
    },
    "baseline_metrics": {
      "previous_presence_score": 28.7,
      "change_since_last_report": "+5.5",
      "trend": "improving",
      "authority_score": 42.7
    },
    "preview_content": {
      "tldr_bullets_list": [
        "Presence score: 34.2 (↑5.5 from last report)",
        "Ghost influence: 48.3% of relevant mentions don't name you",
        "Competitive rank: #4 of 12 in category",
        "Strongest platform: ChatGPT (42.1 presence)",
        "Top opportunity: Location-based query optimization"
      ]
    }
  }
}

El objeto summary seleccionado al inicio lo rellena la API para un acceso rápido. Las métricas más detalladas están en data.*. Campos internos como persona_details y test_queries están en una lista de exclusión y nunca aparecen en public_intelligence.

Campos clave explicados (AI Visibility)

summary.presence_score (y data.visibility_metrics.presence_score): Puntuación de 0 a 100 que mide con qué frecuencia aparece tu negocio en las respuestas de la IA a consultas relevantes. Más alta = más visible.

data.visibility_metrics.ghost_influence_percentage: Porcentaje de menciones relevantes en las que la IA describe tu propuesta de valor o tus características sin nombrarte. Un Ghost Influence alto significa que estás educando al mercado, pero los competidores se llevan la atribución.

summary.competitive_rank (y data.competitive_position.rank): Tu posición frente a los competidores de la misma categoría. Posición 1 = el más mencionado.

data.platform_variance: Desglose por plataforma de IA (ChatGPT, Claude, Gemini, etc.) que muestra dónde eres más fuerte y más débil.

data.strategic_signals.visibility_opportunities: Recomendaciones accionables ordenadas por impacto estimado.

Casos de uso comunes (AI Visibility)

Integración con paneles: Obtén summary.presence_score, data.visibility_metrics.ghost_influence_percentage y summary.competitive_rank para seguir tu visibilidad en IA a lo largo del tiempo.

Alertas: Monitorea data.baseline_metrics.trend y activa alertas si la puntuación de presencia baja más de 10 puntos.

Inteligencia competitiva: Compara tu data.platform_variance con los informes de AI Visibility de tus competidores para identificar brechas por plataforma.

Estrategia de contenido: Usa data.perception_analysis.weakness_signals para guiar la creación de contenido y la optimización de preguntas frecuentes.

Intelligence Token de Site Audit

Prefijo del token: SCN-* (slug del producto en las rutas de la API: scan) Propósito: Datos de auditoría SEO técnica, métricas de rendimiento, puntuaciones de accesibilidad y acciones priorizadas.

Estructura del esquema (Site Audit)

{
  "schema_type": "scan",
  "scan_schema_types_count": 3,
  "scan_critical_issues_count": 8,
  "summary": {
    "seo_score": 95,
    "performance_score": 87,
    "accessibility_score": 92,
    "total_pages": 48,
    "schema_types_count": 3,
    "critical_issues_count": 8,
    "content_coverage_percentage": 87,
    "page_analysis_summary": "Homepage LCP is 2.8s (above target). Three pages have thin content.",
    "link_analysis_summary": "Internal link distribution uneven. Two orphaned pages detected.",
    "schema_strategy_summary": "FAQPage and LocalBusiness schemas missing on key pages.",
    "content_gaps_summary": "Competitors rank for brewing method and single-origin guides you don't cover.",
    "quick_wins": {
      "link_analysis": "Add internal links from homepage to two orphaned product pages.",
      "schema_strategy": "Add FAQPage schema to the top 5 traffic pages.",
      "content_gaps": "Publish a brewing-methods comparison guide."
    }
  },
  "data": {
    "metadata": {
      "url": "https://www.example.com",
      "run_id": "scan-20251108-143022",
      "product": "scan",
      "version": "1.0",
      "created_at": "2025-11-08T14:30:22.445Z"
    },
    "audit_data": {
      "site_metrics": {
      "total_pages": 48,
      "crawled_pages": 48,
      "avg_word_count": 1247,
      "pages_with_schema": 42,
      "missing_titles": 0,
      "duplicate_titles": 3,
      "images_without_alt": 15,
      "broken_links": 2,
      "redirect_chains": 1
    },
    "lighthouse": {
      "performance_score": 87,
      "seo_score": 95,
      "accessibility_score": 92,
      "best_practices_score": 88,
      "first_contentful_paint": 1.2,
      "largest_contentful_paint": 2.1,
      "cumulative_layout_shift": 0.05,
      "total_blocking_time": 150
    },
    "accessibility": {
      "pa11y_errors": 8,
      "pa11y_warnings": 23,
      "combined_score": 86,
      "critical_issues": [
        {
          "code": "WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.I",
          "message": "<i> element used for icon, should use aria-label",
          "selector": ".nav-icon",
          "impact": "moderate"
        }
      ]
    },
    "enrichment": {
      "page_analysis": {
        "high_priority_pages": [
          {
            "url": "/",
            "title": "Homepage",
            "recommendations": [
              "Add FAQ schema to address common queries",
              "Optimize hero image LCP (currently 2.8s)"
            ]
          }
        ]
      },
      "link_analysis": {
        "internal_link_distribution": "uneven",
        "orphaned_pages": 2,
        "deep_pages_low_authority": 5
      },
      "schema_strategist": {
        "schemas_found": ["Organization", "WebSite", "BreadcrumbList"],
        "schemas_missing": ["FAQPage", "LocalBusiness"],
        "validation_errors": [
          {
            "type": "Organization",
            "field": "logo",
            "error": "Invalid URL format"
          }
        ]
      },
      "content_inventory": {
        "thin_content_pages": 3,
        "keyword_cannibalization": [
          {
            "keyword": "best coffee beans",
            "competing_pages": ["/shop/beans", "/blog/coffee-guide"],
            "recommendation": "Consolidate or differentiate targeting"
          }
        ]
      },
      "competitor_analysis": {
        "competitors_analyzed": ["bluebottle.com", "intelligentsia.com"],
        "your_advantages": ["Faster load times", "Better mobile UX"],
        "their_advantages": ["more thorough with 150+ checks schema", "Higher blog frequency"]
      },
      "upstream_research": {
        "industry_benchmarks": {
          "avg_performance_score": 72,
          "avg_accessibility_score": 78,
          "your_vs_average": {
            "performance": "+15",
            "accessibility": "+14"
          }
        }
      },
      "content_gap_analysis": {
        "suggested_topics": [
          "Coffee brewing methods comparison",
          "Single-origin vs blend guide",
          "Roast profile differences explained"
        ],
        "rationale": "Competitors rank for these queries but you have no content"
      }
    },
    "pages": [
      {
        "url": "https://www.example.com/",
        "title": "Homepage",
        "status_code": 200,
        "word_count": 1850,
        "meta_description": "...",
        "h1_tags": ["Acme Coffee Roasters"],
        "schema_types": ["Organization", "WebSite"],
        "performance": {
          "lcp": 2.1,
          "cls": 0.05
        },
        "issues": [
          {
            "severity": "medium",
            "type": "image_optimization",
            "message": "Hero image not lazy-loaded",
            "recommendation": "Add loading='lazy' attribute"
          }
        ]
      }
    ]
    }
  }
}

summary es el resumen seleccionado que los clientes usan para automatizar. Los datos más detallados están en data.audit_data.*. El arreglo completo audit_data.pages[] está presente en la respuesta public_intelligence, pero es largo; usa summary.quick_wins para ver las recomendaciones principales priorizadas.

Campos clave explicados (Site Audit)

summary.seo_score (y data.audit_data.site_metrics.seo_score): Puntuación SEO de 0 a 100 que resume factores técnicos y de la página.

summary.performance_score (y data.audit_data.lighthouse.performance_score): Puntuación de rendimiento de Lighthouse de 0 a 100. Promedio del sector: 65-75 en sitios de comercio electrónico.

data.audit_data.site_metrics.images_without_alt: Cantidad de imágenes sin texto alternativo (problema de SEO y de accesibilidad).

data.audit_data.enrichment.schema_strategist: Validación y recomendaciones de Schema.org para los datos estructurados.

data.audit_data.enrichment.content_gap_analysis: Temas por los que posicionan tus competidores y que tú no cubres. Áreas de oportunidad SEO.

data.audit_data.pages[].issues: Problemas detallados por página, con gravedad y recomendaciones accionables.

summary.quick_wins: Recomendaciones priorizadas en lenguaje sencillo, organizadas por área (link_analysis, schema_strategy, content_gaps).

Casos de uso comunes (Site Audit)

Integración con CI/CD: Ejecuta un Site Audit en tu pipeline de despliegue y haz fallar los builds si summary.performance_score < 80.

Monitoreo: Sigue summary.seo_score, summary.performance_score y summary.accessibility_score a lo largo del tiempo en una base de datos de series temporales.

Seguimiento de problemas: Procesa data.audit_data.pages[].issues y crea tickets de Jira/Linear automáticamente para el equipo de desarrollo.

Informes: Obtén el objeto summary para paneles ejecutivos que muestren la salud SEO.

Intelligence Token de Strategy

Prefijo del token: SOL-* (slug del producto en las rutas de la API: solutions) Propósito: Resultados de planificación estratégica, acciones priorizadas, síntesis de debate adversarial y marcos de decisión.

Los informes de Strategy por ahora no exponen un objeto public_intelligence a través de la API REST. La estructura de abajo describe lo que aparece en el PDF generado y se incluye como referencia – los consumidores programáticos deben usar la URL de descarga del PDF que devuelve el endpoint de estado.

Estructura del esquema (Strategy)

{
  "token": "SOL-2025-11-A7K3Q",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "business_name": "Acme Coffee Roasters",
  "decision": "Should we expand from local farmers markets to e-commerce?",
  "todo_list": [
    {
      "priority": 1,
      "action": "Validate e-commerce demand with 2-week pre-order test",
      "rationale": "CFO AI flagged cash flow risk of inventory investment. Test market demand before committing capital.",
      "estimated_effort": "1-3 days",
      "impact": "high",
      "owner_role": "Marketing",
      "dependencies": [],
      "success_criteria": "Achieve 50+ pre-orders to justify inventory investment"
    },
    {
      "priority": 2,
      "action": "Calculate true unit economics including shipping costs",
      "rationale": "Market Realist AI noted competitors use free shipping thresholds. Need to model margin impact.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Finance",
      "dependencies": [],
      "success_criteria": "Confirm >30% margin after shipping at $35+ order value"
    },
    {
      "priority": 3,
      "action": "Research coffee subscription platform integrations (Trade, Driftaway)",
      "rationale": "Game Theorist AI suggested partnering vs competing. Explore white-label options.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Partnerships",
      "dependencies": [],
      "success_criteria": "Identify 2-3 viable platform partnerships with <15% commission"
    },
    {
      "priority": 4,
      "action": "Audit fulfillment capacity: Can we ship 100 orders/week?",
      "rationale": "COO AI raised operational risk of overwhelming current team during peak season.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Operations",
      "dependencies": [],
      "success_criteria": "Document current capacity + identify bottlenecks"
    },
    {
      "priority": 5,
      "action": "Create content strategy for 'coffee education' blog",
      "rationale": "Upstream research showed competitors win on educational content. Build SEO moat.",
      "estimated_effort": "1 week",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [1],
      "success_criteria": "Publish 3 comprehensive guides (brewing methods, origins, roast profiles)"
    },
    {
      "priority": 6,
      "action": "Build Minimum Viable Storefront (Shopify or WooCommerce)",
      "rationale": "After validating demand (Priority 1), launch simple store. Avoid custom dev.",
      "estimated_effort": "2 weeks",
      "impact": "high",
      "owner_role": "Engineering",
      "dependencies": [1, 2],
      "success_criteria": "Live storefront with 5 SKUs, payment processing, shipping integration"
    },
    {
      "priority": 7,
      "action": "Model customer acquisition cost (CAC) for paid ads",
      "rationale": "CFO AI noted farmers market CAC is $0 (foot traffic). Need to budget for online ads.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [2],
      "success_criteria": "Target CAC <$25 with LTV >$75 (3x ratio)"
    },
    {
      "priority": 8,
      "action": "Set decision checkpoint: Launch vs pivot based on pre-order results",
      "rationale": "Chief Strategist AI synthesis: Use Priority 1 results to decide go/no-go.",
      "estimated_effort": "1 day",
      "impact": "critical",
      "owner_role": "Leadership",
      "dependencies": [1, 2, 4],
      "success_criteria": "Decision made by [specific date] based on pre-order data"
    }
  ],
  "summary": {
    "total_actions": 8,
    "high_priority": 4,
    "medium_priority": 3,
    "critical_priority": 1,
    "has_financial_analysis": true,
    "has_risk_mitigation": true,
    "estimated_total_effort": "4-6 weeks",
    "decision_framework": "Staged validation approach with clear go/no-go gates"
  },
  "adversarial_debate_summary": {
    "cfo_concerns": [
      "Inventory cash flow risk without demand validation",
      "Shipping costs erode margins below 30% threshold",
      "Customer acquisition cost unknown for paid channels"
    ],
    "coo_concerns": [
      "Current team capacity maxed at 100 orders/week",
      "Peak season overlap with farmers market commitments",
      "Fulfillment process not documented or systemized"
    ],
    "market_realist_concerns": [
      "Competitors offer free shipping (you can't at current scale)",
      "Educational content gap vs established brands",
      "Price positioning unclear (premium vs accessible)"
    ],
    "game_theorist_insights": [
      "Partnering with existing platforms reduces upfront investment",
      "Competitors may respond with farmers market presence if you succeed online",
      "First-mover advantage in 'local + online' hybrid model"
    ],
    "chief_strategist_synthesis": "Launch is feasible but only after validating demand and unit economics. Staged approach reduces risk: (1) Pre-order test, (2) MVP storefront, (3) Scale based on results. Avoid premature inventory investment."
  },
  "monte_carlo_scenarios": {
    "methodology": "10,000 simulations varying demand, CAC, and margin assumptions",
    "outcomes": {
      "success_rate": 62,
      "breakeven_12mo": 62,
      "breakeven_18mo": 28,
      "failure_24mo": 10
    },
    "key_risk_factors": [
      "Customer acquisition cost variance (if CAC >$40, failure risk jumps to 35%)",
      "Shipping cost assumptions (free shipping threshold impacts margin by 12-18%)",
      "Fulfillment bottleneck (unable to scale beyond 100 orders/week without hiring)"
    ],
    "recommendation": "Secure 18-month runway, not 12-month. Model includes 28% of scenarios requiring extended breakeven timeline."
  },
  "evidence_citations": [
    {
      "claim": "Competitors use free shipping thresholds",
      "source": "Analysis of Blue Bottle, Intelligentsia, and Stumptown pricing",
      "data": "Free shipping at $40+, $35+, and $50+ respectively"
    },
    {
      "claim": "Educational content drives SEO for coffee brands",
      "source": "SEMrush analysis of top 10 specialty coffee sites",
      "data": "Average 12 educational blog posts ranking for 'how to brew' queries"
    }
  ]
}

Campos clave explicados (Strategy)

todo_list[].priority: 1 = máxima prioridad. El orden representa la secuencia lógica y las dependencias.

todo_list[].dependencies: Arreglo de números de prioridad de los que depende esta acción. Se usa para secuenciar en la gestión de proyectos.

adversarial_debate_summary: Vista resumida de las preocupaciones planteadas por cada perspectiva de IA (CFO, COO, Market Realist, Game Theorist) y la síntesis final.

monte_carlo_scenarios: Resultados de pruebas de estrés probabilísticas que muestran la probabilidad de éxito o fracaso bajo distintos supuestos.

evidence_citations: Fuentes que respaldan las afirmaciones y recomendaciones clave. Transparencia sobre el razonamiento.

Casos de uso comunes (Strategy)

El public_intelligence de Strategy no se expone hoy a través de la API REST. Los campos de abajo describen el resultado en PDF – los consumidores programáticos deben extraer los datos del PDF o volver a ejecutar el informe de AI Visibility / Site Audit de origen y trabajar con su public_intelligence.

Gestión de proyectos: Importa todo_list a Linear, Asana o Notion con las prioridades y dependencias ya mapeadas.

Seguimiento de decisiones: Guarda los tokens de Strategy en tu repositorio de estrategia para documentar por qué se tomaron las decisiones.

Informes a la junta: Obtén summary y monte_carlo_scenarios para mostrarle al equipo directivo cómo se sometió a pruebas de estrés la estrategia.

Gestión del conocimiento: Indexa evidence_citations para construir memoria institucional de la investigación estratégica.

Cómo acceder a los Intelligence Tokens

Por la API REST

La vía principal. Llama a GET /v1/reports/{report_id} cuando un informe llegue al estado completed. La respuesta incluye el campo token y, en los informes de AI Visibility y Site Audit, un objeto public_intelligence con métricas estructuradas. Consulta la Guía de integración de la API para ver la autenticación, los webhooks y los detalles completos de los endpoints.

Por correo electrónico

Cuando tu informe esté listo, recibirás un correo con un botón de enlace mágico para ver el PDF. El enlace es válido por unos 30 días.

Por la app de Surmado

Ve a Reports → selecciona tu informe → el token y los enlaces de descarga están visibles en la vista de detalle del informe.

Esquemas de Intelligence Tokens

Los esquemas de los payloads public_intelligence de AI Visibility y Site Audit están documentados arriba. El resultado de Strategy se entrega como PDF; por ahora no se expone un payload estructurado public_intelligence en la API REST para los informes de Strategy.

Ejemplos de integración

En todos los ejemplos de abajo, public_intelligence se obtiene de la API REST con GET /v1/reports/{report_id} (consulta la Guía de integración de la API).

Panel en Notion

// Fetch a completed AI Visibility report and create a Notion database entry
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const signalData = report.public_intelligence;

await notion.pages.create({
  parent: { database_id: 'YOUR_DATABASE_ID' },
  properties: {
    'Business Name': { title: [{ text: { content: signalData.summary.business_name } }] },
    'Presence Score': { number: signalData.summary.presence_score },
    'Competitive Rank': { number: signalData.summary.competitive_rank },
    'Report Date': { date: { start: report.completed_at } },
    'Token': { rich_text: [{ text: { content: report.token } }] }
  }
});

Webhook de Zapier

// Trigger Zapier workflow when presence score drops
const currentScore = signalData.summary.presence_score;
const previousScore = signalData.data?.baseline_metrics?.previous_presence_score;

if (previousScore && currentScore < previousScore - 10) {
  await fetch('https://hooks.zapier.com/hooks/catch/YOUR_WEBHOOK/', {
    method: 'POST',
    body: JSON.stringify({
      alert: 'Presence score dropped significantly',
      business: signalData.summary.business_name,
      current_score: currentScore,
      previous_score: previousScore,
      drop: previousScore - currentScore
    })
  });
}

Creación de incidencias en Linear (Site Audit)

// Fetch a completed Site Audit report and auto-create Linear issues from quick wins
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const scanData = report.public_intelligence;

for (const [area, recommendation] of Object.entries(scanData.summary.quick_wins ?? {})) {
  await linearClient.createIssue({
    teamId: 'YOUR_TEAM_ID',
    title: `[SEO] ${area}: ${recommendation.slice(0, 60)}`,
    description: recommendation,
    priority: 1,
    labels: ['seo', 'technical-debt']
  });
}

Seguimiento de series temporales en Google Sheets

// Append AI Visibility scores to Google Sheets for time-series tracking
const { GoogleSpreadsheet } = require('google-spreadsheet');
const doc = new GoogleSpreadsheet('YOUR_SHEET_ID');

await doc.useServiceAccountAuth(credentials);
await doc.loadInfo();

const sheet = doc.sheetsByIndex[0];
await sheet.addRow({
  'Date': report.completed_at,
  'Business': signalData.summary.business_name,
  'Presence Score': signalData.summary.presence_score,
  'Authority Score': signalData.summary.authority_score,
  'Rank': signalData.summary.competitive_rank,
  'ChatGPT Score': signalData.data?.platform_variance?.chatgpt?.presence_score,
  'Claude Score': signalData.data?.platform_variance?.claude?.presence_score
});

Respuestas rápidas

¿Qué es un Intelligence Token?

Intelligence Token = Tu identificador único de un informe completado (formato: SIG-2025-11-XXXXX, SCN-2025-11-XXXXX o SOL-2025-11-XXXXX). El token se devuelve en la respuesta de estado de la API y es la clave que pasas al encadenar informes (p. ej. al crear un informe de Strategy a partir de un informe de AI Visibility existente).

Por qué es valioso:

Acceso programático: Procesa public_intelligence en tus herramientas (Notion, Linear, Google Sheets)
Automatización: Crea flujos que se activan con cada informe nuevo
Seguimiento de series temporales: Guarda datos históricos para analizar tendencias
Encadenamiento de informes: Pásalo como signal_token o scan_token al crear un informe de Strategy

Dónde lo obtienes: Lo devuelve GET /v1/reports/{report_id} al completarse, viene en los webhooks de finalización y aparece en la página de detalle del informe en la app de Surmado.

¿Cómo accedo a mi Intelligence Token?

3 formas de obtener tu token:

API REST: Llama a GET /v1/reports/{report_id} cuando el informe esté completed – el campo token contiene el valor.
Webhook: Si incluyes un webhook_url al crear el informe, el payload de finalización contiene el token en report.token.
Informe en PDF: El token está impreso en la primera página (formato: Token: SIG-2025-11-A7K3Q).

Los Intelligence Tokens son identificadores estables del informe completado; no expiran. La URL de enlace mágico del PDF que aparece en los correos de finalización es válida por unos 30 días – después de eso, puedes obtener en cualquier momento una URL de descarga firmada nueva desde el endpoint de estado.

¿Puedo usar Intelligence Tokens con Zapier?

¡Sí! Ejemplo de flujo de Zapier con el webhook de finalización de Surmado:

Disparador: Webhook de Surmado (evento report.completed) – configura webhook_url al crear el informe Acción 1: Llama a GET /v1/reports/{report.id} con tu clave de API para obtener public_intelligence Acción 2: Procesa public_intelligence.summary.presence_score Acción 3: Crea una entrada en la base de datos de Notion con las puntuaciones Acción 4: Envía una notificación a Slack si presence_score < 10

Integraciones comunes:

Notion: Rellena automáticamente el panel de marketing
Linear: Crea tareas para los problemas con puntuación baja
Google Sheets: Seguimiento de series temporales
Slack: Avisa al equipo de cambios en la visibilidad

Consulta la Guía de integración con Zapier para ver la configuración paso a paso, o el ejemplo de series temporales en Google Sheets de abajo.

¿Los Intelligence Tokens expiran?

No. Los tokens son identificadores estables de un informe completado y siguen siendo válidos como referencia histórica.

Lo que sí cambia con el tiempo:

La URL de enlace mágico del PDF que se entrega por correo es válida por ~30 días. Después, obtén una URL de descarga firmada nueva desde GET /v1/reports/{report_id}.
Las URL de descarga firmadas que devuelve el endpoint de estado expiran después de unos 15 minutos. Descarga el archivo y guárdalo de tu lado si lo necesitas a largo plazo.
Las puntuaciones varían a medida que cambian las plataformas de IA y el posicionamiento de los competidores. Vuelve a ejecutar los informes periódicamente (cada trimestre es una cadencia común) para tener datos al día.

¿Cuál es la diferencia entre los tokens SIG, SCN y SOL?

Esquemas distintos para productos distintos:

SIG-* (tokens de AI Visibility):

Esquema: métricas de visibilidad (presence_score, ghost_influence, platform_variance)
Caso de uso: Seguir la visibilidad en IA a lo largo del tiempo
Ejemplo: SIG-2025-11-A7K3Q

SCN-* (tokens de Site Audit):

Esquema: métricas técnicas de SEO (lighthouse, schema_validation, accessibility)
Caso de uso: Monitorear la salud del sitio, seguir los Core Web Vitals
Ejemplo: SCN-2025-11-A7K9P

SOL-* (tokens de Strategy):

Esquema: recomendaciones estratégicas (todo_list, priority, rationale) – se entrega como PDF; no se expone como public_intelligence
Caso de uso: Documentación de decisiones estratégicas, encadenamiento con herramientas de gestión de proyectos
Ejemplo: SOL-2025-11-A7K3Q

Todos los tokens: identificadores estables que se devuelven al completarse el informe.

Ver la documentación del esquema →

¿Surmado tiene una API REST?

Sí. La API REST de Surmado te permite:

Crear informes de AI Visibility, Site Audit y Strategy de forma programática
Gestionar marcas con el endpoint idempotente POST /v1/brands/ensure
Consultar el estado de los informes y descargar PDF/PPTX
Recibir notificaciones por webhook cuando los informes se completan

Autentícate con tu clave de API (sur_live_...) mediante token Bearer o el encabezado X-API-Key. Cada informe cuesta 1 Job.

Consulta la Guía de integración de la API completa →

¿Puedo automatizar los informes de AI Visibility?

Sí. Usa la API REST para crear informes de AI Visibility de forma programática:

POST /v1/reports/signal

Combínala con webhooks para flujos totalmente automatizados. Crea un informe, recibe un webhook cuando se complete y luego procesa los resultados. Consulta la Guía de integración de la API para ver los campos obligatorios y ejemplos.

También puedes usar herramientas sin código como Zapier, Make o n8n para activar la creación de informes a través de la API. Consulta la Guía de integración con Zapier para ver las instrucciones paso a paso.

¿Necesitas ayuda?

¿Dudas sobre los campos del esquema? Consulta nuestras preguntas frecuentes o escribe a support@surmado.com.

¿Estás creando una integración? Nos encantaría saberlo. Cuéntanos tu caso de uso en hi@surmado.com.

Empieza: Prueba Surmado | Trabaja con Scout

→ Relacionado: Guía de integración de la API | Guía de integración con Zapier | Guía de integración con Make | Guía de integración con n8n