API להצגת טופס סליקה והפקת חשבונית אוטומטית באתרי מסחר

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

המדריך הבא מציג הנחיות לממשק ה- API הישן. לממשק ה- API החדש שלנו, לחצו כאן.

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

 

דרישות מקדימות לשימוש בממשק הסליקה וה API

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

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

 

תהליך השימוש בממשק להצגת טופס סליקה

ממשק API זה מקבל מכם פרמטרים שונים כגון המוצרים שנרכשים, סכום הרכישה, שפה (עברית / אנגלית) וסוג המסמך שברצונכם להפיק. על מבנה הנתונים שמתאר את הפרמטרים לחיפוש להישלח למערכת חשבונית ירוקה בפורמט של JSON ושיטת POST.

זהו מבנה נתונים לדוגמא שעליכם לשלוח בבקשה להצגת טופס הסליקה, עם חיוב של ₪10:

{
  "timestamp": 1424332717,
  "client": {
    "name": "שם הלקוח",
    "email": "email@wxample.com",
    "send_email": true
  },
  "income": [
    {
      "price": 10,
      "description": "מוצר לדוגמא"
    }
  ]
}

 

את אובייקט הנתונים, שנקרא לו לצורך הענין בשם params, יש לחתום באופן הבא (דוגמא ב php):

	$params_encoded = json_encode($params);
	$signature = base64_encode(hash_hmac('sha256', $params_encoded, "{api_secret}", true));

 

לאחר מכן, יש לשלוח את החתימה ואת המפתח הציבורי שלכם למערכת ה API (דוגמא ב php):

$data = array(
	"apiKey" => $apiKey,
	"params" => $params,
	"sig" => $signature
);

//Initializing curl
$ch = curl_init();

//Configuring curl options
$options = array(
    CURLOPT_URL => "https://www.greeninvoice.co.il/api/documents/pay",
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => "data=" . urlencode(json_encode($data)),
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_RETURNTRANSFER => true
);

//Setting curl options
curl_setopt_array($ch, $options);

//Getting results
$result = curl_exec($ch); // Getting jSON result string
curl_close($ch);

 

התשובה שמתקבלת תכיל את כתובת עמוד הסליקה (page_url), בתוך שדה data, אליו עליכם לבצע redirect:

{
  "error_code": 0,
  "error_description": "OK",
  "timestamp": 1424333829,
  "processing_time_ms": 162.267,
  "data": {
    "page_url": "https://www.example.com/iframe_form"
  }
}

 

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

//Get real document URLs    
$ticketId = $_POST["ticket_id"]; //מספר בקשה
$documentUrl = $_POST["url"]; //כתובת מסמך מקור להורדה
$id = $_POST["id"]; //מזהה ייחודי של המסמך 
$documentId = $_POST["document_id"]; //מספר המסמך שהופק
$externalData = $_POST["external_data"]; //נתונים שהזנתם בבקשה המקורית
$clientId = $_POST["client_id"]; //מזהה לקוח במערכת שנוסף בבקשת יצירת מסמך

 

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

שם שדהחובהברירת מחדלהערות
timestampכן זמן נוכחי בשניות מאז 01/01/1970
callback_urlלא כתובת דף לקבלת עדכון לאחר סיום התשלום והפקת מסמך
success_urlלאמערכתכתובת דף שמוצג למשתמש במקרה של הצלחה בתשלום בכרטיס אשראי (חובה HTTPS)
failure_urlלאמערכתכתובת דף שמוצג למשתמש במקרה של כשלון בתשלום בכרטיס אשראי (חובה HTTPS)
doc_typeלא סוג מסמך, אם לא נשלח יוגדר קבלה לעוסק פטור וחשבונית מס קבלה לעוסק מורשה
descriptionלא תיאור כללי של המסמך
currencyלאILSמטבע
langלאheשפת המסמך, עברית (he) או אנגלית (en)
external_dataלא שדה לנתונים חוזרים. ערך שתזינו כאן יוחזר לכם לאחר סיום התשלום והפקת המסמך.
clientכן אובייקט נתונים של לקוח, פירוט למטה
incomeכן מערך של שורות מוצרים לפירוט החיוב, פירוט למטה
reply_to_emailלאאימייל עסקלכתובת זו ישלחו מיילים, כאשר משתמש מגיב למייל האוטומטי הנשלח אליו
max_paymentsלא1מספר תשלומים לבחירת המשלם (1-36)

 

 שדה לקוח (client)

שם שדהחובהברירת מחדלהערות
idלא מספר מזהה של הלקוח בחשבונית ירוקה, אם ממלאים שדה זה באופן תקין אין חובה למלא את שדות החובה של הלקוח
addלאfalseהאם להוסיף את הלקוח לחשבון המשתמש במערכת
send_emailלאfalseהאם לשלוח ללקוח את החשבונית במייל
email_subjectלאכפי שמוגדר באתרנושא המייל הנשלח ללקוח
email_bodyלאכפי שמוגדר באתרתוכן המייל הנשלח ללקוח
nameכן שם הלקוח
tax_idלא מספר ח.פ או ת.ז של הלקוח
emailתלוי כתובת המייל של הלקוח, חובה אם send_email=true
addressכן כתובת הלקוח
cityלא עיר
zipלא מיקוד
countryלא מדינה, לפי קודי מדינות
accounting_keyלא מפתח לקוח חיצוני (הנהלת חשבונות)

 

שדה הכנסות (income)

שם שדהחובהברירת מחדלהערות
catalog_numלא מספר קטלוגי, אם לא נשלח לא יופיע במסמך
priceכן מחיר ליחידה, בפורמט של מספר עשרוני עם עד 2 ספרות אחרי הנקודה
quantityלא1כמות יחידות
descriptionכן תיאור שורת ההכנסה, שם הפריט וכד'.
vatלא1האם הסכום כולל מע"מ, פטור ממע"מ או יש להוסיף מע"מ. קודי תנועות מע"מ
 

 

 

המשך קריאה:

עדיין זקוקים לעזרה?

אנחנו כאן בכל עניין ולכל שאלה. ביום עסקים רגיל, בין השעות 9:00 ל-18:00, אנחנו עונים תוך מספר דקות.