Open source: Bol.com Plaza offer management SDK

I recently had to integrate the new Bol.com offer management API into a project. There was no SDK available, so I had to figure most things out by myself. The library I created was heavily integrated into the existing code, so I decided to recreate a stand-alone SDK for others to use.

Features

  • Offer management
  • Request validation
  • Offer validation
  • Understandable error messages
  • Condition enum
  • Delivery code enum

Installation

Simple requiry the `koenreiniers/bol-sdk` package through composer:

composer require koenreiniers/bol-sdk

Usage

There are two ways to use the SDK. The recommended way is using `Kr\Bol\Plaza`, which has predefined methods for each API call.
You can use it as follows:

use \Kr\Bol\Plaza;
use \Kr\Model\Offer;

$plaza = new Plaza($publicKey, $privateKey);
// Create an offer
// Note you can also create an Offer model the old fashioned way using getters/setters
$offer = Offer::toCreate($id, $ean, $condition, $price, $deliveryCode, $quantityInStock, $publish, $referenceCode, $description);
$plaza->;createOffer($offer);

// Update an offer
$offer = Offer::toUpdate($id, $price, $deliveryCode, $publish, $referenceCode, $description);
$plaza->updateOffer($offer);

// Update an offer's stock
$offer = Offer::toUpdate($id, $quantityInStock);
$plaza->updateOfferStock($offer);
// Alternatively:
$plaza->updateOfferStock($id, $quantityInStock);

// Delete an offer
$offer = Offer::toDelete($id);
$plaza->deleteOffer($offer);
// Alternatively:
$plaza->deleteOffer($id);

// Request an export of your offers
$exportFilename = $plaza->requestExport($filter);
// Try to read an export
$offers = $plaza->readExport($exportFilename);

PlazaClient

Alternatively, you can use `\Kr\Bol\Http\PlazaClient`, which can be used for any Plaza api call:

use \Kr\Bol\Http\PlazaClient;

$plazaClient = new PlazaClient($publicKey, $privateKey);
$plazaClient->get("/offers/v1");
$plazaClient->post("/offers/v1", $content);
$plazaClient->put("/offers/v1", $content);
$plazaClient->delete("/offers/v1");

The downside of using `\Kr\Bol\PlazaClient` is that it doesn’t validate your offers against Bol.com’s predefined rules, which `\Kr\Bol\Plaza` does.

Other

There’s also a few more things like the Enums for conditions and delivery codes. They are primarily used to validate offers, but you can also use them to list all the available conditions and delivery codes:

use \Kr\Bol\Enum\Condition;
use \Kr\Bol\Enum\DeliveryCode;

$conditions = Condition::all();
$deliveryCodes = DeliveryCode::all();

And let’s not forget the `HeaderGenerator`:

$headerGenerator = new \Kr\Bol\Http\HeaderGenerator();
$headers = $headerGenerator->generateHeaders($publicKey, $privateKey, $target, $method);