Merge pull request #5 from jacobdekeizer/returns

Add returns endpoint

examples/04-returns.php

@@ -0,0 +1,34 @@
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// get unhandled returns paginated by 50 items
+
+$unhandledReturns = Picqer\BolRetailer\ReturnItem::all(1, false);
+
+foreach ($unhandledReturns as $unhandledReturn) {
+    var_dump($unhandledReturn);
+}
+
+// get handled returns paginated by 50 items
+
+$handledReturns = Picqer\BolRetailer\ReturnItem::all(1, true);
+
+foreach ($handledReturns as $handledReturn) {
+    var_dump($handledReturn);
+}
+
+// get return by rma id
+
+$return = Picqer\BolRetailer\ReturnItem::get(123456);
+
+var_dump($return);
+
+// handle return
+
+Picqer\BolRetailer\ReturnItem::handle(
+    $return->rmaId,
+    Picqer\BolRetailer\ReturnItem::HANDLING_RESULT_RETURN_RECEIVED,
+    $return->quantity
+);
+

src/Exception/ReturnNotFoundException.php

@@ -0,0 +1,6 @@
+<?php
+namespace Picqer\BolRetailer\Exception;
+
+class ReturnNotFoundException extends HttpException
+{
+}

src/Model/ReturnItem.php

@@ -0,0 +1,49 @@
+<?php
+namespace  Picqer\BolRetailer\Model;
+
+use DateTime;
+
+/**
+ * @property int           $rmaId                The RMA (Return Merchandise Authorization) id that identifies this particular return.
+ * @property string        $orderId              The id of the customer order this return item is in.
+ * @property string        $ean                  The EAN number associated with this product.
+ * @property int           $quantity             The quantity that is returned by the customer.
+ * @property DateTime      $registrationDateTime The date and time when this return was registered.
+ * @property string        $returnReason         The reason why the customer returned this product.
+ * @property string        $returnReasonComments Additional details from the customer as to why this item was returned.
+ * @property string        $fulfilmentMethod     Specifies whether this shipment has been fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB). Defaults to FBR.
+ * @property bool          $handled              Indicates if this return item has been handled (by the retailer).
+ * @property string|null   $trackAndTrace        The track and trace code that is associated with this transport.
+ * @property string|null   $title                The product title.
+ * @property string|null   $handlingResult       The handling result requested by the retailer.
+ * @property string|null   $processingResult     The processing result of the return.
+ * @property DateTime|null $processingDateTime   The date and time when the return was processed.
+ * @property array|null    $customerDetails      The customer details
+ */
+class ReturnItem extends AbstractModel
+{
+    public const HANDLING_RESULT_RETURN_RECEIVED = 'RETURN_RECEIVED';
+    public const HANDLING_RESULT_EXCHANGE_PRODUCT = 'EXCHANGE_PRODUCT';
+    public const HANDLING_RESULT_RETURN_DOES_NOT_MEET_CONDITIONS = "RETURN_DOES_NOT_MEET_CONDITIONS";
+    public const HANDLING_RESULT_REPAIR_PRODUCT = "REPAIR_PRODUCT";
+    public const HANDLING_RESULT_CUSTOMER_KEEPS_PRODUCT_PAID = "CUSTOMER_KEEPS_PRODUCT_PAID";
+    public const HANDLING_RESULT_STILL_APPROVED = "STILL_APPROVED";
+
+    protected function getRegistrationDateTime(): ?DateTime
+    {
+        if (empty($this->data['registrationDateTime'])) {
+            return null;
+        }
+
+        return DateTime::createFromFormat(DateTime::ATOM, $this->data['registrationDateTime']);
+    }
+
+    protected function getProcessingDateTime(): ?DateTime
+    {
+        if (empty($this->data['processingDateTime'])) {
+            return null;
+        }
+
+        return DateTime::createFromFormat(DateTime::ATOM, $this->data['processingDateTime']);
+    }
+}

src/ReturnItem.php

@@ -0,0 +1,98 @@
+<?php
+namespace Picqer\BolRetailer;
+
+use GuzzleHttp\Exception\ClientException;
+use Picqer\BolRetailer\Exception\HttpException;
+use Picqer\BolRetailer\Exception\ReturnNotFoundException;
+
+class ReturnItem extends Model\ReturnItem
+{
+    /**
+     * Get a single return.
+     *
+     * @param int $id The RMA id that identifies this particular return.
+     *
+     * @return self|null
+     */
+    public static function get(int $rmaId): ?ReturnItem
+    {
+        try {
+            $response = Client::request('GET', "returns/${rmaId}");
+        } catch (ClientException $e) {
+            static::handleException($e);
+        }
+
+        return new self(json_decode((string) $response->getBody(), true));
+    }
+
+    /**
+     * Get all returns.
+     *
+     * @param int    $page    The requested page number with a pagesize of 50
+     * @param bool   $handled The status of the returns you wish to see, shows either handled or unhandled returns.
+     * @param string $method  The fulfilment method. Fulfilled by the retailer (FBR) or fulfilled by bol.com (FBB).
+     *
+     * @return ReturnItem[]
+     */
+    public static function all(int $page = 1, bool $handled = false, string $method = 'FBR'): array
+    {
+        $query = [ 'page' => $page, 'handled' => $handled, 'fulfilment-method' => $method ];
+
+        try {
+            $response = Client::request('GET', 'returns', ['query' => $query]);
+            $response = json_decode((string) $response->getBody(), true);
+        } catch (ClientException $e) {
+            static::handleException($e);
+        }
+
+        /** @var array<array-key, mixed> */
+        $returns = $response['returns'] ?? [];
+
+        return array_map(function (array $data) {
+            return new self($data);
+        }, $returns);
+    }
+
+    /**
+     * Handle the return.
+     *
+     * @param int    $rmaId            The RMA id that identifies this particular return.
+     * @param string $handlingResult   The return item handling type.
+     * @param int    $quantityReturned The amount of items returned.
+     *
+     * @return Model\ProcessStatus
+     */
+    public static function handle(int $rmaId, string $handlingResult, int $quantityReturned): Model\ProcessStatus
+    {
+        $data = [ 'handlingResult' => $handlingResult, 'quantityReturned' => $quantityReturned ];
+
+        try {
+            $response = Client::request('PUT', "returns/${rmaId}", ['body' => json_encode($data)]);
+        } catch (ClientException $e) {
+            static::handleException($e);
+        }
+
+        return new ProcessStatus(json_decode((string) $response->getBody(), true));
+    }
+
+    private static function handleException(ClientException $e): void
+    {
+        $response = $e->getResponse();
+
+        if ($response && $response->getStatusCode() === 404) {
+            throw new ReturnNotFoundException(
+                json_decode((string) $response->getBody(), true),
+                404,
+                $e
+            );
+        } elseif ($response) {
+            throw new HttpException(
+                json_decode((string) $response->getBody(), true),
+                $response->getStatusCode(),
+                $e
+            );
+        }
+
+        throw $e;
+    }
+}