יצירת לקוח (עם בקשה) דרך ה‑API

מדריך אינטגרציה למפתחים: איך ליצור לקוח חדש — ובמידת הצורך גם בקשה באותה קריאה, וגם לשייך אותו לחברי צוות — דרך ה‑API החיצוני של Docly.

סקירה כללית

ה‑API החיצוני מאפשר ללקוחות המערכת (טננטים) ליצור לקוחות באופן תכנותי. אותה קריאה יכולה גם ליצור בקשה (Request) עבור הלקוח על בסיס תבנית קיימת, וגם לשייך את הלקוח לחברי צוות לפי כתובת אימייל.

גוף הבקשה (Request Body)

מטא‑דאטה — שתי רמות

קיימות שתי רמות נפרדות של מטא‑דאטה, שתיהן אובייקטי JSON חופשיים (key: value):

• מטא‑דאטה ברמת הלקוח — שדה metadata בראש הגוף. נשמר על רשומת הלקוח. משמש גם למתן שמות לתיקיות האחסון (למשל תבנית {metadata.national_id}).
• מטא‑דאטה ברמת הבקשה — שדה metadata בתוך בלוק request. נשמר על רשומת הבקשה. רלוונטי רק כשנשלח בלוק בקשה.

{
  "name": "ישראל ישראלי",
  "metadata": {
    "national_id": "123456789"
  },
  "request": {
    "templateName": "הלוואה לכל מטרה - לווה יחיד",
    "metadata": {
      "request_id": "2025"
    }
  }
}

שיוך הלקוח לחברי צוות (assignedTo)

assignedTo הוא מערך אופציונלי של כתובות אימייל של חברי הצוות בטננט שלך. כשהוא נשלח, הלקוח משויך לחברי הצוות התואמים — בדיוק כמו “צוות מטפל” שאתה מגדיר בפאנל הניהול. השדה הוא אופציונלי לחלוטין: אם לא תשלח אותו, כלום לא משתנה.

מי נחשב חבר צוות שאפשר לשייך אליו? כל אימייל מושווה (ללא רגישות לאותיות גדולות/קטנות) מול המשתמשים בטננט שלך. חבר צוות ניתן לשיוך רק אם הוא:

• משתמש בטננט שלך, וגם
• פעיל (לא מושבת), וגם
• אינו מנהל‑על של הפלטפורמה (super‑admin).

התנהגות ללקוח חדש מול לקוח קיים:

מנגנוני הגנה (כדי שקריאה שגויה לא תמחק צוות):

• "assignedTo": [] (מערך ריק מפורש) נחשב כלא נשלח — ללא פעולה, לעולם לא “נקה הכול”.
• אם assignedTo אינו ריק אך אף אחת מהכתובות אינה תואמת חבר צוות שאפשר לשייך — השיוך הקיים נשאר ללא שינוי (כל הכתובות חוזרות כ‑unmatched). מערך מלא בשגיאות הקלדה לעולם לא ימחק את הצוות המשויך.

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

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

אם תכלול בלוק request, תיווצר בקשה עבור הלקוח החדש על בסיס תבנית. השדות בבלוק:

דוגמה מלאה — cURL

curl --location 'https://app.docly.co.il/api/v1/customers' \
  --header 'Authorization: Bearer docly_xxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "ישראל ישראלי",
    "email": "israel@example.com",
    "phone": "0501234567",
    "customerTypeName": "הלוואה לכל מטרה - לווה יחיד",
    "externalId": "loan-req-12345",
    "assignedTo": ["sarah@firm.co.il"],
    "metadata": {
      "national_id": "123456789"
    },
    "request": {
      "templateName": "הלוואה לכל מטרה - לווה יחיד",
      "metadata": {
        "request_id": "2025"
      }
    }
  }'

תשובות (Responses)

הצלחה — ‏201 Created

{
  "customer": { "id": "...", "guid": "...", "name": "..." },
  "password": "839204",
  "portalUrl": "https://app.docly.co.il/<tenant>/c/<guid>",
  "request": { "id": "...", "guid": "..." }
}

• password מוחזר פעם אחת בלבד — סיסמת הכניסה החד‑פעמית של הלקוח.
• portalUrl — קישור הכניסה של הלקוח לפורטל.
• request מופיע רק אם נשלח בלוק request.

סיכום השיוך — assignment (רק כששלחת assignedTo)

אם — ורק אם — שלחת assignedTo לא‑ריק, התשובה כוללת גם אובייקט assignment שמפרט אילו כתובות שויכו ואילו לא:

{
  "customer": { "...": "..." },
  "portalUrl": "https://app.docly.co.il/<tenant>/c/<guid>",
  "assignment": {
    "assigned":  ["sarah@firm.co.il"],
    "unmatched": ["dan@firm.co.il"]
  }
}

• assigned — הכתובות שהותאמו לחבר צוות ושויכו.
• unmatched — הכתובות שלא נפתרו לחבר צוות שאפשר לשייך.
• כש‑assignedTo לא נשלח (או נשלח ריק), אין שדה assignment כלל — התשובה זהה בדיוק לקודם.

שגיאות נפוצות

בעיות נפוצות ופתרון

1. קיבלתי 404 “סוג לקוח לא נמצא”: השם ב‑customerTypeName אינו תואם במדויק. העתק את השם מהפאנל (copy‑paste, לא הקלדה) כדי להימנע מהבדל במקף או ברווח.
2. קיבלתי 422 על התבנית: ודא ש‑templateName תואם בדיוק לשם תבנית קיימת, או השתמש ב‑templateId.
3. קיבלתי 500: בדוק שהטננט מחובר לאחסון. ללא חיבור אחסון, כל יצירת לקוח תיכשל באותו שלב.
4. חבר צוות לא שויך (הופיע ב‑unmatched): ודא שהאימייל תואם בדיוק לחבר צוות פעיל בטננט שלך, ושאינו מנהל‑על. שיוך לעולם לא מכשיל את הקריאה — בדוק את מערך unmatched בתשובה.
5. למניעת כפילויות: שלח externalId ייחודי לכל בקשה — קריאה חוזרת עם אותו מזהה תחזיר את הלקוח הקיים במקום ליצור כפילות.