> 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/documents/create-document.md). # Create a Document Creates a signed, numbered document. This is the primary endpoint of the API. ## Endpoint | | | | ------------ | ---------------------------------------- | | **Method** | `POST` | | **Path** | `/CreateDocument` | | **Response** | `Document` object — check `Errors` first | Variants: | Path | Method | Notes | | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `/CreateDocument` | POST | Standard. | | `/CreateDocumentREST` | GET/POST | Explicit REST variant, same body. | | `/CreateDocumentWithIdentifierValidation` | POST | Rejects duplicates by `ApiIdentifier` — see [dedicated page](/invoice4u-docs/documents/create-document-with-validation.md). | ## Request schema | Field | Type | Required | Description | | ------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `doc` | Document | Yes | The document to create. See [The Document Object](/invoice4u-docs/documents/document-object.md) and per-type requirements in [Document Types](/invoice4u-docs/documents/document-types.md). | | `token` | string | Yes | Authentication token. | ## Example request — InvoiceReceipt (type 3) ```http POST /Services/ApiService.svc/CreateDocument HTTP/1.1 Host: apiqa.invoice4u.co.il Content-Type: application/json { "doc": { "DocumentType": 3, "Subject": "Monthly subscription", "ClientID": 88231, "TaxIncluded": true, "Currency": "ILS", "ApiIdentifier": "my-system-order-10045", "Items": [ { "Name": "Pro plan - June", "Quantity": 1, "Price": 117.00, "PriceIncludeTax": 117.00 } ], "Payments": [ { "PaymentType": 1, "Amount": 117.00, "Date": "2026-07-05T00:00:00", "NumberOfPayments": 1, "PaymentNumber": "4242" } ], "AssociatedEmails": [ { "Mail": "billing@acme.example", "IsUserMail": false } ] }, "token": "" } ``` ## Example response ```json { "CreateDocumentResult": { "ID": "7f6a2c1e-8b4d-4f2a-9c3e-0d1e2f3a4b5c", "DocumentNumber": 20260123, "DocumentType": 3, "Subject": "Monthly subscription", "Total": 117.0, "TotalWithoutTax": 100.0, "TotalTaxAmount": 17.0, "StatusID": 2, "ApiIdentifier": "my-system-order-10045", "PrintOriginalPDFLink": "https://newview.invoice4u.co.il/Views/PDF.aspx?cipher=...", "PrintCertifiedCopyPDFLink": "https://newview.invoice4u.co.il/Views/PDF.aspx?cipher=...", "Errors": [] } } ``` {% hint style="info" %} On QA the PDF links point to `newviewqa.invoice4u.co.il`; on production to `newview.invoice4u.co.il`. {% endhint %} ## Behavior notes * **Totals are computed server-side** from `Items` (item-based types) or `Payments` (+`Deduction`) — you don't send `Total`. * For **InvoiceReceipt**, payments total must equal items total (±0.01 rounding is auto-fixable — see `AutoFixPaymentsMismatchItems` on the [Document object](/invoice4u-docs/documents/document-object.md)). Mismatch → `PaymentAmountDoesntMatchItemsAmount` (56) with `OpenInfo.PaymentMismatchDelta`. * **Email delivery** happens automatically when `AssociatedEmails` is set; **SMS delivery** when `SmsMessages` is set. * Organizations connected to **2Sign** with signable document flows get the document sent as a signing task instead of a plain email. * Duplicate window: identical document within `ApiDuplicityTimeValidation` seconds (default 60) → `DocumentAlreadyCreated` (134). ### Flow — InvoiceReceipt totals & AutoFix ```mermaid flowchart TD classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 A[InvoiceReceipt:
Items + Payments]:::step --> B["paymentsTotal =
Σ Payments + Deduction"]:::step B --> C{"paymentsTotal == itemsTotal?
(2 decimals)"}:::dec C -- ✓ --> D[Create document]:::cb C -- "±0.01 decimal artifact" --> D C -- ✗ --> E{"diff == ±0.01 or
AutoFixPaymentsMismatchItems?"}:::dec E -- ✓ --> F["Adjustment item added
(AutoFixMismatchItemName) → recalc"]:::step F --> C E -- ✗ --> G[PaymentAmountDoesntMatchItemsAmount 56
+ OpenInfo.PaymentMismatchDelta]:::err ``` ## Foreign-currency documents Answers to the questions that come up most often when a document needs to be issued in a foreign currency (e.g. `USD`) instead of the organization's base currency. **Can I create a document in a foreign currency (e.g. USD, with no conversion to ILS) through the API?** Yes. Set `Currency` on the [Document object](/invoice4u-docs/documents/document-object.md) to the ISO symbol you want (e.g. `"USD"`). The document is created and stored entirely in that currency — `Items`, `Payments` and the resulting `Total`/`TotalWithoutTax`/`TotalTaxAmount` are all in `USD`, not ILS. The API never silently converts the amounts you send. **Which fields are required exactly?** (`Currency="USD"`, `ConversionRate=`, and what value does `ConvertToILS` or another field need?) Only `Currency` is required to issue the document in a foreign currency: * `Currency` — set to `"USD"` (or any symbol that exists in the currency list; an unrecognized symbol → `CurrencyDoesntExists`, 36). * `ConversionRate` — optional, see the next question. It's stored as metadata for reporting/reconciliation against the organization's base currency; it does **not** rescale `Total` or any item/payment amount. * `ConvertToILS` — not related to document creation at all. It's a **report/print display flag** used only by the PDF and Excel export services (open-accounts and income reports) to decide whether to additionally show a converted total next to the original-currency total. Leave it unset — `CreateDocument` ignores it. **Is `ConversionRate` required when the currency isn't ILS, or is sending `0` enough for automatic calculation?** Sending `0` (or omitting the field, which defaults to `0`) is enough — the server automatically resolves the rate between the organization's currency and `Currency` from the daily currency table. Only send an explicit non-zero `ConversionRate` if you need to lock in a specific rate yourself (e.g. one already agreed with the customer). {% hint style="info" %} Example: an organization whose base currency is ILS creating a USD invoice just needs `"Currency": "USD"` in the request body — `ConversionRate` can be omitted entirely. {% endhint %} ## Common errors | Error (ID) | Meaning | | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `UnauthorizedUser` (80) | Invalid token. | | `DocumentTypeNotInRange` (33) | Unknown `DocumentType`. | | `ClientDoesntExists` (7) / `ClientIDDoesntExists` (37) | Missing/unknown customer. | | `CurrencyDoesntExists` (36) | `Currency` symbol isn't in the supported currency list. | | `DocumentItemsNotSpecified` (34) / `DocumentItemMissingName` (39) / `DocumentItemQuantityCannotBeZero` (40) / `DocumentItemPriceCannotBeZero` (41) | Item validation. `Paramters` holds the row number. | | `PaymentsNotSpecified` (45) / `PaymentDateMissing` (46) / `PaymentAmountCannotBeZero` (47) / `PaymentTypeOutOfRange` (51) | Payment validation. | | `PaymentAmountDoesntMatchItemsAmount` (56) | Payments ≠ items total. | | `InvalidDateRange` (3) | `IssueDate` in the future or before your latest document. | | `DocumentAlreadyCreated` (134) | Duplicate detected. | | `NotEnoughDocuments` (65) / `NotEnoughCredits` (18) | Document quota exhausted. | | `ExpiredAccount` (66) | Account subscription expired. | | `ActionRestrictedForUser` (141) | The user is restricted from creating this document type. | | `TimeoutDB` (147) | Server error during creation — verify with [GetDocumentByApiIdentifier](/invoice4u-docs/documents/get-document.md) before retrying. | ## Try it ## 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}}}}}} ```