Overview

Introduction

The BladePRO Public API allows fulfilment customers to view and create orders, products and purchase orders. We have developed the API to be powerful, but simple to integrate with. It is available over HTTPS using REST architecture to accept and return data in JSON format, making it compatible with most scripting languages.

Getting Help

For help or assistance with the Public API please contact technical support team at techops@i-fulfilment.co.uk providing as much detail about your issue as possible.

Where applicable please include:

The full endpoint address you are trying to access
Any error messages you are receiving
The payload you are sending with the request.
The date & time of your request
The username you are making the request with
The request_reference value ( if returned inside the response metadata )

Environments

There are two environments that developers can use when using the BladePRO Public API: Production or Sandbox. The Sandbox environment uses anonymised live data sampled from the production environment for each organisation to provide developers a realistic dataset to test with. No personal or sensitive data is kept within this data. This dataset is refresh every Sunday and any data created on the Sandbox during the week will be reset.

Along with an API access you can also request a regular user account for the BladePRO web portal. This will allow you to see the product and order data you are dealing and can often be helpful when debugging an issue.

Sandbox Details

Public API URL: https://public-api-sandbox.staging.bladepro.co.uk
BladePRO Web Portal: https://sandbox.staging.bladepro.co.uk
Data Refresh: Every Sunday

Production Details

Public API URL: https://public-api.bladepro.io
BladePRO Web Portal: https://app.bladepro.io

REST

The API uses REST architecture over HTTPS. To request, modify, create, or delete data you must select the appropriate HTTP method, shown below.

Method	Action	Description
GET	Read	Retrieve a list of records, or a single record
POST	Create	Add a new record
PUT	Update	Update an existing record
DELETE	Delete	Remove a record

Rate Limits

The BladePRO API uses a leaky bucket algorithm to limit the number of API calls per user in a given time period. A full bucket contains 500 possible connections, and each API endpoint called will deduct one connection from the bucket. An additional five connections will be added to the bucket every minute until it reaches the maximum.

If your bucket becomes empty, API calls will be rejected until more connections are added, i.e. you will be limited to five calls per minute.

Error Codes

The BladePRO API uses the following error codes:

Error Code	Name	Meaning
400	Bad Request	Your request is incorrectly formatted
401	Unauthorized	Your API key is wrong
403	Forbidden	You do not have access to the specified endpoint
404	Not Found	The specified endpoint could not be found
500	Internal Server Error	There is a problem with the API, please try again later

Scopes

The BladePRO API uses the following permission scopes:

Module	Scope	Description
Orders	APP::ORDERS::READ	View READ ONLY order records
Orders	APP::ORDERS::MANAGE	Read, create, update and delete order records
Products	APP::PRODUCTS::READ	View READ ONLY product records
Products	APP:PRODUCTS::MANAGE	Read, create, update and delete product records
Purchase Orders	APP::PURCHASE-ORDERS::READ	View READ ONLY purchase order records
Purchase Orders	APP::PURCHASE-ORDERS::MANAGE	Read, create, update and delete purchase order records
Returns	APP::RETURNS::READ	View READ ONLY return records
Returns	APP::RETURNS::MANAGE	Read, create, update and delete return records
Vendors	APP::VENDORS-ORDERS::READ	View READ ONLY vendor records
Vendors	APP::VENDORS-ORDERS::MANAGE	Read, create, update and delete vendor records

Structure

BladePRO’s Public API works using pre-defined structures for accepting input and its response format. For each endpoint there will be descriptions for the following elements, when appropriate:

Method and URL: Each endpoint is defined by its HTTP method and URL. The URL will never have query string requirements, the base part is always enough to use the endpoint. Segments of the URL with a leading colon character (:) are parameters. These parameters are always syntax checked using regular expressions.
Description: What the endpoint does.
Parameter Regular Expressions: A list of parameters and their regular expressions that need to match the value in order to successfully use the endpoint.
Request Body: The type of input the endpoint requires in the request body, JSON encoded. Some endpoints perform actions that do not require further data, in these cases this section will state that the request body will be ignored.
Types for the Request Body: A list of types and their definitions, describing the endpoint’s validation rules.
Please note that the request types are local to the endpoint.
Return Type: The type of output the endpoint returns. In most cases, this is well defined and this section will contain a link to the type’s definition. These can be found in the Return Types section.
Please note that the return types are global to the API.
Filters: Lists retrieved can usually be filtered. Each filter works on a field on the return type, with one or more allowed operators. To filter by the field created, include the query parameter ?created[MORE_THAN]=2020-01-15 in the URL. This section includes a table of fields, and their accepted operators.
Sortings: Lists retrieved can usually be sorted. This section will contain the fields the results can be sorted by. To sort by the field created ascending, include the URL parameter ?sorting=created. For descending sorting include ?sorting=-created.
Available expands: The API can return related data based on what is allowed for the particular type and the endpoint being used. Include the URL parameter ?expand=…. In case of nested objects, use the dot (.) character to access inside the structure. Multiple relationships can be expanded by separating them with a comma (,).
For example, if the main type is a goodsout, and you want to see the warehouse, the warehouse country, and the lines on the goodsout, adding ?expand=warehouse.country,lines is the way to do that. Notice that you do not need to include warehouse separately.
Scopes: This section defines which permissions (scopes) a user will be required to have in order to access the endpoint.

Types for the Request Body

If present, this section will have one or more subsections. The first will be the one being used as the main type for the endpoint, and will be marked with the text "(root level)". The rest will follow in alphabetical order.

There will be a table in each of these sections, describing the type and listing the fields with description, allowed types and restrictions for validating the values. Fields are optional unless the required restriction is present. Also, fields can accept the value null, unless not null is present.

Possible types include:

integer: An integer, appearing as a number. Can not be a string containing an integer.
number: Any number, appearing as a number. Can not be a string containing a number.
string: A string of characters.
date: ISO formatted date in a string.
any: Any value.
object: Any object.
boolean: true or false.
array<type>: An array made of type elements.
map<string, type>: A key-value map made of string keys and type elements.
enum(value list): An enum, with the allowed values provided inside the brackets. Only the values’ string representations are valid, referencing them by indices is not.
Type: An object of type Type. Type will hold the name of the object and its definition will be included in the same section and will be clickable. These types can also appear in arrays and maps.

For most fields, there will be requirements for which values are valid. For fields with multiple allowed types, some restrictions might only apply to some types. In this case, the requirement text will say “if type is type, then …”. Possible requirements include:

required: The field must be present in the request body.
not null: The field cannot have the value null.
optionally required: The field is required in some cases. The description will always specify these cases.
min count: For arrays, the number of items that are required to appear. By default, array types are not required to have items.
min length: Minimum number of characters for strings.
max length: Maximum number of characters for strings.
match: Regular expression validation for strings.
min: Minimum value for numbers.
max: Minimum value for numbers.

Endpoint Filters

The filters section contain tables that describe which fields are filterable, what operators are allowed, and where the possible values can be retrieved from. It is possible to not filter at all, to filter by one or more different fields, and to filter each field by multiple operators, but it is not possible to filter by the same field and operator by multiple values.

This is valid: ?reference[NOT_EQUALS]=asdf&reference[LIKE]=asd, but this is invalid: ?reference[NOT_EQUALS]=asdf&reference[NOT_EQUALS]=zxcv as it contains two NOT_EQUALS operators.

For operators that allow multiple values, use a comma separated list: ?status[IN]=draft,active. Date types will require ISO strings for values.

The following operators are available:

Operator	Availability
EQUALS	strings, numbers, enums, booleans
NOT_EQUALS	strings, numbers, enums, booleans
IN	strings, numbers, enums
NOT_IN	strings, numbers, enums
LESS_THAN	strings, numbers, dates
MORE_THAN	strings, numbers, dates
LIKE	strings
NOT_LIKE	strings
ON_DATE	dates

Some fields reference library data, such as IDs for channels, warehouses etc. For such fields the Value List URL column of the filter specification will define the URL for the available values.