הגדרות ->ממשקים ומפתחים

מה הם קבצי מוחלפים?

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

למי המדריך מתאים?

המדריך מיועד עבור:

• לקוחות המנויים לקארדקום כחברה סולקת בלבד, ועובדים עם חברת מסופים נפרדת - המעוניינים לקבל קבצי מוחלפים

שלב 1 – יצירת תעודה דיגיטלית

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

כיצד מפיקים תעודה?

1. היכנסו לממשק קארדקום.
2. עברו למסך הגדרות ->ממשקים ומפתחים
3. הפיקו תעודה דיגיטלית חדשה בעזרת הכפתור ''צור תעודה''
4. תנו שם לתעודה ואז לחצו על ''צור תעודה''
5. התעודה נוצרה - ניתן להוריד כקובץ PFX ולהעתיק את התעודה בפורמט base64
6. יש לסמן V בתיבה ''הורדתי ושמרתי את התעודה במקום מאובטח'' - וללחוץ על ''סיום''
   
    

חשוב לדעת

• יש לשמור את התעודה במקום מאובטח.
• תוקף התעודה הוא 4 שנים.
• בקשות לקבלת קבצי מוחלפים יתאפשרו רק עם תעודה תקפה.

שלב 2 – שליחת בקשה לקבלת קובץ מוחלפים

כתובת ה־API

https://secure.cardcom.solutions/api/v11/RecuringPayments/GetMuhlafimFile

סוג הבקשה

HTTP POST

דרישות לפני שליחת הבקשה

יש לצרף לבקשה:

• תעודה דיגיטלית תקפה שהופקה דרך קארדקום
• את התעודה יש להמיר לפורמט Base64 (ראו מדריך כיצד להצפין: https://www.techfabric.com/blog/convert-pfx-certificate-to-base64-string
• את ערך ה־Base64 יש לצרף בגוף הבקשה.

מבנה גוף הבקשה

{
  "SupplierUserName": "XXX",
  "Secret": "XXX",
  "CompanyNumber": XXX,
  "DateFrom": "1999-12-31T23:59:59.999Z",
  "Certification": "MIIQegIBAzCCEDYG............/e0e1AgIH0A=="
}

קבלת קובץ מוחלפים לוקאלית

כתובת לדוגמה

localhost:61240/api/v11/RecuringPayments/GetMuhlafimFile

דוגמה לגוף בקשה

{
  "SupplierUserName": "XXX",
  "Secret": "XXX",
  "CompanyNumber": XXX,
  "DateFrom": "2025-10-23T18:25:43.511Z",
  "DateTo": "2025-12-03T18:25:43.511Z",
  "Certification": "MIIK8gIBAz.....0A=="
}

הסבר על שדות הבקשה

שלב 3 – קבלת תשובה מהמערכת

לאחר שליחת הבקשה, המערכת תחזיר תשובה בפורמט JSON.

דוגמה לתשובה

{
  "Data": [
    {
      "MuhlafID": 000,
      "EntryType": 2,
      "EntryNumber": 1,
      "SapakNumber": 000000,
      "OldCreditNumber": null,
      "NewCreditNumber": null,
      "ReportCode": 1,
      "NewCardExpirationDate": "31/01/2030 0:00:00"
    },
    {
      "MuhlafID": 0000,
      "EntryType": 2,
      "EntryNumber": 2,
      "SapakNumber": 000000,
      "OldCreditNumber": null,
      "NewCreditNumber": null,
      "ReportCode": 1,
      "NewCardExpirationDate": "01/01/2028 0:00:00"
    }
  ]
}

הסבר על שדות התשובה

הודעות שגיאה ותנאים לבקשה

במידה והערכים שנשלחו בבקשה אינם תקינים, המערכת תחזיר את ההודעה:

Something went wrong , please contact support

דגשים חשובים

תקינות טווח תאריכים

יש לוודא כי:

DateFrom < DateTo

כלומר:

• תאריך ההתחלה חייב להיות קטן מתאריך הסיום.

מגבלת טווח נתונים

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

בקשה לטווח תאריכים הגדול מ־3 חודשים עלולה לגרום לשגיאה.

המלצות אבטחה

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

סיכום

על מנת לקבל קבצי מוחלפים:

1. יש להפיק תעודה דיגיטלית תקפה.
2. להמיר את התעודה ל־Base64.
3. לשלוח בקשת HTTP POST ל־API.
4. לוודא שטווח התאריכים תקין ועד 3 חודשים.
5. לעבד את תשובת ה־JSON המתקבלת מהמערכת.

האם ניתן להוריד תעודה פעם נוספת?

לא. אם קובץ התעודה אבד, יש לבטל את התעודה ולהפיק תעודה חדשה.

האם הפקת תעודה חדשה מבטלת את התעודה הקיימת?

לא. התעודה הקיימת תמשיך לעבוד עד לתאריך התפוגה שלה או עד לביטולה.

מה יש לבדוק כאשר ממשק המוחלפים מפסיק לעבוד?

יש לוודא כי:

• מפתח ה-API פעיל.
• למפתח קיימת הרשאה במסוף הרלוונטי.
• קיימת תעודה דיגיטלית בתוקף.
• פרטי המפתח והתעודה המעודכנים הוטמעו במערכת החיצונית.