Table Orders

Make sure you familiarize yourself with the following important concepts of our API:
Prices and Quantities, Products and Articles, Sync Markers
After taking the time to understand these concepts, you will much better understand the basics of our API.

Introduction

Creating table orders is a function used mostly by handheld devices to place an order that is attached to a specific table number in the POS system. Before you can use the function, you need to register as a valid ordering terminal through another function. This tutorial explains how to do all this.

Notice: Table orders are different from regular orders. Make sure you implement the correct one for your use case.

Contents

getAvailableTerminalList Retrieving a list of available terminals

You need to register your application as a terminal before you can place table orders. The following function allows you to retrieve a list of the available terminals in the POS system.

Note: When the customer is also using their own handheld devices, you need to make sure you are not using a terminal used by their handheld devices, because it will interfere with their operation. There needs to be a dedicated terminal that is solely used by the application you are building. To add a new terminal to the list of available terminals, please contact the POS system software supplier of your customer.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
(...)
 
// Then we call the getAvailableTerminalList() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($available_terminals = $mplusqapiclient->getAvailableTerminalList())) {
    // Success, we show the number of retrieved available_terminals.
    exit(sprintf('Retrieved %d available_terminals.', count($available_terminals)));
  } else {
    exit('Unable to retrieve available_terminals.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

registerTerminal Registering as a terminal

After you have selected a terminal out of the $available_terminals, you can use it to register as a terminal with the POS system.

Note: When the customer is also using their own handheld devices, you need to make sure you are not using a terminal used by their handheld devices, because it will interfere with their operation. There needs to be a dedicated terminal that is solely used by the application you are building. To add a new terminal to the list of available terminals, please contact the POS system software supplier of your customer.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
 
// Initialize the client with your details. (...)
 
$selected_terminal = array('branchNumber'=>1,'terminalNumber'=>2,'uniqueDeviceIdentifier'=>'{string that uniquely identifies the terminal}');
 
// This is an example terminal, your actual terminal should always be coming out of the list retrieved with `getAvailableTerminals`
 
// Then we call the registerTerminal() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->registerTerminal($selected_terminal, true)) {
    // Success
    exit('Terminal is successfully registered.');
  } else {
    exit('Unable to register terminal.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

saveTableOrder Saving a table order

Only after you have successfully registered with the POS system as a terminal, you can create and update table orders.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
<?php require_once('Mplusqapiclient.php'); $mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details. (...) $selected_terminal = array('branchNumber'=>1,'terminalNumber'=>2); // This is an example terminal, your actual terminal should be coming out of the list retrieved with `getAvailableTerminals`
 
// Register the terminal
(...)
 
$table_order = array(
  'orderId' => null, // fill this out when you are updating instead of creating a table order
  'tableNumber' => 18,
  'extOrderId' => 'EXTERNAL123',
  'financialBranchNumber' => 1, // the branch to register the order to (in most occasions there is only one branch)
  'financialDate' => time(),
  'lineList' => array(
    array(
      'articleNumber' => 103,
      'data' => array(
        'quantity' => 1,
        ),
      'preparationList' => array(
        array(
          'articleNumber' => 521,
          'data' => array(
            'quantity' => 1,
            ),
          ),
        ),
      ),
    ),
  );
 
// Then we call the saveTableOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->saveTableOrder($selected_terminal, $table_order)) {
    // Success
    exit('Table order is successfully saved.');
  } else {
    exit('Unable to save table order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getTableOrder Getting a table order

Use this function to get the current status of the requested table order.

saveTableOrder Updating a table order

Use this function to update an existing table order. Use getTableOrder first to get the current values of versionNumber and changeCounter. Use them in your call, to let the API know that you are working with the latest version of the table order.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php require_once('Mplusqapiclient.php'); $mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details. (...) $selected_terminal = array('branchNumber'=>1,'terminalNumber'=>2); // This is an example terminal, your actual terminal should be coming out of the list retrieved with `getAvailableTerminals`
 
// Register the terminal
(...)
 
$table_order = array(
  'orderId' => '08ddc39b-6cf0-42bf-8cdb-1c8ccb20de49', // get this value from first running getTableOrder
  'tableNumber' => 18,
  (...)
  'versionNumber' => 2, // get this value from first running getTableOrder
  'changeCounter' => 2, // get this value from first running getTableOrder
  'lineList' => array(
    ...
    ),
  );
 
// Then we call the saveTableOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->saveTableOrder($selected_terminal, $table_order)) {
    // Success
    exit('Table order is successfully saved.');
  } else {
    exit('Unable to save table order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

payTableOrder Paying a table order

Use this function to update an existing table order. Use getTableOrder first to get the current values of versionNumber and changeCounter. Use them in your call, to let the API know that you are working with the latest version of the table order.

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<?php require_once('Mplusqapiclient.php'); $mplusqapiclient = new Mplusqapiclient(); // Initialize the client with your details. (...) $selected_terminal = array('branchNumber'=>1,'terminalNumber'=>2); // This is an example terminal, your actual terminal should be coming out of the list retrieved with `getAvailableTerminals`
 
// Register the terminal
(...)
 
$table_order = $mplusqapiclient->getTableOrder($selected_terminal, $branchNumber=1, $tableNumber=1);
 
$payments = array(
  array(
    'method' => 'CONTANT',
    'amount' => 2500, // 25,00 paid with cash
    ),
  array(
    'method' => 'EFT',
    'amount' => 10000, // 100,00 paid with EFT payment method
    ),
  );
 
// Then we call the payTableOrder() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== $mplusqapiclient->payTableOrder($selected_terminal, $table_order, $payments)) {
    // Success
    exit('Table order is successfully paid.');
  } else {
    exit('Unable to pay table order.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}