דלג לתוכן הראשי

כתובת הייצור והבקשה הראשונה

היכנסו לאפליקציה בכתובת https://app.sorank.com. ניהול המפתחות נמצא בכתובת https://app.sorank.com/settings/api, ובסיס ה-REST הוא https://app.sorank.com/api/public/v1. אין צורך להקים שרת API.
  1. פתחו הגדרות → גישה ל-API וצרו מפתח עם שם, לפחות אתר אחד, הרשאת הצגת אתרים (profiles:read) ותאריך תפוגה. הוסיפו הצגת מכסות (quotas:read) עבור הבקשה השנייה.
  2. העתיקו מיד את המפתח המלא: הוא מוצג פעם אחת בלבד. הקידומת המוצגת לאחר מכן אינה מספיקה לאימות.
  3. בחרו דוגמה. ב-cURL הזינו את המפתח כשתתבקשו. ב-JavaScript או Go הגדירו SORANK_API_KEY בסביבת תהליך השרת. בלשונית HTML מופיע גם שרת Node.js מקומי: הפעילו אותו כשהמפתח בסביבתו ופתחו http://127.0.0.1:3100. לעולם אל תכניסו את המפתח ל-HTML או ל-JavaScript בדפדפן. הוסיפו את אימות האפליקציה שלכם לפני שימוש בדוגמה מחוץ להדגמה מקומית.
התשובה מכילה את האתרים המורשים ב-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 או קטגוריה.
קבוצת ההפניות של ה-API הציבורי מתארת כל פעולה, שדה, תשובה ושגיאה.

מעקב וניסיון חוזר

כל שינוי דורש 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: הגישה נחסמת עד שמצב ההרשאה מתאושש; נסו שוב מאוחר יותר.
העיון ב-API הציבורי מפרט את הקודים של כל פעולה. שתפו עם התמיכה את code ואת request_id, לעולם לא את האסימון. לחיבור עוזר, עיינו במדריך MCP.