Preview - new service methods and APIs

These are the new service methods in development.

raylopay/product/:variation_id/is_supported

This service method checks whether a given product or product variation is supported by Raylo Pay.

Full URL: https://<domain>/rest/V1/raylopay/product/:variation_id/is_supported

Parameters (URL segment):

• :variation_id — string, ID of a product or product variation.

Return type:

{
    "success": true,
    "result": {
        "isSupported": boolean
    }
} | {
    "success": false,
    "error": string,
}

Example return value:

{
    "success": true,
    "result": {
        "isSupported": true
    }
}

raylopay/order/send_update

This service method checks whether a given product or product variation is supported by Raylo Pay.

Full URL: https://<domain>/rest/V1/raylopay/order/send_update

Parameters (POST body):

{
    "order_id": string, // ID of the order in the Merchant system
    "updateInfo": {
        "state": "fulfilled" | "cancelled", // only these two values are accepted
        "stateTimestamp": string, // ISO datetime string
        "fulfillment": undefined | { // can be omitted if the state is "cancelled"
            "courierName": string | undefined,
            "courierReference": string | undefined,
            "courierTrackingUrl": string | undefined,
            "items": Array<{
                "variant": {
                    "reference": string
                },
                "assetDetails": {
                    "imei": string,
                    "serial": string
                } | {
                    "imei": string
                } | {
                    "serial": string
                } | 
            }>
        }
    }
}

Return type:

{
    "success": true,
} | {
    "success": false,
    "error": string,
}

Example return value:

{
    "success": true,
}

Notes:

If the update call originates from the same system, it will be possible to call a PHP API directly. An indicative implementation of it's interface, both for rest calls and direct PHP calls:

<!-- etc/webapi.xml -->

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../vendor/magento/module-webapi/etc/webapi.xsd">
    <!-- ... existing routes ommitted for brevity -->
    <route method="GET" url="/V1/raylopay/product/:variation_id/is_supported">
        <service class="Raylo\RayloPay\Api\InternalServiceInterface" method="getIsProductSupported" />
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
    <route method="POST" url="/V1/raylopay/order/send_update">
        <service class="Raylo\RayloPay\Api\InternalServiceInterface" method="sendOrderUpdate" />
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

// Api/InternalServiceInterface.php

// namespace subject to change
namespace Raylo\RayloPay\Api;

class AssetDetails {
    public ?string $imei = '';
    public ?string $serial = '';
}

class ProductVariant {
    public string $reference = '';
}

class OrderItemUpdateInfo {
    public ProductVariant $variant;
    // at least one of imei or serial should be provided
    public AssetDetails $assetDetails;
}

class FulfillmentInfo {
    public ?string $courierName = '';
    public ?string $courierReference = '';
    public ?string $courierTrackingUrl = '';

    /** @var OrderItemUpdateInfo[] */
    public array $items = [];
}

class OrderUpdateInfo {
    public const ORDER_STATE_FULFILLED = "fulfilled";
    public const ORDER_STATE_CANCELLED = "cancelled";

    // should be one of the values above
    public string $state = '';

    public \DateTime $stateTimestamp;

    public ?FulfillmentInfo $fulfillment;
}

/**
 * This interface defines service methods that enable the integration with a custom UI or another service via HTTP calls.
 * 
 * @api
 */
interface InternalServiceInterface {

    // ... existing service interface declarations ommitted for brevity ...
    
    // new methods:
    
    /**
     * Gets an object containing a boolean value indicating whether the given product or product variation is supported by Raylo.
     * `isSupported` in the return value is expected to contain `true` if the product is mapped by Raylo and currently available for leasing; `false` otherwise.
     * 
     * @api
     * @param int $variationId The ID of the product or product variation to check for support.
     * @return \Raylo\RayloPay\Model\Api\InternalServiceResponse<\stdClass> An which indicates whether the given product or product variation is supported. That object contains a single property `isSupported` of type `bool`.
     */
    public function getIsProductSupported(int $variationId)
        : \Raylo\RayloPay\Model\Api\InternalServiceResponse;

    /**
     * Send an update to Raylo regarding a specific order.
     * @param int $orderId The ID of the order to update.
     * @param OrderUpdateInfo $updateInfo Update to send about the order.
     * @return \Raylo\RayloPay\Model\Api\InternalServiceResponse<\stdClass> Result of the update call to the Raylo service.
     */
    public function sendOrderUpdate(int $orderId, OrderUpdateInfo $updateInfo)
        : \Raylo\RayloPay\Model\Api\InternalServiceResponse;
}

// Controller/API/InternalService.php

/**
 * This class implements service methods that enable the integration with a custom UI or another service via HTTP calls.
 * 
 * @api
 */
class InternalService implements InternalServiceInterface {

    // ... existing service class implementation ommitted for brevity ...
    
    // new methods:

    public function getIsProductSupported(int $variationId): InternalServiceResponse {
        // available for preview only; always returns `true` in preview.
        // defining return type as an object rather than a singe bool for possible extension in future.
        return $this->doServiceMethod(fn () => 
            (object)[
                'variationId' => $variationId,
                'isSupported' => true,
            ]);
    }

    public function sendOrderUpdate(int $orderId, OrderUpdateInfo $updateInfo): InternalServiceResponse {
        // available for preview only; always returns success in preview.
        return $this->doServiceMethod(fn () => 
            (object)[
                // there will be nothing else returned besides the top level success/error info
            ]);
    }
}