Skip to main content
Matrix42 Self-Service Help Center

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.

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

  • /mpl-api/Check
    Request for testing connectivity

GET

  • /mpl-api/MplProduct
    Dictionary Request for the list of current Marketplace-Products

GET

  • /mpl-api/MplOrder
    Create a new OrderGET

POST

  • /mpl-api/MplOrder/{id}
    Load client-relevant data of an existing Order

GET

  • /mpl-api/MplSubscription/{id}
    Cancel an existing Subscription

DELETE

  • /mpl-api/MplPartnerCustomer/{id}
    Load Customers for Partner

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

  • Was this article helpful?