PostPayAndAllocateSalesInvoice - accountsIQ/API-Wiki GitHub Wiki

The PostPayAndAllocateSalesInvoice function supports common scenarios that many third party applications require when integrating sales data with AccountsIQ.

For example, an online e-shop or EPOS will often want to record a customer invoice and receipt simultaneously and allocate the two together at the same time from an accounting point of view.

This enables the efficient and atomic implementation of the following set of operations:

1. For a given customer, verify that there are no existing invoices with the same reference number (ie 'external reference' or 'Ext Ref' in AccountsIQ). This is a step used to prevent duplicate invoices from being created.
2. Verify that there are no sales receipts with a given receipt reference already existing in the system.
3. Post a sales batch invoice to the Sales Ledger (AR).
4. Post a sales receipt for the full or partial amount of money of the invoice to the Sales Ledger (AR).
5. Allocate the receipt to the invoice for accounting purposes.

If any of the steps fails, then everything is rolled back as if nothing had happened. The creation of either the invoice and receipt are optional, but at least one of the two must be requested. The allocation step is also optional and driven by a flag. The values for the allocation are defaulted unless provided, please see below for the details.

public WSResult2<WSPostPayAndAllocateSalesInvoiceResult> PostPayAndAllocateSalesInvoice(String token, WSPostPayAndAllocateSalesInvoiceQuery query)

The query object is mandatory and is composed the following way:

• BatchInvoice [ BatchSalesInvoice ]: The sales batch invoice to be created. Not mandatory, but if an allocation is requested, then it must be present.
• Receipt [ SalesReceipt ]: The sales receipt to be created. Not mandatory, but if an allocation is requested, then it must be present.
• PerformExternalReferenceDuplicateCheckOnInvoice [ Boolean ]: Flag indicating whether the system should first check if the external reference has already been used for an invoice on the same customer. If the reference exists, then the call will fail with the error code INVOICE_EXTERNAL_REFERENCE_ALREADY_EXISTS. Mandatory
• PerformExternalReferenceDuplicateCheckOnReceipt [ Boolean ]: Flag indicating whether the system should first check if the receipt reference has already been used for an other sales receipt on the same customer. If the reference exists, then the call will fail with the error code RECEIPT_EXTERNAL_REFERENCE_ALREADY_EXISTS. Mandatory
• PerformAllocation [ Boolean ]: Flag indicating whether the system should be allocating the receipt to the invoice to clear the invoice in part of in full. Mandatory.
• AllocationDate [ DateTime ]: Date at which the invoice and the receipt must be allocated. Not mandatory; if not present it will use the receipt date. The date is only important for retrospective ageing.
• AllocationAmount [ Decimal ]: This controls how much of the receipt is allocated to the invoice. This is not mandatory and will default to the smallest amount between the invoice and the receipt if it's not present. The amount cannot be more than the smallest amount between the invoice and the receipt. If the total value of the invoice is allocated it is then fully allocated; otherwise it will be partially allocated and will remain outstanding.
• AllocationReference [ String ]: Reference for the allocation. Mandatory if the PerformAllocation flag is set. This does not need to be unique.
• ClientUniqueReference [ String ]: Optional string used to identify the request. This is not used by the system but will be returned in the result and will allow you match it back to the source. Especially useful in the bulk form of the method.

NOTE at least the invoice or the receipt information must be present in the query.
NOTE if both the invoice and receipt are present, they must be for the same customer.

The resulting structure will have its status set to Failure if anything has failed and to Success otherwise. If the method failed, the ErrorCode and ErrorMessage will contain more details. The errors that you may get will be the same as you would get when calling the individual methods to create a batch invoice, a sales receipt or perform an allocation via the API.

The WSPostPayAndAllocateSalesInvoiceResult result contains the following fields:

• InvoiceTransactionID [ null | Integer ]: if the invoice was created and the method was entirely successful, it will contain the unique transaction ID of the created invoice.
• ReceiptTransactionID [ null | Integer ]: if the receipt was created and the method was entirely successful, it will contain the unique transaction ID of the created receipt.
• ClientUniqueReference [ String ]: it will contain the matching value from the received query.

The following example creates an invoice, a receipt and perform an allocation:

Integration ws = new Integration();

String auth = ws.Login(entityID, partnerKey, userKey);
if( auth != null )
{
	BatchSalesInvoice invoice = new BatchSalesInvoice();

	invoice.CustomerCode = cust.Code;
	invoice.ExchangeRate = 1M;
	invoice.InvoiceDate = DateTime.Now;
	inv.Lines = new BatchSalesInvoiceLine[1]
	{
			new BatchSalesInvoiceLine()
			{
				Description = "Line 1",
				GLAccountCode = "1000",
				NetAmount = 100M,
				TaxAmount = 0M,
				TaxCode = "V01",
				TaxRate = 0
			}
	};
	
	SalesReceipt receipt = new SalesReceipt()
	{
		BankAccountCode = "6010",
		BankExchangeRate = 1M,
		CheckReference = "REF01",
		CustomerCode = "CUST012",
		Description = "Receipt",
		ExchangeRate = 1M,
		PaymentAmount = 199M,
		PaymentDate = DateTime.Now.AddDays(2)
	};

	var result = ws.PostPayAndAllocateSalesInvoice(auth, new WSPostPayAndAllocateSalesInvoiceQuery()
	{
		BatchInvoice = invoice,
		Receipt = receipt,
		PerformAllocation = true,
		AllocationAmount = 100M,
		AllocationDate = DateTime.Now,
		AllocationReference = "REFERENCE"
	});

	result.Status.Should().Be(OperationStatus.Success);

	var res = result.Result;
	res.Should().NotBeNull();
	var invoiceTransactionID = res.InvoiceTransactionID;
	var receiptTransactionID = res.ReceiptTransactionID;
}

• PostPayAndAllocateSalesInvoices