API Documentation | PurchasePlus

Table of Contents

Overview

Authentication

Authorisation

The PurchasePlus 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 5 separate modules representing functional areas within PurchasePlus. Each module has its own swaggerhub reference documentation. Your application may need to interact with some or all of these modules, depending on your requirements.

The API can be used by any Purchasing or Supplying Organisation in the PurchasePlus ecosystem. You will require the email address and password of a registered PurchasePlus user account to use the PurchasePlus API. To obtain a user account, please speak with an administrator at your Organisation, or contact our friendly customer success team.

API URLs

The PurchasePlus API can be accessed via the following URLs:

Production Environment: https://api.purchaseplus.com
Staging Environment: https://staging.api.purchaseplus.com‍

Technical Reference Documentation

Swaggerhub reference documentation is available for each of our separate API modules. We are in the process of thoroughly updating our documentation for each module, and we anticipate completion of this by July 2024. The app.swaggerhub.com paths shown below are being gradually replaced with the purchaseplus.com paths. In the meantime, please consider the app.swaggerhub.com paths insufficiently documented and maintained.

Access Module: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Access/2.0
Goods Module: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Goods/2.0‍
Inventory Module: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Inventory/2.0
Point of Sale Module: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-PointOfSale/2.0
Purchasing Module: https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Purchasing/2.0‍

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. To obtain additional authorisation please speak with an administrator at your Organisation, or contact our friendly customer success team.

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 and is out of your control. Please contact our team 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"

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

For 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"
}

Relationship Links

Every resource will contain a link to itself in the following 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, for example;

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

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 provided, 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, or any new or deleted fields.

Rate Limiting

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"

Idempotent Requests

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 our team if the limit value is too low for your requirements.

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

Change Notes

September 2019

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

April 2024

An overhaul of the PurchasePlus Version 2 API commences. Updated swaggerhub documentation is underway for all modules. The team will review and update all of our Version 2 offering, and ensure that swaggerhub documentation reflects current functionality. We anticipate completion of this project by July of 2024, with the exciting addition of a new Supplying module.