החיבור של גלי.
המיפוי כבר בפנים.

מה כבר הוגדר עבורך

איש קשר: שם פרטי, שם משפחה ואימייל מתוך donor; שלושה שדות מותאמים; תגית Donorbox | {campaign}; שיוך למשתמש Ayelet Hanina במזהה cCJGpKcZCJnu3VL6MRFk; Pipeline בשם Donorbox ושלב Donations; הזדמנות בסטטוס Won; חמישה שדות מותאמים להזדמנות. פירוט מדויק בהמשך.

לא נדרשת הקמת חשבון Donorbox חדש. הוסף כתובת וובהוק בחשבון הקיים. הגשר אינו מפעיל את טריגר ה־Inbound Webhook של GHL ואינו קורא ל־/opportunities/upsert. הוא מחפש הזדמנות ואז משתמש ב־POST /opportunities/ או PUT /opportunities/{id}, עם Version: v3.

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

1. העלאה והתקנה בהוסטינגר

1. צור סאב־דומיין ייעודי והפעל SSL, לדוגמה bridge.your-domain.com. אפשר גם תיקייה ייעודית באתר קיים.
2. בחר PHP 8.3. נתמכת גרסה 8.1 ומעלה. ודא שקיימות ההרחבות pdo_sqlite, curl, openssl ו־mbstring. מסך ההתקנה בודק אותן. אין צורך ב־MySQL, Composer, Node או WordPress.
3. העלה את תוכן התיקייה donorbox-ghl-bridge לתיקיית האתר, כולל קובצי .htaccess שבתיקייה הראשית ובתיקיות הפנימיות. בתיקייה נפרדת תחת WordPress אין לדרוס את .htaccess הראשי של WordPress.
4. ערוך במנהל הקבצים את install-key.php. החלף רק את הטקסט שבתוך המירכאות במחרוזת אקראית פרטית שלך, 32 תווים לפחות.
5. פתח https://YOUR-DOMAIN/setup.php. הזן את מפתח ההתקנה, בחר שם משתמש וסיסמה באורך 14 תווים לפחות והשלם התקנה.
6. ההתקנה שומרת מסד נתונים, מפתח הצפנה ו־Sessions בתיקייה פרטית בשם zd-donorbox-... מחוץ ל־Document Root. config.php מכיל רק את הנתיב. אם אין הרשאת יצירה שם, פנה לתמיכה להגדרת תיקייה פרטית מתאימה; אין להעביר את הנתונים לתיקייה ציבורית כפתרון.
7. היכנס למערכת והשאר קליטה בלבד. לאחר ההתקנה אפשר למחוק setup.php ו־install-key.php.

טוקן, סוד חתימה ו־payload מקורי נשמרים בהצפנת AES-256-GCM. המפתח והמסד נמצאים מחוץ לתיקייה הציבורית. שמור גיבוי שלהם יחד. טופסי הסודות נשארים ריקים לאחר שמירה; ריק פירושו שמירת הערך הקיים. ההצפנה אינה מבודדת מפני מי שכבר שולט בכל חשבון האחסון.

2. Private Integration ב־GHL

1. בתת החשבון של גלי, עבור אל Settings → Private Integrations וצור חיבור בשם Donorbox Direct Bridge.
2. בחר את ההרשאות הבאות:

contacts.readonly
contacts.write
opportunities.readonly
opportunities.write
locations/customFields.readonly
locations.readonly
users.readonly

קריאת אנשי הקשר וההזדמנויות משמשת לאימות לאחר כתיבה; קריאת השדות לזיהוי המזהים; קריאת Location לקבלת אזור זמן; קריאת Users לאימות המשתמש המשויך. אין צורך בהרשאות Workflows, שליחת הודעות או יצירת Custom Fields.

העתק את הטוקן המלא ואת Location ID של תת החשבון לממשק הגשר ושמור במצב קליטה בלבד. Location ID אינו Agency ID; הוא מופיע לרוב בכתובת GHL אחרי /location/.

3. טעינת היעדים והמיפוי בלחיצה

1. פתח ״הגדרות החיבור״, הזן Token ו־Location ID ושמור.
2. לחץ ״טעינת ואימות המיפוי מ־GHL״. המערכת טוענת Pipelines, שלבי Pipeline, קטלוג שדות איש קשר, קטלוג שדות הזדמנות, פרטי משתמש ואזור זמן. הקריאות החיצוניות הן לקריאה בלבד.
3. ודא שנמצאו Donorbox → Donations ושכל שמונת השדות בטבלת המיפוי נבחרו. במקרה של כמה שדות באותו שם, בחר את השדה הנכון ברשימה, שמור ולחץ שוב על טעינת המיפוי. גם אם השם לא זהה, אפשר לבחור במפורש שדה קיים מאותו סוג רשומה.
4. מלא Wait בשניות לפי ה־Workflow הקיים, וסמן שהשלמת אותו. ניתן לבחור 0 אם מעוניינים לבטל את ההמתנה. ערך זה אינו מוסק מהצילומים.
5. בדוק שאזור הזמן שנקרא מ־GHL מתאים לתת החשבון. הוא ישמש לשדות Current date, גם סמוך לחצות.
6. אל תבחר מצב פעיל עד להשלמת הגדרת Donorbox, Cron ובדיקת המיפוי.

טעינת מיפוי מחדש נעשית במצב קליטה בלבד. לאחר טעינה יש לבדוק ולאשר מחדש את הגדרות הפלואו. בעת הפעלה חיה המערכת מאמתת שוב את היעדים מול החשבון.

4. המיפוי המדויק שהוכן

לפי המיפוי שסופק, טלפון ושדה שם מלא אינם נשלחים כברירת מחדל. ניתן להפעיל אותם כהרחבה בממשק. אין שינוי אוטומטי ב־DND, הסכמה שיווקית, Contact Source או בשדות רגילים אחרים שלא הוגדרו בפלואו.

בדוגמה שסופקה amount הוא 131.5 USD, לעומת net_amount בסך 125.09 USD. ההזדמנות ושדות Donation Amount / DON Amount מקבלים 131.5. זה כולל את מה שכבר נכלל בשדה המקור, ללא חישוב עמלה נוסף בצד הגשר.

תגית דינמית נוצרת לכל תרומה. פסיק בשם הקמפיין נשאר חלק מאותה תגית. GHL עשוי לשמור תגיות באותיות קטנות; האימות מקבל שינוי רישיות זה.

התנהגות הזדמנויות חוזרות

Allow duplicate opportunities מוגדר כבוי לפי הצילום: הגשר מחפש לפי Contact ID ו־Pipeline. הזדמנות קיימת אחת מתעדכנת; כשאין התאמה נוצרת חדשה. יותר מהתאמה אחת עוצרת את האירוע לבדיקה. תרומה נוספת של אותו תורם מעדכנת את השווי לתרומה האחרונה שעובדה; אין צבירה אוטומטית.

Allow opportunity to move to any previous stage כבוי. אם הזדמנות כבר נמצאת בשלב מתקדם יותר מ־Donations, הגשר מעדכן את יתר השדות ושומר את השלב המתקדם. סדר השלבים מאומת מתוך Pipeline; אם אינו ניתן לאימות, האירוע נעצר. ניתן לשנות מדיניות זו במפורש בממשק.

תאריכים והמתנה

Current date מחושב אחרי ההמתנה, כאשר מגיע תור יצירת/עדכון ההזדמנות, ולא בעת קבלת הוובהוק. שני שדות התאריך מקבלים אותו תאריך באזור הזמן של תת החשבון. התאריך נשמר עם תוכנית האירוע ונשאר קבוע בניסיונות חוזרים של אותה פעולה.

5. בדיקת תאימות Opportunity Source

בצילומים מופיע מקור הזדמנות רגיל ששווה לשם הקמפיין. בתיעוד הרשמי הנוכחי של GHL, source מופיע בתוצאות קריאה אך אינו מופיע בין שדות סכמת הכתיבה של Create/Update Opportunity. לא ניתן לאשר את תמיכת הכתיבה בפועל בלי בדיקה בתת החשבון.

הגרסה שולחת את source ושאר השדות ומבצעת GET לאחר הכתיבה. אם GHL דוחה את הפרמטר או מתעלם ממנו, האירוע לא יסומן כהושלם. אם הכתיבה בוצעה והערך חסר בקריאה, המערכת תחזור רק על בדיקות הקריאה עד 3 פעמים, ולא תיצור הזדמנות נוספת. בפרטי האירוע יופיע source כשדה שלא נשמר.

האימות כולל גם שם, סטטוס, שווי, Pipeline, שלב, שיוך ושדות מותאמים. הצלחת HTTP בלבד אינה מספיקה כדי לסמן את האירוע כהושלם.

6. Donorbox: כתובת וובהוק חדשה

1. בחשבון Donorbox הקיים פתח Zapier & API → Custom Webhooks → Add new endpoint URL.
2. העתק את הכתובת שמופיעה בסקירת הגשר ומסתיימת ב־webhook.php.
3. בחר donation.created בלבד וגרסה v2. הגשר תומך גם ב־v1. אינו מטפל ב־donation.updated, בהחזרים או באירועי כרטיסים.
4. פתח את פרטי ה־Endpoint החדש והעתק את Signature Secret שלו. זה אינו ה־API Key ואינו הסוד של היעד הישן.
5. הדבק את הסוד בממשק הגשר ושמור. אין צורך במפתח API של Donorbox: הנתונים מגיעים בוובהוק.

כל בקשה חייבת לכלול כותרת Donorbox-Signature תקינה על הבתים המקוריים. חלון הזמן הוא דקה, כך ששעון השרת צריך להיות מסונכרן. הכותרות שהועתקו לתוך קובץ ה־JSON שהצגת ב־GHL אינן משמשות לאימות; נבדקת כותרת HTTP האמיתית של הבקשה החדשה.

בצילום המקורי הופיעה בקשת אימות אימייל ב־Donorbox. אם היא עדיין חוסמת שינוי הגדרות, השלם את האימות דרך בעלת החשבון.

הגשר אינו מושך נתוני עבר. רק donation.created במצב paid מעובד. מזהה התרומה מונע קליטה חוזרת של אותו אירוע גם אם נשלח שוב או הוחלפה גרסת וובהוק.

7. Cron כל דקה

1. ב־hPanel פתח Advanced → Cron Jobs ובחר פקודה מותאמת.
2. בחר כל דקה. חמשת שדות התזמון הם * * * * *.
3. העתק את הפקודה המדויקת מהסקירה. דוגמה בלבד:

/usr/bin/php /home/u123456789/domains/bridge.example.com/public_html/worker.php

בדוק ש־PHP CLI בגרסה 8.1+ ועם אותן הרחבות. גרסת PHP באתר וזו של Cron עשויות להיות שונות. הנתיב שמוצג בממשק הוא נתיב ההתקנה שלך. אין להעביר טוקן בשורת הפקודה. אם קיימת מגבלת אורך ב־hPanel, בחר תיקיית התקנה קצרה יותר.

השאר פלט Cron זמין בתחילת ההרצה. worker.php הוא CLI בלבד ופנייה אליו בדפדפן מחזירה 404. כפתור ״עיבוד התור כעת״ מאפשר בדיקה ידנית מתוך הניהול.

לוח הבקרה מציג מתי רץ העובד. אזהרה מופיעה אם לא נצפתה ריצה בחמש הדקות האחרונות. ההמתנה אינה מחזיקה בקשת HTTP פתוחה; היא מועד עתידי בתור. המשך העיבוד מתבצע בריצה הראשונה אחרי מועד זה, לרוב בתוספת של עד דקה בעומס רגיל.

8. מעבר לאוויר

1. שמור צילום של משך ה־Wait ושל הגדרות ה־Workflow. אל תמחק את החיבור הישן בשלב זה.
2. הפעל את היעד החדש ב־Donorbox כאשר הגשר במצב קליטה בלבד. בדוק שהאירועים מופיעים כמוחזקים ושהנתונים מתאימים.
3. בדוק במיפוי שכל שמונת מזהי השדות נטענו, ערכי הבחירה נמצאו ומשך ההמתנה הושלם. מסך בדיקת המיפוי מקומי בלבד ואינו שולח ל־GHL.
4. בצע את המעבר בזמן שקט; אם אפשר, השהה זמנית קליטת תרומות. כבה את יעד הוובהוק הישן ב־Donorbox ובדוק ריצות שכבר נמצאות בתוך Wait ב־GHL. כיבוי טריגר אינו בהכרח מפסיק ריצות קיימות.
5. לאחר שהמסלול הישן אינו מעבד עוד תרומות חדשות, בחר בגשר מצב פעיל וסמן שבדקת את המיפוי ואת Wait. ההפעלה מבצעת אימות נוסף של היעדים.
6. בצע תרומה מבוקרת חדשה אחרי שעת המעבר. בדוק שהאירוע הושלם ושכל השדות הרגילים והמותאמים נכונים ב־GHL, כולל Source, סטטוס Won, שיוך ותאריכים.
7. בדוק מסירה חוזרת של אותו אירוע לפי כלי Donorbox הזמין. לא אמורה להיקלט רשומת תרומה נוספת בגשר. בדוק גם תרומה חדשה מאותו תורם שמעדכנת הזדמנות אחת.

אם לא ניתן להשהות תרומות בזמן המעבר, רשום שעה ומזהי תרומות סביב המעבר והשווה בין מסירות Donorbox, ריצות GHL ויומן הגשר. שני היעדים אינם מספקים מעבר אטומי ביניהם.

9. עדכון מהגרסה הקודמת

1. אם טרם התקנת, השתמש רק ב־ZIP הזה והתקן כרגיל.
2. אם 1.0 כבר מותקנת, גבה את הקוד, config.php והתיקייה הפרטית. השאר את config.php ואת הנתונים במקומם. אל תריץ התקנה חדשה.
3. סיים תחילה אירועים שהתחילו לעבד בחיבור הישן של הגשר. העבר לקליטה בלבד, עצור Cron בזמן העלאה והחלף את קובצי הקוד. .htaccess וקובצי app מעודכנים גם הם.
4. פתח הגדרות ולחץ ״טעינת פרופיל גלי שסופק״. ההגדרות נשמרות בקליטה בלבד; טוקן וסוד קיימים נשמרים. הכפתור חסום כשיש אירועים בתהליך שכבר נוצר עבורם איש קשר.
5. לחץ על טעינת ואימות המיפוי, השלם Wait ובצע את בדיקת המעבר. הפעל שוב Cron.

אירוע שכבר התחיל מחזיק תוכנית עבודה קבועה משלו. עדכון קוד אינו משנה בשקט את המיפוי של אירועים קיימים. אירוע מוחזק שטרם התחיל משתמש במיפוי העדכני כאשר משחררים אותו.

10. תפעול ושחזור תקלות

429: כיבוד Retry-After בשניות או בתאריך HTTP והשהיה משותפת לקריאות API מקומיות. 5xx/רשת: ניסיון חוזר עם השהיה גדלה, עד 10 ניסיונות בשלב. אימות אחרי כתיבה: עד 3 ניסיונות קריאה, ואז עצירה לטיפול. 401/403: בדיקת טוקן והרשאות. 400/422: בדיקת מבנה שדות, מזהים ותאימות API.

כוונת יצירה נשמרת לפני POST של הזדמנות. אם התשובה אבדה, המערכת מחפשת את ההזדמנות במקום לשלוח שוב יצירה. אם התוצאה אינה ודאית ולא נמצאה התאמה, היא נעצרת לאחר ניסיונות. אישור יצירה מחדש זמין רק אחרי בדיקה ידנית ב־GHL שאין רשומה קיימת. אין הבטחת exactly-once מול שירות חיצוני; ההגנות מצמצמות כפילויות במצבי כשל.

Upsert של איש קשר, הוספת תגיות ועדכונים עשויים להישלח שוב אם תשובה אבדה. אוטומציות GHL אחרות עשויות להגיב לעדכונים אלה. קריאות האימות עצמן אינן מעדכנות רשומות.

הגשר מיועד לשרת יחיד עם אחסון מקומי. נעילות מונעות עובדים מקומיים חופפים. אין התראות אימייל מובנות; בדוק לוח בקרה ופלט Cron. אם אין אירועים חדשים, בדוק שהיעד פעיל ב־Donorbox וש־donation.created נבחר.

אבחון מהיר

• פתיחת webhook.php בדפדפן מחזירה 405: נדרשת POST חתומה.
• 401 בקליטה: בדוק סוד חתימה של היעד החדש ושעון שרת. אין שימוש בחתימה הישנה שהופיעה בתוך קובץ הדוגמה.
• 503 בקליטה: סוד חתימה לא הוגדר או אחסון אינו זמין. האירוע אינו מאושר לפני שמירה. בדוק יומן מסירות Donorbox ואפשרות שליחה מחדש; אין להניח שתבוצע מסירה נוספת אוטומטית.
• שדה לא נמצא: תן locations/customFields.readonly, בדוק תת חשבון ומודל contact/opportunity. בחר ID מפורש רק מהרשימה שחזרה מהחשבון.
• כשל source באימות: ראה סעיף Opportunity Source. אין לשחרר אירוע שכבר יצר הזדמנות על ידי אישור ״אין הזדמנות״ אם היא קיימת.
• האתר עובד ו־Cron נכשל: בדוק PHP CLI, הרחבות ונתיב מוחלט.
• נתוני אירוע היסטורי הוסרו: זו מדיניות השמירה, לא מחיקת איש קשר ב־GHL.

גיבוי ופרטיות נתונים

גבה config.php ואת התיקייה הפרטית יחד. לגיבוי SQLite עקבי, עצור מסירות ו־Cron בזמן העתקה, או השתמש ב־SQLite Online Backup. אין להעתיק רק את bridge.sqlite מתוך מסד פעיל בלי WAL/SHM. אובדן key.phpdata מונע פענוח סודות ו־payload.

לאחר תקופת השמירה, Cron מוחק פרטי אירועים שהושלמו/דולגו ואת הלוגים הישנים. מזהה התרומה נשמר כדי למנוע עיבוד חוזר. אירועים פתוחים נשמרים לטיפול. מחיקה פיזית מעותקי מסד וגיבויים מנוהלת בנפרד באחסון. CSV כולל פרטי תורמים ונגיש למנהל בלבד.

לשחזור סיסמת ניהול באמצעות גישת שרת, טען את app/bootstrap.php מקובץ PHP זמני מחוץ לתיקייה הציבורית, צור App עם הנתיב הפרטי הקיים ועדכן רק admin.password באמצעות password_hash. אל תמחק מסד או מפתח כדי לאפס סיסמה.

מה נבדק ומה נשאר לבדיקת החשבון

QA-REPORT.txt כולל את בדיקות הפיתוח. הן נעשו ב־PHP 8.3 דרך PHP.wasm, עם מסד SQLite, חתימות, דפדפן ו־API מדומה. לא נמסרו מפתחות לחשבונות האמיתיים, ולכן אין בדיקת קצה חיה של הרשאות, Source, Cron בהוסטינגר או תגובות האוטומציות האחרות בחשבון.

המיפוי והערכים המוגדרים נבדקו גם מול מבנה ה־payload שסופק, בלי לשלוח נתוני תורמים החוצה. קובצי נתוני התורם והכותרות המקוריים אינם כלולים בחבילה. בדיקות הפרויקט כוללות נתוני בדיקה מלאכותיים בלבד.

מקורות רשמיים

נבדקו ב־21.10.2026.

• GHL — קריאת שדות מותאמים
• GHL — תת חשבון ואזור זמן
• GHL — Upsert Contact
• GHL — Create Opportunity v3
• GHL — Update Opportunity v3
• GHL — ה־SDK הרשמי, כולל סכמות שדות הכתיבה
• Donorbox — Custom Webhooks
• Donorbox — אימות חתימה

המסלול החדש אינו מפעיל טריגר Inbound Webhook ב־GHL. עלויות חשבון, אחסון וגישה לוובהוקים ב־Donorbox תלויות במסלולים שלך; אין כאן ביטול של חיובים אחרים.