מרכז הידע / תוכנת קארדקום

שאלו את ה-AI

✦ תשובת ה-AI

חושב…

מקורות

    WEBHOOK (וובהוק) - חשבונית : קבלת דיווח על יצירת מסמכים למערכת חיצונית - API

    שימו לב.

    1.  עליך לדעת לטפל בדיווח כפול. ניתן לבדוק דיווחים כפולים לפי המספר עסקה עם פרטר ExtReadInvoiceHead_InvoiceNumber.

      חשבונית : קבלת דיווח על יצירת מסמכים למערכת חיצונית

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

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

    הגדרות

    להפעלת האפשרות יש לעבור בתפריטים במערכת הניהול אל :  הגדרות -> 3. מסמכים -> 4. הגדרות מסמכים בממשקים.

    להלן פירוט האופציות המתוארות בדף ההגדרה:

    1. יש לבחור את המסוף שעבורו מבצעים את ההגדרות.
       
    2. ניתן לבחור את סוג המסמך שיופק בעת מסמך אוטומטי.
       
    3. מזהה ייחודי של החברה במערכת קארדקום יתקבל לשרת שלך בעת פנייה לדיווח על מסמך חדש. - מזהה חברה יחודי של מערכת אישורית זהב
      מזהה חברה יחודי - לא ניתן לשינוי
      ערך זה יתווסף לפנייה בשם : BillGoldCompID
      שים לב! פרמטר זה אחיד לכול המסופים !
       
    4. לא חובה - מזהה ייחודי של החברה שלך בשרת היעד. - מזהה חברה יחודי חברה
      במידה ושונה מריק, ערך זה יתווסף לפנייה בשם : ExternalCompID
      שים לב! פרמטר זה אחיד לכול המסופים !
       
    5. הפעל דיווח לשרת חיצוני למסוף נבחר. - דיווח על יצירת מסמך למערכת חיצונית
      האם לבצע דיווח למערכת חיצונית. בעת יצירת מסמך. מתאים כאשר רוצים לדווח על הפקת מסמך למערכת צד שלישי.
      שים לב !פרמטר זה מוגדר ברמה של המסוף!
       
    6. כתובת לביצוע POST עם פרטי המסמך.

       
    7. פרמטרים נוספים להוסיף לפנייה. - מחרוזת תוספת לפנייה
      אפשר להוסיף נתונים לפנייה לדוגמה:
      Term=1234&secret=abcs
      פרמטרים אילו יתווספו לפנייה
      שים לב! לא מתבצע URL ENCODE לערכים איילו לכן אין להוסיף תווים מיוחדים כגון רווח , עברית וכו..
      מומלץ רק אותיות באנגלית, ומספרים.
    8. הוספת פרטי המסמך בדיווח ה POST. - פרטי המסמך יתקבלו ב POST במקום לבצע משיכה משרת קארדקום
      שים לב !פרמטר זה מוגדר ברמה של המסוף!

    mceclip1.png

     

    פרמטרים המתקבלים לכתובת הדיווח (6) ב POST.

      פרמטר  ערכים לדוגמה תיאור
    1 BillGoldCompID 27ac3bd7-aa5d-4596-a789-6f326d750eb4 מזהה ייחודי חברה של קארדקום (מס 3)
    2  DocType 1 - חשבונית מס קבלה
    3- קבלה למכ"ר
    101 - הזמנה מאתר    		  סוג המסמך שהופק
    3  DocNumber 1006  מספר מסמך
    5 ExternalCompID DemoCompany  מזהה חברה יחודי כפי שהוקלד (מס 4)
    6 פרטמרים נוספים לפי סעיף 7 data=1&otherInfo=2  
    7 ResponseCode 0 הפעולה בוצעה בהצלחה
    8 InvoiceDefHe_InvoiceComments תודה שרכשת נשמח לשמוע הערות למסמך שהוגדרו ברמת הממשק
    9 InvoiceDefHe_Name אבי מזגנים בע"מ שם החברה במערכת קארדקום
    10 InvoiceDefHe_Line1 חולון כתובת שורה 1 המוגדרת במערכת
    11 InvoiceDefHe_Line2 הבקעה כתובת שורה 2 המוגדרת במערכת
    12 InvoiceDefHe_Line3 23 כתובת שורה 3 המוגדרת במערכת
    13 InvoiceDefEn_InvoiceComments thank you for you purcase הערות באנגלית שהוגדרו ברמת הממשק
    14 InvoiceDefEn_Name avi Father of air conditioners LTD שם החברה באנגלית בקארדקום
    15 InvoiceDefEn_Line1 Holon כתובת אנגלית שורה 1 המוגדרת במערכת
    16 InvoiceDefEn_Line2 Ha-Bika כתובת אנגלית שורה 2 המוגדרת במערכת
    17 InvoiceDefEn_Line3 23 כתובת אנגלית שורה 3 המוגדרת במערכת
    18 CashNIS 150 אמצעי תשלום מזומן שתועד במסמך
    19 ExtReadInvoiceHead_CustName Jhonas שם הלקוח למסמך
    20 ExtReadInvoiceHead_CustAddresLine1 סחרוב 22 כתובת הלקוח למסמך
    21 ExtReadInvoiceHead_CustAddresLine2 בניין 2 כתובת שורה 2 למסמך
    22 ExtReadInvoiceHead_CustCity Vegas עיר הלקוח למסמך
    23 ExtReadInvoiceHead_CustLinePH 03-4572354 טלפון קווי של הלקוח למסמך
    24 ExtReadInvoiceHead_CustMobilePH 054-7654221 טלפון נייד של הלקוח למסמך
    25 ExtReadInvoiceHead_CompID 435128744 ת.ז או ח.פ של הלקוח למסמך
    26 ExtReadInvoiceHead_Languge עברית שפת המסמך
    27 ExtReadInvoiceHead_Comments thank you for your purchase הערות למסמך שהוספו ברמת הקוד
    28 ExtReadInvoiceHead_CoinID

    1 - שקל

    2 - דולר

    סוג המטבע שנבחר

    ניתן לראות רשימה מלאה ב - רשימת קודי מטבע
    29 ExtReadInvoiceHead_Email test@gmail.com מייל הלקוח
    30 ExtReadInvoiceHead_SendByEmail True / False האם לשלוח מסמך ללקוח או לא
    31 ExtReadInvoiceHead_CustomerNumber 8539 מס' הלקוח שנוצר בקארדקום
    32 ExtReadInvoiceHead_Discount 0.0 סכום ההנחה שהוגדר
    33 ExtReadInvoiceHead_InvoiceDate 23.1.2023 תאריך הפקת המסמך (מתעד גם כאשר מגדירים הפקה של מסמך בתאריך שונה מיום העסקה)
    34 ExtReadInvoiceHead_InvoiceType

    1 -מס קבלה

    וכו'

    סוג המסמך שהוגדר להפקה

    ניתן לראות רשימה מלאה ב - 
    35 ExtReadInvoiceHead_InvoiceNumber 511284 מס' החשבונית שהופקה
    36 ExtReadInvoiceHead_TerminalNumber 1000 מס' הטרמינל שביצע את הפעולה
    37 ExtReadInvoiceHead_TotalIncludeVAT 150 סכום מלא כולל מע"מ
    38 ExtReadInvoiceHead_TotalNoVat 128.21 סכום מלא לא כולל מע"מ
    39 ExtReadInvoiceHead_TotalVatFree 0.0 סכום שאינו חייב במע"מ
    40 ExtReadInvoiceHead_VAT 0.17 אחוז המע"מ שנגבה
    41 ExtReadInvoiceHead_VATOnly 21.79 סכום המע"מ שנגבה
    42 ExtReadInvoiceHead_IsOpen True / False האם המסמך פתוח או סגור
    43 ExtReadInvoiceHead_DepartmentID 36

    מס' המחלקה שתחתיה הופק המסמך

    ניתן לראות מספרי מחלקות ב - 
    בעת הפקת מסמך במטבע שאינו שקלים
    44 ExtReadInvoiceHead_TotalIncludeVATNIS 150 סכום מלא כולל מע"מ בשקלים (NIS)
    45 ExtReadInvoiceHead_TotalNoVatNIS 128.21 סכום מלא ללא מע"מ בשקלים (NIS)
    46 ExtReadInvoiceHead_TotalVatFreeNIS 0.0 סכום שאינו חייב במע"מ בשקלים (NIS)
    47 ExtReadInvoiceHead_VATOnlyNIS 21.79 סכום המע"מ שנגבה בשקלים (NIS)
    פרמטרים ברמת שורת המסמך
    48 TotalExtReadInvoiceLines 1 מס' השורות במסמך
    49 ExtReadInvoiceLines_CostNoVat 128.21 סכום מלא ללא מע"מ ברמת שורת המוצר
    50 ExtReadInvoiceLines_Description test product שם המוצר בשורה
    51 ExtReadInvoiceLines_InvoiceNumber 511284 מס' המסמך שהופק
    52 ExtReadInvoiceLines_ProductID GLSY מס' מק"ט מוצר
    53 ExtReadInvoiceLines_Quantity 1 כמות המוצר
    54 ExtReadInvoiceLines_TotalLineCostIncludeVAT 150 סכום כולל מע"מ
    56 ExtReadInvoiceLines_TotalLineCostNoVat 128.21 סכום ללא מע"מ
    57 ExtReadInvoiceLines_TotalLineCostVATOnly 21.79 מע"מ שנגבה
    58 ExtReadInvoiceHead_VAT 0.17 אחוז מע"מ שנגבה
    59 ExtReadInvoiceHead.ExternalId Order 1234 מזה עסקה חיצוני
    60 ExtReadInvoiceHead_RoundUp 0.01 הנחת עיגול לשלמים

     

    דוגמה לפרמטרים שיתקבלו :

    BillGoldCompID=27ac3bd7-aa5d-4596-a789-6f326d750eb4&DocType=1&DocNumber=1006&ExternalCompID=DemoCompany&data=1&otherInfo=2

    אמצעי תשלום:

    כרטיס אשראי:

    טבלת פרמטרים : נתונים המתקבלים מחברות האשראי:

    בנוסף לנתונים הפנימיים של מערכת הסליקה אישורית זהב, בעת ביצוע חיוב אשראי ישנם נתונים נוספים אשר מתקבלים ישירות מחברות האשראי.

    הערות:

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

    הפרמטרים הם דינמיים, יתכן ויתווספו שדות נוספים בעתיד.

     

      פרמטר ערכים אפשריים לדו' תיאור
    1 ExtShvaParams.Status1 בהתאם לטבלת הודעות קודים 0-300  .
    זהירות- ישנם קודים ששונים מ -0 אבל עדיין אומרים עסקה תקינה !    		 קוד תשובה של הפנייה לחברות האשראי
    2 ExtShvaParams.Sulac25 קודים של חברה סולקת בהתאם למאמר :תיאור קודים חברות האשראי חברה סולקת של הכרטיס
    3 ExtShvaParams.CardNumber5 4580 ארבע ספרות אחרונות של כרטיס אשראי של הלקוח
    4 ExtShvaParams.JParameter29

    0 - ברירת מחדל לפי הגדרות חברות האשראי.

    2 - בדיקה בלבד של ספרת ביקורת

    5 - קבלת אישור מול חברות האשראי

    		 J- פרמטר , סוג בדיקה שבוקשה לביצוע על הכרטיס
    5  ExtShvaParams.Tokef30 1229  תוקף הכרטיס
    6 ExtShvaParams.Sum36 150 סכום שלקוח שילם באגורות - באותו מטבע - לא חייב להיות ש"ח.
    7 ExtShvaParams.SumStars52 100 סכום ששולם בכוכבים
    8 ExtShvaParams.ApprovalNumber71 0 - ללא אישור , קבלת מספר האישור מחברת ש.ב.א ולא מחברות האשראי מכיוון שסכום העסקה מתחת לתקרה.
    אחרת
    מספר האישור שהתקבל מחברות האשראי או מספר האישור שהוקלד בעת ביצוע העסקה.    		 מספר אישור על ביצוע עסקה
    9 ExtShvaParams.FirstPaymentSum78 50.00 סכום תשלום הראשון
    10 ExtShvaParams.ConstPayment86 20.00 סכום מספר התשלומים הנוספים
    11 ExtShvaParams.NumberOfPayments94 שם לב!
    כאשר ExtShvaParams.CreditType63=6  עסקה של 6 תשלומים יופיע 6.    		 שם לב !
    כאשר ExtShvaParams.CreditType63=6
    שדה זה מייצג את סה"כ מספר התשלומים !
    12 ExtShvaParams.CardTypeCode60 קודים של חברה סולקת בהתאם למאמר :תיאור קודים חברות האשראי קוד חברת האשראי המנפיקה
    13 ExtShvaParams.Mutag24 0 - כרטיס פרטי של חברה מנפיקה(PL)
    1 - מסטרכרד
    2 - ויזה
    3 - מאסטרו
    5 - ישראכראט    		 קוד מותג הכרטיס
    14 ExtShvaParams.CardOwnerName  Yaniv  שם בעל הכרטיס כפי שהוקלד ע"י המשלם
    15  ExtShvaParams.CardToken AA-BB-CC אסימון הכרטיס במידה ונוצר מסוג GUID
    16  ExtShvaParams.CardHolderIdentityNumber 040000000   ת.ז. בעל הכטיס
    17  ExtShvaParams.CreditType63 1- רגיל
    2 - ישראקרדיט, עדיף 30+
    3 - חיוב מידי
    4 - אשראי מועדון
    5 - סופר קרדיט
    6 - קרדיט בתשלומים
    8 - תשלומים
    9 - מועדון בתשלומים.    		 סוג חיוב האשראי
    18  ExtShvaParams.AbroadCard119 0 - כרטיס ישראלי
    1 - כרטיס תייר
    2 - כרטיס דלק
    3 - כרטיס חיוב מיידי
    4 - כרטיס מתנה / נטען ( פרט לכרטיס שמופק ע"י חברת ויזה כא"ל בשלב זה)    		 סוג כרטיס חיוב
    19 ExtShvaParams.DealType61  00 - כרטיס חסום
    01 - עסקת חובה רגילה
    02 - עסקת חובה מאושרת
    03 - עסקה מאולצת.
    51 - עסקת זכות.
    52 - עסקת ביטול.
    53 - עסקת זכות מאושרת.     		 סוג עסקה
    20 ExtShvaParams.ChargType66   00 - עסקה רגילה
    01 - שירות עצמי
    02 - שירות עצמי בתחנות דלק
    05 - contactless
    06 - contactless self service
    50 - עסקה טלפונית
    51 - עסקת חתימה בלבד.    		 קוד עסקה 
    21  ExtShvaParams.BinId 1-  כרטיס אשראי שופרסל  (4580XX44)
    2 - כרטיס חבר   185000000 - 195000000    		 מזה סוג הכרטיס.
    במידה וישנם כרטיסים נוספים לזיהוי יש לפנות את התמיכה להוספה
    22  ExtShvaParams.InternalDealNumber 123456     מספר עסקה פנימי של קארדקום (Int64)
    23  ExtShvaParams.CouponNumber  120112011  מספר שובר - מחרוזת 
    24 ExtShvaParams.DealDate   תאריך ביצוע העיסקה
    25 ExtShvaParams.CardOwnerPhone   טלפון בעל הכרטיס
    26 BillLocation Direct = 1 [ממשק ישיר]
    Open = 2 [ דף אישורית זהב]

    LowProfile = 7 [פרופיל נמוך]
    Suspended= 9 [עסקה מושהית]
    RecuringBilling = 10 [הוראת קבע]    		 מקום ביצוע העסקה בעסקת אשראי
    27 InvoiceCreatorUserID 83 מספר היוזר/משתמש שהפיק את המסמך
    ניתן לבדוק את היוזר במערכת תחת :
    הגדרות 1 - 2 הרשאות משתמשים בטבלה תחת - מספר משתמש.

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

     
     
     

    מזומן :

      פרמטר ערכים אפשריים לדוגמה תיאור
    1 CashNIS 100.2 סה"כ מזומן בשקל
     
     

    המחאות :

    טבלת פרמטרים : המחאות לחשבוניות קבלה

    הערות:

    שם המחלקה ב Web Server היא  RciExtCheque ולא  Cheque!

    ניתן להעביר מספר המחאות ראה דוגמה לסוף הדף

      פרמטר ערכים אפשריים לדוגמה תיאור
    1 Cheque.ChequeNumber 1234 מספר המחאה
    2 Cheque.BankNumber 12  מספר בנק
    3 Cheque.SnifNumber 1  מספר סניף בנק
    4 Cheque.AccountNumber 123456 מספר חשבון
    5 Cheque.DateCheque  dd/MM/yyyy תאריך פירעון המחאה
    6 Cheque.Sum 100.50 סכום המחאה

     

    העברה של מספר המחאות :

    על מנת להעביר "מערך" של המחאות יש למספר את האמחאות  לדוגמה :
    המחאה ראשונה :

    Cheque.ChequeNumber=1234&Cheque.DateCheque=1/10/2011&Cheque.Sum=150.00


    המחאה שנייה :

    Cheque1.ChequeNumber=1234&Cheque1.DateCheque=2/10/2011&Cheque1.Sum=150.00


    המחאה שלישית:

    Cheque2.ChequeNumber=1234&Cheque2.DateCheque=3/10/2011&Cheque2.Sum=150.00
     

    אחר:

    טבלת פרמטרים : הוספת "תשלום אחר" לחשבונית.

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

     

     

    הערות:

    שם המחלקה ב Web Server היא RciExtCustome ולא CustomPay.

    עבודה ב Name to Value  POST   להשתמש כרגיל CustomPay.TransactionID לפי הטבלה .

    ניתן להעביר מספר תשלומים ראה דוגמה לסוף הדף.

      פרמטר ערכים אפשריים לדו' תיאור
    1 CustomPay.TransactionID 32 מספר חשבון המוגדר מראש במערכת הסליקה אישורית זהב.
    ראה מאמר : הגדרות חשבוניות : חשבונות שונים
    יש להעביר את הנתון מספר רץ.
    2 CustomPay.TranDate 31/12/2012 תאריך  אסמכתה
    3 CustomPay.Description קבלת תשלום מPayPal תיאור פעולה 
    4 CustomPay.Asmacta 123456-ZZC מספר אסמכתה פעולה 
    5 CustomPay.Sum 150.00 סכום

    העברה של מספר "תשלום אחר":

    על מנת להעביר "מערך" של תשלום אחר יש למספר את התשלומים לדוגמה:

    תשלום אחר אחד:

    CustomPay.TransactionID=31&CustomPay.TranDate=31/12/2011&CustomPay.Asmacta=ZZ123&CustomPay.Sum=150

    תשלום אחר שתיים :

    CustomPay1.TransactionID=31&CustomPay1.TranDate=31/11/2011&CustomPay1.Asmacta=ZZ123&CustomPay1.Sum=150

    תשלום אחר שלוש:

    CustomPay2.TransactionID=31&CustomPay2.TranDate=31/10/2011&CustomPay2.Asmacta=ZZ123&CustomPay2.Sum=150

     

     

    לאחר קבלת הפניה יש לפנות למערכת אישורית זהב לקבל את פרטי המסמך לפי סוג המסמך ומספר המסמך.
    ראה מאמר : פעולות : משיכת פרטי חשבונית

    הערות

    1. אישורית זהב תבצע דיווח לכתובת הניתנת. יש להחזיר http status 200 אישור קבלת הפנייה. אישורית זהב תפנה עד 7 פעמים ב 24 שעות כול עוד לא התקבל http status 200.

     

    * במקרה של תקלה בדיווח עסקה מהשרת של קארדקום לשרת של הלקוח * 

    נדרש לפתוח את כל טווחי הכתובת IP הבאים של קארדקום בחומת האש של החברה (גם ב cloudflare למי שיש)

    - 82.80.227.17/255.255.255.248 (CIDR 29) >> מחשבון subnet

    - 82.80.222.124/255.255.255.248 (CIDR 29) >> מחשבון subnet

    בנוסף יש לפתוח כמובן PORT ים : 80 , 8080 , 443 .

     

     

    האם המאמר הזה עזר לך?