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

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

🔗 פורטל המערכת (app.takbull.co.il) 📦 סביבת פיתוח Postman תיעוד באנגלית (Apiary)

🔐 אימות (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 עם סטטוס התשלום
Endpoint:
POST /api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl 
{
  "order_reference": "A11A234",
  "OrderTotalSum": 150.77,
  "RedirectAddress": "someurl.com"
}
✅ שימו לב: חובה להגדיר גם כתובת IPN לקבלת עדכון תשלום, אחרת לא תתקבל התראה.

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

בעת יצירת ההזמנה יש להוסיף את הפרמטרים הבאים בבקשת ה-POST לכתובת:
POST /api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl
להלן רשימת הפרמטרים העיקריים עם הסבר:
פרמטר טיפוס חובה תיאור
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 – מערך שגיאות אם היו.

🧭 רשימת Endpoints מרכזיים (Reference)

Endpoints נפוצים בממשק External API:
  • POST /api/ExtranalAPI/GetTakbullPaymentPageRedirectUrl – יצירת הזמנה וקבלת כתובת תשלום
  • POST /api/ExtranalAPI/ValidateNotification – אימות סטטוס (חובה לבצע אחרי IPN/Redirect)
  • POST /api/ExtranalAPI/ChargeToken – חיוב חוזר באמצעות טוקן
  • POST /api/ExtranalAPI/Refund – ביטול עסקה / החזר מלא או חלקי
Endpoints נפוצים במסמכים:
  • POST /api/DocumentApi/Create – יצירת מסמך (חשבונית/קבלה/חשבונית מס קבלה/זיכוי ועוד)
🇬🇧 למפרט מלא, דוגמאות ופרמטרים נוספים: תיעוד API באנגלית (Apiary)

🔄 אימות הזמנה

לאחר קבלת התראה או ביצוע תשלום, ניתן לבצע בדיקה חוזרת על סטטוס ההזמנה:
Endpoint:
POST /api/ExtranalAPI/ValidateNotification 
{ "uniqId": "..." }
דוגמה לבקשת Validate (מומלץ): 
{
  "uniqId": "A1B2C3D4"
}
דוגמה לתשובת Validate (אפשרי): 
{
  "Status": "Approved",
  "Amount": 150.77,
  "Currency": "ILS",
  "Token": "tok_456",
  "TransactionId": "TX987",
  "Message": "העסקה אושרה",
  "Errors": []
}
⚠️ הערה חשובה: גם אם המשתמש חזר ב-Redirect, וגם אם התקבל IPN — עדיין מומלץ לבצע Validate כדי לוודא סטטוס אמיתי בשרת.

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

מערכת תקבול תשלח בקשה אוטומטית (Webhook) לכתובת שהגדרת – עם פרטי העסקה, סטטוס התשלום, טוקן, מסמך וכו'.
מומלץ: לטפל בבקשה זו בשרת שלכם ולבצע עיבוד מתאים.
דוגמה למבנה נתונים אפשרי שתקבלו ב-IPN: 
{
  "order_reference": "A11A234",
  "uniqId": "A1B2C3D4",
  "TransactionId": "TX987",
  "Status": "Approved",
  "OrderTotalSum": 150.77,
  "Currency": "ILS",
  "Token": "tok_456",
  "DocumentUrl": "https://...."
}
✅ Best Practice: קבלתם IPN → שמרו לוג → החזירו 200 → בצעו ValidateNotification כדי לאמת סופית.

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

במקום להזין פרטי אשראי שוב – ניתן לשמור טוקן לאחר עסקה ראשונה ולחייב באמצעותו (מתאים למנויים או טעינה חוזרת).
POST /api/ExtranalAPI/ChargeToken
יש לשלוח את הפרמטרים הבאים:
פרמטר טיפוס חובה תיאור
Token String כן המזהה המאובטח מהעסקה הראשונה
OrderTotalSum Number כן סכום לתשלום
order_reference String כן מזהה הזמנה פנימי
IPNAddress String לא כתובת לקבלת התראת תשלום
RedirectAddress String לא כתובת להעברת המשתמש בסיום התהליך
CreateDocument Boolean לא אם להפיק חשבונית/קבלה
Products Array לא רשימת מוצרים עבור יצירת מסמך
דוגמה לבקשת חיוב טוקן (ChargeToken): 
{
  "Token": "tok_456",
  "OrderTotalSum": 99.90,
  "order_reference": "ORDER124",
  "IPNAddress": "https://example.com/ipn",
  "RedirectAddress": "https://example.com/success",
  "CreateDocument": true,
  "Products": [
    {
      "ProductName": "מוצר לדוגמה",
      "Price": 99.90,
      "Quantity": 1,
      "Description": "תיאור מוצר",
      "ProductCode": "SKU-001",
      "VATType": 1
    }
  ]
}
דוגמה לתשובה אפשרית: 
{
  "uniqId": "Z9Y8X7W6",
  "Status": 1,
  "Message": "הצלחה",
  "Errors": []
}
📄 תיעוד באנגלית – ChargeToken

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

ממשק יצירת מסמכים מאפשר הפקת חשבוניות, קבלות, תרומות ועוד ישירות לאחר ביצוע תשלום או פעולה ידנית.
POST /api/DocumentApi/Create
סוגי מסמכים נפוצים (דוגמאות):
  • Receipt – קבלה
  • Invoice – חשבונית
  • InvoiceReceipt – חשבונית מס / קבלה
  • CreditInvoice – חשבונית זיכוי
דוגמה לבקשת יצירת מסמך: 
{
  "uniqId": "A1B2C3D4",
  "DocumentType": "InvoiceReceipt",
  "Customer": {
    "FullName": "ישראל ישראלי",
    "Email": "test@test.com",
    "Phone": "0500000000",
    "IdNumber": "123456789",
    "Address": "רחוב הדוגמה 1",
    "City": "תל אביב",
    "ZipCode": "0000000",
    "Country": "IL"
  },
  "Products": [
    {
      "ProductName": "מוצר לדוגמה",
      "Price": 150.77,
      "Quantity": 1,
      "Description": "תיאור מוצר",
      "ProductCode": "SKU-001",
      "VATType": 1
    }
  ]
}
דוגמה לתשובה אפשרית: 
{
  "Status": 1,
  "Message": "המסמך נוצר בהצלחה",
  "DocumentUrl": "https://....",
  "Errors": []
}

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

ניתן לבצע ביטול מלא, החזר חלקי או ביטול עם מסמך נלווה (למשל תעודת זיכוי).
POST /api/ExtranalAPI/Refund
יש לשלוח את הפרמטרים הבאים:
פרמטר טיפוס חובה תיאור
uniqId String כן המזהה של העסקה המקורית
RefundAmount Number לא סכום להחזר (אם לא נשלח – מבוצע ביטול מלא)
CancelReason String לא סיבת הביטול או הערה פנימית
CreateDocument Boolean לא אם ליצור תעודת זיכוי
דוגמה לבקשת Refund (החזר מלא/חלקי): 
{
  "uniqId": "A1B2C3D4",
  "RefundAmount": 150.77,
  "CancelReason": "ביטול לפי בקשת לקוח",
  "CreateDocument": true
}
דוגמה לתשובה אפשרית: 
{
  "Status": 1,
  "Message": "ההחזר בוצע בהצלחה",
  "Errors": []
}
📄 תיעוד באנגלית – Refund

📌 קודי סטטוס ושגיאות נפוצות

סטטוסים נפוצים:
Status משמעות
Approved אושר
Declined נדחה
Pending בהמתנה
Refunded זוכה
שגיאות נפוצות:
קוד תיאור
401 API Key / Secret שגוי
400 שדות חסרים / בקשה לא תקינה
500 שגיאת מערכת

✅ Best Practices מומלצים ליישום

  • תמיד לבצע Validate – לאחר Redirect, לאחר IPN, וגם כאשר הלקוח מדווח “שילמתי”.
  • לא להסתמך על Redirect בלבד – זהו Flow צד לקוח, ולא מקור אמת.
  • להחזיר 200 מהר ב-IPN – ואז לבצע עיבוד לוגי/Validate בצורה אסינכרונית בצד שרת (כדי למנוע timeouts).
  • OrderId / order_reference חייב להיות ייחודי – כדי למנוע התנגשויות בהזמנות.
  • לא לחשוף API Keys בצד לקוח – מפתחות חייבים להיות בשרת בלבד.
  • לשמור Token בצורה מאובטחת – זהו מזהה רגיש לחיוב עתידי.
  • לשמור לוגים – לכל IPN/Validate/Refund כדי שיהיה trace מלא לתמיכה ולבקרה.

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

1. מה זה API ואיך משתמשים בו?

API הוא ממשק שמאפשר לתוכנות "לדבר" זו עם זו. למשל: אתר אינטרנט שולח בקשה לתשלום – ותקבול מבצעת את הפעולה ברקע.

🔗 הסבר ב-MDN

2. מה זה Token ולמה הוא משמש?

Token הוא מזהה מאובטח שנוצר לאחר תשלום – דרכו ניתן לחייב שוב מבלי לחשוף פרטי אשראי. חובה לאחסן אותו בצורה מאובטחת.

🔗 הסבר באתר Auth0

3. מה ההבדל בין Redirect ל-Iframe?

Redirect: מעביר את המשתמש לעמוד חיצוני (עמוד תשלום של תקבול)
Iframe: מטמיע את טופס התשלום בעמוד שלך, ללא מעבר.

🔗 מידע נוסף על iframe

📨 יצירת קשר

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