API של תקבול.
החיבור בין המערכת שלכם לתשלום.

מהחיבור הראשון ועד לתשלום מאומת

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

1. יוצרים הזמנה בשרתשולחים סכום ופרטי הזמנה ומקבלים uniqId.
2. מציגים דף תשלוםמפנים את הלקוח או מטמיעים iframe.
3. מאמתים את התוצאהמקבלים IPN ובודקים את התשלום באמצעות API.
4. מעדכנים את המערכתמתאימים את העסקה להזמנה ובודקים גם את המסמך.

אימות וחיבור לסביבת הבדיקות

API_Key: <YOUR_API_KEY>
API_Secret: <YOUR_API_SECRET>
Content-Type: application/json

יצירת הזמנה ודף תשלום

{
  "responseCode": 0,
  "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a"
}

{
  "order_reference": "ORDER-1001",
  "OrderTotalSum": 150,
  "Currency": "ILS",
  "Language": "he",
  "DealType": 1,
  "PaymentMethodType": 3,
  "DisplayType": "redirect",
  "PostProcessMethod": "0",
  "RedirectAddress": "https://example.com/payment/return",
  "CancelReturnAddress": "https://example.com/cart",
  "IPNAddress": "https://example.com/payment/ipn",
  "CreateDocument": false,
  "Customer": {
    "CustomerFullName": "לקוח לדוגמה",
    "Email": "customer@example.com"
  }
}

פרטי לקוח ומוצרים

הצגת דף התשלום: Redirect, iframe ו־Bit

Bit ואמצעי תשלום נוספים

לתשלום ב־Bit שולחים PaymentMethodType=21. בגלישה בנייד משתמשים ב־IsMobile=true בהתאם להקשר; כאשר מוחזרת כתובת url מפנים אליה כדי לאפשר את המשך התשלום באפליקציה.

אימות תשלום לפני עדכון ההזמנה

{
  "uniqId": "89fd6612-2c4b-4a7b-91a3-dd9bdf0ee26a"
}

IPN ו־Webhook: לקבל עדכונים גם בלי חזרה מהדפדפן

יש להבחין בין שלושה מנגנונים: עדכון תשלום לכתובת IPNAddress של ההזמנה, Webhooks המוגדרים לחשבון, ועדכון הפעלת חשבון ספק ל־IpnUrl. מבנה ההודעה והשמות אינם זהים.

אירועי Webhook כוללים שינוי הזמנה כללי (0), מסמך חדש (10), תשלום מוצלח (20), תשלום שנכשל (30), הזמנה ממתינה (40) והזמנה שננטשה (50). ב־GET של הזמנה מוחזר מזהה לשליפה; באירוע מסמך מוחזר invoiceUniqId.

בתיעוד ה־Webhook מצוינים עד שלושה ניסיונות מסירה בסך הכול, במרווח של 15 דקות לאחר כשל. למדריך ה־Webhook המלא.

שליפת עסקה והזמנה מלאה

GetTransaction מאפשרת לבדוק עסקה בודדת: סכום, מטבע, סטטוס, אמצעי תשלום, מספר תשלומים, פרטי טוקן ומצב הפקת המסמך. שדות המסמך כוללים isDocumentCreated, invoiceId, invoiceUniqId ו־documentNumber.

GetOrder מחזירה את התמונה המלאה של ההזמנה: פרטי לקוח, סכומים, מוצרים, עסקאות, מסמכים ומשלוח. בין המערכים המוחזרים: products, transactions ו־invoices.

חיוב כרטיס שמור באמצעות טוקן

{
  "order_reference": "ORDER-1002",
  "OrderTotalSum": 150,
  "Currency": "ILS",
  "Language": "he",
  "CustomerFullName": "לקוח לדוגמה",
  "CreateDocument": false,
  "IPNAddress": "https://example.com/payment/ipn",
  "CreditCard": {
    "CardExternalToken": "REPLACE_WITH_SAVED_CARD_TOKEN"
  }
}

תשלומים, הוראות קבע וביטול מנוי

תשלומים והוראת קבע הם מסלולים שונים. עסקת תשלומים משתמשת ב־DealType=2 ובשדות מספר התשלומים. יצירת הוראת קבע משתמשת ב־DealType=4 ובשדות החיוב החוזר.

לביטול מנוי שולחים את uniqId של ההזמנה המקורית שהוחזר ביצירת דף התשלום. הפעולה מתועדת כ־GET, אך משנה מצב: יש להפעיל אותה מהשרת בלבד, לאחר הרשאת משתמש ובקרה, ולא כקישור לחיץ במאמר או בדפדפן.

הפקת חשבוניות, קבלות ומסמכים

ניתן להפיק מסמך כחלק מהתשלום באמצעות CreateDocument ו־Products, או להפיק מסמך בפעולה נפרדת. לשתי האפשרויות מבנה בקשה שונה.

{
  "invoiceItems": [
    {
      "description": "שירות לדוגמה",
      "isTaxteble": false,
      "unitPrice": 150,
      "totalPrice": 150,
      "quantity": 1
    }
  ],
  "customerVM": {
    "customerFullName": "לקוח לדוגמה"
  },
  "sendToCustomer": false,
  "totalTaxAmount": 0,
  "taxtable": false,
  "totalTaxFree": 150,
  "totalPriceWithTax": 150,
  "isItemIncludeTax": false,
  "currency": "ILS",
  "language": "he",
  "documentType": 300
}

פירוט תקבולים ואמצעי תשלום

ניתן להעביר סכומי תקבולים במזומן, בהמחאות, באשראי ובהעברה בנקאית, לצד מערכי cashes, checks, wireTransfers ו־customPayments. יש לוודא התאמה בין פירוט התקבולים לבין הסכומים וסוג המסמך.

ב־customPayments מופיעים methodName, amount, creationDate, currancy, payerAccountNumber ו־referanceId. לפי טבלת התיעוד amount ו־creationDate נדרשים. האיות currancy ו־referanceId הוא האיות המתועד.

ביטול עסקה וזיכוי מלא או חלקי

{
  "RefundType": 4,
  "RefundAmount": 50,
  "TransactionInternalNumber": "00012547",
  "Comments": "זיכוי חלקי לפי בקשת הלקוח"
}

פתיחת חשבונות ספקים למרקטפלייס ולבתי תוכנה

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

נתוני הבקשה

נדרשים Email ייחודי ו־Password. לפי התיעוד, הסיסמה חייבת לכלול לפחות שמונה תווים, אות גדולה, אות קטנה, ספרה ותו מיוחד. מעבירים גם MerchantDetails ו־BusinessType בהתאם לדרישות פרטי העסק; את הסיסמה אין לרשום בלוגים.

שדות נוספים כוללים FirstName, LastName, Phone, PackageUniqId, SubscriptionPayer, RedirectUrl ו־IpnUrl. כאשר הספק משלם, RedirectUrl נדרש, ו־IpnUrl מומלץ לקבלת התוצאה בשרת.

בפתיחת חשבון סליקה Upay חדש נדרשים בפרטי העסק בין היתר Name, BusinessNumber, BusinessType, BizRegiEmail, PhoneNumber1, Address1, City, FirstName, LastName, IdentityNumber, bankcode, branchcode ו־accountnumber. קיימים גם פרטים משלימים, תאריכים ו־Mcc לפי תחום הפעילות. יש להשתמש בערכי BusinessType של תקבול, ולא בערכי סוג חברה של הספק החיצוני.

חיבור חשבון Upay קיים

כאשר כבר קיים חשבון Upay, התיעוד מאפשר להעביר בתוך MerchantDetails את IsExistingAccount=true, ProviderKey ו־ProviderSecret. כאן מדובר בפרטי הכניסה לחשבון Upay הקיים. הם נבדקים לפני גבייה; לפי התיעוד, החבילה מחויבת במלואה, כולל דמי הקמה.

הספק משלם: התהליך האסינכרוני

1. שולחים בקשת CreateAccount עם חבילה בתשלום, SubscriptionPayer="Child", RedirectUrl ו־IpnUrl.
2. שומרים את AffiliationId ואת OrderUniqId ומפנים את הספק ל־PaymentRedirectUrl. קוד 600113 מציין שדרוש תשלום, ולא שהחשבון כבר פעיל.
3. לאחר הזנת הכרטיס והשלמת התהליך נוצרים החשבון והחבילה, נפתחת הרשאת החיוב ומונפקים מפתחות לפי המודולים הכלולים.
4. מקבלים POST JSON ל־IpnUrl עם Status, StatusCode, AffiliationId, MerchantId ופרטי החיבור כאשר הונפקו. יש לקשר לבקשה המקורית ולשמור את הסודות בשרת בלבד.

יש להחזיר 2xx ל־IPN ולטפל בכפילויות לפי AffiliationId. לפי התיעוד מתבצעים עד שלושה ניסיונות מסירה במרווחי 15 דקות. בנטישת התשלום לא נשלח IPN: ניתן לקרוא שוב ל־CreateAccount עם אותו Email כדי לבטל את הבקשה הממתינה ולקבל קישור חדש. אחרי Failed בעקבות תשלום יש לפנות לתמיכה, ולא למחזר אוטומטית את הכתובת.

למרקטפלייס על WordPress ו־WooCommerce קיימת גם אפשרות חיבור באמצעות WCFM. למאמר על חיבור מרקטפלייס בוורדפרס ו־WooCommerce.

ניהול הגדרות מסמכים באמצעות API

{
  "ChildMid": "MID_EXAMPLE",
  "Language": "he",
  "Settings": {
    "EmailFromDisplayName": "העסק לדוגמה",
    "EmaiSubjectMsg": "המסמך שלך מהעסק",
    "EmailDocumentToMerchantAsCopy": true,
    "MerchantEmailToSendCopy": "merchant@example.com",
    "AddPaymentLink": true
  }
}

• סוג מסמך, מטבע ומע״מ: DefaultDocumentType, CurrencyCode, IsTaxtable, IsItemIncludeTax.
• דואר: EmailFromDisplayName, EmaiSubjectMsg, EmailBodyMsg, EmailDocumentToMerchantAsCopy ו־MerchantEmailToSendCopy. בגוף המייל קיימים מצייני מקום כגון [[customerName]] ו־[[documentType]].
• הודעות וקישורים: SmsMsg, SmsFrom ו־AddPaymentLink.
• עיצוב ותצוגה: ThemeId, HideSQU, HideUnits, KabalaWithoutItems, RoundSum, ShowCustomerBalance ושדות נוספים בתיעוד.
• מספור: DocumentNumbering מכיל רשומות עם DocumentType ו־Count. Count הוא המספר האחרון / הנוכחי ואינו יכול להיות נמוך ממספר מסמך שכבר הופק.

ריכוז הפעולות המעודכן

כל הנתיבים בטבלה יחסיים ל־https://api.takbull.co.il. פרטי הבקשה והתגובה המלאים מופיעים ב־תיעוד ה־API הרשמי.

קודי הצלחה ושגיאה: לפי הפעולה

בדיקות מומלצות לפני מעבר לייצור

• בדקו בסביבת הבדיקות הצלחה, דחייה, ביטול, נטישה, כשל בהפקת מסמך ותקלה בתקשורת.
• שמרו בנפרד את מזהה ההזמנה אצלכם, uniqId, מספר העסקה ומזהה המסמך. בפרויקט מרקטפלייס שייכו אותם גם לחשבון הספק הנכון.
• מנעו אספקה כפולה בעקבות IPN כפול.
• בדקו חיוב והפקת מסמך בנפרד. כשל במסמך אינו סיבה לחייב את הלקוח שוב.
• אל תשמרו בלוגים מפתחות, סיסמאות או טוקנים מלאים. הגבילו הרשאות, השתמשו ב־HTTPS והפרידו בין נתוני בדיקה לייצור.
• בדקו התאמה לנייד, תפעול מקלדת וכותרת ל־iframe. הציגו הודעות שגיאה ברורות בלי לחשוף פרטים רגישים.
• בדקו במיוחד את קודי המצב, האיות והאותיות הגדולות / הקטנות בכל endpoint; חלק מהדוגמאות בתיעוד אינן אחידות.

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

שאלות נפוצות למפתחים

תיעוד, דוגמאות ועזרה בחיבור

• תיעוד API העדכני של תקבול
• סביבת Postman של תקבול
• מדריך Webhook
• חיבור מרקטפלייס ב־WordPress וב־WooCommerce
• support@takbull.co.il — תמיכה טכנית