Fiscal Cash Register Custom Functions

Introduction

You can add any operations to the list of fiscal register commands. This may be required, for example, if you need some operations to be carried out before or after the printing of receipts. It can be schematically displayed the following way:

If the plugin needs to take control while printing a payment or refund receipt or during the depositing, withdrawing, and printing X and Z reports, it’s enough to implement the IChequeTaskProcessor interface and register it by invoking the RegisterChequeTaskProcessor() API method:

var chequeTaskProcessor = new ChequeTaskProcessor()
PluginContext.Operations.RegisterChequeTaskProcessor(chequeTaskProcessor);

All IChequeTaskProcessor interface commands can interrupt the main operation: receipt fiscalization, depositing, withdrawing, printing of X and Z reports. For this, you need to throw any type of exception in the command body. For example, we add a condition forbidding virtual receipt printers (FCR) to close orders:

public BeforeDoCheckActionResult BeforeDoCheckAction(ChequeTask chequeTask, ICashRegisterInfo device, CashRegisterChequeExtensions chequeExtensions, IViewManager viewManager)
{
	// Example: allow printing payment and prepayment receipts only on physical devices.
	if (device.IsVirtual)
		throw new Exception("Cash register is virtual. Please close order on real device.");

	PluginContext.Log.InfoFormat("Before printing the receipt: {0} ({1})", device.FriendlyName, device.Id);
	
	...
}

When an order is paid on a virtual FCR, Syrve POS would display an error message and the order remains open:

You can find the IChequeTaskProcessor implementation and registration example in SDK SamplePlugin.

Interface IChequeTaskProcessor

Let’s take a closer look at IChequeTaskProcessor commands.

1. BeforeDoCheckAction

BeforeDoCheckAction() - a command executed before the receipt fiscalization. This may be the order closing, refund, guest bill printing, guest bill canceling, and product return. The main purpose of it is to check the operation availability and to add some extra details to a receipt.

How to add extra details to a receipt?

You can do it in two ways:

• By adding a receipt template in «Syrve Office» > «Administration» > «Receipt templates» > «Add» > «Type: Addition to fiscal receipt». The template will be added at the bottom of receipt chequeTask.TextAfterCheque. This is not a custom FCR function, so you don’t need to register IChequeTaskProcessor.

• The plugin can add its values to chequeTask.TextBeforeCheque, chequeTask.TextAfterCheque and change a cashier name chequeTask.cashierName. This data will be sent to the FCR for printing. For this, you need to fill up corresponding fields in the resulting BeforeDoCheckActionResult. value. If fields are not to be edited, return null.

public BeforeDoCheckActionResult BeforeDoCheckAction(ChequeTask chequeTask, ICashRegisterInfo device, CashRegisterChequeExtensions chequeExtensions, IViewManager viewManager)
{
 var beforeCheque = new List<Data.Print.Document>();
 var documentBefore = new Data.Print.Document();
 documentBefore.Markup.Add(new XElement(Tags.LargeFont, "Welcome"));
 documentBefore.Markup.Add(new XElement(Tags.SmallFont, "tel. 555-123456"));
 beforeCheque.Add(documentBefore);

 var afterCheque = new List<Data.Print.Document>();
 var documentAfter = new Data.Print.Document();
 documentBefore.Markup.Add(new XElement(Tags.SmallFont, "Thank you for shopping"));
 documentBefore.Markup.Add(new XElement(Tags.QRCode, "en.syrve.help"));
 beforeCheque.Add(documentAfter);
	
 return new BeforeDoCheckActionResult
 {
     BeforeCheque = beforeCheque,
     AfterCheque = afterCheque,
     CashierName = "CashierName"
 };
}

Arguments of the BeforeDoCheckAction() function:

• chequeTask — order details. All details on order items, discounts/surcharges, payments, and so on (check the External Fiscal Registers article).
• device — information about the fiscal register used to close the order.
• chequeExtensions — receipt additional information. Stores the markup to be added to the receipt top or bottom (chequeExtensions.BeforeCheque, chequeExtensions.AfterCheque). It also stores the chequeExtensions.PastOrderId identifier and chequeExtensions.PastOrderNumber number of the order closed within the previous till shift. These fields are filled up when past till shift orders are refunded.
• viewManager — window manager.It allows displaying preset Syrve POS dialogs (check the Dialogs).

2. AfterDoCheckAction

AfterDoCheckAction() — a command executed after the receipt fiscalization operation. The main purpose of it is to perform the final action after the printing of receipts. For example, to queue the operation of export to the external system. The result argument describes an FCR operation result. result.Success = true — operation is successful, otherwise, it is not. If the operation is not successful result.Success = false, the error description will be given in result.Message.

3. BeforeXReport

BeforeXReport() — a command executed before printing an X Report. The following parameters are passed: a fiscal register that performs the operation, IViewManager to display messages or data input, and the authUser user who initiated the printing of the X report.

4. AfterXReport

AfterXReport() — a command executed after printing an X Report. The arguments are similar to the AfterDoCheckAction command.

5. BeforeZReport

BeforeZReport — a command executed before printing a Z Report. Parameters pass the following data: FCR, user, and the IViewManager window manager.

6. AfterPayIn

AfterPayIn — a command executed after depositing money to the cash register. The function receives the following data: FCR, FCR response during the deposit operation, the IViewManager window manager, and the amount of money deposited to the cash register.

7. AfterPayOut

AfterPayOut — a command executed after withdrawing money from the cash register. The function receives the following data: FCR, FCR response during the withdrawal operation, the IViewManager window manager, and the amount of money withdrawn from the cash register.

Additional Interfaces IReadonlyChequeTaskProcessor and IEditableChequeTaskProcessor

Along with the IChequeTaskProcessor interface described above, there are IReadonlyChequeTaskProcessor and IEditableChequeTaskProcessor, extending interfaces which allow completing specific tasks before depositing and withdrawing.

They are registered the same way as the parent interface. The difference between them is only that when using the IReadonlyChequeTaskProcessor interface, the plugin, during the withdrawal, cannot edit the withdrawal amount, whereas the IEditableChequeTaskProcessor — interface can do it through the ref estimatedSum parameter. This is implemented to let the plugin control withdrawal amounts at the end of the day.