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.
Il contratto 1.2 aggiunge permessi che le chiavi e le connessioni esistenti non hanno: Ricerca e genera parole chiave (keywords:generate), Visualizza miglioramenti (audit:read), Avvia analisi e correggi articoli (audit:write), Aggiorna prodotti (products:write), Modifica prompt di visibilità IA (geo:write), Visualizza backlink (backlinks:read), Gestisci backlink e missioni (backlinks:write) e Visualizza fatture (billing:read). Crea una nuova chiave o ricollega l’applicazione per concederli. La ricerca di parole chiave e le correzioni degli articoli spendono i crediti IA del sito, non la quota di articoli: getQuotas restituisce il saldo e il prezzo attuale di ogni azione in ai_credits.
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.
Cercare parole chiave, correggere articoli e gestire il resto
Queste operazioni fanno ciò che fanno le schermate corrispondenti di Sorank, con gli stessi limiti e gli stessi prezzi in crediti IA.- Parole chiave (
keywords:generate):researchKeywordsegetKeywordMetricsrestituiscono parole chiave con volume, difficoltà, CPC e intento, come il chat SEO.generateKeywordsavvia una ricerca completa di parole chiave (202); seguila congetKeywordRun(keywords:read). - Miglioramenti (
audit:read,audit:write):getAuditelistAuditPagesrestituiscono l’ultima analisi e le pagine da correggere.estimateAuditFixescalcola il prezzo di una pagina o di tutto il sito senza addebitare nulla.fixAuditPageprepara correzioni o una riscrittura,applyAuditFixscrive una correzione sul tuo CMS erestoreAuditFixripristina la versione precedente (entrambe richiedono anchearticles:publish).fixAuditBulkcorregge tutto il sito (richiede anchearticles:generateearticles:publish).startAuditavvia una nuova analisi. - Prodotti (
products:write):refreshProductCataloganalizza di nuovo il tuo negozio, con lo stesso tempo di attesa dell’app (429 rate_limitedconRetry-After). - Indicizzazione Google (
articles:read):getArticleIndexStatusrestituisce lo stato di indicizzazione che Sorank conosce già per un articolo pubblicato. - Prompt di visibilità IA (
geo:read,geo:write):listGeoPrompts,createGeoPrompts,updateGeoPromptedeleteGeoPrompts, entro il limite di prompt del tuo piano (prompt_limit_exceeded). - Backlink (
backlinks:read,backlinks:write):getBacklinkselistBacklinkQuestsrestituiscono le impostazioni della rete, i tuoi crediti e le missioni.updateBacklinkSettingsattiva o disattiva la rete, eclaimBacklinkQuestinvia la prova di una missione per la verifica. - Fatture (
billing:read):listInvoicesrestituisce le fatture dell’abbonamento di questo sito con un link al PDF.
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.
Su un sito Framer, getPublication restituisce anche site_deploy. Framer mostra una modifica solo dopo una pubblicazione del sito, che Sorank avvia circa un minuto dopo ogni modifica: pending indica che public_url non mostra ancora l’ultima modifica, e live che è online. Finché lo stato è pending, last_error_code indica l’errore dell’ultimo deploy non riuscito, ad esempio cms_token_expired quando la chiave API di Framer va sostituita.
Quando una pubblicazione non riesce, getPublication restituisce status failed con last_error.code publication_failed. Se Sorank ha registrato la causa, last_error.reason la indica, ad esempio site_unreachable: Sorank non è riuscito a connettersi al sito, quindi verifica che sia online e che il suo hosting o il suo firewall non blocchino Sorank. Possono aggiungersi nuove cause: gestisci una causa sconosciuta come un errore generico.
Su un negozio PrestaShop collegato con una chiave Webservice, senza il modulo Sorank, updatePublishedArticle non può cambiare l’indirizzo di una pagina pubblicata. Se hai modificato lo slug dell’articolo, l’operazione termina in failed con publication_change_failed. Ripristina lo slug pubblicato oppure installa il modulo Sorank sul negozio.
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.402 insufficient_credits: il saldo di crediti IA non copre l’azione;details.requirededetails.balanceindicano gli importi.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.503 service_unavailable: Sorank è temporaneamente non disponibile; attendiRetry-After, poi riprova una scrittura con la stessaIdempotency-Key.
code e request_id con il supporto, mai il tuo token.
Per collegare un assistente, leggi la guida MCP.
