מסמך מקור מתקדם. דפי ההתקנה, פרוטוקול ההפעלה וששת הסקילים זמינים לקריאה בעברית; קובץ המקור נשמר כפי שהוא.

שני מסלולי Meta מושהים — חוזה ביצוע מקומי

24.10.2026. קובץ yskit/campaign_routes_v3.py הוא מדיניות וקוד תיאום מקומי, לא מחבר Meta פעיל. הקוד הקיים approval_v2.py נשאר לחוזה ההדמיה הישן של Instant Form. אין לשדרג אישורי V1/V2 למסלול V3 בשקט.

חוזי המסלולים

• website: מקור האתר, URL תקין ב־HTTPS, פרויקט/טבלה/טופס של מקור הליד, dataset ואירוע Lead. אין form_id של Meta.
• meta_instant_form: מזהה טופס Meta בבעלות הדף, תנאי Lead Ads שהתקבלו ואומתו, ויכולת נתיב native. אין שדות מקור אתר.
• בשניהם: tenant, חשבון, Page, גרסת פרופיל, run ID, תקציב יומי מפורש ב־ILS ביחידות מטבע קטנות, מיקום תקציב, hash של נכסי הקריאייטיב ו־PAUSED בקמפיין, ב־adset ובמודעה. התזמון מוצג במפורש כ־not_scheduled עם אזור זמן החשבון ותאריכי התחלה/סיום לא מוגדרים; יצירה כזו אפשרית רק אם בדיקת יכולת החשבון מאשרת זאת, והיא אינה אישור להפעלה ללא מועד סיום. אין בחבילה סכום תקציב מאושר או ברירת מחדל. תקציב כולל/לכל החיים אינו נתמך בחוזה הביצוע הזה ואין להמירו ליומי בלי החלטה.

preflight חייב להכיל תצפית מתוארכת, valid_until שנקבע לפי מקור הראיה, וגרסת API, זהות חשבון/דף/מקור, בעלות מקור, תמיכת objective ו־conversion location, מטבע, יחידות תקציב, מינימום ומיקום תקציב נתמך. הוא נקשר ל־hash של מפרט האישור. אין זמן תוקף אוניברסלי: הבעלים של המחבר המוגן קובע ומאמת את חלון התוקף והטריגרים לרענון לפי מקור ושינוי מהותי. זהו מבנה ראיה, לא ראיה ש־Meta אומתה: adapter וה־verifier המוגנים חייבים להביא ולאמת אותה. לפני כל שליחת שלב מופעל fresh_readcheck ממוקד של מקור, אירוע, מטבע, יחידות ומינימום, אזור זמן, גרסת API ותאימות המפרט. שינוי מקור, טופס, dataset, creative או תקציב משנה את digest ודורש אישור מתאים. הקוד אינו ממציא מינימום, גרסת API או תמיכת חשבון.

אישור, ביצוע וכשל

authorize_route מקבל טענות מאומתות בלבד מ־verifier.verify; אין signer או מפתח בחבילה. ב־customer-pilot הוא דוחה verifier שמסומן test_only. תצוגת האישור כוללת מסלול, מקור, מזהים, תקציב, נכסים, digest המפרט וה־preflight, ו־PAUSED. אישור למסלול אחד לא מועבר לאחר. חידוש ריצה אחרי יצירה חלקית דורש פעולה resume_own_paused_run, רשימת stage IDs שנוצרו באותה ריצה ונשמרו ביומן, חתימת אישור חדשה ו־readback לפני כל המשך. אין שינוי או ניקוי של קמפיינים היסטוריים.

PausedRouteRunner דורש RouteMetaPort ו־StageJournal מוזרקים. SQLiteStageJournal מספק יומן מקומי עמיד בקובץ SQLite עם WAL ו־FULL sync והרשאת קובץ לבעלים בלבד. היומן קשור ל־tenant, חשבון, מסלול, מזהה ריצה ו־digest מפרט. כל שלב campaign → adset → creative → ad נשמר טרנזקציונית לפני שליחה; מזהה מרוחק נשמר מיד כשחזר, ואישור השלב שומר digest של ה־readback הגולמי, סטטוס והורים. פתיחה חוזרת אחרי קריסה משמרת prepared/uncertain ומונעת שיגור חוזר; שתי ריצות אינן יכולות להכניס אותו שלב פעמיים. אחרי timeout או תוצאה עמומה הסטטוס נשאר uncertain ואין ניסיון יצירה חוזר. reconcile יכול לאשר רק מציאה חיובית יחידה ו־readback של מזהה, מקור, הורה, מפרט וסטטוס. קריאה ריקה אינה הוכחת ביטול. אין ממשק הפעלה. תצוגת מיקומים מסומנת לא מאומתת גם כשה־readback עובר. ה־provider adapter חייב למפות יחסי הורה לפי סמנטיקת Meta האמיתית; יחסי השלבים בקוד הם גבול תיאום, לא טענה על Graph API.

הקובץ המקומי אינו חסין בפני תהליך שפועל עם אותה הרשאת מערכת ואינו תחליף למאמת אישורים המבודד מן הסוכן. נדרש נתיב מוחלט; המעטפת המוגנת צריכה לאכוף תיקייה פרטית צפויה, לזהות בלעדית את run_id ואת נתיב היומן בכל התהליכים ולא לאפשר פתיחת קובץ חדש לאותה ריצה. אחרת אפשר לעקוף את היסטוריית הכפילויות המקומית באמצעות קובץ אחר. שים אותו בדיסק מתמשך ומוגן מחוץ לקבצים שהסוכן רשאי לערוך, עם גיבוי ותפעול אחראי לפני שימוש חי. אין כאן מריץ רקע, סנכרון ענן או הגנה מפני מנהל מערכת עוין. SQLite מגן על מעבר מצב יחיד בתוך אותו קובץ בין תהליכים מקומיים, ואינו מוכיח שהשליחה המרוחקת הייתה יחידה; זו הסיבה שמצב ambiguous מחייב פיוס חיובי.

ראיית תנאים ונקודת בעלים

מקור ההסכם הרשמי: Meta Lead Ads Terms; כניסה לקבלתו: Meta Leadgen acceptance. בעל הרשאה בודק את התנאים עבור הדף המדויק ומקבל אותם אם בחר במסלול הטופס המובנה. שדה leadgen_tos_accepted=false שמחזיר מחבר עשוי להיות לא מכריע; אין לעקוף אותו או להסיק ממנו קבלה. פותרים אי־התאמה באמצעות ראיה עצמאית מורשית, ובודקים בנפרד הרשאות, Leads Access ויכולת נתיב הכתיבה לפני פעולה ב־native.

מה עבר ומה נותר

tests/test_campaign_routes_v3.py ו־tests/test_campaign_journal_v3.py בודקים בחוזים מדומים שתי דרכים, פיצול אישורים, חשבון/מקור/תקציב/נכסים שגויים, preflight, הרשאה חסרה, PAUSED, כשל שליחה, readback, פיוס וחידוש מדויק גם אחרי פתיחת מסד חדש. זוהי בדיקה לא־רשתית בלבד. אין בחבילה כעת RouteMetaPort חי, יומן במיקום מוגן לפריסה, verifier חיצוני, בדיקת מקור בזמן אמת או תצוגת מיקומים. יצירה בחשבון לקוח, בדיקת שני המקורות, ליד בדיקה, הפעלה, הוצאה ומדידת תוצאות לא נבדקו בקוד זה. אין להשתמש ב־fake verifier מהבדיקות בלקוח חי.