Invoices

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

Using these API functions, you will be able to request the invoices based on certain search criteria you set in the request.

Contents

getInvoice Retrieving invoice

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

findInvoice Finding invoice

PHP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!--?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
$extInvoiceId = "INV-0001"; // This can be a number come from your internal system
 
// Then we call the findInvoice() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($invoice = $mplusqapiclient->findInvoice($extInvoiceId ))) {
    exit('Found invoice.');
  } else {
    exit('Unable to find invoice.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}
</pre-->

getInvoices Retrieving invoices

When you want to synchronize invoices from Mplus to another application, it is smart to make use of Sync Markers.

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

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
<!--?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// Then we create the request array that will contain the search criteria
$syncMarker = null;
// Search for invoices from August 1, 2014 up to and including August 31, 2014
$fromFinancialDate = '2014-08-01';
$throughFinancialDate = '2014-08-31';
// Only get invoices that are booked on branch 1
$branchNumbers = array(1);
// We don't want to filter by employee, so we leave this empty
$employeeNumbers = array();
// We don't want to filter by customer, so we leave this empty
$relationNumbers = array();
// We only want invoices that contain an article with barcode '87123456789'
$articleBarcodes = array('87123456789');
// We don't care about the remaining article filters
$articleNumbers = array();
$articleTurnoverGroups = array();
$articlePluNumbers = array();
 
$syncMarker, $fromFinancialDate, $throughFinancialDate, $branchNumbers = null, $employeeNumbers = null, $relationNumbers = null, $articleNumbers = null, $articleTurnoverGroups = null, $articlePluNumbers = null, $articleBarcodes = null)
 
// Then we call the getInvoices() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($invoices_result = $mplusqapiclient->getInvoices($syncMarker, $fromFinancialDate, $throughFinancialDate, $branchNumbers, $employeeNumbers, $relationNumbers, $articleNumbers, $articleTurnoverGroups, $articlePluNumbers, $articleBarcodes))) {
    // Success, we show the number of found invoices
    exit(sprintf('Found %d invoice(s).', count($invoices_result)));
  } else {
    exit('Invalid result after running getInvoices.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}
</pre-->

saveInvoice Creating new invoice

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
<!--?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
$invoice = array(
  'invoiceType' => 'INVOICE-TYPE-INVOICE',
  'relationNumber' => 1022, // relationNumber must be present in Mplus
  'extInvoiceId' => "INV-0001", // any string is allowed, but must be unique
  'reference' => "Descriptive text",
  'branchNumber' => 1, // branchNumber must be present in Mplus
  'financialBranchNumber' => 1, // financialBranchNumber must be present in Mplus
  'employeeNumber' => 999999, // employeeNumber must be present in Mplus
  // options are:
  // (1) VAT-METHOD-INCLUSIVE (VAT included)
  // (2) VAT-METHOD-EXCLUSIVE (VAT excluded)
  // (3) VAT-METHOD-SHIFTED (VAT shifted, for international business)
  'vatMethod' => 'VAT-METHOD-EXCLUSIVE',
  'lineList' => array(
    array(
      'articleNumber' => 13, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 200, // prices are always in cents
        ),
      ),
    array(
      'articleNumber' => 10, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 4000, // prices are always in cents
        ),
      ),
    array(
      'articleNumber' => 22, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 600, // prices are always in cents
        ),
      ),
    ),
  );
 
// Then we call the saveInvoice() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($result = $mplusqapiclient->saveInvoice($invoice))) {
    $invoiceId = $result['invoiceId']; // Save this internally, you can use it later to retrieve and update the invoice.
    exit('Saved invoice.');
  } else {
    exit('Unable to save invoice.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

saveInvoice Update existing invoice

When you update an exising invoice, you first need to retrieve the current invoice from the API, so you can fill the versionNumber and changeCounter parameters with the proper values. Doing this “proves” to the API that you are aware of the most recent version of the invoice, and are knowingly adding or omitting invoice lines.

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<!--?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// This is an example ID, you should have saved this earlier when creating the invoice.
// Alternatively, you can first call `findInvoice` using your own `extInvoiceId` and retrieve the proper `invoiceId` that way.
$invoiceId = '47bba911-1d4e-4eda-a23b-c147e7167472';
 
$versionNumber = null;
$changeCounter = null;
 
try {
  if (false !== ($invoice = $mplusqapiclient->getInvoice($invoiceId))) {
    $versionNumber = $invoice['versionNumber'];
    $changeCounter = $invoice['changeCounter'];
  } else {
    exit('Unable to get invoice.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}
 
$invoice = array(
  'invoiceId' => $invoiceId,
  'versionNumber' => $versionNumber,
  'changeCounter' => $changeCounter,
  'invoiceType' => 'INVOICE-TYPE-INVOICE',
  'relationNumber' => 1022, // relationNumber must be present in Mplus
  'extInvoiceId' => "INV-0001", // any string is allowed, but must be unique
  'reference' => "Descriptive text",
  'branchNumber' => 1, // branchNumber must be present in Mplus
  'financialBranchNumber' => 1, // financialBranchNumber must be present in Mplus
  'employeeNumber' => 999999, // employeeNumber must be present in Mplus
  'lineList' => array(
    array(
      'articleNumber' => 13, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 200, // prices are always in cents
        ),
      ),
    array(
      'articleNumber' => 10, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 4000, // prices are always in cents
        ),
      ),
    array(
      'articleNumber' => 22, // articleNumber must be present in Mplus
      'data' => array(
        'quantity' => 1,
        'price' => 600, // prices are always in cents
        ),
      ),
    ),
  );
 
// Then we call the saveInvoice() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($result = $mplusqapiclient->saveInvoice($invoice))) {
    var_dump($save_result);
    exit('Saved invoice.');
  } else {
    exit('Unable to save invoice.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

payInvoice Pay an invoice

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
<!--?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// This is an example ID, you should have saved this earlier when creating the invoice.
$invoiceId = '47bba911-1d4e-4eda-a23b-c147e7167472';
 
$payments = array(
  array(
    'method' => 'K_WEBSHOP', // used to identify payment method, must be present in Mplus
    'amount' => 1995, // 19,95 EUR
  ),
);
 
// Then we call the payInvoice() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($pay_result = $mplusqapiclient->payInvoice($invoiceId, $payments))) {
    // Success, we show the result
    var_dump($pay_result);exit;
  } else {
    exit('Invalid result after running payInvoice.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}