לחבר AI ל-CRM: ה-Search API שלא מראה כמה מכסה נשארה

סוכן AI שמעדכן רשומות לקוחות ב-CRM לאט לאט עובד חלק - אבל אותו סוכן שמחפש רשומות (למשל "מצא את כל הלקוחות שפנו החודש") עלול להיתקע במגבלה שונה לגמרי, בלי אזהרה מוקדמת בתשובת ה-API עצמה.

מגבלות לפי תוכנית, לא אחידות

לפי HubSpot, אפליקציה פרטית (private app) בתוכנית Free או Starter מוגבלת ל-100 בקשות לכל 10 שניות ו-250,000 ביום. תוכנית Professional מקבלת 190 בקשות ל-10 שניות ו-625,000 ביום, ו-Enterprise מקבלת אותו קצב אבל עם תקרה יומית של מיליון. אפליקציה שמופצת לציבור (public OAuth app) מוגבלת יותר - 110 בקשות ל-10 שניות לכל חשבון שמתקין אותה, ללא אפשרות להגדיל את המכסה הזו.

Search API: כלל שונה, בלי חלונות ראווה

לפי אותו מקור, ל-CRM Search API יש מגבלות משלו - לפעמים מחמירות יותר מהמגבלה הכללית - וההבדל הקריטי: תשובות מנקודות הקצה של Search API לא כוללות את כותרות ה-rate-limit headers שקריאות רגילות כן מחזירות. המשמעות המעשית: אי אפשר "לראות" בקוד שלכם כמה מכסת חיפוש נשארה לפני שהיא נגמרת - צריך לעקוב אחרי זה בעצמכם, בקוד, ולא לסמוך על מידע שה-API יחזיר.

הפתרון המעשי הוא לבנות בעצמכם (או לבקש מהמפתח שמקים את האינטגרציה) מנגנון ספירה פשוט: שומרים מתי כל קריאת חיפוש נשלחה, ולפני כל קריאה חדשה בודקים כמה קריאות כבר יצאו בשנייה האחרונה - אם הגענו לתקרה (למשל 3, כדי להישאר בבטחון מתחת למגבלה), פשוט ממתינים רגע לפני שממשיכים. מעקב עצמאי כזה קריטי דווקא כי אין מידע חוזר מה-API עצמו לגבי Search - בניגוד לרוב הקריאות שכן מחזירות מידע על המכסה הנותרת.

איך AI נכנס לתמונה בפועל

תרחיש נפוץ: סוכן AI שמעשיר רשומות לקוח - קורא רשומה, שולח את התוכן שלה למודל לניתוח (למשל סיווג רמת עניין או זיהוי הזדמנות מכירה), וכותב את התוצאה בחזרה לשדה מותאם ב-CRM. שני חלקי הזרימה הזו נתונים למגבלות שונות: הקריאה הראשונית (רשימת רשומות) עלולה לעבור דרך Search API עם המגבלות המחמירות והבלתי-נראות, בעוד העדכון עצמו (קריאה רגילה) כן מחזיר מידע על המכסה שנותרה.

מקרה קצה: שדה מותאם שה-AI ממלא לא קיים עדיין

סוכן AI שמנסה לכתוב תוצאת ניתוח לשדה מותאם (custom property) שעדיין לא נוצר ב-CRM נכשל בשקט או מחזיר שגיאה לא ברורה, תלוי בהגדרות. לפני שמריצים סוכן שכותב לשדות מותאמים, צריך לוודא שהשדות האלה כבר קיימים בסכימת ה-CRM - חלק שקל לפספס כשמפתחים את האינטגרציה מול חשבון בדיקה שבו השדות כבר הוגדרו ידנית, ואז שוכחים ליצור אותם באותו האופן בסביבת הפרודקשן.

דוגמה מספרית: העשרת 2,000 לידים

עסק על תוכנית Professional (625,000 בקשות ביום, 190 ל-10 שניות) שרוצה להעשיר 2,000 לידים - קריאה, ניתוח AI, כתיבה - צריך כ-4,000 קריאות API בסך הכל (קריאה וכתיבה לכל ליד). זה רחוק מאוד מהתקרה היומית, אבל אם הקוד לא מפזר את הבקשות ומנסה לרוץ במקביל מלא, הוא יחצה את מגבלת ה-190 ל-10 שניות תוך פחות מדקה. הפתרון: להריץ עם concurrency מוגבל (למשל 15-20 בקשות במקביל, לא אלפים) ולתת ל-HubSpot SDK הרשמי לטפל ב-retry אוטומטי כשמקבלים 429 - לא לבנות retry ידני שמנחש כמה לחכות.

אפליקציה פרטית מול ציבורית: ההבדל שקובע כמה אפשר להגדיל

אם אתם בונים את האינטגרציה כאפליקציה פרטית (private app) לשימוש פנימי בעסק שלכם, יש אפשרות לרכוש תוספת "API Limit Increase" שמעלה את המגבלה עד 250 בקשות ל-10 שניות ומיליון ביום. אבל אם בונים אפליקציה שמופצת בשוק (public OAuth app) להתקנה אצל לקוחות אחרים, המגבלה של 110 בקשות ל-10 שניות לכל חשבון מתקין קבועה - תוספת ההגדלה לא חלה על אפליקציות ציבוריות בכלל. ההבדל הזה משפיע ישירות על ארכיטקטורת הסוכן: אינטגרציה פנימית יכולה להרשות לעצמה עיבוד אגרסיבי יותר, בעוד מוצר שמותקן אצל לקוחות רבים חייב לתכנן קצב שמתאים למגבלה הקבועה מלכתחילה.

מה לנסות עכשיו

לבדוק מראש איזו תוכנית HubSpot פעילה ומה המגבלה היומית שלה, ולתכנן את קצב הפעולות של הסוכן בהתאם - במיוחד אם חלק מהפעולות עוברות דרך Search API, ששם אין לכם את חלון הראווה של headers שמראים כמה מכסה נשארה. ואם האינטגרציה מיועדת להפצה ציבורית ולא רק לשימוש פנימי, לתכנן מלכתחילה סביב המגבלה הקבועה של 110 בקשות ל-10 שניות, ולא לבנות על הנחה שאפשר יהיה להגדיל אותה בהמשך.