Bol.com Retailer API client for PHP

This is an open source PHP client for the Bol.com Retailer API version 5.

Installation

This project can easily be installed through Composer:

composer require picqer/bol-retailer-php-client "^5"

Usage

Create an instance of the client and authenticate

$client = new \Picqer\BolRetailerV5\Client();
$client->authenticate('your-client-id', 'your-client-secret');

Then you can get the first page of open orders by calling the getOrders() method on the client

$reducedOrders = $client->getOrders();

foreach ($reducedOrders as $reducedOrder) {
    echo 'hello, I am order ' . $reducedOrder->orderId . PHP_EOL;
}

Exceptions

Methods on the Client may throw Exceptions. All Exceptions have the parent class Picqer\BolRetailerV5\Exception\Exception:

ConnectException is thrown when a problem occurred in the connection (e.g. API server is down or a network issue). You may retry later.
ServerException (extends ConnectException) is thrown when a problem occurred on the Server (e.g. 500 Internal Server Error). You may retry later.
ResponseException is thrown when the received response could not be handled (e.g. not of proper format or unexpected type). Retrying will not help, investigation is needed.
UnauthorizedException is thrown when the server responded with 400 Unauthorized (e.g. invalid credentials).
RateLimitException is thrown when the throttling limit has been reached for the API user.
Exception is thrown when an error occurred in the HTTP library that is not covered by the cases above. We aim to map as much as possible to either ConnectionException or ResponseException.

Migrate from v4 to v5

If you're migrating from v4 to v5, please have a look at the Migration guide to see what has changed.

Generated Models and Client

All the Models and Client are generated by the supplied API specifications by Bol. By generating these this ensures no typos are made, not every operation needs a test and future (minor) updates to the specifications can easily be applied.

The generated classes contain all data to properly map method arguments and response data to the models: the specifications are only used to generate them.

Client

The Client contains all operations specified in the specifications. The 'operationId' is converted to camelCase and used as method name for each operation.

The specifications define types for each request and response (if it needs to send data). If a model for such a type encapsulates just one field, that model is abstracted from the operation have a smoother development experience:

A method in the Client accepts that field as argument instead of the model
A method in the Client returns the field from that model instead of the model itself

To generate the Client, the following composer script may be used:

# Generates Picqer\BolRetailerV5\Client
composer run-script generate-client

Models

The class names for models are equal to the keys of the array 'definitions' in the specifications.

To generate the Models, the following composer script may be used:

# Generates all Picqer\BolRetailerV5\Model\* models
composer run-script generate-models

Known quirks

Some type definitions in de specifications are sentences, for example 'Container for the order items that have to be cancelled.'. These are converted to CamelCase and dots are removed.
Some operations in the specifications have no response type specified, while there is a response. Currently, this is only the case for operations that return CSV.
There a type 'Return' defined in the specifications. As this is a reserved keyword in PHP, it can't be used as class name for the model (in PHP <= 7), so for now it's replaced with 'ReturnObject'.
If an array field in a response is empty, the field is (sometimes?) omitted from the response. E.g. the raw JSON response for getOrders is
```
{ }
```
where you might expect
```
{
  "orders": [ ]
}
```
Operation 'Get all invoices' is specified to have a string as response, while there is clearly some data model returned in JSON or XML.

arne-s/bol-retailer-php-client