מדריך עבודה עם קבצי מוחלפים - קארדקום סליקה

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

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

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

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

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

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

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

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

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

חשוב לדעת

• יש לשמור את התעודה במקום מאובטח.
• תוקף התעודה הוא 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 המתקבלת מהמערכת.