כתובת הייצור והבקשה הראשונה
היכנסו לאפליקציה בכתובתhttps://app.sorank.com. ניהול המפתחות נמצא בכתובת https://app.sorank.com/settings/api, ובסיס ה-REST הוא https://app.sorank.com/api/public/v1. אין צורך להקים שרת API.
- פתחו הגדרות → גישה ל-API וצרו מפתח עם שם, לפחות אתר אחד, הרשאת הצגת אתרים (
profiles:read) ותאריך תפוגה. הוסיפו הצגת מכסות (quotas:read) עבור הבקשה השנייה. - העתיקו מיד את המפתח המלא: הוא מוצג פעם אחת בלבד. הקידומת המוצגת לאחר מכן אינה מספיקה לאימות.
- בחרו דוגמה. ב-cURL הזינו את המפתח כשתתבקשו. ב-JavaScript או Go הגדירו
SORANK_API_KEYבסביבת תהליך השרת. בלשונית HTML מופיע גם שרת Node.js מקומי: הפעילו אותו כשהמפתח בסביבתו ופתחוhttp://127.0.0.1:3100. לעולם אל תכניסו את המפתח ל-HTML או ל-JavaScript בדפדפן. הוסיפו את אימות האפליקציה שלכם לפני שימוש בדוגמה מחוץ להדגמה מקומית.
- cURL
- HTML
- JavaScript
- Go
data. השתמשו בערך data[].id בתור profile_id לבקשות נוספות. אם הרשימה ריקה, בדקו את בחירת האתרים ואת ההרשאות שלכם. דוגמאות cURL, JavaScript ו-Go קוראות גם את מכסת הפרופיל הראשון עם quotas:read.
מפרט ה-API הציבורי בניווט למפתחים מציג נתיבים, הרשאות נדרשות ותשובות.
אימות
צרו מפתח אישי ב-הגדרות → גישה ל-API עבור סקריפטים, או אשרו לקוח OAuth עם PKCE S256. הגבילו את הפרופילים וה-scopes לנדרש. שלחו את האסימון כ-Bearer. קובצי Cookie של הדפדפן ואסימוני Supabase אינם מתאימים ל-API הזה. לאפליקציה הפועלת בשם משתמש, התחילו ב-https://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 וב-https://app.sorank.com/.well-known/oauth-authorization-server. גלו את נקודות הקצה של OAuth, רשמו לקוח ציבורי לפי הצורך והשתמשו ב-authorization code עם PKCE S256, ההרשאות הדרושות והמשאב המדויק https://app.sorank.com/api/public/v1. אסימון OAuth המיועד ל-MCP אינו תקף ל-REST.
הרשאות ומכסה
בדקו אתgetQuotas לפני יצירה. הדוגמה דורשת profiles:read, quotas:read, calendar:read, calendar:write, articles:read, articles:generate ו-articles:publish. יצירת לוח שנה דורשת גם הרשאות יצירה ופרסום. האפליקציה, REST ו-MCP חולקים מכסה אחת; מפתחות נוספים אינם מגדילים אותה.
הרשאות הקריאה הצגת מוצרים (products:read), הצגת ניתוחים (analytics:read), הצגת נראות AI (geo:read) ו-הצגת הגדרות (settings:read) לעולם אינן צורכות מכסה. עריכת הגדרות (settings:write) משנה את אותן הגדרות כמו האפליקציה; העניקו אותה רק אם אינטגרציה צריכה לשנות אותן.
בדיקת זכאות
ה-API זמין לאחר שהשלמתם את תהליך ההצטרפות ב-Sorank ולאתר יש מנוי בתוקף. משתף פעולה של סוכנות משתמש במנוי של בעל האתר. Sorank בודקת זאת ביצירת מפתח או באישור חיבור OAuth, ושוב בכל בקשה.listProfilesמחזירה רק אתרים זכאים.- תהליך הצטרפות שלא הושלם מחזיר
403 onboarding_required. - אתר ללא מנוי בתוקף מחזיר
402 subscription_required, עםdetails.reason(paused,past_due,incompleteאוinactive) כשהוא ידוע.
קריאת מוצרים, ניתוחים, נראות AI והגדרות
קריאות אלה מחזירות את מה שאפליקציית Sorank מציגה לכם. הן לעולם אינן מפעילות ניתוח, סנכרון או יצירת תוכן.- מוצרים (
products:read):listProductsעוברת על קטלוג המוצרים עם סמן. לאחר409 product_catalog_cursor_stale, התחילו שוב מהעמוד הראשון. - ניתוחים (
analytics:read): ביצועים, שאילתות, עמודים, מדינות ומכשירים מ-Search Console, ותנועה מ-Google Analytics שמגיעה מעוזרי AI.startו-end(YYYY-MM-DD) הם חובה. כל קריאה פונה ל-Google בזמן אמת ומוגבלת בקצב נמוך יותר. חברו קודם את Google ב-Sorank; אחרת תקבלו409 gsc_not_connectedאו409 ga_not_connected, ו-403 google_access_lostאם הגישה אבדה. - נראות AI (
geo:read): סטטיסטיקות GEO, התפתחות האזכורים, ציר הזמן של הציטוטים, המקורות המצטטים והמתחרים שצוטטו בניתוח. - הגדרות (
settings:read):getSettingsמחזירה את האתר, את תקציר העסק עם ה-revisionשלו, את המתחרים, את ברירות המחדל של המאמרים, את הוויזואליים ואת ערוץ YouTube.
שינוי הגדרות
עםsettings:write אפשר לשנות את שם העסק, צבע המותג והשוק, להחליף את תקציר העסק ואת רשימת המתחרים, לשנות את ברירות המחדל של מאמרי לוח השנה, את מצב התמונות ואת תמונות השער, ולחבר, להשהות או לנתק את ערוץ YouTube. לא ניתן לשנות את כתובת האתר דרך ה-API (400 field_not_writable).
כל שינוי דורש Idempotency-Key. התגובה כוללת את ההגדרות שהתקבלו, קבלה ורשימת effects של התהליכים שהופעלו ברקע, כמו באפליקציה: geo_questions_regeneration_queued, backlink_refresh_queued, calendar_slots_shifted, image_gallery_analysis_queued, youtube_sync_queued או youtube_purge_queued.
כדי להחליף את תקציר העסק, שלחו את expected_revision שנקרא מ-getSettings. אם התקציר השתנה בינתיים, תקבלו 409 business_brief_revision_conflict: קראו שוב את ההגדרות לפני ניסיון חוזר.
תרחיש REST מלא
דוגמה מתקדמת זו יוצרת תוכן ועלולה לנצל מכסה. החליפו את המזהים, התאריכים העתידיים, מפתחות האידמפוטנטיות והאישור לדוגמה לפני ההרצה. התאריכים בלוח השנה משתמשים באזור הזמן IANA שצוין. בדקו אתgetCapabilities לפני בחירת יעד CMS או קטגוריה.
מעקב וניסיון חוזר
כל שינוי דורשIdempotency-Key ייחודי. השתמשו באותו מפתח כשאתם חוזרים על אותה פקודה. קראו את data.receipt.operation_id ובדקו את getOperation עד succeeded, failed או verification_pending. קבלה שהתקבלה אינה אומרת שהפרסום הושלם. אצוות יצירת מאמרים מחזירה 202 עם קבלה שכבר במצב succeeded; עקבו אחר כל מאמר שמופיע ב-selection.accepted_ids באמצעות getArticle. ההרשאה נבדקת בכל בדיקה, כך שביטול גישה נכנס לתוקף מיד.
טיפול בשגיאות
לכל שגיאה אותו מבנה ב-REST וב-MCP:{"error": {"code", "message", "request_id", "retryable", "details"}}. בססו את הלוגיקה על code ולא על ההודעה. נסו שוב רק כאשר retryable הוא true, לאחר Retry-After כשהוא קיים.
401 invalid_credential: אישור גישה לא תקין, שפג תוקפו או שבוטל.403 missing_scopeאו403 onboarding_required;402 subscription_requiredאו402 insufficient_quota.404 not_found: המשאב אינו קיים או אינו נגיש לאישור הגישה הזה.409: התנגשות כגוןidempotency_conflict;429 rate_limited: המתינו ל-Retry-After.503 auth_state_unavailable: הגישה נחסמת עד שמצב ההרשאה מתאושש; נסו שוב מאוחר יותר.
code ואת request_id, לעולם לא את האסימון.
לחיבור עוזר, עיינו במדריך MCP.
