Dati strutturati e Intelligence Token

15 min di lettura

TLDR

Ogni report di Surmado include JSON strutturato per l’accesso programmatico. I token di AI Visibility contengono metriche di visibilità e dati sui concorrenti. I token di Site Audit includono punteggi di prestazioni e problemi tecnici. I token di Strategy contengono raccomandazioni strategiche e modelli finanziari. Integrali con Notion, Airtable, Google Sheets, Zapier o strumenti personalizzati. Segui le metriche nel tempo, automatizza i report, crea pannelli o attiva avvisi quando la visibilità cala.

Cerchi l’API REST? Consulta la Guida all’integrazione dell’API per creare report, gestire i brand e ricevere webhook in modo programmatico.

Ogni report di Surmado include JSON strutturato per l’accesso programmatico.

Cosa sono gli Intelligence Token?

Gli Intelligence Token sono identificativi univoci di ogni report completato (ad esempio SIG-2025-11-A7K3Q). Il token viene restituito nella risposta dell’API REST quando un report è completato e, per i report di AI Visibility e Site Audit, sblocca un payload JSON strutturato public_intelligence che puoi integrare in:

Pannelli (Notion, Airtable, Retool, app React personalizzate)
Flussi di automazione (Zapier, Make, n8n)
Strumenti interni (CRM, gestione dei progetti, piattaforme di BI)
Agenti personalizzati (assistenti AI, bot di monitoraggio, integrazioni con Slack)

Dove trovarli: chiama GET /v1/reports/{report_id} quando il tuo report è completed. Le risposte di AI Visibility e Site Audit includono un oggetto public_intelligence con campi selezionati e leggibili dalle macchine. I report di Strategy restituiscono il token al completamento, ma per ora non espongono public_intelligence: usa il PDF generato per il risultato di Strategy. Consulta la Guida all’integrazione dell’API per l’autenticazione e i dettagli sugli endpoint.

Formato: JSON standard. Nel tempo possono essere aggiunti nuovi campi; il nostro obiettivo è mantenere stabili quelli esistenti.

Intelligence Token di AI Visibility

Prefisso del token: SIG-* (slug del prodotto nei percorsi API: signal) Scopo: metriche di visibilità nell’AI, posizionamento competitivo e misurazione del Ghost Influence.

Struttura dello schema (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"
      ]
    }
  }
}

L’oggetto summary in cima è compilato dall’API per un accesso rapido. Le metriche più approfondite si trovano sotto data.*. I campi interni come persona_details e test_queries sono esclusi e non compaiono mai in public_intelligence.

Campi principali spiegati (AI Visibility)

summary.presence_score (e data.visibility_metrics.presence_score): punteggio da 0 a 100 che misura quanto spesso la tua attività compare nelle risposte dell’AI a domande pertinenti. Più alto = più visibile.

data.visibility_metrics.ghost_influence_percentage: percentuale di menzioni pertinenti in cui l’AI descrive la tua proposta di valore o le tue funzionalità senza nominarti. Un Ghost Influence alto = stai educando il mercato, ma sono i concorrenti a ottenere l’attribuzione.

summary.competitive_rank (e data.competitive_position.rank): la tua posizione rispetto ai concorrenti della stessa categoria. Posizione 1 = il più menzionato.

data.platform_variance: dettaglio per piattaforma AI (ChatGPT, Claude, Gemini e così via) che mostra dove sei più forte e dove più debole.

data.strategic_signals.visibility_opportunities: raccomandazioni attuabili ordinate per impatto stimato.

Casi d’uso comuni (AI Visibility)

Integrazione con i pannelli: recupera summary.presence_score, data.visibility_metrics.ghost_influence_percentage e summary.competitive_rank per seguire la visibilità nell’AI nel tempo.

Avvisi: monitora data.baseline_metrics.trend e attiva avvisi se il punteggio di presenza cala di più di 10 punti.

Analisi della concorrenza: confronta il tuo data.platform_variance con i report di AI Visibility dei concorrenti per individuare le lacune specifiche di ogni piattaforma.

Strategia dei contenuti: usa data.perception_analysis.weakness_signals per orientare la creazione di contenuti e l’ottimizzazione delle FAQ.

Intelligence Token di Site Audit

Prefisso del token: SCN-* (slug del prodotto nei percorsi API: scan) Scopo: dati dell’audit SEO tecnico, metriche di prestazioni, punteggi di accessibilità e azioni prioritarie.

Struttura dello schema (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 è il riepilogo selezionato che i clienti usano per l’automazione. I dati più approfonditi si trovano sotto data.audit_data.*. L’array completo audit_data.pages[] è presente nella risposta public_intelligence ma è lungo; usa summary.quick_wins per le raccomandazioni più prioritarie.

Campi principali spiegati (Site Audit)

summary.seo_score (e data.audit_data.site_metrics.seo_score): punteggio SEO da 0 a 100 che riassume i fattori tecnici e on-page.

summary.performance_score (e data.audit_data.lighthouse.performance_score): punteggio di prestazioni Lighthouse da 0 a 100. Media del settore: 65-75 per i siti di e-commerce.

data.audit_data.site_metrics.images_without_alt: numero di immagini senza testo alternativo (problema sia di SEO sia di accessibilità).

data.audit_data.enrichment.schema_strategist: validazione Schema.org e raccomandazioni per i dati strutturati.

data.audit_data.enrichment.content_gap_analysis: argomenti per cui i concorrenti si posizionano e che tu non copri. Aree di opportunità SEO.

data.audit_data.pages[].issues: problemi dettagliati per pagina, con gravità e raccomandazioni attuabili.

summary.quick_wins: raccomandazioni prioritarie in linguaggio semplice, organizzate per area (link_analysis, schema_strategy, content_gaps).

Casi d’uso comuni (Site Audit)

Integrazione CI/CD: esegui un Site Audit nella tua pipeline di rilascio e fai fallire le build se summary.performance_score < 80.

Monitoraggio: segui summary.seo_score, summary.performance_score e summary.accessibility_score nel tempo in un database di serie temporali.

Gestione dei problemi: analizza data.audit_data.pages[].issues e crea in automatico ticket Jira/Linear per il team di sviluppo.

Reportistica: recupera l’oggetto summary per i pannelli direzionali che mostrano lo stato di salute della SEO.

Intelligence Token di Strategy

Prefisso del token: SOL-* (slug del prodotto nei percorsi API: solutions) Scopo: output di pianificazione strategica, azioni prioritarie, sintesi del dibattito avversariale e quadri decisionali.

I report di Strategy per ora non espongono un oggetto public_intelligence tramite l’API REST. La struttura qui sotto descrive ciò che compare nel PDF generato ed è inclusa come riferimento: chi lavora in modo programmatico deve usare l’URL di download del PDF restituito dall’endpoint di stato.

Struttura dello schema (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"
    }
  ]
}

Campi principali spiegati (Strategy)

todo_list[].priority: 1 = priorità massima. L’ordine rappresenta la sequenza logica e le dipendenze.

todo_list[].dependencies: array dei numeri di priorità da cui dipende questa azione. Serve a ordinare la sequenza nella gestione dei progetti.

adversarial_debate_summary: vista sintetica delle preoccupazioni sollevate da ciascuna prospettiva AI (CFO, COO, Market Realist, Game Theorist) e sintesi finale.

monte_carlo_scenarios: risultati di stress test probabilistici che mostrano la probabilità di successo o fallimento al variare delle ipotesi.

evidence_citations: fonti a sostegno delle affermazioni e delle raccomandazioni principali. Trasparenza sul ragionamento.

Casi d’uso comuni (Strategy)

public_intelligence di Strategy oggi non è esposto tramite l’API REST. I campi qui sotto descrivono l’output del PDF: chi lavora in modo programmatico deve estrarre i dati dal PDF oppure rieseguire il report di AI Visibility o Site Audit di partenza e lavorare sul suo public_intelligence.

Gestione dei progetti: importa todo_list in Linear, Asana o Notion con priorità e dipendenze già mappate.

Tracciamento delle decisioni: conserva i token di Strategy nel tuo archivio strategico per documentare il motivo delle decisioni.

Report per il consiglio: recupera summary e monte_carlo_scenarios per mostrare al team dirigente come è stata messa alla prova la strategia.

Gestione della conoscenza: indicizza evidence_citations per costruire la memoria aziendale della ricerca strategica.

Come accedere agli Intelligence Token

Tramite API REST

La strada principale. Chiama GET /v1/reports/{report_id} quando un report raggiunge lo stato completed. La risposta include il campo token e, per i report di AI Visibility e Site Audit, un oggetto public_intelligence con metriche strutturate. Consulta la Guida all’integrazione dell’API per autenticazione, webhook e tutti i dettagli sugli endpoint.

Tramite email

Quando il tuo report è pronto, ricevi un’email con un pulsante magic link per vedere il PDF. Il link è valido per circa 30 giorni.

Tramite l’app Surmado

Vai su Reports → seleziona il tuo report → il token e i link di download sono visibili nella vista di dettaglio del report.

Schemi degli Intelligence Token

Gli schemi dei payload public_intelligence di AI Visibility e Site Audit sono documentati sopra. L’output di Strategy viene consegnato come PDF; per ora un payload public_intelligence strutturato non è esposto tramite l’API REST per i report di Strategy.

Esempi di integrazione

In tutti gli esempi qui sotto, public_intelligence viene recuperato dall’API REST con GET /v1/reports/{report_id} (vedi la Guida all’integrazione dell’API).

Pannello in 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 di 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
    })
  });
}

Creazione di issue in 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']
  });
}

Tracciamento delle serie temporali in 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
});

Risposte rapide

Cos’è un Intelligence Token?

Intelligence Token = il tuo identificativo univoco di un report completato (formato: SIG-2025-11-XXXXX, SCN-2025-11-XXXXX o SOL-2025-11-XXXXX). Il token viene restituito nella risposta di stato dell’API ed è la chiave che passi quando colleghi i report in sequenza (ad esempio per creare un report di Strategy a partire da un report di AI Visibility esistente).

Perché è utile:

Accesso programmatico: analizza public_intelligence nei tuoi strumenti (Notion, Linear, Google Sheets)
Automazione: crea flussi che si attivano a ogni nuovo report
Tracciamento delle serie temporali: conserva i dati storici per analizzare le tendenze
Collegamento dei report: passalo come signal_token o scan_token quando crei un report di Strategy

Dove lo trovi: viene restituito da GET /v1/reports/{report_id} al completamento, è incluso nei webhook di completamento ed è mostrato nella pagina di dettaglio del report nell’app Surmado.

Come accedo al mio Intelligence Token?

3 modi per ottenere il tuo token:

API REST: chiama GET /v1/reports/{report_id} quando il report è completed: il campo token contiene il valore.
Webhook: se includi un webhook_url alla creazione del report, il payload di completamento contiene il token in report.token.
Report in PDF: il token è stampato sulla prima pagina (formato: Token: SIG-2025-11-A7K3Q).

Gli Intelligence Token sono identificativi stabili del report completato e non scadono. L’URL magic link del PDF mostrato nelle email di completamento è valido per circa 30 giorni: dopo quel periodo puoi recuperare in qualsiasi momento un nuovo URL di download firmato dall’endpoint di stato.

Posso usare gli Intelligence Token con Zapier?

Sì! Esempio di flusso Zapier che usa il webhook di completamento di Surmado:

Trigger: webhook di Surmado (evento report.completed): configura webhook_url alla creazione del report Azione 1: chiama GET /v1/reports/{report.id} con la tua chiave API per recuperare public_intelligence Azione 2: analizza public_intelligence.summary.presence_score Azione 3: crea una voce nel database di Notion con i punteggi Azione 4: invia una notifica su Slack se presence_score < 10

Integrazioni comuni:

Notion: compila in automatico il pannello di marketing
Linear: crea attività per i problemi con punteggio basso
Google Sheets: tracciamento delle serie temporali
Slack: avvisa il team quando la visibilità cambia

Consulta la Guida all’integrazione con Zapier per la configurazione passo per passo, oppure l’esempio di serie temporali con Google Sheets qui sotto.

Gli Intelligence Token scadono?

No. I token sono identificativi stabili di un report completato e restano validi come riferimento storico.

Cosa cambia nel tempo:

L’URL magic link del PDF consegnato via email è valido per circa 30 giorni. Dopo, recupera un nuovo URL di download firmato da GET /v1/reports/{report_id}.
Gli URL di download firmati restituiti dall’endpoint di stato scadono dopo circa 15 minuti. Scarica il file e conservalo da parte tua se ti serve a lungo termine.
I punteggi cambiano al variare delle piattaforme AI e del posizionamento dei concorrenti. Riesegui i report periodicamente (ogni trimestre è una cadenza comune) per avere dati aggiornati.

Qual è la differenza tra i token SIG, SCN e SOL?

Schemi diversi per prodotti diversi:

SIG-* (token di AI Visibility):

Schema: metriche di visibilità (presence_score, ghost_influence, platform_variance)
Caso d’uso: seguire nel tempo la reperibilità nell’AI
Esempio: SIG-2025-11-A7K3Q

SCN-* (token di Site Audit):

Schema: metriche di SEO tecnico (lighthouse, schema_validation, accessibility)
Caso d’uso: monitorare lo stato di salute del sito, seguire i Core Web Vitals
Esempio: SCN-2025-11-A7K9P

SOL-* (token di Strategy):

Schema: raccomandazioni strategiche (todo_list, priority, rationale), consegnate come PDF; non esposte come public_intelligence
Caso d’uso: documentazione delle decisioni strategiche, collegamento agli strumenti di gestione dei progetti
Esempio: SOL-2025-11-A7K3Q

Tutti i token: identificativi stabili restituiti al completamento del report.

Vedi la documentazione degli schemi →

Surmado ha un’API REST?

Sì. L’API REST di Surmado ti permette di:

Creare in modo programmatico report di AI Visibility, Site Audit e Strategy
Gestire i brand con POST /v1/brands/ensure, idempotente
Controllare lo stato dei report e scaricare PDF e PPTX
Ricevere notifiche webhook quando i report sono completati

Autenticati con la tua chiave API (sur_live_...) tramite token Bearer o header X-API-Key. Ogni report costa 1 Job.

Vedi la Guida completa all’integrazione dell’API →

Posso automatizzare i report di AI Visibility?

Sì. Usa l’API REST per creare report di AI Visibility in modo programmatico:

POST /v1/reports/signal

Combinala con i webhook per flussi completamente automatizzati. Crea un report, ricevi un webhook quando è completato, poi analizza i risultati. Consulta la Guida all’integrazione dell’API per i campi obbligatori e gli esempi.

Puoi anche usare strumenti no-code come Zapier, Make o n8n per avviare la creazione dei report tramite l’API. Consulta la Guida all’integrazione con Zapier per le istruzioni passo per passo.

Serve aiuto?

Domande sui campi degli schemi? Consulta le nostre FAQ o scrivi a support@surmado.com.

Stai creando un’integrazione? Ci piacerebbe saperlo! Racconta il tuo caso d’uso a hi@surmado.com.

Inizia: Prova Surmado | Lavora con Scout

→ Correlati: Guida all’integrazione dell’API | Guida all’integrazione con Zapier | Guida all’integrazione con Make | Guida all’integrazione con n8n