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 | לא | מספר ח.פ או ת.ז של הלקוח | |
תלוי | כתובת המייל של הלקוח, חובה אם send_email=true | ||
address | כן | כתובת הלקוח | |
city | לא | עיר | |
zip | לא | מיקוד | |
country | לא | מדינה, לפי קודי מדינות | |
accounting_key | לא | מפתח לקוח חיצוני (הנהלת חשבונות) |
שדה הכנסות (income)
שם שדה | חובה | ברירת מחדל | הערות |
---|---|---|---|
catalog_num | לא | מספר קטלוגי, אם לא נשלח לא יופיע במסמך | |
price | כן | מחיר ליחידה, בפורמט של מספר עשרוני עם עד 2 ספרות אחרי הנקודה | |
quantity | לא | 1 | כמות יחידות |
description | כן | תיאור שורת ההכנסה, שם הפריט וכד'. | |
vat | לא | 1 | האם הסכום כולל מע"מ, פטור ממע"מ או יש להוסיף מע"מ. קודי תנועות מע"מ |
המשך קריאה: