Introduction

Welcome to the MBX API. This API outlines some of the standard integration capabilities offered by MBX Systems. Our API follows standard RESTful practices, which means that the API users can push and request information directly to and from the API using standard HTTP verbs.

We also have webhooks available that allow you to subscribe to specific order events. When one of those events is triggered, we’ll send an HTTP POST payload to the webhook’s configured URL.

In addition, we offer a variety of other custom integration paths and have setup custom EDI’s with most ERP systems, such as NetSuite, Oracle, and SAP.

For additional details and integration assistance, please contact your account manager to setup an integration consultation with our technical team.


What You Can Do with the API

The MBX Systems API allows you to integrate your internal operations with MBX Systems to automate and streamline activities such as purchasing, fulfillment and inventory management. Using our API and direct integration services you can reduce process time and lower your administration costs by pulling and pushing data directly between your system and MBX Systems operating platform.

Examples include:

  • Get automatic updates of your fulfillment orders with shipment notifications and tracking information.
  • Push purchase orders and fulfillment orders directly to MBX from your order management platform.
  • Update purchase and fulfillment orders with real time anticipated shipment dates.
  • Streamline billing reconciliation by pulling outstanding invoice information.
  • Pull real-time inventory information directly into your application.

Authentication

The MBX API allows for two different forms of authentication. For the highest level of security we provide support for HMAC (or Hash-based message authentication code). Additionally we also support authentication via OAuth 2 for API users that are using a client or library that already has built in support for standard OAuth 2.

HMAC

MBX strongly recommends the use of an HMAC for authentication. The API user needs to send an HMAC signature, along with a set of special HTTP headers, when they make an API request. An HMAC signature is the product of a hash function that is applied to the body of the request along with the user's secret token.

Instead of having to send your username and password with the request, you send a string that contains an identifier for the secret token and an HMAC. When the server receives the request, it looks up the secret token and uses it to create an HMAC signature. Having the HMAC signature ensures that the request is authentic. If the HMAC signature submitted with the request matches the signature calculated by the server, the request will be authenticated.

To generate the HMAC signature and send an API request, the API user needs the following information:

Information Description
Public token Provided by MBX Systems
Secret token Provided by MBX Systems
HTTP request verb Ex: GET, POST, etc.
Current date in ISO-8601 format Ex: yyyy-mm-dd
Data or body of the request The request from the API user
URL or endpoint the request is being sent to Ex: /v2/customer_order_submissions

Please contact your Account Manager to obtain a Public and Secret token.

HMAC generation code:

Python
import binascii
import md5
import hashlib
import string
import collections
import requests
import datetime
import hmac

Credentials = collections.namedtuple('Credentials', ['token', 'secret'])

def headers(token, signature, date):
    """Generates the request header"""
    auth_template = string.Template("$token:$signature")
    auth_header = auth_template.substitute(token=token, signature=signature)
    return {"MBX-Auth": auth_header,
            "Content-Type": "application/json",
            "X-Date": date}

def signature(secret, verb, data, url, date):
    """Generates the authentication signature"""
    m = md5.new()
    m.update(data)
    thing = "\n".join([verb, m.hexdigest(), date, url])
    h = hmac.new(secret, thing, hashlib.sha1)
    return binascii.b2a_base64(h.digest()).rstrip('\n')

Node.js and Crypto.js will need to be installed prior to running the Javascript HMAC generation.

Javascript
var Crypto = require('cryptojs').Crypto
var https = require('https');

var headers = function(token, signature, date){
  return {"MBX-Auth": token + ':' + signature, "X-Date": date, "Content-Type": "application/json"}
};

var signature = function(secret, verb, data, url, date){
  var hashedData = Crypto.MD5(data);
  var preHmac = verb + '\n' + hashedData + '\n' + date + '\n' + url;
  return Crypto.util.bytesToBase64(Crypto.HMAC(Crypto.SHA1, preHmac, secret, {asBytes: true}));
};

var credentials = {
  token: "token-provided-by-mbx",
  secret: "secret-provided-by-mbx"
};

var date = new Date().toISOString();
var apiServer = "api-sandbox.mbx.com";
var data = JSON.stringify({});
var url = '/v2/authenticate';
var verb = 'POST';
var sig = signature(credentials.secret, verb, data, url, date);

var options = {
  host: apiServer,
  path: url,
  port: 443,
  method: 'POST',
  headers: headers(credentials.token, sig, date)
}

var callback = function(response){
  var str = ''
  response.on('data', function (chunk) {
    str += chunk;
  });

  response.on('end', function () {
    console.log(str);
  });
}

var req = https.request(options, callback);
req.write(data);
req.end();

OAuth 2

The MBX API also supports the OAuth 2.0 protocol for authentication and authorization. MBX supports common OAuth 2 scenarios such as those for server and client-side applications.

To begin, MBX will provide you with a client id and client secret which will be used to authenticate your application. You will need to provide a redirect URL which will be used to receive the access grant or authentication token.

Step 1: Obtain an access grant

To start the authentication process, your application must obtain an access grant by sending your client_id to the GET /oauth/authorize endpoint. The only unique parameter in this request is the client_id, which will be provided by MBX.

GET /oauth/authorize?response_type=code&client_id=myclientid HTTP/1.1
User-Agent: Example HTTP Client
Host: api.mbx.com
Accept: */*

The API server will respond with a 302 redirect to your predefined redirect URL with the access grant code as the parameter. Your application at the redirect URL can then pull the access grant code from its parameters. Alternatively, your application may elect to receive the code directly from the Location HTTP response header.

HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Status: 302 Found
Location: http://www.example.com?code=examplegrant

If the client id is not valid, the API server will return a 401 error with the error message of Invalid client_id.

Step 2: Obtain a bearer token

After receiving the access grant code from step 1, you will use it to request a bearer token from the POST /oauth/token endpoint. You will also include the client_id and client_secret provided by MBX within the parameter list.

POST /oauth/token HTTP/1.1
Host: api.mbx.com
User-Agent: Example HTTP Client
Accept: */*
Content-Length: 107

grant_type=authorization_code&code=t5vTMArm3dd1kufSvAw3dw&client_id=myclientid&client_secret=myclientsecret

If all the parameters are correct, the API server will respond with a JSON object containing the bearer token and for how long the bearer token is valid.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Status: 200 OK

{"access_token":"Px_SL8iAOWQVcqKqs3CU_A","token_type":"bearer",
"expires_in":10800,"refresh_token":"WURMUaWlrd0-ImwapRsHaw"}

This bearer token will be used to authorize future API requests. Since bearer tokens are set to expire after 3 hours, a refresh token can also be given to generate new bearer tokens.

Step 3: Authenticate using the bearer token

To authorize an individual request, include an authorization header with the given bearer token from step 2. For example, you can make a request to the GET /v2/authenticate endpoint to validate that your bearer token is valid.

GET /v2/authenticate HTTP/1.1
Host: api.mbx.com
User-Agent: Example HTTP Client
Accept: */*
Authorization: Bearer Px_SL8iAOWQVcqKqs3CU_A

If the request was successfully authorized, you will receive a 200 OK response with the results of the given query.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Status: 200 OK

Successfully authenticated as Example Organization

The 'q' Parameter

Requests will be passed through the "q" parameter as URI escaped JSON.

Command example:

Python
GET /api/v2/people?q=%7B"limit"%3A5%7D

Output Format

Results will be returned in standard JSON format.

JSON example:

JSON
{
    "count":1000,
    "offset":0,
    "total_results":54153,
    "results":
        [
            {
                ...
            }
        ],
    "errors":null
}

HTTP Verbs

The HTTP verb examples below are using the items endpoint. The actions of the verbs will work the same across all endpoints.

GET

If the API user needs to retrieve a list of items from the API, they can send a GET request to the items endpoint.

GET request example:

Python
print requests.get("https://api.mbx.com/v2/items", headers = headers(credentials.token, sig, date)).text

If the API user needs to retrieve information on a specific item from the API, they can send a GET request to the items endpoint that includes the item ID.

GET request example (for specific item):

Python
print requests.get("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

DELETE

If the API user needs to delete a record, they can send a DELETE request to the model endpoint.

DELETE request example:

Python
print requests.delete("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

POST

If the API user needs to create a record, they can send a POST request to the model endpoint.

POST request example:

Python
print requests.post("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text

PUT

If the API user needs to update a record, they can send a PUT request to the model endpoint.

PUT request example:

Python
print requests.put("https://api.mbx.com/v2/items/123456", headers = headers(credentials.token, sig, date)).text