📘 תיעוד API של תקבול

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

🔗 התחלת עבודה: לקבלת פרטי גישה לסביבת בדיקות (sandbox) וגישה לפורטל המערכת:

https://app.takbull.co.il

📦 סביבת פיתוח Postman: מעבר למרחב

🔐 אימות (Authentication)

כל קריאה לממשק תקבול דורשת אימות באמצעות שני פרמטרים שמועברים בכותרות (headers) של הבקשה:

• API_Key – מפתח ציבורי
• API_Secret – מפתח פרטי

את המפתחות תקבלו מצוות התמיכה בעת פתיחת חשבון.

curl --location 'https://api.takbull.co.il/api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl' \
--header 'Content-Type: application/json' \
--header 'API_Secret: YOUR_SECRET' \
--header 'API_Key: YOUR_KEY'

🧾 יצירת הזמנה ותהליך תשלום

תהליך יצירת ההזמנה מתבצע בשלבים הבאים:

1. שולחים פרטי הזמנה לשרת
2. מקבלים מזהה ייחודי להזמנה (uniqId)
3. מפעילים תשלום באמצעות Redirect או Iframe
4. המשתמש מועבר לכתובת RedirectAddress לאחר התשלום
5. המערכת שולחת התראת IPN עם סטטוס התשלום

{
  "order_reference": "A11A234",
  "OrderTotalSum": 150.77,
  "RedirectAddress": "someurl.com"
}

✅ שימו לב: חובה להגדיר גם כתובת IPN לקבלת עדכון תשלום, אחרת לא תתקבל התראה.

📦 פרמטרים להזמנה

בעת יצירת ההזמנה יש להוסיף את הפרמטרים הבאים בבקשת ה-POST לכתובת:

להלן רשימת הפרמטרים העיקריים עם הסבר:

פרמטר	טיפוס	חובה	תיאור
order_reference	String	כן	מזהה פנימי של ההזמנה במערכת שלכם.
OrderTotalSum	Number	כן	סכום ההזמנה הכולל לתשלום.
RedirectAddress	String	כן	הכתובת אליה יועבר המשתמש לאחר התשלום.
IPNAddress	String	לא	כתובת ה-IPN לקבלת עדכון בזמן אמת על תוצאה.
DisplayType	String	לא	'Iframe' או 'redirect' להצגת טופס התשלום.
PostProcessMethod	Number	לא	0 להפניה רגילה, 1 לשליחת event לחלון.
CancelReturnAddress	String	לא	כתובת להחזרת המשתמש במקרה ביטול.
CustomerFullName	String	לא	שם מלא של הלקוח.
Customer	Object	לא	אובייקט הכולל פרטים מלאים על הלקוח (ראו למטה).
DealType	Number	לא	סוג עסקה: רגיל=1, תשלומים=2, מנוי=4, טוקן=6.
PaymentMethodType	Number	לא	סוג תשלום: אשראי=3 (ברירת מחדל), Bit=21.
Currency	String	לא	סוג מטבע: ILS / USD / EUR.
Language	String	לא	שפת הטופס: "he", "en", "fr".
CreateDocument	Boolean	לא	האם ליצור מסמך לאחר התשלום (חשבונית / קבלה).
Products	Array	לא	מערך מוצרים הכולל שם, מחיר, כמות ועוד (ראו למטה).

👤 אובייקט לקוח (Customer)

שדה	טיפוס	חובה	תיאור
FullName	String	כן	שם מלא של הלקוח
Email	String	כן	כתובת דוא"ל של הלקוח
Phone	String	כן	מספר טלפון
IdNumber	String	לא	מספר זהות או ח.פ.
Address	String	לא	כתובת מלאה
City	String	לא	עיר
ZipCode	String	לא	מיקוד
Country	String	לא	מדינה

📦 אובייקט מוצר (Products)

שדה	טיפוס	חובה	תיאור
ProductName	String	כן	שם המוצר
Price	Number	כן	מחיר ליחידה
Quantity	Number	כן	כמות נדרשת
Description	String	לא	תיאור נוסף
ProductCode	String	לא	קוד מזהה פנימי/חיצוני
VATType	Number	לא	סוג מע"מ (0=ללא, 1=כולל, 2=לא כולל)

✳️ דוגמת בקשת JSON ניתן לראות למעלה בדוגמה.

📎 להסבר מלא עם כל הפרמטרים האפשריים, ניתן לעיין בתיעוד ב-Postman.

📥 תגובת שרת

לאחר שליחת הבקשה, השרת מחזיר את התגובה הבאה:

{
  "uniqId": "A1B2C3D4",
  "PaymentPageUrl": "https://api.takbull.co.il/payment/A1B2C3D4",
  "Status": 1,
  "Message": "הצלחה",
  "Errors": []
}

• uniqId – מזהה ייחודי להזמנה (לשימוש באימות עתידי).
• PaymentPageUrl – הקישור לעמוד התשלום עבור המשתמש.
• Status – סטטוס התגובה (1 = הצלחה, 0 = כישלון).
• Message – הודעה טקסטואלית לגבי תוצאת הבקשה.
• Errors – מערך שגיאות אם היו.

🔄 אימות הזמנה

לאחר קבלת התראה או ביצוע תשלום, ניתן לבצע בדיקה חוזרת על סטטוס ההזמנה:

{ "uniqId": "..." }

📬 IPN – עדכון תשלום (Webhook)

מערכת תקבול תשלח בקשה אוטומטית (Webhook) לכתובת שהגדרת – עם פרטי העסקה, סטטוס התשלום, טוקן, מסמך וכו'.

מומלץ: לטפל בבקשה זו בשרת שלכם ולבצע עיבוד מתאים.

💳 חיוב לפי טוקן

במקום להזין פרטי אשראי שוב – ניתן לשמור טוקן לאחר עסקה ראשונה ולחייב באמצעותו (מתאים למנויים או טעינה חוזרת).

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

פרמטר	טיפוס	חובה	תיאור
Token	String	כן	המזהה המאובטח מהעסקה הראשונה
OrderTotalSum	Number	כן	סכום לתשלום
order_reference	String	כן	מזהה הזמנה פנימי
IPNAddress	String	לא	כתובת לקבלת התראת תשלום
RedirectAddress	String	לא	כתובת להעברת המשתמש בסיום התהליך
CreateDocument	Boolean	לא	אם להפיק חשבונית/קבלה
Products	Array	לא	רשימת מוצרים עבור יצירת מסמך

📄 תיעוד באנגלית – ChargeToken

🧾 יצירת מסמכים

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

🔙 ביטול עסקה / החזר

ניתן לבצע ביטול מלא, החזר חלקי או ביטול עם מסמך נלווה (למשל תעודת זיכוי).

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

פרמטר	טיפוס	חובה	תיאור
uniqId	String	כן	המזהה של העסקה המקורית
RefundAmount	Number	לא	סכום להחזר (אם לא נשלח – מבוצע ביטול מלא)
CancelReason	String	לא	סיבת הביטול או הערה פנימית
CreateDocument	Boolean	לא	אם ליצור תעודת זיכוי

📄 תיעוד באנגלית – Refund

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

📨 יצירת קשר

לשאלות טכניות, תמיכה או פתיחת משתמשים – ניתן לפנות אלינו:

support@takbull.co.il