יצירת חשבוניות & מסמכים ב NAME TO VALUE API
ממשק ליצירת מסמכים חשבונאיים בממשק API
מאמר זה מסכם כיצד ניתן ליצור מסמכים באופן עצמאי ללא חיוב אשראי.
מיועד להפקת מסמך כאשר החיוב הוא לא באשראי כגון צ'קים מזומן והעברות בנקאיות.
במידת הצורך ניתן גם להצליב את המסמך לעסקת חיוב אשראי קיימת במערכת רטרו.
כאשר רוצים להפיק מסמך בעת חיוב האשראי , יש להעביר את פרטי המסמך וסוג המסמך עם פרטי החיוב ולא להשתמש בממשק זה.
הסבר שלבי העבודה:
על מנת ליצור מסמך יש לפנות פעם אחת לשרת הסליקה אישורית זהב ולעביר את הפרמטרים המתאימים. הפרמטרים מתחלקים ל 3 קבוצות:
- פרמטרים לפרטי לקוח וסוג המסמך.
- פרטי המסמך הכוללים: כותרת המסמך ושורות המסמך (חוץ ממסמך 400 ).
- אמצעי התשלום: יש להעביר אמצעי תשלום כגון : מזומן , צ'קים, חיוב אשראי שבוצע בעבר או אמצעי תשלום אחר(כגון העברה בנקאית , PayPal). ניתן להעביר מספר אמצעי תשלום שונים לאותה מסמך. ( במידה ויש אמצעי תשלום למסמך )
מקרא:
פרמטר אדום - חובה
פרמטר מודגש - מומלץ
פרמטר לא אדום ולא מודגש - אופציונלי
כתובת הפונקציה ב - Name to Value היא: https://secure.cardcom.solutions/Interface/CreateInvoice.aspx
טבלת פרמטרים לבקשה:
| פרמטר | ערכים לדוגמא |
הסבר |
|
פרמטרים לזיהוי לקוח וסוג המסמך להפקה | |||
| 1 | terminalnumber | 1000 | מספר מסוף פנימי |
| 2 | username | TestUser | שם משתמש לממשקים |
| 3 |
InvoiceType |
1 - חשבונית מס קבלה 50- הצעת מחיר 100 - הזמנה (ללא תשלום) 101 - אישור הזמנה - מאתר ( מסמך פנימי לא להנח"ש) - הזמנה ששולמה 300 - חשבון עסקה 301 - דרישה לתשלום 302 - ביטול דרישה לתשלום 305 - חשבונית מס 330 - חשבונית זיכוי 410 - החזר כספים לקוחות(קבלה זיכוי) 405 - קבלה על תרומה 406 - זיכוי קבלה תרומה(החזר כספים) 303 - חשבון קבלה (כמו חשבונית לעוסק פטור , נדיר לשימוש) 304 - חשבון קבלה זיכוי |
סוג המסמך להפקה. לעומת זאת בפניה לפונקציה של חיוב אשראי + חשבונית https://secure.cardcom.solutions/Interface/LowProfile.aspx יש להשתמש בפרמטר DocTypeToCreate במקום . |
פרטי החשבוניות- כותרת מסמך | |||
| 4 | InvoiceHead.CustName |
אלי כהן בע"מ | שם לקוח / חברה למסמך (השם שעליה תצא החשבונית) |
| 5 | InvoiceHead.SendByEmail | true | האם לשלוח מסמך בדואר אלקטרוני. במידה וכן יש לציין כתובת דואר. |
| 6 | InvoiceHead.Language |
he - עברית en - אנגלית |
שפת המסמך |
| 7 | InvoiceHead.Email | israel@gmail.com | כתובת דואר הלקוח , שלשם ישלח המסמך. (ניתן לשרשר כמה מיילים באמצעות נקודה פסיק ; ) |
| 8 | InvoiceHead.CustAddresLine1 | Saharov 22 | כתובת לקוח , שורה ראשונה |
| 9 | InvoiceHead.CustAddresLine2 | P.O. 1234 | כתובת לקוח, שורה שנייה |
| 10 | InvoiceHead.CustCity | Reshin-Le-Zion | עיר |
| 11 | InvoiceHead.CustLinePH | 03-9619611 | טלפון קווי |
| 12 | InvoiceHead.CustMobilePH | 0549876543 | טלפון נייד (במודול SMS ישלח SMS לנייד זה) |
| 13 | InvoiceHead.CompID | 040617640 | מספר ת.ז. או ח.פ חברה |
| 14 | InvoiceHead.Comments | דוגמא: אחריות של שנה מיום החשבונית (עד 250 תווים ) | הערות למסמך - יודפסו במסמך למטה |
| 15 | InvoiceHead.CoinID |
1 - שקל ראה רשימת קודי מטבעות נוספים - רשימת קודי מטבעות |
מטבע מסמך |
| 16 | InvoiceHead.ExtIsVatFree | true = מע"מ 0 False = מע"מ 18 |
האם המסמך כולו הוא ללא מע"מ - מתאים ללקוח חו"ל |
| 17 | InvoiceHead.ManualInvoiceNumber | maxint() |
מספור ידני של המסמך. ניתן לשימוש רק ביצירת מסמך ללא חיוב. יש לבקש הרשאה מיוחדת לשימוש בפרמטר זה. ראה הערות בסוף המאמר. במקרים נדירים ניתן להעביר את מספר החשבוניות שהמערכת תיצור במקום להשתמש במונה הפנימי של המערכת. שם לב! במידה וישנה התנגשות במונים החשבונית לא תיוצר , יש לבקש הרשאה מיוחדת לשימוש בפרמטר זה.
|
| 18 | InvoiceHead.IsAutoCreateUpdateAccount |
false - כל הלקוחות ירשמו על "לקוחות שונים". true - יפתח כרטיס לקוח לכל עסקה , ומידה וקים יבוצע שיוך ללקוח לפי ההסבר. |
האם ליצור ללקוח כרטיס לקוח במערכת. במידה ולא מועבר יתבצע איתור לפי מפתח זר ולאחר מכן לפי מזהה ייחודי אתר ואז לפי EMAIL לקוח. (הפרמטר הראשון שנמצע בשרת מולצב ולא ממשיך לחפש עוד ) |
| 19 | InvoiceHead.AccountForeignKey | 1234 (String) |
מספר מפתח זר של הלקוח - פעיל רק אם יוצר ללקוח כרטיס לקוח. (מספר הנח"ש) |
| 20 | InvoiceHead.InvDate |
dd/MM/yyyy | תאריך המסמך - ניתן להעביר תאריך מסמך במבנה dd/MM/yyyy - לא חובה , לפי חוק ניתן להפיק עד 14 יום אחורה . (לא פעיל בדף פרופיל נמוך) |
| 21 | InvoiceHead.DepartmentId | 123 (int) |
קוד מחלקה להצגה בדוחות והעברה להנח"ש ראה הגדרת המחלקות במסוף : מיון מסמכים ושימוש במחלקות |
| 22 | InvoiceHead.SiteUniqueId | (String) |
מזהה ייחודי לאתר - פרמטר אינפורמטיבי. (מזהה נוסף) |
| 23 | InvoiceHead.AccountID | (int) 123 | מספר הלקוח במערכת אישורית זהב לשיוך המסמך (לא פעיל בעסקה מושהית ) |
| 24 | InvoiceHead.ValueDate | dd/MM/yyyy | תאריך ערך למסמך , (לא פעיל בדף פרופיל נמוך) |
| 25 | InvoiceHead.ExternalId | (String) | מזהה מערכת חיצוני ברמת מסמך בלבד (לא נשמר ברמת כרטיס לקוח) במקרה שיועבר אותו מזהה המערכת תחזיר את אותו מסמך של המזהה המקורי ברמת החברה. |
| 26 | InvoiceHead.IsLoadInfoFromAccountID | true | בהפקת מסמך ידני בלבד, האם למשוך את פרטי הלקוח |
פרטי החשבוניות- שורות המסמך |
|||
| 27 | InvoiceLines.Description |
קורס אינטרנטי | תיאור המוצר |
| 28 | InvoiceLines.Price | 50 | מחיר יחידה של פריט לחיוב. |
| 29 | InvoiceLines.Quantity | 1 | כמות הפריטים בהעברה של כמות מעל 1 , יש להכפיל במחיר ולשלוח אמצעי תשלום מתאים. |
| 30 | InvoiceLines.ProductID | ZZASA AASSA - 12 |
קוד פריט , מק"ט , קוד מוצר - מומלץ להעביר לשם דוחות , ניתן לראות ב דוח פריטים במסמך במקרה של שני פריטים ניתן להפריד כך: InvoiceLines1.ProductID=AAA
InvoiceLines2.ProductID=BBB
|
| 31 | InvoiceLines.IsVatFree | false true |
|
פרמטרים לשורה ראשונה במסמך:
InvoiceLines1.Description=Item1&InvoiceLines1.Price=200.50&InvoiceLines1.Quantity=2
פרמטרים לשורה שנייה במסמך :
InvoiceLines2.Description=Item2&InvoiceLines2.Price=200.50&InvoiceLines2.Quantity=2
פרמטרים לשורה שלישית במסמך :
InvoiceLines3.Description=Item3&InvoiceLines3.Price=100&InvoiceLines3.Quantity=3
* אין להעביר תווים אסורים ב ערך עצמו , כמו: אמפרסנט & או נקודה פסיק ;
( לדוגמא בתיאור לחשבונית שלא יהיה פריט עם תווים אלה )
* במקרים של מספרים עשרוניים - יש לעשות חישוב ולקצץ בהתאם ל 2 ספרות אחרי הנקודה העשרונית.
* ניתן לתת שורת הנחה במינוס , אך יש לדאוג שסה"כ סכום החשבונית יהיה תואם בדיוק לסכום העסקה.
* בריבוי פריטים יש לשלוח את הבקשה ב POST ולא ב GET עקב מגבלת תווים .
אמצעי התשלום :
מזומן
| פרמטר | ערכים לדוגמא | הסבר | |
| 1 | cash | 50.30 | סכום שהועבר במזומן . |
ציקים/המחאות
| פרמטר | ערכים לדוגמא | הסבר | |
| 1 | Cheque.ChequeNumber | 1234 | מספר המחאה |
| 2 | Cheque.BankNumber | 12 | מספר בנק |
| 3 | Cheque.SnifNumber | 1 | מספר סניף בנק |
| 4 | Cheque.AccountNumber | 123456 | מספר חשבון |
| 5 | Cheque.DateCheque | dd/MM/yyyy | תאריך פירעון המחאה |
| 6 | Cheque.Sum | 100.50 | סכום המחאה |
העברה של מספר המחאות:
על מנת להעביר "מערך" של המחאות יש למספר את המחאות לדוגמה :
המחאה ראשונה : Cheque.ChequeNumber=123&Cheque.DateCheque=1/2/2011&Cheque.Sum=150.00
המחאה שנייה : Cheque1.ChequeNumber=123&Cheque1.DateCheque=2/2/2011&Cheque1.Sum=150.00
המחאה שלישית: Cheque2.ChequeNumber=123&Cheque2.DateCheque=3/2/2011&Cheque2.Sum=150.00
אשראי - הצלבת חשבונית לעסקת אשראי קיימת
ניתן להצליב עסקה שחייבה בעבר לחשבונית.
- אסור שהעסקה תהייה מוצלבת לחשבונית אחרת, יצירת החשבונית תכשל.
- יש לשם לב להצלבה נכונה של עסקאות זיכוי עם חשבוניות זיכוי.
- הפרמטר ב Web Service נקרא RciExtDealNum.
| פרמטר | ערכים לדוגמא | הסבר |
| CreditDealNum.DealNumber | 14214 (InternalDealNumber ) | מספר העסקה בדוחות קארדקום (פרמטר InternalDealNumber ) להצלבת החשבונית. בעסקת ביטול יש להעביר עסקת זיכוי/ביטול. |
ניתן להוסיף אמצעי "תשלום אחר" על חשבונית. השימוש של "תשלום אחר" הוא במידה ומתקבל כסף ממקור אחר שהוא לא כרטיס אשראי, מזומן או צ'קים כגון העברה בנקאית או קבלת תשלום פי-פאל. יש להגדיר את החשבון במערכת הניהול לפני העברת התשלום האחר בממשק ראה : הגדרות חשבוניות : חשבונות שונים.
- שם המחלקה ב Web Server היא RciExtCustome ולא CustomPay.
| פרמטר | ערכים לדוגמא | הסבר | |
| 1 | CustomPay.TransactionID | 32 | מספר חשבון המוגדר מראש במערכת הסליקה אישורית זהב. ל מנת להוסיף חשבון נוסף יש להיכנס למערכת הניהול אישורית זהב : הגדרת אמצעי תשלום נוספים יש להעביר את הנתון של המספר רץ, לדוגמא 30 הפקדה בנקאית |
| 2 | CustomPay.TranDate | 31/12/2012 | תאריך אסמכתה |
| 3 | CustomPay.Description | קבלת תשלום מPayPal | תיאור פעולה |
| 4 | CustomPay.Asmacta | 123456-ZZC | מספר אסמכתה פעולה |
| 5 | CustomPay.Sum | 150.00 | סכום |
העברה של מספר "תשלום אחר":
על מנת להעביר "מערך" של תשלום אחר יש למספר את התשלומים לדוגמה:
תשלום אחר אחד:
תשלום אחר שתיים :
תשלום אחר שלוש:
CustomPay2.TransactionID=31&CustomPay2.TranDate=31/10/2011&CustomPay2.Asmacta=ZZ123&CustomPay2.Sum=150
טבלת פרמטרים תשובה המתקבלת לאחר הפנייה :
| פרמטר | ערכים לדוגמא | הסבר | |
| 1 | ResponseCode | 0 - תקין . אחרת - שגיאה. | קוד תשובה ליצירת מסמך |
| 2 | Description | תקין | תיאור קוד תשובה ליצירת המסמך |
| 3 | InvoiceNumber | 9871 | מספר המסמך שנוצר |
| 4 | InvoiceType | 1 - חשבונית מס קבלה 2 - חשבונית מס קבלה זיכוי 3 - קבלה מלכ"ר 4 - החזר כספים לקוחות (קבלה זיכוי מלכ"ר) 101 - אישור הזמנה - מאתר ( מסמך פנימי לא להנח"ש) 102 - זיכוי הזמנה - מאתר ( מסמך פנימי לא להנח"ש) 200 - תעודת משלוח (210 - תעודת החזר) 300 - חשבון עסקה 305 - חשבונית מס (330 - חשבונית מס זיכוי) 400 - קבלה לחשבונית מס (410 - החזר כספים לקוחות) |
סוג המסמך שנוצר |
| 5 | TaxAuthorityAllocationNumber | aabbcc | מספר הקצאה רשות המיסים - רק בית עסק שלא משתמשים בהעברה להנהלת חשבונות מהמערכת שלנו צריכים פרמטר זה - נדיר |
ניתן לקבל דיווחים לווב הוק של החשבונית :
https://support.cardcom.solutions/hc/he/articles/360007138014
ניתן להוריד קוד לדוגמה ↓
יש ליצור קשר עם התמיכה לקבלת שם משתמש לבדיקות.
דוגמה:
Request
https://secure.cardcom.solutions/Interface/CreateInvoice.aspx?terminalnumber=1000&username=test2025&InvoiceType=3&InvoiceHead.CustName=yuvaltest& InvoiceHead.SendByEmail=true& InvoiceHead.Language=he
& InvoiceHead.Email=yuval@gmail.com& InvoiceHead.IsAutoCreateUpdateAccount=true&InvoiceLines.Description="test"&InvoiceLines.Price=50&InvoiceLines.Quantity=1&CustomPay.TransactionID=30
&CustomPay.TranDate=31/12/2024&CustomPay.Description="הפקדה בנקאית "&CustomPay.Asmacta=12345&CustomPay.Sum=50
Response
ResponseCode=0&Description=&InvoiceNumber=17072&InvoiceType=3&AccountID=11595&TaxAuthorityAllocationNumber=