> 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/documents/credit-invoices.md).

# חשבוניות זיכוי (מלא וחלקי)

‫**חשבונית זיכוי** (`DocumentType: 4`) מבטלת את כולה או חלק מחשבונית או חשבונית מס קבלה שהופקה קודם. היא נוצרת במתודה הרגילה של [יצירת מסמך](/invoice4u-docs/he/documents/create-document.md) — מה שמייחד אותה הוא מערך ההפניות `Invoices` וכללי הולידציה סביבו.‬

{% hint style="info" %}
‫**זיכויים חלקיים הם נושא התמיכה הנפוץ ביותר.** הכלל המרכזי: כל מסמך מקושר ניתן לזיכוי רק עד **היתרה הניתנת לזיכוי** שלו — `Total − CreditAmount` (מה שטרם זוכה). קראו את [כללי הולידציה](#validation-rules) לפני האינטגרציה.‬
{% endhint %}

## ‫שלוש הדרכים להפיק זיכוי‬

| ‫מצב‬             | ‫איך‬                                                             | ‫מתי להשתמש‬                                                                                                  |
| ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| ‫**זיכוי מלא**‬   | ‫הפניה למסמך המקורי עם `ReceiptAmount` השווה למלוא היתרה שנותרה.‬ | ‫ביטול חשבונית במלואה. המקור הופך ל-`FullyCredited` (StatusID 3).‬                                            |
| ‫**זיכוי חלקי**‬  | ‫הפניה למקור עם `ReceiptAmount` **הקטן** מהיתרה שנותרה.‬          | ‫החזר על פריט אחד, תיקון חיוב יתר. המקור הופך ל-`PartiallyCredited` (StatusID 4); ניתן לזכות את היתרה בהמשך.‬ |
| ‫**זיכוי עצמאי**‬ | ‫ללא מערך `Invoices` — רק `Items` (ו/או `Payments`).‬             | ‫זיכוי על משהו שאינו קשור למסמך ספציפי במערכת (למשל חשבוניות מיובאות/ישנות).‬                                 |

‫חשבונית זיכוי **ללא** הפניות, ללא פריטים וללא תשלומים נדחית עם `InvoiceCreditMustHaveRefDocuments` (57).‬

## ‫מבנה הבקשה (זיכוי עם הפניה)‬

```http
POST /Services/ApiService.svc/CreateDocument HTTP/1.1
Host: apiqa.invoice4u.co.il
Content-Type: application/json

{
  "doc": {
    "DocumentType": 4,
    "DocumentReffType": 1,
    "ClientID": 88231,
    "Subject": "Credit for invoice 20260123",
    "TaxIncluded": true,
    "Invoices": [
      { "ID": "7f6a2c1e-1111-2222-3333-444455556666", "ReceiptAmount": 50.0 }
    ],
    "Items": [
      { "Name": "Refund - Pro plan June", "Quantity": 1, "Price": 50.0 }
    ]
  },
  "token": "<token>"
}
```

‫הערות שדות:‬

| ‫שדה‬                      | ‫כלל‬                                                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `DocumentType`             | `4` (InvoiceCredit).                                                                                              |
| `DocumentReffType`         | ‫סוג המסמכים המזוכים: `1` (Invoice) או `3` (InvoiceReceipt) **בלבד**. כל דבר אחר ← `DocumentReffTypeNotInRange`.‬ |
| `Invoices[].ID`            | ‫GUID של המסמך לזיכוי (שדה ה-`ID` של המקור, לא `DocumentNumber`). חייב להשתייך לארגון שלכם.‬                      |
| `Invoices[].ReceiptAmount` | ‫הסכום לזיכוי כנגד **אותו** מסמך. מספרים חיוביים — **אל** תשלחו שלילי.‬                                           |
| `Items`                    | ‫שורות פריטים המתארות את הזיכוי, במחירים **חיוביים**. השרת מטפל בסימן החשבונאי.‬                                  |
| `ClientID`                 | ‫חייב להתאים ללקוח במסמכים המקושרים.‬                                                                             |

‫ניתן לזכות **מספר מסמכים בחשבונית זיכוי אחת** — הוסיפו רשומה פר מסמך ב-`Invoices`, כל אחת עם `ReceiptAmount` משלה.‬

## ‫כללי ולידציה‬ <a href="#validation-rules" id="validation-rules"></a>

‫נבדקים פר שורה של `Invoices` (‏`Paramters` של השגיאה מכיל `"Row Number - N"`):‬

1. ‫**קיום ובעלות** — ה-GUID חייב להתאים למסמך בארגון שלכם ← `DocumentIDDoesntExists`.‬
2. ‫**התאמת לקוח** — ה-`ClientID` של המסמך המקושר חייב להיות שווה ל-`ClientID` של הזיכוי ← `ReceiptClientNameDoesntMatchInvoiceClientName`.‬
3. ‫**התאמת סוג** — סוג המסמך המקושר חייב להיות שווה ל-`DocumentReffType` ← `ReceiptDocumentReffTypeDoesntMatchInvoiceDocumentType`.‬
4. ‫**סטטוס** — מסמך שכבר `FullyCredited` (StatusID 3) לא ניתן לזיכוי נוסף ← `DocumentStatusInValid`.‬
5. ‫**תקרת הסכום** — כלל הזיכוי החלקי:‬

$$0 < \text{ReceiptAmount} \le \text{Total} - \text{CreditAmount}$$

‫`CreditAmount` הוא סכום כל הזיכויים שכבר הוחלו על אותו מסמך. חריגה מהיתרה שנותרה (או שליחת `0`/שלילי) ← `DocumentReceiptAmountOutOfRange`.‬

## ‫מה קורה אחרי זיכוי מוצלח‬

* ‫ה-`CreditAmount` של המסמך המקושר גדל ב-`ReceiptAmount` שלכם.‬
* ‫ה-`StatusID` שלו הופך ל-`4` (PartiallyCredited) או ל-`3` (FullyCredited) כאשר הזיכוי המצטבר מגיע ל-`Total`.‬
* ‫חשבונית הזיכוי עצמה מקבלת `DocumentNumber` חוקי משלה ברצף חשבוניות הזיכוי.‬
* ‫שלפו את המקור עם [שליפת מסמך בודד](/invoice4u-docs/he/documents/get-document.md) כדי לקרוא את ה-`CreditAmount`, ‏`Balance` ו-`StatusID` המעודכנים לפני הפקת זיכויים נוספים.‬

## ‫מלכודות נפוצות‬

| ‫תופעה‬                                             | ‫סיבה‬                                               | ‫תיקון‬                                                                                  |
| --------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `DocumentReceiptAmountOutOfRange` על סכום "תקין"    | ‫זיכויים חלקיים קודמים כבר צרכו חלק מהיתרה.‬         | ‫שלפו את המקור תחילה; זכו לכל היותר `Total − CreditAmount`.‬                             |
| `DocumentReceiptAmountOutOfRange` עם סכומים שליליים | ‫שליחת `ReceiptAmount`/מחירים שליליים כדי "להפחית".‬ | ‫שלחו ערכים חיוביים — סוג המסמך נושא את הסימן.‬                                          |
| `DocumentStatusInValid`                             | ‫המקור כבר זוכה במלואו.‬                             | ‫לא נשאר מה לזכות; בדקו `StatusID` לפני הקריאה.‬                                         |
| `DocumentReffTypeNotInRange`                        | ‫ניסיון לזכות קבלה, הצעת מחיר או הזמנה.‬             | ‫רק חשבונית (1) וחשבונית מס קבלה (3) ניתנות לזיכוי. ביטול קבלות — באמצעות קבלה מבטלת.‬   |
| ‫אי-התאמות סכומים בזיכויים מרובי שורות‬             | ‫עיגול בין שורות.‬                                   | ‫עגלו כל `ReceiptAmount` ל-2 ספרות; ודאו שסכום הפריטים שווה לסכום ה-`ReceiptAmount`-ים.‬ |

## ‫שגיאות‬

| ‫שגיאה (ID)‬                                            | ‫משמעות‬                                              |
| ------------------------------------------------------- | ----------------------------------------------------- |
| `InvoiceCreditMustHaveRefDocuments` (57)                | ‫לא נשלחו הפניות, פריטים או תשלומים.‬                 |
| `DocumentReffTypeNotInRange` (53)                       | ‫`DocumentReffType` אינו חשבונית/חשבונית מס קבלה.‬    |
| `DocumentIDDoesntExists`                                | ‫ה-GUID המקושר לא נמצא בארגון שלכם.‬                  |
| `ReceiptClientNameDoesntMatchInvoiceClientName`         | ‫אי-התאמת לקוח בין הזיכוי למסמך המקושר.‬              |
| `ReceiptDocumentReffTypeDoesntMatchInvoiceDocumentType` | ‫סוג המסמך המקושר ≠ `DocumentReffType`.‬              |
| `DocumentStatusInValid` (49)                            | ‫המסמך המקושר כבר זוכה במלואו.‬                       |
| `DocumentReceiptAmountOutOfRange` (50)                  | ‫`ReceiptAmount` ≤ 0 או עולה על היתרה הניתנת לזיכוי.‬ |

## ‫נסו את זה‬

## Create a document

> Creates a signed, numbered document. Totals are computed server-side from Items/Payments. Check the returned Errors list before using the result.

```json
{"openapi":"3.0.3","info":{"title":"Invoice4U API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Create and retrieve documents (invoices, receipts, etc.)."}],"servers":[{"url":"https://api.invoice4u.co.il/Services/ApiService.svc","description":"Production"},{"url":"https://apiqa.invoice4u.co.il/Services/ApiService.svc","description":"QA (staging)"}],"paths":{"/CreateDocument":{"post":{"tags":["Documents"],"operationId":"CreateDocument","summary":"Create a document","description":"Creates a signed, numbered document. Totals are computed server-side from Items/Payments. Check the returned Errors list before using the result.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["doc","token"],"properties":{"doc":{"$ref":"#/components/schemas/Document"},"token":{"type":"string"}}}}}},"responses":{"200":{"description":"The created document (or a document carrying Errors).","content":{"application/json":{"schema":{"type":"object","properties":{"CreateDocumentResult":{"$ref":"#/components/schemas/Document"}}}}}}}}}},"components":{"schemas":{"Document":{"allOf":[{"$ref":"#/components/schemas/CommonObject"},{"type":"object","required":["DocumentType"],"properties":{"ID":{"type":"string","format":"uuid","readOnly":true},"DocumentNumber":{"type":"integer","format":"int64","readOnly":true,"description":"Legal sequential number, per type."},"DocumentType":{"type":"integer","description":"1 Invoice, 2 Receipt, 3 InvoiceReceipt, 4 InvoiceCredit, 5 ProformaInvoice, 6 InvoiceOrder, 7 InvoiceQuote, 8 InvoiceShip, 9 Deposits, 10 SupplierInvoiceToInventory, 13 PurchaseOrder.","enum":[1,2,3,4,5,6,7,8,9,10,13]},"Subject":{"type":"string","nullable":true},"ClientID":{"type":"integer","nullable":true,"description":"Existing customer ID. Required unless GeneralCustomer is supplied or the type doesn't need a customer."},"GeneralCustomer":{"$ref":"#/components/schemas/GenerelCustomer"},"Items":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/DocumentItem"}},"Payments":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/Payment"}},"Invoices":{"type":"array","nullable":true,"description":"Referenced documents (each with ID and ReceiptAmount). Requires DocumentReffType.","items":{"type":"object","properties":{"ID":{"type":"string","format":"uuid"},"ReceiptAmount":{"type":"number","format":"double"}}}},"DocumentReffType":{"type":"integer","description":"Type of the referenced documents."},"IssueDate":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to today. Not in the future; not before your latest document of the type."},"Currency":{"type":"string","nullable":true},"ConversionRate":{"type":"number","format":"double","description":"Auto-resolved when 0."},"TaxPercentage":{"type":"number","format":"double","nullable":true},"TaxIncluded":{"type":"boolean","description":"Whether item prices include VAT."},"Discount":{"$ref":"#/components/schemas/Discount"},"BranchID":{"type":"integer","nullable":true,"description":"Defaults to the organization's default branch."},"Language":{"type":"integer","description":"1 Hebrew, 2 English."},"AssociatedEmails":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/AssociatedEmail"}},"ExternalComments":{"type":"string","nullable":true,"maxLength":5000},"InternalComments":{"type":"string","nullable":true},"EmailCustomComment":{"type":"string","nullable":true},"ApiIdentifier":{"type":"string","nullable":true,"description":"Idempotency key. Auto-generated if missing."},"ApiDuplicityTimeValidation":{"type":"integer","description":"Duplicate-detection window in seconds. Default 60."},"PaymentDueDate":{"type":"string","format":"date-time","nullable":true},"Deduction":{"type":"number","format":"double","description":"Withholding-tax deduction (receipts)."},"CloseReceipt":{"type":"boolean"},"IsSelfInvoice":{"type":"boolean"},"SupplierId":{"type":"integer","nullable":true},"SupplierName":{"type":"string","nullable":true},"UseDecimalValues":{"type":"boolean"},"AutoFixPaymentsMismatchItems":{"type":"boolean","description":"Auto-fix ±0.01 rounding gaps between payments and items."},"AutoFixMismatchItemName":{"type":"string","nullable":true},"Total":{"type":"number","format":"double","readOnly":true},"TotalWithoutTax":{"type":"number","format":"double","readOnly":true},"TotalTaxAmount":{"type":"number","format":"double","readOnly":true},"StatusID":{"type":"integer","readOnly":true,"description":"1 Open, 2 Closed, 3 FullyCredited, 4 PartiallyCredited, 5 Cancelled."},"PrintOriginalPDFLink":{"type":"string","readOnly":true},"PrintCertifiedCopyPDFLink":{"type":"string","readOnly":true},"CipherText":{"type":"string","readOnly":true},"CipherTextOriginal":{"type":"string","readOnly":true},"AllocationNumber":{"type":"string","nullable":true,"readOnly":true},"Paid":{"type":"number","format":"double","readOnly":true},"CreditAmount":{"type":"number","format":"double","readOnly":true},"Balance":{"type":"number","format":"double","readOnly":true}}}]},"CommonObject":{"type":"object","description":"Response envelope inherited by most objects. Server-generated — never send these fields in requests. Always check Errors before using the payload.","properties":{"Errors":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonError"}},"Info":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/CommonInfo"}},"OpenInfo":{"type":"object","readOnly":true,"additionalProperties":{"type":"string"},"nullable":true}}},"CommonError":{"type":"object","properties":{"ID":{"type":"integer","description":"Numeric error code, e.g. 80 = UnauthorizedUser, 134 = DocumentAlreadyCreated."},"Error":{"type":"string","description":"Error name."},"Paramters":{"type":"string","nullable":true,"description":"Optional context, e.g. \"Row Number - 0\"."}}},"CommonInfo":{"type":"object","properties":{"ID":{"type":"integer"},"Info":{"type":"string"},"Paramters":{"type":"string","nullable":true}}},"GenerelCustomer":{"type":"object","required":["Name"],"description":"One-off (general) customer for documents without a stored customer record.","properties":{"ID":{"type":"integer"},"Name":{"type":"string"},"Identifier":{"type":"string","description":"VAT/ID number."}}},"DocumentItem":{"type":"object","required":["Name","Quantity","Price"],"properties":{"Name":{"type":"string"},"Description":{"type":"string","nullable":true},"Price":{"type":"number","format":"double","description":"Unit price."},"PriceIncludeTax":{"type":"number","format":"double","description":"Price including VAT (when TaxIncluded)."},"Quantity":{"type":"number","format":"double"},"TaxPercentage":{"type":"number","format":"double","nullable":true,"description":"Per-item VAT override."},"Discount":{"$ref":"#/components/schemas/Discount"},"Code":{"type":"string","nullable":true,"description":"Catalog code."},"LawyerIdentifier":{"type":"string","nullable":true,"description":"Lawyer accounts: \"1\" deposits, \"2\" expenses."},"InventoryId":{"type":"integer","nullable":true},"WarehouseId":{"type":"integer","nullable":true},"Total":{"type":"number","format":"double","readOnly":true},"TotalWithoutTax":{"type":"number","format":"double","readOnly":true},"TotalTax":{"type":"number","format":"double","readOnly":true}}},"Discount":{"type":"object","required":["Value"],"properties":{"Value":{"type":"number","format":"double"},"IsNominal":{"type":"boolean","description":"true = fixed amount, false = percent."},"BeforeTax":{"type":"boolean"}}},"Payment":{"type":"object","required":["PaymentType","Amount"],"properties":{"ID":{"type":"integer","description":"Existing payment ID — used for Deposits documents."},"PaymentType":{"type":"integer","description":"1 CreditCard, 2 Check, 3 MoneyTransfer, 4 Cash, 5 Credit, 6 WithholdingTax, 7 Other, 8 Bit, 9 PayBox.","enum":[1,2,3,4,5,6,7,8,9]},"Amount":{"type":"number","format":"double"},"Date":{"type":"string","format":"date-time","nullable":true},"DateStr":{"type":"string","nullable":true,"description":"Alternative string date when Date is not set."},"NumberOfPayments":{"type":"integer","description":"Credit-card installments."},"CreditCardName":{"type":"string","nullable":true,"description":"Card brand name; resolved against configured credit companies."},"CreditCardType":{"type":"integer","nullable":true},"PaymentNumber":{"type":"string","nullable":true,"description":"Check number / last 4 card digits."},"BankName":{"type":"string","nullable":true},"BranchName":{"type":"string","nullable":true},"AccountNumber":{"type":"string","nullable":true},"PayerID":{"type":"string","nullable":true},"ExpirationDate":{"type":"string","nullable":true},"PaymentTypeOtherId":{"type":"integer","description":"Sub-type when PaymentType=7 (Other)."},"PaymentTypeLiteral":{"type":"string","nullable":true}}},"AssociatedEmail":{"type":"object","required":["Mail"],"properties":{"Mail":{"type":"string","format":"email"},"IsUserMail":{"type":"boolean","description":"true marks the copy sent to the account owner."},"ClientId":{"type":"integer","nullable":true},"IsSendDoc":{"type":"boolean","nullable":true}}}}}}
```