Salvate solo come hash
Il valore completo della chiave è visibile una sola volta, al momento della creazione. Nel database resta un hash: anche un accesso indesiderato non espone la credenziale.
API & Integrations
API REST e webhook per la GEO
Porta contenuti ottimizzati, riassunti AI e dati di visibilità dentro i tuoi strumenti. API versionate, chiavi con scope, webhook firmati e risposte condizionali: l'infrastruttura per integrare la GEO in qualsiasi flusso di lavoro.
2versioni REST stabili
4scope per chiave API
6eventi webhook supportati
326test automatici superati
Il livello di integrazione
I tuoi contenuti, nella lingua dei tuoi strumenti
Un sito ottimizzato per le AI non serve a niente se i dati restano chiusi nell'admin. L'API espone contenuti, riassunti e segnali GEO in formati che CMS headless, data warehouse, agenti e pipeline di contenuto possono consumare subito.
- Contenuto pulito in Markdown, pronto per LLM e generatori statici
- HTML raw quando serve il rendering, senza passare dal tema
- Metadata e riassunto AI nella stessa risposta della v1
- Webhook per reagire a eventi senza polling continuo
- Chiavi con permessi separati per lettura, analytics e report
REST v1
Un endpoint, un documento pronto da usare
GET /wp-json/geo-pro/v1/content/{id} restituisce Markdown puro con metadata, contenuto e riassunto AI. È il formato ideale per ingestion, ricerca semantica e pipeline RAG.
Cosa trovi nella risposta
- Front matter con titolo, slug, data, autore e lingua
- Riassunto AI validato, allineato al GEO Score del contenuto
- Corpo in Markdown con heading, liste, link e citazioni
- Identificativo stabile per sincronizzazioni incrementali
- Nessun markup del tema, nessun widget, nessun rumore
Pensato per gli LLM. Il documento è autosufficiente: chi lo riceve non deve ricostruire il contesto dalla pagina HTML, e può citare il contenuto senza ambiguità.
curl -s \
-H "Authorization: Bearer $GOP_API_KEY" \
"https://example.com/wp-json/geo-pro/v1/content/123"
# Risposta: text/markdown
---
title: Guida alla GEO
slug: guida-alla-geo
language: it
ai_summary: Come strutturare i contenuti
per essere citati dalle AI.
---
## Perché la GEO conta
Le AI non ordinano dieci link:
scelgono poche fonti affidabili.
REST v2
Contenuto grezzo, negoziazione esplicita
La v2 separa il contenuto dal wrapper: niente JSON obbligatorio, niente campi da scavare. Scegli il formato con l'header Accept e ricevi esattamente ciò che hai chiesto, con il content type corretto.
Accept: text/markdownper testo puro e citabileAccept: text/htmlper markup pronto al rendering- Header di risposta coerenti e cacheabili
- Stesso identificativo della v1, per migrazioni graduali
- Nessuna trasformazione lato client: il formato è contrattuale
# Markdown puro
curl -s \
-H "Authorization: Bearer $GOP_API_KEY" \
-H "Accept: text/markdown" \
"https://example.com/wp-json/geo-pro/v2/content/123"
# HTML grezzo
curl -s \
-H "Authorization: Bearer $GOP_API_KEY" \
-H "Accept: text/html" \
"https://example.com/wp-json/geo-pro/v2/content/123"
# Risposta 200 con Content-Type
Content-Type: text/markdown; charset=utf-8
Sicurezza delle chiavi
Chiavi con scope, hash e revoca immediata
Una chiave API è una credenziale, non un identificativo. Per questo viene generata una sola volta, salvata solo come hash e limitata agli scope che le assegni.
| Scope | Permette | Non permette |
|---|---|---|
content:read |
Leggere contenuti, metadata e riassunti AI | Modificare contenuti o impostazioni |
analytics:read |
Leggere hit dei bot, citazioni e referral | Accedere ai dati di altri siti |
reports:read |
Elencare e scaricare i report generati | Configurare branding o destinatari |
webhooks:manage |
Creare, attivare e ruotare gli endpoint | Leggere il secret in chiaro dopo la creazione |
Bearer, non query string
La chiave viaggia nell'header Authorization: Bearer, viene estratta dal middleware dedicato e non finisce nei log degli accessi come parametro URL.
Revoca immediata
Disattivare una chiave la invalida alla richiesta successiva. Puoi ruotare le credenziali senza toccare il codice e tenere una chiave separata per ogni strumento.
Webhooks
Eventi firmati, segreti cifrati, zero polling
Quando succede qualcosa di importante, GEO Optimizer Pro chiama il tuo endpoint con una firma HMAC-SHA256. Tu verifichi, elabori e rispondi 2xx: il resto è gestito dalla coda.
Eventi disponibili
content.optimized— un contenuto ha completato l'ottimizzazionereport.generated— report HTML o PDF prontovisibility.alert— soglia di visibilità o citazioni superatacitation.detected— nuova citazione rilevata su un motore AIjob.failed— un job asincrono ha esaurito i tentativiissue.created— nuovo problema aperto nell'Issue Center
Segreti cifrati. Il secret di ogni endpoint è protetto con AES-256-GCM, viene mostrato una sola volta e non è mai esportabile. La migrazione dai vecchi secret in chiaro avviene in modo trasparente.
# Header ricevuti
X-GEO-Signature: sha256=6f2c...
X-GEO-Timestamp: 1761177600
# Verifica lato ricevente
expected=$(printf '%s' "$body" \
| openssl dgst -sha256 -hmac "$GOP_WEBHOOK_SECRET" \
| awk '{print $2}')
[ "sha256=$expected" = "$HTTP_X_GEO_SIGNATURE" ] \
|| exit 1
# Poi elabora il payload e rispondi 2xxOgni endpoint ha un interruttore attivo o disattivo, una coda di retry con backoff esponenziale e la cronologia delle ultime consegne.
Efficienza e limiti
Risposte condizionali e rate limit espliciti
Le integrazioni non devono costare più del valore che portano. ETag, Last-Modified e 304 evitano di riscaricare contenuti identici; i limiti proteggono il sito e rendono prevedibile l'uso delle chiavi.
Cache condizionale
- ETag forte sul contenuto e sul riassunto AI
- Last-Modified basato sulla data di modifica reale
- If-None-Match e If-Modified-Since riconosciuti
- 304 Not Modified senza corpo quando nulla è cambiato
- Header coerenti tra v1 e v2, per client e cache proxy
Meno token, più sincronizzazioni. Un client che rispetta la cache evita di rianalizzare lo stesso testo e riduce i costi delle pipeline AI collegate.
curl -s -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer $GOP_API_KEY" \
-H 'If-None-Match: "b7e4c1"' \
"https://example.com/wp-json/geo-pro/v2/content/123"
# 304 se il contenuto non è cambiato
# 200 con nuovo ETag se è stato aggiornato
# Rate limit per chiave
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
Retry-After: 30 (solo su 429)| Risorsa | Limite predefinito | Comportamento |
|---|---|---|
| REST v1 contenuti | 60 richieste al minuto per chiave | 429 con Retry-After, nessun blocco dell'admin |
| REST v2 contenuti | 120 richieste al minuto per chiave | Header di quota su ogni risposta |
| Webhook in uscita | 5 tentativi con backoff esponenziale | Endpoint disattivato dopo errori ripetuti, con avviso |
Endpoint pubblico /ask |
20 richieste al minuto per IP | Nonce, same-origin e limite dedicato |
I limiti sono configurabili in base al carico del sito. I valori predefiniti sono prudenti e separano il traffico API da quello degli utenti.
Integration Hub
Collega gli strumenti che usi già
Un solo pannello per connessioni, scope e stato. Dal Marketplace alle API proprietarie, ogni integrazione dichiara cosa può fare e si revoca con un clic.
Integration Hub
Vista unica di tutte le connessioni attive: provider AI, Search Console, analytics, webhook e strumenti di terze parti. Ogni voce mostra scope, stato e ultima attività.
Marketplace
Connessioni con partner e strumenti selezionati: CRM, piattaforme di reporting, automazioni e data pipeline. Installazione guidata e permessi espliciti, senza incollare credenziali ovunque.
Google OAuth
Collega Search Console con OAuth 2.0 e scope di sola lettura. Nessuna password condivisa, token cifrati con AES-256-GCM e revoca dal pannello o direttamente dall'account Google.
Le connessioni si governano, non si subiscono. Ogni integrazione può essere disattivata senza disinstallare il plugin. Se revochi un token, il job collegato si ferma e ti avvisa, invece di fallire in silenzio.
Dal curl alla produzione
Quattro passi per un'integrazione stabile
La documentazione parte da esempi copiabili e arriva alla gestione degli errori. Non serve un SDK: bastano HTTP, JSON e una chiave con lo scope giusto.
1. Crea la chiave
Assegna solo gli scope necessari allo strumento. Salva il valore in un secret manager: dopo la creazione non sarà più visibile.
2. Chiama l'endpoint
Usa Bearer nell'header Authorization e scegli il formato con Accept. Parti dalla v1 per il documento completo o dalla v2 per il contenuto grezzo.
3. Gestisci cache ed errori
Rispetta ETag e Last-Modified, interpreta 304 come conferma, gestisci 429 con Retry-After e registra il request id delle risposte non 2xx.
4. Reagisci agli eventi
Configura un webhook per gli eventi che ti interessano, verifica la firma HMAC e rispondi rapidamente. La coda ritenta gli errori temporanei.
Qualità verificata. Le API, le chiavi, i webhook e le risposte condizionali sono coperti dalla suite di 326 test automatici: le integrazioni non sono un'aggiunta fragile, sono parte del prodotto.
Domande frequenti
API e webhook: le risposte rapide
Qual è la differenza tra REST v1 e REST v2?
La v1 restituisce Markdown puro con metadata e riassunto AI in un unico documento. La v2 separa il contenuto grezzo e negozia Markdown o HTML tramite header Accept, senza wrapper JSON.
Come vengono protette le chiavi API?
Ogni chiave è mostrata una sola volta, viene salvata solo come hash e possiede scope espliciti. Viaggia nell'header Authorization come Bearer token e può essere revocata in qualsiasi momento.
Come verifico che un webhook arrivi davvero da GEO Optimizer Pro?
Ogni consegna include una firma HMAC-SHA256 calcolata sul payload e un timestamp. Il ricevente ricalcola la firma con il proprio secret e rifiuta le richieste non valide o troppo vecchie.
Cosa succede se un webhook non risponde?
La consegna viene ritentata con backoff esponenziale e ogni endpoint ha un interruttore attivo o disattivo. Gli errori restano visibili nel pannello senza bloccare la coda principale.
A cosa servono ETag e Last-Modified?
Permettono al client di chiedere il contenuto solo se è cambiato. Se i dati sono identici, l'API risponde 304 senza corpo: meno banda, meno token e sincronizzazioni più rapide.
L'integrazione con Google Search Console richiede una password?
No. Il collegamento usa Google OAuth con scope di sola lettura. I token vengono cifrati e puoi revocare l'accesso dal pannello Integration Hub in qualsiasi momento.
Integra la GEO nei tuoi flussi
La tua piattaforma merita dati GEO, non screenshot.
30 giorni di prova gratis, 14 giorni money back e tutte le funzioni Pro incluse: REST v1 e v2, chiavi con scope, webhook firmati, Integration Hub e OAuth Google. Collega il sito e porta i dati dove lavori.
30 giorni di prova gratuita · 14 giorni money back · tutte le funzioni Pro incluse