מאמרים בקטגוריית המשנה הזאת

יצירת חשבוניות ב API

Avatar
מוטי תמיכה אישורית
  • עודכן
עקוב

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

הסבר שלבי העבודה:

על מנת ליצור מסמך יש לפנות פעם אחת לשרת הסליקה אישורית זהב ולעביר את הפרמטרים המתאימים. הפרמטרים מתחלקים ל 3 קבוצות:

  1. פרמטרים לפרטי לקוח וסוג המסמך.
  2. פרטי המסמך הכוללים: כותרת המסמך ושורות המסמך (חוץ ממסמך 400 ).
  3. אמצעי התשלום: יש להעביר אמצעי תשלום  כגון : מזומן , צ'קים, חיוב אשראי שבוצע בעבר או אמצעי תשלום אחר(כגון העברה בנקאית , PayPal). ניתן להעביר מספר אמצעי תשלום שונים לאותה מסמך. ( במידה ויש אמצעי תשלום למסמך )

מקרא:
פרמטר אדום - חובה
פרמטר מודגש - מומלץ
פרמטר לא אדום ולא מודגש - אופציונלי

כתובת הפונקציה ב -  Name to Value היא:  https://secure.cardcom.solutions/Interface/CreateInvoice.aspx

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

  פרמטר

ערכים לדוגמא

הסבר

פרמטרים לזיהוי לקוח וסוג המסמך להפקה
1 terminalnumber 1000 מספר מסוף
2 username TestUser שם משתמש לממשקים
3
 

InvoiceType

1 - חשבונית מס קבלה
2 -  חשבונית זיכוי והחזר כספים
3 - קבלה מלכ"ר / פטור מע"מ
4 - קבלה מלכ"ר זיכוי (החזר כספים)

50- הצעת מחיר

100 - הזמנה (ללא תשלום)

101 - אישור הזמנה - מאתר  ( מסמך פנימי לא להנח"ש) - הזמנה ששולמה
102 - זיכוי הזמנה - מאתר (מסמך פנימי לא להנח"ש) - הזמנה שזוכתה

200 - תעודת משלוח 210 - תעודת החזרה

300 - חשבון עסקה

301 - דרישה לתשלום

302 - ביטול דרישה לתשלום

305 - חשבונית מס

330 - חשבונית זיכוי
400 - קבלה (לחשבונית)

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 -  שקל
2  - דולר 
978 - אירו

ראה רשימת קודי מטבעות נוספים - רשימת קודי מטבעות

 מטבע מסמך -
תקף רק בהפקת מסמך ללא חיוב ,
במידה ומפיקים מסמך עם חיוב המטבע נקבע לפי מטבע חיוב אשראי
16 InvoiceHead.ExtIsVatFree true = מע"מ 0
False = מע"מ 17

 האם המסמך כולו הוא ללא מע"מ - מתאים ללקוח חו"ל
17  InvoiceHead.ManualInvoiceNumber  maxint() מספור ידני של המסמך. ניתן לשימוש רק ביצירת מסמך ללא חיוב. יש לבקש הרשאה מיוחדת לשימוש בפרמטר זה. ראה הערות בסוף המאמר.

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

 
18  InvoiceHead.IsAutoCreateUpdateAccount false - כל הלקוחות ירשמו על "לקוחות שונים".

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

האם ליצור ללקוח כרטיס לקוח במערכת.
מצב זה חובה להעביר את פרמטר: InvoiceHead.CompID - ת.ז. / ח.פ. של הלקוח.
אם הלקוח כבר קיים לא יפתח כרטיס חדש.

במידה ולא מועבר יתבצע איתור לפי  מפתח זר ולאחר מכן לפי מזהה ייחודי אתר ואז לפי  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
  • מאפשר ערבוב של פריטים עם מע"מ וללא מע"מ בחשבונית אחת. האם המחיר שורה פטור  מע"מ. ברוב המקרים "לא".
  • במידה וכול החשבונית היא ללא מע"מ יש להשתמש בפרמטר InvoiceHead.ExtIsVatFree של כותרת החשבונית.

 

פרמטרים לשורה ראשונה במסמך:

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

 

אשראי - הצלבת חשבונית לעסקת אשראי קיימת 

ניתן להצליב עסקה שחייבה בעבר לחשבונית.

  1. אסור שהעסקה תהייה מוצלבת לחשבונית אחרת, יצירת החשבונית תכשל.
  2. יש לשם לב להצלבה נכונה של עסקאות זיכוי עם חשבוניות זיכוי.
  3. הפרמטר ב Web Service נקרא RciExtDealNum.
פרמטר ערכים לדוגמא הסבר
CreditDealNum.DealNumber 14214 (InternalDealNumber ) מספר העסקה בדוחות קארדקום (פרמטר  InternalDealNumber ) להצלבת החשבונית.
בעסקת ביטול יש להעביר עסקת זיכוי/ביטול.

 

תשלום אחר - טבלת פרמטרים : הוספת "תשלום אחר" לחשבונית.

ניתן להוסיף אמצעי "תשלום אחר" על חשבונית. השימוש של  "תשלום אחר" הוא במידה ומתקבל כסף ממקור אחר שהוא לא כרטיס אשראי, מזומן או צ'קים כגון העברה בנקאית או קבלת תשלום פי-פאל. יש להגדיר את החשבון במערכת הניהול לפני העברת התשלום האחר בממשק ראה : הגדרות חשבוניות : חשבונות שונים.

  1. שם המחלקה ב 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  סכום
 

העברה של מספר "תשלום אחר":

על מנת להעביר "מערך" של תשלום אחר יש למספר את התשלומים לדוגמה:

תשלום אחר אחד:

CustomPay.TransactionID=31&CustomPay.TranDate=31/12/2011&CustomPay.Asmacta=ZZ123&CustomPay.Sum=150
תשלום אחר שתיים :
CustomPay1.TransactionID=31&CustomPay1.TranDate=31/11/2011&CustomPay1.Asmacta=ZZ123&CustomPay1.Sum=150
תשלום אחר שלוש:

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

ניתן להוריד קוד לדוגמה ↓
יש ליצור קשר עם התמיכה לקבלת שם משתמש לבדיקות.

מאמרים קשורים

הערות

0 הערות

היכנס למערכת כדי להגיב.

מופעל על ידי Zendesk