Relations

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

Relations in Mplus can be persons or companies. For example, customers are relations, but so are suppliers and other companies you do business with.

Contents

getRelations Getting a list of all relations

Use this function to get a complete or partial list of all available relations.
You can use the array relationNumbers to limit the results to specific relations.
You can specify a syncMarker to limit the results to changes since a certain moment.
Learn more about sync markers here.

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.
 
$relationNumbers = array();
$syncMarker = 0;
 
// Then we call the getRelations() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($relations = $mplusqapiclient->getRelations($relationNumbers, $syncMarker))) {
    // Success, we show the amount of found relations
    exit(sprintf('Found %d relations.', count($relations)));
  } else {
    exit('Failure while getting relations.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

getRelation Retrieving an existing relation

If you happen to already know the number of an existing relation, you can use that to retrieve the data of that relation.

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.
 
$relation_number = 681; // We happen to know a relation with number 681 exists.
 
// Then we call the getRelation() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($relation = $mplusqapiclient->getRelation($relation_number))) {
    // Success, we've now got the relation's data.
    exit(sprintf('Retrieved relation with number %d.', $relation['relationNumber']));
  } else {
    // Failure, relation not found.
    exit('Unable to retrieve relation.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

findRelation Finding an existing relation

Before you create new relations in an Mplus database, it might be wise to check whether or not a relation with your data already exists. This way, you can reuse or update an existing relation. You can do this using the API function findRelation. The search terms are all optional and also case-insensitive. They will also match partially, so ‘john d’ will match ‘John Doe’.

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
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// First we create the array that will the relation's data.
$relation = array(
  'name' => 'Doe Inc',
  'address' => 'Main Street 134b',
  'zipcode' => '12345',
  'city' => 'Small Town',
  'country' => 'Faraway',
  'telephone' => '123456789',
  'mobile' => '987654321',
  'email' => 'john.doe@example.com',
  'contact' => 'John Doe',
  'deliveryAddress' => 'Business Lane 44a',
  'deliveryZipcode' => 54321,
  'deliveryCity' => 'Big Town',
  'deliveryCountry' => 'Faraway',
);
 
// Then we call the findRelation() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($existing_relation = $mplusqapiclient->findRelation($relation))) {
    // Success, we show the existing relation's number.
    exit(sprintf('Found existing relation with number %d.', $existing_relation['relationNumber']));
  } else {
    exit('Relation not found. We\'d better create a new one.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

List of possible fields to search in.
​- extRelationId
​- name
​- address
​- zipcode
​- city
– ​country
​- deliveryAddress
​- deliveryZipcode
​- deliveryCity
​- deliveryCountry
​- contact
​- telephone
​- mobiel
​- email
​- website
​- relationCode
​- birthDate
​- categoryId
​- cardNumber
​- bankAccountNumber

createRelation Creating a new relation

If an existing relation is not found, you can create a new relation. The following example shows the findRelation function followed up with the createRelation function.

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.
 
// First we create the array that will hold the new relation's data.
$relation = array(
  'name' => 'Doe Inc',
  'address' => 'Main Street 134b',
  'zipcode' => '12345',
  'city' => 'Small Town',
  'country' => 'Faraway',
  'telephone' => '123456789',
  'mobile' => '987654321',
  'email' => 'john.doe@example.com',
  'contact' => 'John Doe',
  'deliveryAddress' => 'Business Lane 44a',
  'deliveryZipcode' => 54321,
  'deliveryCity' => 'Big Town',
  'deliveryCountry' => 'Faraway',
);
 
// Then we call the findRelation() and createRelation() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false === ($existing_relation = $mplusqapiclient->findRelation($relation))) {
    if (false !== ($relation_number = $mplusqapiclient->createRelation($relation))) {
      // Success, we show the created relation's number.
      exit(sprintf('Created relation with number %d.', $relation_number));
    } else {
      // Failure, unfortunately something went wrong.
      exit('Unable to create relation.');
    }
  } else {
    exit(sprintf('Found existing relation with number %d.', $existing_relation['relationNumber']));
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

updateRelation Updating an existing relation

If you know a relation already exists, and you have its relation number, you can update the existing relation instead of creating a new one. The syntax to updating a relation is very similar to finding a relation.

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
<?php
 
require_once('Mplusqapiclient.php');
 
$mplusqapiclient = new Mplusqapiclient();
// Initialize the client with your details.
 
// First we create the array that will hold the relation's new data.
// In this case, we know the existing relation has number 681.
$relation = array(
  'relationNumber' => 681, // If you don't add this parameter, updateRelation won't work.
  'name' => 'Doe Inc',
  'address' => 'Main Street 134b',
  'zipcode' => '12345',
  'city' => 'Small Town',
  'country' => 'Faraway',
  'telephone' => '123456789',
  'mobile' => '987654321',
  'email' => 'john.doe@example.com',
  'contact' => 'John Doe',
  'deliveryAddress' => 'Business Lane 44a',
  'deliveryZipcode' => 54321,
  'deliveryCity' => 'Big Town',
  'deliveryCountry' => 'Faraway',
);
 
// Then we call the updateRelation() function wrapped in a try/catch block to intercept any exceptions.
try {
  if (false !== ($result = $mplusqapiclient->updateRelation($relation))) {
    // Success, the relation was updated.
  } else {
    // Failure, unfortunately something went wrong.
    exit('Unable to update relation.');
  }
} catch (MplusQAPIException $e) {
  exit($e->getMessage());
}

adjustPoints Adjust points of a relation

Best Practices
How to keep your application up to date with the latest data

The best way to keep your application up to date with our relations is through the use of the syncMarker property.

How you ask? When your application runs for the first time you call getRelations with a syncMarker of 0. This will return a list of relations from the API (for a maximum of 1000 at a time).

You then start processing the list and each time you do you save the highest syncMarker that was processed. For your next run you take the syncMarker that you saved, increment its value with 1 and use that for your next call to getRelations.

When relations are changed on our side, its syncMarker gets updated. Therefore, if you use this method, you will only receive a list of all the changed relations. This makes for a faster and more efficient synchronization process.

Learn more about Sync Markers here.