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
- For production: https://api.purchaseplus.com
- For testing: https://demo.api.purchaseplus.com
- OR https://staging.api.purchaseplus.com
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: “ -H “Client: “ -H “Uid: ”
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. |
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.
Change Notes
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.
- Access – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Access/2.0
- Accounting – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Accounting/2.0
- Billing – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Billing/2.0
- Goods – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Goods/2.0
- Inventory – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Inventory/2.0
- Point of Sale – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-PointOfSale/2.0
- Purchasing – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Purchasing/2.0
- Rebates – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Rebates/2.0
- Recipes – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Recipes/2.0
- Supply – https://app.swaggerhub.com/apis-docs/marketboomer/PurchasePlusAPI-Supply/2.0