Creating a Document Associated with a Deal
This article explains how to create a document for a deal that does not yet have an associated document, using the CreateDocument API endpoint. It includes the request parameters, document and payment objects, response fields, and a JSON example.
When should this function be used?
This function is intended specifically for issuing a document for deals that are not associated with a document.
Such deals may be created when no document-generation parameters were sent, when landing pages have had the document-generation setting removed, or when standing orders have no document-generation setting.
Common actions performed by this function
The function can issue a document and associate it with the specific deal number.
In addition, the function can issue a document independently, without associating it with a deal, using various payment details such as cash, checks, bank transfers, and more.
Required models and prerequisites
Document model.
A deal without an associated document.
JSON function link
Request method: POST.
Create a document associated with a deal
https://secure.cardcom.solutions/api/v11/Documents/CreateDocument
The following parameters must be passed to the CreateDocument function.
Legend:
Red parameter – required
Bold parameter – recommended
Parameter that is neither red nor bold – optional
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | ApiName | test2025 | Interface username. This parameter must be obtained from the business. |
| 2 | ApiPassword | "kzFKfohEvL6AOF8aMEJz" | API password, intended for refunds and transaction cancellations. |
| 4 | Cash | 50 | Amount paid in cash. |
| 7 | DealNumbers Array of objects | DealNumber - 204477861 | DealNumber – the internal number of the completed deal. |
| 8 | IsSendSMS | boolean - true / false | Whether to send the document by SMS. |
Document values – Document object (3)
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | DocumentTypeToCreate | "Auto" – automatic, according to settings 3->4. "TaxInvoiceAndReceipt" – tax invoice and receipt "TaxInvoiceAndReceiptRefund" – tax invoice and receipt refund "Receipt" – nonprofit receipt "ReceiptRefund" – nonprofit receipt refund "Quote" – quote "Order" – order "OrderConfirmation" – order confirmation from the website "OrderConfirmationRefund" – order confirmation refund from the website "DeliveryNote" – delivery note "DeliveryNoteRefund" – return note "ProformaInvoice" – pro forma invoice "DemandForPayment" – payment demand "DemandForPaymentRefund" – payment demand cancellation "ProformaDealInvoice" – pro forma deal receipt "ProformaDealInvoiceRefund" – pro forma deal receipt refund "TaxInvoice" – tax invoice "ProformaInvoiceRefund" – pro forma invoice refund "TaxInvoiceRefund" – tax invoice refund "ReceiptForTaxInvoice" – receipt for a tax invoice "DonationReceipt" – donation receipt "DonationReceiptRefund" – donation receipt refund "ReceiptForTaxInvoiceRefund" – customer refund (receipt refund) | Type of document to issue. |
| 2 | Name | Mr. Test | Customer name. |
| 3 | TaxId | 040617640 | Personal identification number or company registration number. |
| 4 | israel@gmail.com | Customer email address to which the document will be sent. Multiple email addresses can be separated with a semicolon (;). | |
| 5 | IsSendByEmail | true / false | Whether to send the document by email. |
| 6 | AddressLine1 | Saharov 22 | Customer address, first line. |
| 7 | AddressLine2 | P.O. 1234 | Customer address, second line. |
| 8 | City | Rishon LeZion | City. |
| 9 | Mobile | 03-9619611 | Landline telephone number. |
| 10 | Phone | 0549876543 | Mobile telephone number. The SMS module sends an SMS to this number. |
| 11 | Comments | Example: One-year warranty from the invoice date (up to 250 characters) | Comments for the document, printed at the bottom of the document. |
| 12 | IsVatFree | true = 0% VAT false = 18% VAT | Whether the entire document is VAT-exempt, suitable for an overseas customer. |
| 13 | DepartmentId | 123 (int) | Department code displayed in reports and transferred to accounting. See the document classification and department usage settings. |
| 14 | AdvancedDefinition Object containing parameters | IsAutoCreateUpdateAccount (bool) – false AccountForeignKey (string) – e.g. 300 SiteUniqueId (string) AccountID (integer) – 123 IsLoadInfoFromAccountID (boolean) – true / false | IsAutoCreateUpdateAccount (bool) – whether to create a customer card in the system. When true, InvoiceHead.CompID (the customer's personal or company registration number) must also be provided. If the customer already exists, a new card will not be created. If this parameter is not passed, the system searches first by foreign key, then by site unique identifier, and finally by customer email. Once a match is found, the search ends. AccountForeignKey (string) – the customer's foreign key number, active only when a customer card is created (accounting number). SiteUniqueId (string) – a unique site identifier; an informational parameter. AccountID (integer) – the customer's number in the Gold Approval system, used to associate the document. Not active for a suspended deal. IsLoadInfoFromAccountID (boolean) – when AccountID exists, whether to retrieve the details from the customer card associated with that number and add them to the document. |
| 15 | Products Array of objects | ProductID (string) – ZZASA AASSA - 12 Description (string) – Online course Quantity (integer) – 2 UnitCost (integer) – 50.57 TotalLineCost (integer) – 51 IsVatFree (boolean) – true / false | ProductID (string) – item code, SKU, or product code. Recommended for reporting; see the document item report. For two items, use for example InvoiceLines1.ProductID=AAA and InvoiceLines2.ProductID=BBB. Description (string) – product description. Quantity (integer) – item quantity. When passing a quantity greater than 1, multiply the price accordingly and send a suitable payment method. UnitCost (integer) – unit price. TotalLineCost (integer) – recommended when the product quantity is not a whole number; this can prevent price-rounding issues. IsVatFree (boolean) – whether this product is VAT-exempt. |
| 16 | ExternalId | (String) | External system identifier passed by the programmer at the individual-document level. If the same identifier is passed again, the system returns the same document associated with the original identifier at the company level. |
| 17 | ManualNumber | 585177 | Manual document numbering. Can be used only when creating a document without charging. Special authorization is required. In rare cases, the number of the invoice to be created can be passed instead of using the system's internal counter. If the counters conflict, the invoice will not be created. |
| 18 | DocumentDate | "05/03/2025" | Document issue date. |
| 19 | ValueDate | "12/03/2025" | Document value date, intended for journal entries. |
| 20 | ISOCoinID | 1 – shekel 2 – dollar Additional currency codes | Currency used to charge the deal. |
| 21 | ISOCoinName | ILS / USD / EUR | Equivalent to ISOCoinID; this parameter receives the currency name rather than the currency number. |
| 22 | Language | "he" / "en" | Document language. |
Values for the Cheques object array (5)
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | ChequeNumber | "1234" | Check number. |
| 2 | BankNumber | 12 | Bank number. |
| 3 | SnifNumber | 1 | Bank branch number. |
| 4 | AccountNumber | "123456" | Account number. |
| 5 | DateCheque | "MM/dd/yyyy" | Check payment date. |
| 6 | Sum | 50 | Check amount. |
Values for the CustomFields object array (6)
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | TransactionID | 32 | Number of an account predefined in the Gold Approval clearing system. To add another account, go to Additional payment method settings. Pass the sequential number, for example 30 for a bank deposit. |
| 2 | TranDate | "MM/dd/yyyy" | Reference date. |
| 3 | Description | "Payment received from PayPal" | Transaction description. |
| 4 | asmacta | "123456-ZZC" | Transaction reference number. |
| 5 | Sum | 50 | Amount. |
Response from Create a document associated with a deal
| No. | Parameter | Example values | Description |
|---|---|---|---|
| 1 | ResponseCode | 0 | 0 – operation successful. Any other value indicates an error, usually a development error. |
| 2 | Description | "The deal was completed successfully" | Response description. If a different response is received, the operation was unsuccessful. |
| 3 | DocumentType | See DocumentTypeToCreate above. | Type of document issued. |
| 4 | DocumentNumber | 65451 | Document number. |
| 5 | AccountId | (string) "123" | Customer card number. |
| 6 | ForeignAccountNumber | 21451 | Customer's accounting number, only if a customer card was created or merged. |
| 7 | SiteUniqueId | (String) | Unique site identifier – informational parameter. |
| 8 | DocumentUrl | (String) | Returns the document URL. |
Example function code and response
Request to issue a document for a deal without a document:
{
"ApiName": "test2025",
"ApiPassword": "test5000$",
"Document": {
"DocumentTypeToCreate": "TaxInvoiceAndReceipt",
"Name": "plz",
"Email": "t@t.com",
"Products": [
{
"Description": "test",
"UnitCost": 21,
"Quantity": 1,
"IsVatFree": false
}
],
"ISOCoinID": "1"
},
"DealNumbers": [
{
"DealNumber": "205078451"
}
]
}
Response:
{
"ResponseCode": 0,
"Description": "",
"DocumentType": "TaxInvoiceAndReceipt",
"DocumentNumber": 586136,
"AccountId": 0,
"ForeignAccountNumber": null,
"SiteUniqueId": null,
"DocumentUrl": "https://secure.cardcom.solutions/api/v11/documents/DownloadDoc/?c=1&code=iKm1mI1S7d6CAqzerQN+IMRsYjKepupkHsjFFvZkRnlaLuk6UA78U3RaWJxUL4nu"
}