> For the complete documentation index, see [llms.txt](https://invoice4u.gitbook.io/invoice4u-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://invoice4u.gitbook.io/invoice4u-docs/he/getting-started/key-tips.md).

# טיפים וחידודים

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

### ‫בקשות‬

* ‫**הכל POST עם JSON** (אלא אם צוין אחרת בעמוד). הפרמטרים עטופים בשם בתוך גוף הבקשה — `{ "doc": {...}, "token": "..." }` — לא נשלחים כאובייקט חשוף.‬
* ‫התשובות עוטפות את התוצאה במאפיין `<Operation>Result`, לדוגמה `CreateDocumentResult`.‬
* ‫לחלק מהמתודות יש גרסת `GET` (עם סיומת `REST`) שמקבלת פרמטרים ב-query string — נוח לבדיקות מהירות, לא מומלץ לפרודקשן (פרטי התחברות ב-URL).‬

### ‫שגיאות‬

* ‫סטטוס ה-HTTP כמעט תמיד **200** — השגיאות נמצאות ברשימת `Errors` שבתוך אובייקט התשובה. \*\*תמיד בדקו את `Errors` לפני שימוש בתוצאה.\*\*‬
* ‫`Errors[].ID` הוא קוד מספרי קבוע (למשל `80` משתמש לא מורשה, `134` מסמך כבר נוצר); השדה `Paramters` מכיל לרוב הקשר כמו `"Row Number - 0"`.‬
* ‫חלק ממתודות ההתחברות/שליפה מחזירות `null` במקום אובייקט שגיאה — התייחסו ל-`null` ככישלון.‬

### ‫טוקנים‬

* ‫**מפתח ה-API** (GUID) שלכם הוא הטוקן — העבירו אותו כ-`token` בכל קריאה; אין שלב התחברות נפרד ([פרטים](/invoice4u-docs/he/authentication/is-authenticated.md)). התחברות עם אימייל וסיסמה הוצאה משימוש — היא עדיין פועלת בתקופת המעבר, אך יש לעבור למפתח ה-API.‬
* ‫מפתח לא תקין ← `UnauthorizedUser` (80). בדקו את המפתח באפליקציית ה-Invoice4U.‬

### ‫מסמכים‬

* ‫מסמכים הם **סופיים** מרגע היצירה — אין עדכון. טעות? הפיקו [חשבונית זיכוי](/invoice4u-docs/he/documents/document-types.md) כנגד המסמך.‬
* ‫**תמיד קבעו `ApiIdentifier`** (מזהה ההזמנה/עסקה שלכם). השתמשו ב-[CreateDocumentWithIdentifierValidation](/invoice4u-docs/he/documents/create-document-with-validation.md) לניסיונות חוזרים בטוחים — שגיאה `134` עם `DocumentNumber` גדול מ-0 פירושה "כבר קיים", לא כישלון.‬
* ‫הסכומים מחושבים **בצד השרת** מתוך `Items`/`Payments` — אל תחשבו ותשלחו `Total` בעצמכם.‬
* ‫מספרי מסמכים הם רציפים **לפי סוג מסמך** — `GetDocumentByNumber` דורש גם מספר וגם סוג.‬
* ‫`IssueDate` לא יכול להיות עתידי ולא מוקדם מהמסמך האחרון שלכם מאותו סוג.‬
* ‫ב**חשבונית מס קבלה**, סכום התשלומים חייב להיות שווה לסכום הפריטים; הפעילו `AutoFixPaymentsMismatchItems` לספיגת פערי עיגול של ±0.01.‬

### ‫סליקה‬

* ‫תהליך דף הסליקה המתארח הוא **אסינכרוני**: `ProcessApiRequestV2` מחזיר `ClearingRedirectUrl`; תוצאת החיוב מגיעה ל-`CallBackUrl` שלכם.‬
* ‫חיוב בטוקן (`ChargeWithToken`) וזיכויים הם **סינכרוניים** — התוצאה חוזרת בתשובה.‬
* ‫קבעו `IsQaMode: true` בבדיקות מול סביבת QA.‬
* ‫שמרו את ה-`PaymentId` מחיובים מוצלחים — תצטרכו אותו ל[זיכויים](/invoice4u-docs/he/clearing-payments/process-api-request-v2.md#refunds).‬

### ‫סביבות‬

* ‫QA ופרודקשן הן **חשבונות ונתונים נפרדים** — טוקן של QA לא עובד בפרודקשן.‬
* ‫קישורי ה-PDF מפנים ל-`newviewqa.invoice4u.co.il` ב-QA ול-`newview.invoice4u.co.il` בפרודקשן.‬