Shipping methods

API endpoint: /plugin/delivery

Allows you to create a custom shipping method on the store and display an interactive shipping address selection in the order form.

Creating a new shipping method

POST /plugin/delivery

 
    {
        "name": "My Delivery Method",
        "description": "Optional Description",
        "image": "https://plugin.tld/images/icon.png",
        "widget": "<script src="https://plugin.tld/delivery.js"></script>"
    }

The above request will create the basis for a new shipping method on the e-shop. The user of the e-shop is left free to set up the new transport in more detail (price of transport, connection with payment methods, name, etc.)

Example: 

 
    $curl = curl_init();
    curl_setopt_array($curl, array(
        CURLOPT_URL => 'https://api.webareal.cz/plugin/delivery',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => json_encode([
            "name" => "My Delivery Method",
            "description" => "Optional Description",
            "image" => "https://plugin.tld/images/icon.png",
            "widget" => "<script src="https://plugin.tld/delivery.js"></script>"
        ])
        CURLOPT_HTTPHEADER => array(
            'X-Wa-api-token: ' . $api_token, // apiToken získáte při instalaci doplňku, viz. nápověda
            'Authorization: Bearer ' . $bearer, // access token získáte zde, údaje zde (záložka API přístup)
            'Content-Type: application/json'
      ),
    ));

    $response = curl_exec($curl);
    curl_close($curl);
    echo $response;

Working with the widget

If the customer has selected this shipping method on the e-shop, the HTML/JS code is displayed on the order form page.

Eshop defines a JS interface BS.delivery to simplify working with the widget popup window and saving the selected delivery address.

Methods of the object:

  • openWindow(options) - display the widget window. The options parameter is an object with the following properties:
    • title <string> - window name
    • body <HTMLElement> - content of the window
    • dialogSize <string> - the size of the window. Possible values: md, lg, full
  • closeWindow() - closing the widget window
  • goBack() - return the customer to the previous step of the ordering process
  • save(address) - confirm the choice of delivery address. The method returns a Promise object. The address parameter is an object with the following properties:
    • name <string> - name on the delivery address (optional)
    • address <string> - street, descriptive number...
    • city <string> - city
    • zipCode <string> - postal code
    • data <Object> - optional custom data (e.g. the identifier of the selected branch).

Example of a simple widget implementation

 
    document.addEventListener('DOMContentLoaded', () => {
        "use strict";

        const options = {
            title: 'My Delivery',
            body: content,
            dialogSize: 'lg'
        };

        const template = `
            <div>
                <h5>Select pickup point</h5>
                <button type="button" class="js-plugin-close">Close</button>
                <button type="button" class="js-plugin-confirm">Confirm</button>
            </div>
        `;

        const content = document.createElement('div');
        content.innerHTML = template;

        const buttons = content.querySelectorAll('button');
        for(const button of buttons) {
            button.addEventListener('click', e => {
                if(e.target.classList.contains('js-plugin-close')) {
                    BS.delivery.closeWindow();
                } else {
                    BS.delivery.save({
                        name: 'Name',
                        address: 'Street, 12',
                        city: 'City',
                        zipCode: '12345',
                        data: {
                            point: 1,
                        }
                    }).then(address => {
                        console.log(address);
                        BS.delivery.closeWindow();
                    }).catch(e => {
                        console.log(e);
                    });
                }
            })
        }

        setTimeout(() => {
            BS.delivery.openWindow(options);
        }, 500);
    });

Submitting your own data after creating an order

If the plugin has registered order.create webhook, the order data object is extended with the custom values of the address object under the pluginData key.

Back