מההרשמה
לפנייה הראשונה.

1. נכנסים לחשבון שמנהל את העסק

1. נכנסים ל־LanLeads עם חשבון Devop של בעל העסק. בוחרים את הפרופיל העסקי, למשל ביטוח, אם המערכת מבקשת זאת.
2. בודקים את שם החשבון וסביבת העבודה המופיעים במערכת. ההרשאות והפניות שייכות לסביבה הנבחרת. אם מנהלים כמה סביבות, בוחרים את סביבת העסק המתאימה לפני יצירת החיבור.
3. בעלים או מנהל פותחים ״החיבור לאתר״, מזינים שם אתר ודומיין בלבד, למשל example.co.il, ולוחצים ״יצירת החיבור״.
4. שומרים את מפתח החיבור במקום פרטי: הוא מוצג פעם אחת. כתובת הקליטה היא https://crm.devop.co.il/api/v1/leads.

לכל חשבון בעלים אתר אחד ושם מארח מדויק אחד. example.co.il, www.example.co.il ו־lp.example.co.il נחשבים שמות מארח שונים. כל הדפים והטפסים באותו שם מארח יכולים להתחבר יחד. משתמש צוות רואה רק את הסביבות שאליהן אושרה לו גישה.

צריך גישה להגדרות ה־DNS ולשירות הטפסים שבשרת. מפתח האתר אינו צריך לקבל את סיסמת Devop האישית: בעל העסק יוצר את החיבור ומעביר לו את פרטי ההתקנה בערוץ פרטי.

2. מאמתים בעלות על הדומיין

במסך ״החיבור לאתר״ מוצגים שם רשומת TXT וערך אימות ייחודי לאתר שלכם. מוסיפים אותם אצל ספק ה־DNS שמנהל את הדומיין. Cloudflare יכול לנהל את ה־DNS גם כשהאתר מאוחסן בשרת אחר; הוא אינו תנאי לשימוש ב־LanLeads.

אם ה־DNS מנוהל ב־Cloudflare

1. בוחרים את הדומיין הנכון, עוברים אל DNS → Records → Add record ובוחרים סוג TXT.
2. מזינים Name לפי הטבלה. ב־Content מדביקים בדיוק את הערך המלא שמתחיל lanleads-verification=, כפי שמוצג בחשבון. ללא נקודה בסוף התוכן.
3. משאירים TTL במצב Auto ושומרים. לרשומת TXT אין מתג ענן כתום/אפור.
4. חוזרים ל־LanLeads ולוחצים ״בדיקת האימות״. אם הרשומה עדיין לא מופיעה, בודקים את השם והערך ומנסים שוב לאחר עדכון ה־DNS.

הדוגמאות הן להמחשה. אצל ספק אחר ייתכן שהשדה דורש שם מלא; בדקו את תצוגת הרשומה הסופית כדי שהדומיין לא יתווסף פעמיים. משאירים את רשומת האימות. לחיבור טפסים באתר קיים אין צורך לשנות כתובת IP, רשומות A/CNAME, רשומות מייל או שרתי שמות.

ה־TXT הוא ערך אימות ציבורי. מפתח ה־API הוא סוד נפרד ואינו מוכנס ל־DNS. הוראות DNS רשמיות של Cloudflare ↗

3. בוחרים איך שירות הטפסים ישלח

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

מסלול א · Cloudflare Workers או Pages Functions

1. בוחרים את הפרויקט שמטפל בפועל בטפסים, תחת Workers & Pages.
2. ב־Worker נכנסים אל Settings → Variables and Secrets → Add, בוחרים Secret וקוראים לו LANLEADS_API_KEY. מדביקים את המפתח הפרטי ושומרים באמצעות Deploy. ב־Pages מגדירים Secret לפרויקט ומבצעים פריסה חדשה; בודקים שמוגדרת סביבת Production המתאימה.
3. אם המתאם שלכם משתמש במשתנה LANLEADS_API_URL, מגדירים אותו כטקסט רגיל עם הכתובת המלאה של ה־API. בדוגמת הקוד למטה הכתובת כבר קבועה בפונקציה.
4. מחברים את המסירה למטפל הקיים של הטופס אחרי אימות ושמירה. ב־Worker קוראים לסוד דרך env.LANLEADS_API_KEY, וב־Pages דרך context.env.LANLEADS_API_KEY.

למפתח שעובד עם Wrangler, מתוך פרויקט ה־Worker הנכון:

npx wrangler secret put LANLEADS_API_KEY

הפקודה מבקשת את ערך המפתח בקלט פרטי. משתמשים בסביבת הפריסה המתאימה. הוספת Secret או הגדרת TXT אינה מתקינה את קוד המסירה. סודות Workers ↗ · סודות Pages Functions ↗

אפשר להשתמש ב־D1 לשמירת פניות ותור, וב־scheduled לניסיונות חוזרים. waitUntil לבדו אינו תור עמיד; יש לשמור מצב מסירה לפני הפעלתו. אלה אפשרויות עבור Cloudflare, ולא דרישה לכל אתר.

מסלול ב · שרת פרטי, Node.js או PHP

1. מגדירים LANLEADS_API_KEY כסוד בשירות האחסון או במנהל התהליכים. בקובץ סביבה פרטי יש לשמור אותו מחוץ לתיקייה הציבורית, ללא גישה מהאתר וללא הוספה ל־Git. טעינת קובץ סביבה תלויה במסגרת ובאחסון שלכם.
2. מוודאים שלתהליך השרת יש גישת HTTPS יוצאת אל crm.devop.co.il בפורט443, עם אימות תעודה פעיל. אין צורך לפתוח פורט כניסה חדש או לאפשר גישה למסד שלכם.
3. משלבים את פונקציית המסירה אחרי שהטופס אומת ונשמר. ב־Node.js קוראים מ־process.env.LANLEADS_API_KEY; ב־PHP מ־getenv('LANLEADS_API_KEY'). ב־PHP צריך גם את הרחבת cURL.
4. מוסיפים תור עמיד או טבלת משלוחים ומשימה מתוזמנת. לאחר שינוי הסוד מעדכנים את תהליך האתר לפי שיטת האחסון ובודקים שההגדרה נטענה.

// פונקציית מסירה בלבד: קוראים לה עם המטען שכבר נשמר במסד.
async function deliverToLanLeads(apiKey, savedPayload) {
  if (!/^ll_live_[A-Za-z0-9_-]{43}$/.test(apiKey || '')) {
    throw new Error('missing_lanleads_key');
  }
  const response = await fetch('https://crm.devop.co.il/api/v1/leads', {
    method: 'POST',
    redirect: 'manual',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`
    },
    body: JSON.stringify(savedPayload),
    signal: AbortSignal.timeout(8000)
  });
  const result = await response.json();
  const delivered = [200, 201].includes(response.status)
    && result.ok === true
    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(result.id || '');
  return { delivered, status: response.status, code: result.code,
    id: delivered ? result.id : null };
}

// Cloudflare Worker: await deliverToLanLeads(env.LANLEADS_API_KEY, savedPayload);
// Pages Function: await deliverToLanLeads(context.env.LANLEADS_API_KEY, savedPayload);
// Node.js בשרת: await deliverToLanLeads(process.env.LANLEADS_API_KEY, savedPayload);
// timeout/JSON לא תקין: משאירים בתור. לא מסמנים כנמסר בלי delivered=true.

<?php
// PHP עם הרחבת cURL. קוראים רק אחרי אימות ושמירה במסד.
function deliverToLanLeads(array $savedPayload): array {
    $key = getenv('LANLEADS_API_KEY');
    if (!is_string($key) || !preg_match('/^ll_live_[A-Za-z0-9_-]{43}$/D', $key)) {
        throw new RuntimeException('missing_lanleads_key');
    }
    $ch = curl_init('https://crm.devop.co.il/api/v1/leads');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => false,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 8,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer ' . $key],
        CURLOPT_POSTFIELDS => json_encode($savedPayload, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
    ]);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($raw === false) {
        throw new RuntimeException('lanleads_network_error');
    }
    $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
    $delivered = in_array($status, [200, 201], true)
        && ($result['ok'] ?? false) === true
        && preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iD', $result['id'] ?? '');
    return ['delivered' => (bool) $delivered, 'status' => $status,
        'code' => $result['code'] ?? null, 'id' => $delivered ? $result['id'] : null];
}

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

מסלול ג · WordPress, בוני אתרים ושירותי טפסים

המפתח מחבר את שלב השליחה בצד השרת של תוסף הטפסים, לאחר אימות ושמירה. אם קיימת אפשרות Webhook שרת שמאפשרת JSON, כותרת Authorization סודית, מזהה קבוע, הסכמה ומנגנון retry, אפשר למפות אותה לאותו API. אם האפשרות חסרה או אינה שומרת פניות וניסיונות, נדרש מתאם שרת.

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

4. ממפים את פרטי הפנייה

POST https://crm.devop.co.il/api/v1/leads
כותרות שרת: Content-Type: application/json ו־Authorization: Bearer …. אין להעביר את כותרת Origin של הדפדפן ל־API; בקשות קליטה שמכילות Origin נדחות.

{
  "external_id": "7d502a8e-077c-4c37-9d2a-453908cd7d92",
  "name": "בדיקת חיבור לדוגמה",
  "phone": "0500000000",
  "email": "",
  "service": "בקשה לשיחת היכרות",
  "form_id": "landing-contact",
  "source_url": "https://example.co.il/contact/",
  "consent": true,
  "consent_at": "2026-10-29T09:00:00.000Z"
}

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

5. שומרים לפני המסירה

1. בשרת האתר מאמתים שדות, הסכמה ומקור, ומפעילים הגנת ספאם מתאימה. המפתח נשאר בשרת.
2. שומרים יחד את הפנייה ואת המטען המקורי לתור מסירה עמיד. שומרים מזהה, consent_at, סטטוס, מספר ניסיונות, מועד ניסיון הבא ונעילה נגד שני ניסיונות מקבילים.
3. מנסים למסור אחרי השמירה. רק200/201 עם ok=true ומזהה id תקין מסמנים כנמסר.
4. ב־timeout, תגובה לא תקינה,408/425/429 או5xx שומרים בתור לניסיון חוזר בהשהיה. מכבדים Retry-After כשמוחזר. אותו external_id ואותו מטען מונעים כפילות גם כשאישור המסירה אבד.
5. שגיאת מפתח, דומיין, ולידציה או סתירת מזהה דורשת תיקון; מציגים מצב תקלה למפעיל. שומרים רק קוד שגיאה בלוג התפעולי, ללא מפתחות או פרטי קשר.

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

6. בודקים לפני שמפעילים ללקוחות

בדיקת גישה ללא יצירת פנייה

לאחר אימות TXT והתקנת המפתח, מפתח האתר יכול לשלוח מהשרת גוף חסר פרטי קשר עם consent=false. תשובת422 עם code=invalid_lead מאשרת שהמפתח, הדומיין והגישה לקולט תקינים; הגוף נדחה ולא נוצר ליד. זו בדיקת גישה בלבד.

// בדיקת חיבור מהשרת בלבד, עם המפתח הסודי מתוך סביבת השרת.
// החליפו לדומיין המאומת בחשבון. גוף זה לא יוצר ליד.
const check = await deliverToLanLeads(apiKey, {
  source_url: 'https://example.co.il/',
  consent: false
});
// צפוי: status=422, code='invalid_lead', delivered=false.
// זו הצלחה של בדיקת הגישה בלבד, לא של קליטת פנייה תקינה.

בדיקה מלאה של הטופס

1. מתאמים פנייה סינתטית ברורה, למשל שם ״בדיקת חיבור״ וטלפון0500000000. אם האתר שולח התראות, מתאמים גם את מיילי הבדיקה.
2. שולחים בפועל מכל סוג טופס שונה באתר, עם הגנת הספאם וההסכמה הרגילות.
3. בודקים שהפנייה נשמרה באתר, מופיעה בסביבת ה־CRM הנכונה וכוללת מקור ונושא נכונים.
4. המפתח משחזר את אותה בקשת מסירה עם אותו מזהה ומטען: צפויה200 עם duplicate=true ואותו id. לא יוצרים מזהה חדש כדי לנסות שוב.
5. בודקים ניסיון חוזר לאחר תקלה, מעקב אחר תור חסום ואי־חשיפת מפתח בקוד הציבורי. בודקים בנפרד התראות: אישור ספק מייל אינו הוכחת קבלה בתיבה.

פתרון תקלות נפוצות

החלפת מפתח

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

מה להעביר למפתח האתר

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