Table of Contents
API USAGE
For the implementation of any client software to use the API it is necessary to understand the context in which this API exists as well as the processes existing withing the Matrix42 Marketplace that apply to the retrieval and placement of Order-related data, including Product, Shipping, Subscription, and Order information.
Note: Access to the API is logged for improvement purposes.
The host for the API is a subdomain for the Matrix42 Website.
https://mpl-api.matrix42.com/
The particular routes included in the API are the following
|
GET |
|
GET |
|
POST |
|
GET |
|
DELETE |
|
GET |
Authentication and Headers
The authentication of all requests is based on a bearer token submitted in the header of the respective request.
The mechanism involves two steps. One is to obtain a personal access token (PAT) from https://accounts.matrix42.com/my/account (see above), the other is to obtain an access token via code from the exchange URL and use it in the authorization header of the request that is sent to the Marketplace API.
C# sample Code using PAT token to obtain token:
var httpWebRequest =
(HttpWebRequest)WebRequest
.Create("https://accounts.matrix42.com/api/se...okens/exchange");
httpWebRequest.Method = "GET";
httpWebRequest.PreAuthenticate = true;
httpWebRequest.Accept = "application/json";
httpWebRequest.Headers.Add("Authorization", "Bearer " + pat_token);The request has no payload body.
The result is a JSON with a single field containing the final token.
{
"RawToken": "eyJ0eXAiO..."
}The resulting Token can be used in all further requests as a Bearer Token in the Authorization Header.
Scope of retrievable Data
The data that can be queried by a Partner is restricted to those products that have been explicitly marked for availability in the Partner Center by Matrix42.
The initial list of orderable products is limited to the Ego Secure products (see below).
Over time, more and more products will be marked as available for the Partner Center, so the list will grow. The intention is to perform a gradual release of products.
| Product | License | Vendor |
| Cloud hosting Upgrade to Australia | per User | Matrix42 AG |
| Cloud hosting Upgrade to Germany | per User | Matrix42 AG |
| Cloud hosting Upgrade to Switzerland | per User | Matrix42 AG |
| Matrix42 Endpoint Security Analytics Saa S | per User | Matrix42 AG |
| Matrix42 Endpoint Security Encryption Saa S | per User | Matrix42 AG |
| Matrix42 Endpoint Security GDPR Saa S | per User | Matrix42 AG |
| Matrix42 Endpoint Security Prevention Saa S | per User | Matrix42 AG |
| Matrix42 Endpoint Security Protection Saa S | per User | Matrix42 AG |
Result structure
All routes return a Result object that contains overall information about the success of a request, as well as the requested payload data.
Fields
Status-Value, Integer, Code indicating the condition of the response
Message, String, Short informative notice
Exception-Message, String (optional), Elaborate, technical informative notice
Extra-Info, Dictionary, List of Key-Value pairs
JSON-Example
{
"StatusValue": 200,
"Message": "Everything is alright.",
"ExceptionMessage": null,
"ExtraInfo": null
}The Status-Value can contain any of the following code values as integer:
| 200 | OK | Request succeeded |
| 403 | Not allowed | Request failed due to an authorization restriction |
| 404 | Not found | Request failed due to unavailable result payload data |
If the request resulted in a response carrying payload data, then the Result structure contains additional informational fields, as well as a Data field which is an array of the requested payload (it is an array even if only a single instance is returned).
Fields
Status-Value, Integer
Message, String
Exception-Message, String (optional)
Total-Count, Integer, Overall number of available results
Offset, Integer, Start-index in paged data
Limit, Integer, Number of results in paged data
Extra-Info, Dictionary, Additional key-value-paired information
Data, Array, Response payload
JSON-Example
{
"StatusValue": 200,
"Message": "Hello world.",
"ExceptionMessage": null,
"TotalCount": 1,
"Offset": -1,
"Limit": -1,
"Data": [
{
"Id": 45614,
"Name": "Acme Inc",
"CustomerNumber": "2345678",
"BillingName": "Acme Inc.",
"Street1": "High Road 15",
"Zip": "12345",
"City": "Neverland",
"Country": "DE",
"Mail": "boss@acme.net"
}
]
}The functionality of the API and requesting data from it subject to the Matrix42 ACS authentication including the assignment of appropriate rights to induvial client systems.
For some routes language-dependent results are returned. The selection of the language is made via the HTTP-Header
Particular method routes
The particular routes with their respective parameters are as follows:
Check
mpl-api/Check GET
The purpose of the Check route is to simply allow for a client to test the connection, as to ensure the proper URL and authentication. The request has no URL arguments.
Response
{
"StatusValue": 200,
"Message": "Friday, 13 March 2020 14:08:42",
"ExceptionMessage": null
}Mpl Product
/mpl-api/Mpl Product GET
The purpose of the Mpl Product route is to send a request for a list of current Marketplace-Products that are available for ordering within the Partner Center context. The request has no URL arguments.
The request results in MPL Products that contain all necessary information for display to an end-customer and for subsequently placing an order.
Response
{
"StatusValue": 200,
"Message": null,
"ExceptionMessage": null,
"TotalCount": 8,
"Offset": -1,
"Limit": -1,
"ExtraInfo": {
"Request-Language": "English [ LCID = 9 ]"
},
"Data": [ (Array of MPL Product) ]
}The full specification of the result structure is contained in the Data Contracts section of this document. Due to its complexity it is not rendered here.
Mpl Order (with ID)
/mpl-api/Mpl Order/{id} GET
The purpose of the Mpl Order route is to load client-relevant data of an existing Order. The URL argument is the Order-ID of an existing Order.
The request results in a single record containing the information of one Order, including the Subscription information derived from the Order.
Response
{
"StatusValue": 200,
"Message": null,
"ExceptionMessage": null,
"TotalCount": 8,
"Offset": -1,
"Limit": -1,
"ExtraInfo": {
"Request-Language": "English [ LCID = 9 ]"
},
"Data": [ (Array of MPL Order with one entry) ]
}The full specification of the request and result structures is contained in the Data Contracts section of this document. Due to its complexity it is not rendered here.
Mpl Order
/mpl-api/Mpl Order POST
The purpose of the Mpl Order route is to place a new Order within the Matrix42 Marketplace. The request has no URL arguments, and it conveys the Order information from the request body. The required Order information is based on the data obtained via the Mpl Product route.
The request results in a single record containing the information of one Order, including the Subscription information derived from the Order. The result is identical in structure to the one retrieved via the previous Mpl Order GET route with the Order-ID as argument.
Request body
{
"CustomerId": 65996,
"CustomerName": "Matrix42 AG",
"ShippingInfo": {
"FirstName": "Stefan",
"LastName": "Gies",
"Company": "Matrix42 AG",
"Address1": "Elbinger Strasse 7",
"City": "Frankfurt am Main",
"Postcode": "60487",
"Country": "DE",
"Email": "stefan.gies@matrix42.com"
},
"OrderItems": [
{
"ProductId": 162269,
"ProductName": "Cloud hosting Upgrade to Germany",
"Quantity": 1
},
...More entries...
]
}Response
{
"StatusValue": 200,
"Message": null,
"ExceptionMessage": null,
"TotalCount": 8,
"Offset": -1,
"Limit": -1,
"ExtraInfo": {
"Request-Language": "English [ LCID = 9 ]"
},
"Data": [ (Array of MPL Order with one entry) ]
}The full specification of the result structure is contained in the Data Contracts section of this document. Due to its complexity it is not rendered here.
Mpl Subscription
/mpl-api/Mpl Subscription/{id} DELETE
The purpose of the Mpl Subscription route called with the DELETE verb is to cancel existing Subscriptions. The URL argument is the comma-separated list of IDs of the Subscription, as obtained via either Mpl Order call (POST for Order creation or GET by ID for Order retrieval).
The request results in a list containing information of the canceled Subscriptions grouped by originating Order, such as the success of the cancellation as well as the remaining run-time.
Response
{
"StatusValue": 200,
"Message": null,
"ExceptionMessage": null,
"TotalCount": 4,
"Offset": 0,
"Limit": 0,
"Data": [
{
"Id": 123456, /* Order ID */
"Success": true,
"Message": null,
"Subscriptions": [
{
"Id": 45678, /* Subscription ID*/
"Success": true,
"Message": null,
"StartDate": "2017-06-01T00:00:00",
"NextPaymentDate": null,
"EndDate": "2020-06-01T00:00:00"
},
... more entries ...
]
}
]
}The full specification of the result structure is contained in the Data Contracts section of this document. Due to its complexity it is not rendered here.
Mpl Partner Customer
/mpl-api/Mpl Partner Customer GET
The purpose of the Mpl Partner Customer route is to return a list of customers with which a Matrix42 Partner enterprise has current interactions. The information conveyed in the result
The request results in a list of basic Customer information that suffices to create the Shipping information of an Order for an already existing Customer.
Response
{
"StatusValue": 200,
"Message": null,
"ExceptionMessage": null,
"TotalCount": 216,
"Offset": -1,
"Limit": -1,
"Data": [
{
"Id": 66666,
"Name": "Matrizius",
"CustomerNumber": "6789012",
"BillingName": "Matrizius",
"Street1": "Der Beste Weg 3",
"Street2": "Matrizius GmbH & Co. KG",
"Zip": "76137",
"City": "Karlsruhe",
"Country": "DE",
"Mail": ""
},
... more entries ...
]
}The full specification of the result structure is contained in the Data Contracts section of this documention. Due to its complexity it is not rendered here.
The full documentation can be downloaded here: Matrix42 Marketplace Partner Center API 2020 03 31.pdf