Dados estruturados e Intelligence Tokens

Leitura de 15 min

TLDR

Todo relatório da Surmado inclui JSON estruturado para acesso programático. Os tokens de AI Visibility contêm métricas de visibilidade e dados de concorrentes. Os tokens de Site Audit trazem notas de desempenho e problemas técnicos. Os tokens de Strategy têm recomendações estratégicas e modelagem financeira. Integre com Notion, Airtable, Google Sheets, Zapier ou ferramentas próprias. Acompanhe métricas ao longo do tempo, automatize relatórios, monte painéis ou dispare alertas quando a visibilidade cair.

Procurando a API REST? Veja o Guia de integração da API para criar relatórios, gerenciar marcas e receber webhooks de forma programática.

Todo relatório da Surmado inclui JSON estruturado para acesso programático.

O que são Intelligence Tokens?

Intelligence Tokens são identificadores únicos de cada relatório concluído (por exemplo, SIG-2025-11-A7K3Q). O token é retornado na resposta da API REST quando um relatório termina e, nos relatórios de AI Visibility e Site Audit, libera um payload JSON estruturado public_intelligence que você pode integrar a:

Painéis (Notion, Airtable, Retool, apps React próprios)
Fluxos de automação (Zapier, Make, n8n)
Ferramentas internas (CRMs, gestão de projetos, plataformas de BI)
Agentes próprios (assistentes de IA, bots de monitoramento, integrações com o Slack)

Onde encontrar: chame GET /v1/reports/{report_id} assim que o relatório estiver completed. As respostas de AI Visibility e Site Audit incluem um objeto public_intelligence com campos selecionados e legíveis por máquina. Os relatórios de Strategy retornam o token na conclusão, mas hoje não expõem public_intelligence: use o PDF gerado para o resultado do Strategy. Veja o Guia de integração da API para autenticação e detalhes dos endpoints.

Formato: JSON padrão. Campos podem ser adicionados com o tempo; buscamos manter estáveis os campos existentes.

Intelligence Token de AI Visibility

Prefixo do token: SIG-* (slug do produto nos caminhos da API: signal) Finalidade: métricas de visibilidade em IA, posicionamento competitivo e medição de Ghost Influence.

Estrutura do 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"
      ]
    }
  }
}

O objeto summary, selecionado e posicionado no topo, é preenchido pela API para acesso rápido. As métricas mais detalhadas ficam em data.*. Campos internos como persona_details e test_queries ficam em lista de bloqueio e nunca aparecem em public_intelligence.

Campos principais explicados (AI Visibility)

summary.presence_score (e data.visibility_metrics.presence_score): nota de 0 a 100 que mede a frequência com que seu negócio aparece nas respostas de IA a consultas relevantes. Quanto maior, mais visível.

data.visibility_metrics.ghost_influence_percentage: porcentagem das menções relevantes em que a IA descreve sua proposta de valor ou seus recursos sem citar você pelo nome. Ghost Influence alta significa que você está educando o mercado, mas os concorrentes ficam com o crédito.

summary.competitive_rank (e data.competitive_position.rank): sua posição em relação aos concorrentes da mesma categoria. Posição 1 = mais mencionado.

data.platform_variance: detalhamento por plataforma de IA (ChatGPT, Claude, Gemini etc.) mostrando onde você está mais forte e mais fraco.

data.strategic_signals.visibility_opportunities: recomendações práticas ordenadas pelo impacto estimado.

Casos de uso comuns (AI Visibility)

Integração com painéis: puxe summary.presence_score, data.visibility_metrics.ghost_influence_percentage e summary.competitive_rank para acompanhar a visibilidade em IA ao longo do tempo.

Alertas: monitore data.baseline_metrics.trend e dispare alertas se a nota de presença cair mais de 10 pontos.

Inteligência competitiva: compare seu data.platform_variance com os relatórios de AI Visibility dos concorrentes para identificar lacunas específicas de cada plataforma.

Estratégia de conteúdo: use data.perception_analysis.weakness_signals para orientar a criação de conteúdo e a otimização de FAQs.

Intelligence Token de Site Audit

Prefixo do token: SCN-* (slug do produto nos caminhos da API: scan) Finalidade: dados de auditoria técnica de SEO, métricas de desempenho, notas de acessibilidade e itens de ação priorizados.

Estrutura do 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 é o resumo selecionado que os clientes usam para automação. Os dados mais profundos ficam em data.audit_data.*. O array completo audit_data.pages[] está presente na resposta public_intelligence, mas é longo; use summary.quick_wins para as recomendações prioritárias.

Campos principais explicados (Site Audit)

summary.seo_score (e data.audit_data.site_metrics.seo_score): nota de SEO de 0 a 100 que reúne fatores técnicos e de página.

summary.performance_score (e data.audit_data.lighthouse.performance_score): nota de desempenho do Lighthouse de 0 a 100. Média do setor: 65 a 75 para sites de e-commerce.

data.audit_data.site_metrics.images_without_alt: número de imagens sem texto alternativo (problema de SEO e de acessibilidade).

data.audit_data.enrichment.schema_strategist: validação do Schema.org e recomendações para dados estruturados.

data.audit_data.enrichment.content_gap_analysis: temas em que os concorrentes se posicionam, mas que você não cobre. Áreas de oportunidade de SEO.

data.audit_data.pages[].issues: problemas detalhados por página, com gravidade e recomendações práticas.

summary.quick_wins: recomendações priorizadas, em linguagem simples, organizadas por área (link_analysis, schema_strategy, content_gaps).

Casos de uso comuns (Site Audit)

Integração com CI/CD: rode um Site Audit no seu pipeline de deploy e faça o build falhar se summary.performance_score < 80.

Monitoramento: acompanhe summary.seo_score, summary.performance_score e summary.accessibility_score ao longo do tempo em um banco de dados de séries temporais.

Controle de problemas: analise data.audit_data.pages[].issues e crie tickets no Jira/Linear automaticamente para o time de desenvolvimento.

Relatórios: puxe o objeto summary para painéis executivos que mostram a saúde de SEO.

Intelligence Token de Strategy

Prefixo do token: SOL-* (slug do produto nos caminhos da API: solutions) Finalidade: resultado de planejamento estratégico, itens de ação priorizados, síntese de debate adversarial e estruturas de decisão.

Os relatórios de Strategy hoje não expõem um objeto public_intelligence pela API REST. A estrutura abaixo descreve o que aparece no PDF gerado e está incluída como referência: quem consome de forma programática deve usar a URL de download do PDF retornada no endpoint de status.

Estrutura do 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 principais explicados (Strategy)

todo_list[].priority: 1 = maior prioridade. A ordem representa a sequência lógica e as dependências.

todo_list[].dependencies: array com os números de prioridade dos quais esta ação depende. Usado para definir a sequência na gestão de projetos.

adversarial_debate_summary: visão condensada das preocupações levantadas por cada perspectiva de IA (CFO, COO, Market Realist, Game Theorist) e da síntese final.

monte_carlo_scenarios: resultados de testes de estresse probabilísticos que mostram a probabilidade de sucesso ou fracasso sob diferentes premissas.

evidence_citations: fontes que sustentam as principais afirmações e recomendações. Transparência sobre o raciocínio.

Casos de uso comuns (Strategy)

O public_intelligence do Strategy não é exposto pela API REST hoje. Os campos abaixo descrevem o resultado em PDF: quem consome de forma programática deve extrair do PDF ou rodar de novo o relatório de AI Visibility / Site Audit de origem e trabalhar a partir do public_intelligence dele.

Gestão de projetos: importe todo_list para o Linear, Asana ou Notion com prioridades e dependências já mapeadas.

Registro de decisões: guarde os tokens de Strategy no seu repositório de estratégia para documentar por que as decisões foram tomadas.

Relatórios para a diretoria: puxe summary e monte_carlo_scenarios para mostrar à equipe executiva como a estratégia foi testada sob estresse.

Gestão do conhecimento: indexe evidence_citations para construir a memória institucional da pesquisa estratégica.

Como acessar os Intelligence Tokens

Pela API REST

É o caminho principal. Chame GET /v1/reports/{report_id} quando um relatório chegar ao status completed. A resposta inclui o campo token e, nos relatórios de AI Visibility e Site Audit, um objeto public_intelligence com métricas estruturadas. Veja o Guia de integração da API para autenticação, webhooks e todos os detalhes dos endpoints.

Por e-mail

Quando seu relatório estiver pronto, você recebe um e-mail com um botão de magic link para ver o PDF. O link vale por cerca de 30 dias.

Pelo app da Surmado

Acesse Reports → selecione seu relatório → o token e os links de download aparecem na tela de detalhes do relatório.

Esquemas do Intelligence Token

Os esquemas dos payloads public_intelligence de AI Visibility e Site Audit estão documentados acima. O resultado do Strategy é entregue em PDF; um payload estruturado public_intelligence hoje não é exposto pela API REST para os relatórios de Strategy.

Exemplos de integração

Em todos os exemplos abaixo, o public_intelligence é obtido da API REST com GET /v1/reports/{report_id} (veja o Guia de integração da API).

Painel no 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 do 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
    })
  });
}

Criação de issues no 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']
  });
}

Acompanhamento de séries temporais no 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
});

Respostas rápidas

O que é um Intelligence Token?

Intelligence Token = seu identificador único de um relatório concluído (formato: SIG-2025-11-XXXXX, SCN-2025-11-XXXXX ou SOL-2025-11-XXXXX). O token é retornado na resposta de status da API e é a chave que você passa ao encadear relatórios (por exemplo, ao criar um relatório de Strategy a partir de um relatório de AI Visibility existente).

Por que ele é valioso:

Acesso programático: analise o public_intelligence nas suas ferramentas (Notion, Linear, Google Sheets)
Automação: monte fluxos que disparam a cada novo relatório
Acompanhamento em série temporal: guarde dados históricos para análise de tendências
Encadeamento de relatórios: passe como signal_token ou scan_token ao criar um relatório de Strategy

Onde obter: retornado por GET /v1/reports/{report_id} na conclusão, incluído nos webhooks de conclusão e exibido na página de detalhes do relatório no app da Surmado.

Como acesso meu Intelligence Token?

3 formas de obter seu token:

API REST: chame GET /v1/reports/{report_id} quando o relatório estiver completed. O campo token traz o valor.
Webhook: se você incluir um webhook_url ao criar o relatório, o payload de conclusão traz o token em report.token.
Relatório em PDF: o token vem impresso na primeira página (formato: Token: SIG-2025-11-A7K3Q).

Os Intelligence Tokens são identificadores estáveis do relatório concluído e não expiram. A URL de magic link do PDF mostrada nos e-mails de conclusão vale por cerca de 30 dias; depois disso, busque uma nova URL de download assinada no endpoint de status quando quiser.

Posso usar Intelligence Tokens com o Zapier?

Sim! Exemplo de fluxo no Zapier usando o webhook de conclusão da Surmado:

Gatilho: webhook da Surmado (evento report.completed) – configure webhook_url ao criar o relatório Ação 1: chame GET /v1/reports/{report.id} com sua chave de API para buscar o public_intelligence Ação 2: analise public_intelligence.summary.presence_score Ação 3: crie uma entrada no banco de dados do Notion com as notas Ação 4: envie uma notificação no Slack se presence_score < 10

Integrações comuns:

Notion: preenche automaticamente o painel de marketing
Linear: cria tarefas para problemas de nota baixa
Google Sheets: acompanhamento em série temporal
Slack: avisa o time sobre mudanças na visibilidade

Veja o Guia de integração com o Zapier para a configuração passo a passo, ou o exemplo de séries temporais no Google Sheets abaixo.

Os Intelligence Tokens expiram?

Não. Os tokens são identificadores estáveis de um relatório concluído e continuam válidos como referência histórica.

O que muda com o tempo:

A URL de magic link do PDF enviada por e-mail vale por cerca de 30 dias. Depois disso, busque uma URL de download assinada em GET /v1/reports/{report_id}.
As URLs de download assinadas retornadas pelo endpoint de status expiram em cerca de 15 minutos. Baixe o arquivo e guarde do seu lado se precisar dele a longo prazo.
As notas oscilam conforme as plataformas de IA e o posicionamento dos concorrentes mudam. Rode os relatórios de novo periodicamente (a cada trimestre é uma cadência comum) para ter dados atualizados.

Qual é a diferença entre os tokens SIG, SCN e SOL?

Esquemas diferentes para produtos diferentes:

SIG-* (tokens de AI Visibility):

Esquema: métricas de visibilidade (presence_score, ghost_influence, platform_variance)
Caso de uso: acompanhar a descoberta por IA ao longo do tempo
Exemplo: SIG-2025-11-A7K3Q

SCN-* (tokens de Site Audit):

Esquema: métricas técnicas de SEO (lighthouse, schema_validation, accessibility)
Caso de uso: monitorar a saúde do site e acompanhar os Core Web Vitals
Exemplo: SCN-2025-11-A7K9P

SOL-* (tokens de Strategy):

Esquema: recomendações estratégicas (todo_list, priority, rationale) – entregue em PDF; não exposto como public_intelligence
Caso de uso: documentação de decisões estratégicas, encadeamento em ferramentas de gestão de projetos
Exemplo: SOL-2025-11-A7K3Q

Todos os tokens: identificadores estáveis retornados na conclusão do relatório.

Veja a documentação do esquema →

A Surmado tem uma API REST?

Sim. A API REST da Surmado permite:

Criar relatórios de AI Visibility, Site Audit e Strategy de forma programática
Gerenciar marcas com o POST /v1/brands/ensure idempotente
Consultar o status dos relatórios e baixar PDFs/PPTX
Receber notificações por webhook quando os relatórios terminam

Autentique com sua chave de API (sur_live_...) por token Bearer ou pelo cabeçalho X-API-Key. Cada relatório custa 1 Job.

Veja o Guia de integração da API completo →

Posso automatizar relatórios de AI Visibility?

Sim. Use a API REST para criar relatórios de AI Visibility de forma programática:

POST /v1/reports/signal

Combine com webhooks para ter fluxos totalmente automatizados. Crie um relatório, receba um webhook quando ele terminar e depois analise os resultados. Veja o Guia de integração da API para os campos obrigatórios e exemplos.

Você também pode usar ferramentas sem código como Zapier, Make ou n8n para disparar a criação de relatórios pela API. Veja o Guia de integração com o Zapier para instruções passo a passo.

Precisa de ajuda?

Dúvidas sobre os campos do esquema? Consulte nosso FAQ ou escreva para support@surmado.com.

Está montando uma integração? Vamos adorar saber! Conte seu caso de uso em hi@surmado.com.

Comece agora: Experimente a Surmado | Trabalhe com o Scout

→ Veja também: Guia de integração da API | Guia de integração com o Zapier | Guia de integração com o Make | Guia de integração com o n8n