2. Partner Center API Usage
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 EgoSecure 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 SaaS |
per User |
Matrix42 AG |
|
Matrix42 Endpoint Security Encryption SaaS |
per User |
Matrix42 AG |
|
Matrix42 Endpoint Security GDPR SaaS |
per User |
Matrix42 AG |
|
Matrix42 Endpoint Security Prevention SaaS |
per User |
Matrix42 AG |
|
Matrix42 Endpoint Security Protection SaaS |
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
}
MplProduct
/mpl-api/MplProduct GET
The purpose of the MplProduct 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.
MplOrder (with ID)
/mpl-api/MplOrder/{id} GET
The purpose of the MplOrder 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.
MplOrder
/mpl-api/MplOrder POST
The purpose of the MplOrder 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 MplProduct 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 MplOrder 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.
MplSubscription
/mpl-api/MplSubscription/{id} DELETE
The purpose of the MplSubscription 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 MplOrder 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.
MplPartnerCustomer
/mpl-api/MplPartnerCustomer GET
The purpose of the MplPartnerCustomer 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_PartnerCenter_API_2020_03_31.pdf