Indirizzo di produzione e prima chiamata
Accedi all’app suhttps://app.sorank.com. Gestisci le chiavi su https://app.sorank.com/settings/api e invia le richieste a https://app.sorank.com/api/public/v1. Non devi creare un server API.
- Apri Impostazioni → Accesso API e crea una chiave con nome, almeno un sito, Visualizza siti (
profiles:read) e scadenza. Aggiungi Visualizza quote (quotas:read) per la seconda chiamata. - Copia subito la chiave completa: viene mostrata una sola volta. Il prefisso visibile in seguito non autentica le richieste.
- Scegli un esempio. Con cURL, inserisci la chiave quando richiesto. Per JavaScript o Go, imposta
SORANK_API_KEYnell’ambiente del processo server. La scheda HTML include un server Node.js locale: avvialo con la chiave nell’ambiente e aprihttp://127.0.0.1:3100. Non inserire mai la chiave nell’HTML o nel JavaScript del browser. Aggiungi l’autenticazione della tua app prima di usare questo schema oltre la demo locale.
- cURL
- HTML
- JavaScript
- Go
data. Usa un valore data[].id come profile_id nelle chiamate successive. Se l’elenco è vuoto, verifica la selezione dei siti e i tuoi permessi. Gli esempi cURL, JavaScript e Go leggono anche la quota del primo profilo con quotas:read.
La Riferimento API pubblica nella navigazione sviluppatori descrive percorsi, scope e risposte.
Autenticarsi
Crea una chiave personale in Impostazioni → Accesso API per gli script oppure autorizza un client OAuth con PKCE S256. Limita profili e scope al necessario. Invia il token come Bearer. Cookie del browser e token Supabase non autorizzano questa API. Per un’applicazione che agisce per conto dell’utente, inizia dahttps://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 e https://app.sorank.com/.well-known/oauth-authorization-server. Scopri gli endpoint OAuth annunciati, registra un client pubblico se necessario e usa authorization code con PKCE S256, gli scope necessari e la risorsa esatta https://app.sorank.com/api/public/v1. Un token OAuth MCP non vale per REST.
Permessi e quota
ControllagetQuotas prima della generazione. L’esempio richiede profiles:read, quotas:read, calendar:read, calendar:write, articles:read, articles:generate e articles:publish. La creazione del calendario richiede anche i permessi di generazione e pubblicazione. App, REST e MCP condividono la quota; altre chiavi non la aumentano.
I permessi di lettura Visualizzare i prodotti (products:read), Visualizzare le analisi (analytics:read), Visualizza visibilità IA (geo:read) e Visualizzare le impostazioni (settings:read) non consumano mai quota. Modificare le impostazioni (settings:write) modifica le stesse impostazioni dell’app; concedilo solo se un’integrazione deve cambiarle.
Verificare l’idoneità
L’API è disponibile dopo aver completato l’onboarding in Sorank e se il sito ha un abbonamento valido. Un collaboratore di agenzia usa l’abbonamento del proprietario del sito. Sorank lo verifica alla creazione di una chiave o all’approvazione di una connessione OAuth, e di nuovo a ogni richiesta.listProfilesrestituisce solo i siti idonei.- Un onboarding non completato restituisce
403 onboarding_required. - Un sito senza abbonamento valido restituisce
402 subscription_required, condetails.reason(paused,past_due,incompleteoinactive) quando noto.
Leggere prodotti, analisi, visibilità IA e impostazioni
Queste letture restituiscono ciò che l’app Sorank ti mostra. Non avviano mai un’analisi, una sincronizzazione o una generazione.- Prodotti (
products:read):listProductsscorre il catalogo prodotti con un cursore. Dopo409 product_catalog_cursor_stale, ricomincia dalla prima pagina. - Analisi (
analytics:read): prestazioni, query, pagine, paesi e dispositivi di Search Console, e traffico Google Analytics proveniente da assistenti IA.starteend(YYYY-MM-DD) sono obbligatori. Ogni chiamata legge Google in tempo reale e ha un limite di frequenza più basso. Collega prima Google in Sorank; altrimenti ricevi409 gsc_not_connectedo409 ga_not_connected, e403 google_access_lostse l’accesso è stato perso. - Visibilità IA (
geo:read): statistiche GEO, evoluzione delle menzioni, cronologia delle citazioni, fonti che citano il sito e concorrenti citati in un’analisi. - Impostazioni (
settings:read):getSettingsrestituisce il sito, il brief aziendale con la suarevision, i concorrenti, le impostazioni predefinite degli articoli, le immagini e il canale YouTube.
Modificare le impostazioni
Consettings:write puoi modificare il nome dell’azienda, il colore del brand e il mercato, sostituire il brief aziendale e l’elenco dei concorrenti, cambiare le impostazioni predefinite degli articoli del calendario, la modalità immagini e le copertine, e collegare, sospendere o scollegare il canale YouTube. L’URL del sito non può essere modificato tramite l’API (400 field_not_writable).
Ogni modifica richiede un Idempotency-Key. La risposta contiene le impostazioni risultanti, una ricevuta e un elenco effects con le attività avviate in background, come nell’app: geo_questions_regeneration_queued, backlink_refresh_queued, calendar_slots_shifted, image_gallery_analysis_queued, youtube_sync_queued o youtube_purge_queued.
Per sostituire il brief aziendale, invia la expected_revision letta da getSettings. Se nel frattempo il brief è cambiato, ricevi 409 business_brief_revision_conflict: rileggi le impostazioni prima di riprovare.
Provare un flusso REST completo
Questo esempio avanzato crea contenuti e può consumare quota. Sostituisci ID, date future, chiavi di idempotenza e credenziale di esempio prima di eseguirlo. Le date del calendario seguono il fuso IANA indicato. ControllagetCapabilities prima di scegliere destinazione o categoria CMS.
Monitorare e riprovare
Ogni modifica richiede unIdempotency-Key univoco. Riutilizza la stessa chiave per ripetere lo stesso comando. Leggi data.receipt.operation_id e interroga getOperation fino a succeeded, failed o verification_pending. Una ricevuta accettata non significa che la pubblicazione sia completata. Un lotto di generazione di articoli restituisce 202 con una ricevuta già succeeded; segui ogni articolo elencato in selection.accepted_ids con getArticle. L’autorizzazione viene verificata a ogni interrogazione, quindi una revoca ha effetto immediato.
Gestire gli errori
Ogni errore ha la stessa forma in REST e MCP:{"error": {"code", "message", "request_id", "retryable", "details"}}. Basa la tua logica su code, non sul messaggio. Riprova solo se retryable è true, dopo Retry-After quando presente.
401 invalid_credential: credenziale non valida, scaduta o revocata.403 missing_scopeo403 onboarding_required;402 subscription_requiredo402 insufficient_quota.404 not_found: la risorsa non esiste o non è accessibile con questa credenziale.409: un conflitto comeidempotency_conflict;429 rate_limited: attendiRetry-After.503 auth_state_unavailable: l’accesso resta negato finché lo stato di autorizzazione non torna disponibile; riprova più tardi.
code e request_id con il supporto, mai il tuo token.
Per collegare un assistente, leggi la guida MCP.
