API – הפעלת דפי סליקה ליצירת הוראות קבע

מבוא

כספית מאפשרת למשתמש ליצור דפי מכירה שבהם הלקוחות שלו יכולים לבחור בפריט ולשלם עבורו. בעת ההקמה של דף מכירה המשתמש יכול לבחור בפעולה ("מסמך המשך") שכספית תבצע לאחר התשלום. הפעולות האפשריות הן:

1. יצירת חשבונית/קבלה ומשלוח שלה ללקוח. בגרסת כספית+עמותות: חשבון/קבלה.
2. יצירת קבלה בלבד. המשתמש יפיק את החשבונית מן הקבלה בהמשך לאחר השלמת תהליך המכירה. בגרסת עמותות: קבלה רגילה או קבלה לתרומה.
3. הוראת קבע חודשית או שנתית.

אם המשתמש בחר במסמך המשך הוראת קבע, כספית לא תחייב את הלקוח אלא (1) תקים את הלקוח; (2) תקלוט את פרטי כרטיס האשראי שלו; (3) תקים הוראת קבע מתאימה. המשתמש יכול גם להגדיר URL שכספית תקרא לו לאחר סיום הפעולה ותשלח אליו את פרטי ההזמנה של הלקוח ואת פרטי מסמך ההמשך. כספית לא קולטת את ה-CVV של כרטיס האשראי שהוא חיוני לביצוע סליקה. ראו פרטים סוף התיעוד.

הדרישות

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

תהליך הפעולה הצפוי

1. המשתמש מקים דף מכירה כמו בדוגמה הבאה:

בתמונה ניתן לראות את הפרטים הבאים:

1. 1. הפריטים למכירה, המחירים לא כוללים מע"מ, לכן כספית תוסיף מע"מ בעת יצירת הוראת הקבע
   2. מסמך ההמשך הוא הוראת קבע חודשית
   3. מספר החיובים (שדה "מספר תשלומים מירבי") הוא 12. ניתן לבחור בכל מספר בין 1 ל-999. 999 מסמן ה"ק "מתגלגלת" ללא עצירה.
   4. URL של מערכת צד ג' שאליה תקרא כספית.
   5. הקישור להצגת דף המכירה.

1. המפתח של מערכת צד ג' מכין קישור כמו הקישור הבא:

https://app.caspit.biz/Order/Index/32058a6c-c5f3-44f1-ac29-11c0cc8a8a02-8da0d52d-cbff-4d35-8c6b-ca9279d441dd?osekMorshe=514001432&businessName=%D7%9E%D7%A0%D7%97%D7%9D%20%D7%91%D7%A8%D7%95%D7%9A%20%D7%A9%D7%95%D7%95%D7%A8%D7%A5&address1=%D7%93%D7%A0%D7%99%D7%90%D7%9C%20%D7%94%D7%9B%D7%94%D7%9F%208&address2=%D7%93%D7%99%D7%A8%D7%94%206&city=%D7%91%D7%A0%D7%99%20%D7%91%D7%A8%D7%A7&postalCode=6554438&email=dror%40caspit.biz&mobilePhone=054-9967766&comments=%D7%94%D7%96%D7%9E%D7%A0%D7%94%20%D7%9E%D7%9E%D7%A2%D7%A8%D7%9B%D7%AA%20%D7%94%D7%9E%D7%A1%D7%97%D7%A8%20%22%D7%A1%D7%97%D7%A8%20%D7%99%D7%9D%22%20%D7%92%D7%A8%D7%A1%D7%94%206.8.565&trxId=728282-829

הזיהוי של דף המכירה נעשה על-ידי ה-ID  שלו שזמין כספית במסך דפי מכירה. הזיהוי של העסקה נעשה על-ידי שדה trxId.

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

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

1. בסיום ההקמה של הוראת הקבע כספית קוראת ל-URL שהוגדר בדף המכירה. הקריאה היא ב-POST וה-body יכיל json ובן פרטי ההזמנה, ופרטי הוראת הקבע. אחד הפרטים יהיה ה-TrxId שנשלח לדף המכירה בהתחלת התהליך:

POST http://localhost:8085/wh?zid=72728

{
  “orderId”: “9ad360d1-8cdd-4413-8124-a6c8c146e0c1-df7aa678-a065-4dd2-97f5-1f94c90ee373”,
  "salesPageNumber":"4195",
  "salesPageId":"32058a6c-c5f3-44f1-ac29-11c0cc8a8a02-8da0d52d-cbff-4d35-8c6b-ca9279d441dd",
  “orderNumber”: “10075”,
  “orderStatus”: “8”, //8 = הוראת קבע
  “caspitBusinessId”: “dc30e052-b06c-469d-a388-63818d656f82”,    //המפתח של העסק של המשתמש בכספית
  “contactId”: “f0a3c6f6-f386-44d7-9a8f-2d51e6bd70e2”,   //המפתח של הלקוח בכספית
  “customerName”: “מנחם ברוך שוורץ”,
  “osekMorshe”: “514001432”,
  “address1”: “דניאל הכהן 8”,
  “address2”: “דירה 6”,
  “city”: “בני ברק”,
  “postalCode”: “6554438”,
  “mobilePhone”: “054-9967766”,
  “email”: “dror@caspit.biz”,
  “total”: “12.98000000”,
  “vat”: “1.98000000”,
  “extraField1”: null, //בדף המכירה אפשר להגדיר עד 3 שדות אופציונליים לקלוט מידע כמו מקצוע, תחום עניין, בקשות מיוחדות וכו'
  “extraField2”: null,
  “extraField3”: null,
  “trxId”: “728282-829”,
  “comments”: “הזמנה ממערכת המסחר \"סחר ים\" גרסה 6.8.565”, 
  “productId1”: “0b0c7f50-49ae-47db-a358-0502121e0c16”,
  “productCatalogNumber1”: “101010”,
  “ProductName1”: “פריט 1”,
  “unitNumber1”: “1”,
  “unitPrice1”: “11.000”,
  “PreAuthorizedDebit”: “{\r\n  \”PreAuthorizedDebitId\”: \”9ad360d1-8cdd-4413-8124-a6c8c146e0c1-df7aa678-a065-4dd2-97f5-1f94c90ee373\”,\r\n  \”PreAuthorizedDebitNumber\”: 2216,\r\n  \”ContactId\”: \”f0a3c6f6-f386-44d7-9a8f-2d51e6bd70e2\”,\r\n  \”TemplateId\”: \”הזמנה 10075\”,\r\n  \”Template\”: {\r\n    \”BusinessId\”: \”dc30e052-b06c-469d-a388-63818d656f82\”,\r\n    \”DocumentId\”: \”הזמנה 10075\”,\r\n    \”DocumentSource\”: 0,\r\n    \”DocumentNumberBranch\”: 1,\r\n    \”TrxTypeId\”: 51,\r\n    \”Number\”: \”01/990031\”,\r\n    \”Date\”: \”2026-07-15\”,\r\n    \”CustomerId\”: \”f0a3c6f6-f386-44d7-9a8f-2d51e6bd70e2\”,\r\n    \”CustomerBusinessName\”: \”מנחם ברוך שוורץ\”,\r\n    \”CustomerOsekMorshe\”: \”514001432\”,\r\n    \”CustomerAddress1\”: \”דניאל הכהן 8\”,\r\n    \”CustomerCity\”: \”בני ברק\”,\r\n    \”CustomerPostalCode\”: \”6554438\”,\r\n    \”CustomerEmail\”: \”dror@caspit.biz\”,\r\n    \”MobilePhone\”: \”054-9967766\”,\r\n    \”Details\”: \”מספר הזמנה: 10075 | הערות להזמנה: הזמנה ממערכת המסחר \\\"סחר ים\\\" גרסה 6.8.565 | חשבונית במייל: כן | מספר תשלומים: 1\”,\r\n    \”TotalLinesChargeVAT\”: 11.000000,\r\n    \”Rebate\”: 0.0,\r\n    \”RebatePercent\”: 0.0,\r\n    \”RountTotal\”: false,\r\n    \”RebateRounding\”: 0.0,\r\n    \”TotalBeforeVAT\”: 11.000000,\r\n    \”TotalBeforeVATChargeVAT\”: 11.000000,\r\n    \”TotalNoChargeVat\”: 0.00,\r\n    \”Vat\”: 1.98000000,\r\n    \”Total\”: 12.98000000,\r\n    \”EffectiveTotal\”: 0.0,\r\n    \”VatRate\”: 18.00,\r\n    \”Payment\”: 0.0,\r\n    \”TaxDeduction\”: 0.0,\r\n    \”TotalPayment\”: 0.0,\r\n    \”ReceiptCurrencySymbol\”: \”₪\”,\r\n    \”ReceiptRate\”: 1.0,\r\n    \”TaxDeductionNIS\”: 0.0,\r\n    \”PaymentNIS\”: 0.0,\r\n    \”TotalPaymentNIS\”: 0.0,\r\n    \”DocumentLines\”: [\r\n      {\r\n        \”Number\”: 1,\r\n        \”ProductId\”: \”0b0c7f50-49ae-47db-a358-0502121e0c16\”,\r\n        \”ProductCatalogNumber\”: \”101010\”,\r\n        \”ProductName\”: \”פריט 1\”,\r\n        \”UnitPrice\”: 11.0000,\r\n        \”Qty\”: 1.0,\r\n        \”CurrencySymbol\”: \”₪\”,\r\n        \”Rate\”: 1.00,\r\n        \”Rebate\”: 0.00,\r\n        \”ExtendedPrice\”: 11.000000,\r\n        \”ChargeVAT\”: true,\r\n        \”VATRate\”: 0.0,\r\n        \”VAT\”: 1.98000000\r\n      }\r\n    ],\r\n    \”ReceiptLines\”: [],\r\n    \”TrxCode\”: \”הכנסות/מכירות\”,\r\n    \”TrxCodeNumber\”: 3,\r\n    \”Status\”: 0,\r\n    \”DueDate\”: \”2026-07-15\”,\r\n    \”RowVersion\”: \”AAAAAAFjYSk=\”,\r\n    \”LinkToPdf\”: \”https://localhost:44310/api/v1/Pdf/%d7%94%d7%96%d7%9e%d7%a0%d7%94+10075?token=_REPLACE_WITH_YOUR_TOKEN_\”,\r\n    \”RelatedDocuments\”: [],\r\n    \”DateCreated\”: \”2026-07-15\”,\r\n    \”UserCreated\”: \”demo\”,\r\n    \”DateUpdated\”: \”2026-07-15\”,\r\n    \”UserUpdated\”: \”demo\”\r\n  },\r\n  \”Status\”: 1,\r\n  \”ChargePeriod\”: 1,\r\n  \”DateStart\”: \”2026-07-15\”,\r\n  \”DateEnd\”: \”2027-06-15\”,\r\n  \”DateOfLastCharge\”: \”2000-01-01\”,\r\n  \”NumOfCharges\”: 12,\r\n  \”NumOfChargesAlreadyCharged\”: 0,\r\n  \”Description\”: \”בדיקה של הוראת קבע\”,\r\n  \”NextDocument\”: 0,\r\n  \”NextDocumentTrxCodeId\”: 75237,\r\n  \”ChargeAmount\”: 12.98000000,\r\n  \”IsActive\”: true,\r\n  \”DebitCahrages\”: [],\r\n  \”DateCreated\”: \”2026-07-15\”,\r\n  \”UserCreated\”: \”demo\”,\r\n  \”DateUpdated\”: \”2026-07-15\”,\r\n  \”UserUpdated\”: \”demo\”\r\n}”
}

הערה: בשל הצורך לתמוך במערכות קיימות כל השדות ב-json הם מסוג string כולל השדה PreAuthorizedDebit שמכיל stringified json. לכן אם יש עניין בפרטים של הוראת הקבע, יש צורך לשלוף את ה-string ולבצע parsing נוסף בכדי לקבל אותו בתור אוביקט. אין כרגע תיעוד של מבנה ה-Order, אבל אני חושב שהוא די ברור. הוא כולל את פרטי ההזמנהף פרטי דף המכירה שממנו נוצרה, פרטי הלקוח, הפריטים שנבחרו, עלות הפריטים, כמויות ומחירים. הפריטים ממוספרים 1, 2, 3, וכו'. יש תיעוד של המבנה של האובייקט של הוראת קבע כאן: https://app.caspitweb.biz/ApiHelp/ResourceModel?modelName=CaspitPreAuthorizedDebit

בעיית ה-CVV

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

הגרסה של כספית

המודול מומש בכספית גרסה 2.4.9692.20830