API Documentation

Introduction

The Purchase Plus API is a RESTful API. It uses resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and a mix of standard and extended action verbs.

The API is broken down into separate modules representing functional areas within PurchasePlus. Each module has its own reference page. Your application may only need to interact with one or two of these modules depending on your requirements.

URLs

Authentication

The PurchasePlus API uses token-based authentication. You will be required to make a request to sign in, upon which you will receive your Access-token, Client and Uid from the headers of a successful authentication.

To sign in:

$ curl -D - https://api.purchaseplus.com/access/api/auth/sign_in
-H “Accept: application/vnd.mbapi.v2+json”
-d “email=your.name@yourbusiness.com&password=yourpassword"

Change the email and password values to your own.

If you receive an error at this point please refer to the errors section.

If you are successful you will receive a response containing information about your user account in the body of the response, and in the headers will be the Access-token, Client and Uid

Access-token XxhhFMpq-RQxBJb_LhuCNO
Client 4eWvqjwfS8KFaNG89dD4Tj
Uid your.name@yourorganisation.com

In all subsequent API calls you will need to provide those three header values in order to successfully call an endpoint.

$ curl https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices
-H “Accept: application/vnd.mbapi.v2+json”
-H “Access-token: XxhhFMpq-RQxBJb_LhuCNO“
-H “Client: 4eWvqjwfS8KFaNG89dD4Tj“
-H “Uid: your.name@yourorganisation.com”

Authorisation

Once your user is authenticated, the resources you will have access to and what you can do with those resources is controlled by the authorisation system.

This is currently based on the Personas your user has been assigned and can only be maintained through the PurchasePlus user interface. Please contact help@marketboomer.com if you need access to additional resources.

Errors

PurchasePlus uses standard error codes to indicate whether your request was successful or there was an issue of some kind. The following table describes what the codes mean:

200 – OK The request was successful
400 – Bad Request A bad request has been made, possibly missing data
401 – Unauthorised The authentication details you provided are incorrect. Follow the Authentication process carefully to ensure you are providing a valid Access-token, Client, and Uid
403 – Forbidden Your user account does not have the authorisation to perform that action or retrieve that data.
404 – Not Found The resource you’ve asked for cannot be found. Check the URL carefully, and if an id was required, make sure it is correct.
406 – Not Acceptable Your request is missing required attributes.
409 – Conflict An indicator that the resource you are updating may have already been updated since you retrieved it.
429 – Too Many Requests You have made too many API requests. Our current limit is 5 per second. If you feel this value is too low for your requirements please contact us.
500 – Error This is an error on the PurchasePlus server out of your control. Please inform us if the issue persists.

Pagination

For requests that return multiple records it may be necessary for you to make multiple requests to retrieve all the results.

To do this you can pass the `page` parameter with the page number you wish to request.

$ curl https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices
-H “Accept: application/vnd.mbapi.v2+json”
-H “Access-token: ”
-H “Client: ”
-H “Uid: ”
-d “page=2"

See the Links section for useful links that will provided to assist with retrieving paginated data.

Links

Resource and Collection links

For a response that contains a resource it will contain a links attribute that will at minimum have a link to “self”, and if the resource has associated collections there will be links for those associations as well.

Pagination links

For a response that returns a collection of resources a separate links object will be included.

This links object will contain links for:

  • first: The first page of the collection
  • last: The last page of the collection
  • next: The next page of the collection
  • prev: The previous page of the collection

Example:

"links": {
    "first": "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=1&per_page=25",
    "last": "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=2&per_page=25",
    "prev": null,
    "next": "https://api.purchaseplus.com/supply/en/api/suppliers/xxx/catalogues?page=2&per_page=25"
}

Relationships Links

Every resource will contain a link to itself in the format:

"links": {
  "self": "https://api.purchaseplus.com/supply/api/suppliers/xxx/catalogues/xxxxxx/priced_catalogued_products/xxxxxxx"
}

Each resource may also have links to relationships that are relevant that that resource. For instance, a sale may have a link for retrieving the lines for that sale. You can take this link and use it to make a subsequent API call to retrieve that information.

"relationships": {
  "lines": {
    "links": {
      "self": "https://api.purchaseplus.com/point_of_sale/api/sales/1/lines"
    }
  }
}

Each resource may also have relationship data that can be used to look up information from the included Related Resources (see below).

"relationships": {
  "product": {
    "data": {
      "type": "products",
      "id": "411853"
    }
  }
}

Related Resources

Some calls to retrieve resource data will also return related resources to save the need to make subsequent API calls.

An example is retrieving product data on an invoice line, or details about a department with an invoice.

"included": [
  {
    "id": "xxxxxx",
    "type": "products",
    "attributes": {
      "concatenated_description": "Chicken Thigh Meat : Diced (AW 2.5kg) 1 kg"
    }
  }
}

Filtering

For requests that return multiple records it is possible to filter the result of these using filter parameters.

An example which will return invoices containing the string “INV”:

$ curl https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices
-H “Accept: application/vnd.mbapi.v2+json”
-H “Access-token: ”
-H “Client: ”
-H “Uid: ”
-d “filter[invoice_number_cont]=INV"

The available options for the filters include:

Predicate Description Notes
*_eq equal
*_not_eq not equal
*_matches matches with LIKE e.g. q[email_matches]=%@gmail.com
*_does_not_match does not match with LIKE
*_matches_any Matches any
*_matches_all Matches all
*_does_not_match_any Does not match any
*_does_not_match_all Does not match all
*_lt less than
*_lteq less than or equal
*_gt greater than
*_gteq greater than or equal
*_present not null and not empty Only compatible with string columns. Example: q[name_present]=1 (SQL: col is not null AND col != ”)
*_blank is null or empty. (SQL: col is null OR col = ”)
*_null is null
*_not_null is not null
*_in match any values in array e.g. q[name_in][]=Alice&q[name_in][]=Bob
*_not_in match none of values in array
*_lt_any Less than any SQL: col < value1 OR col < value2
*_lteq_any Less than or equal to any
*_gt_any Greater than any
*_gteq_any Greater than or equal to any
*_matches_any *_does_not_match_any same as above but with LIKE
*_lt_all Less than all SQL: col < value1 AND col < value2
*_lteq_all Less than or equal to all
*_gt_all Greater than all
*_gteq_all Greater than or equal to all
*_matches_all Matches all same as above but with LIKE
*_does_not_match_all Does not match all
*_not_eq_all none of values in a set
*_start Starts with SQL: col LIKE ‘value%’
*_not_start Does not start with
*_start_any Starts with any of
*_start_all Starts with all of
*_not_start_any Does not start with any of
*_not_start_all Does not start with all of
*_end Ends with SQL: col LIKE ‘%value’
*_not_end Does not end with
*_end_any Ends with any of
*_end_all Ends with all of
*_cont Contains value uses LIKE
*_cont_any Contains any of
*_cont_all Contains all of
*_not_cont Does not contain
*_not_cont_any Does not contain any of
*_not_cont_all Does not contain all of
*_true is true
*_false is false
*_fuzzy Full text search
*_time_from
*_time_to
*_quarter_equals Matches any date that falls within the quarter. Can use either Q1, q1 or 1 (for quarter 1).

Request IDs

Each request you make to our API will be logged and assigned a request id. This Id is returned in the header as PP-Request-Id.

You can use this request id when making any requests for technical support for a particular request you are having issues with.

Versioning

The PurchasePlus API is currently on version 2.0.

When making a request to the system you must provide the version information in the request header. If this is not given then the system will assume you intend to use the deprecated version 1.0 API (API reference here: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlus/1.0.0)

To set the version number on a request set the “Accept” header with a value of “application/vnd.mbapi.v2+json”

$ curl https://api.purchaseplus.com/access/api/auth/sign_in
-H “Accept: application/vnd.mbapi.v2+json”

Refer to the Change Notes below for any breaking version changes, new endpoints being added, and any new or deleted fields.

Rate Limiting

The PurchasePlus API has implemented rate limiting in order to protect all of our users from experiencing load issues. If your application reaches this rate limit you will begin to see HTTP error code 429 on your requests. Currently our limit is 5 requests per second per IP address. Please contact if you feel this value is too low for your requirements and we can investigate alternative solutions for you.

In order to handle these errors gracefully we recommend that your application monitors for 429 errors and implements a retry mechanism whenever they occur.

Idempotent Requests

The PurchasePlus API can optionally support idempotency which will help prevent the same transaction from occurring multiple times.

In order to use this you must provide a header on your API request called “Idempotency-Key”. This is case sensitive and its value must be a UUID.

If you make a request with the same Idempotency-Key then you will receive a cached version of the original successful result.

You should only be providing an Idempotency-Key for POST or PATCH requests as they are not needed for GET or DELETE.

Example:

$ curl https://api.purchaseplus.com/purchasing/api/purchaser/:id/invoices
-H "Accept: application/vnd.mbapi.v2+json"
-H "Idempotency-Key: ca2a1871-82a2-496f-a2d2-3525d69426c3"
-H "Access-token: XxhhFMpq-RQxBJb_LhuCNO"
-H "Client: 4eWvqjwfS8KFaNG89dD4Tj"
-H "Uid: your.name@yourorganisation.com"

February 2020

Inventory module API documentation complete.

Support for Idempotent Requests added.

API request rate limiting added.

Added supplier_product_code and purchaser_product_code to Invoice Line Item results in the Purchasing module.

Added department as a related resource to Invoice results in the Purchasing module.

November 2019

Changes to Point of Sale endpoints to better suit user workflow.

Completed Point of Sale API module documentation.

Initial endpoints available for suppliers to upload catalogue information.

New documentation section for Related Resources.

September 2019

Version 2 of the PurchasePlus API is introduced (see Versioning section for more detail).

Initial endpoints in Version 2 will be for the Point of Sale module.

Using the API Reference

The API Reference is broken into a page for each module within PurchasePlus. Follow the link to the module you wish to review.

The documentation is hosted on SwaggerHub and has been specified using version 3.0.1 of the OpenAPI specification.

The endpoints for each PurchasePlus resource are grouped together at the top of the page. Expanding a resource will show you what actions are available.

At the bottom of the page is documentation regarding the schema of the resources themselves.

Using the “Try it out” function

If you do not have a user account yet with PurchasePlus you may use the virtual server for that module. It will return example responses based on the resource and action you have chosen.

If you wish to try out the endpoints using one of our real servers you may do so by choosing the appropriate server from the Servers drop down. Doing so will require you to have a user account on that system in order to retrieve your authentication details (See Authentication).

You will then need to click on the Authorize button to bring up a dialog to enter your Access-token, Client, and Uid.

“Try it out” caveats

If using the virtual server you will be receiving pre-determined example responses so do not expect the parameters you pass to the actions to match up with the example response. This does not apply when using the real server endpoints.