README

Hcapi is a tool created for easier connection between shopping adviser Heureka.cz and shops which users of these services and shopping cart want.

About this fork

This is a Bestfornet fork of heureka/hcapi, which has been unmaintained since November 2018 (last release v1.0.1). The namespace stays Hcapi\, so the fork is a drop-in replacement — no code changes are needed when switching over.

Differences against upstream v1.0.1:

Depot API delivery type — added DeliveryType::DELIVERY_TYPE_DEPOT_API = 9. Without it, carts using Heureka's external pickup point providers fail validation.
Depot API store type — added StoreType::STORE_TYPE_DEPOT_API = 3, the store type used for external pickup points (see the depot-api shipper list).
Tolerant price validation — upstream compared count * price against priceTotal, and the sum of priceTotal against priceSum, using the strict !== operator. Comparing floats that way rejects valid carts: prices are carried rounded to two decimal places, so binary representation and per-unit rounding produce differences that are not errors. Both checks now compare with a tolerance of ProductsAvailability::PRICE_TOLERANCE (0.01) per unit / per product, and the exceptions report the expected and received value so mismatches can be diagnosed.

Verified to run on PHP 8 — the source contains no constructs removed in PHP 7 or 8. The bundled test suite still targets PHPUnit 5 and is kept as it was upstream.

Usage

Install by composer:

composer require bestfornet/hcapi

Implementation

In this section you will find the manual for hcapi implementation to your project.

Connection via Callables

First way how to connect your shop by HCAPI is using Callable callback.

In your code must create functions (for all services), which receive data from Heureka (array), process them and return required data (array). Structure of required data you can find there.

Example of function for Payment/Status:

//PaymentStatus.php

public function setPaymentStatus($receiveData)
    {
        //set payment status for order

        return [
            'status' => false,
        ];
    }

In second step you must connect these functions with your routing. You must use specific service for every from API methods. For example Payment/Status:

//Router.php

if ($_SERVER['REQUEST_URI'] === 'https://www.example.com/api/1/payment/status') {
            $service = new PaymentStatus();
            return $service->processData(
                [
                    'Hcapi\Example\CallableExample\PaymentStatus',
                    'setPaymentStatus',
                ],
                $receiveData);
        }

Services are located in /src/Services/ More examples are located in /example/InterfaceExample/

Implementation via Interfaces

Second way how to connect your shop by HCAPI is via Interfaces. In folder /scr/Interfaces/ is located interface IShopImplementation.php. You must implement this interface for all classes which work with data from Heureka.

Example:

class OrderCancel implements IShopImplementation
{
    /**
     * @param array $receiveData
     *
     * @return array
     */
    public function getResponse($receiveData)
    {
        //Do something with receive data

        return [
            'status' => true,
        ];
    }

}

In second step you must connect this functions to your routing. You must use specific service for every from API methods. For example Order/Cancel:

if ($_SERVER['REQUEST_URI'] === 'https://www.example.com/api/1/order/cancel') {
    $service = new OrderCancel();
    $orderCancel = new \Hcapi\Example\InterfaceExample\OrderCancel();

    return $service->processData($orderCancel, $receiveData);
}

More examples are located in /example/CallableExample/

bestfornet / hcapi

Maintainers

Package info

Statistics

Security