Skip to content

Woocommerce Couriero Plugin Developer Documentation

Plugin Structure

For every new courier, we need to create new shipping class which will extend the class from the WooCommerce abstract class WC_Shipping_Method.

1. Creating Class

Before we create a new class, make sure to create new courier php file inside relevant courier folder.

Create new folder inside couriers folder. You can give name of the folder as courier name. In our case we will give folder name as Bookurier as we are going to create new shipping method for Bookurier.

Create new php file and make sure to give unqiue class name. When creating a shipping method, we need to extend the class from the WooCommerce abstract class WC_Shipping_Method.

Our shipping calculation logic will go inside calculate_shipping method which will call laravel api of that specific courier and will return the shipping cost.

Below code snippets shows how new shipping method can be created in plugin. In our case, we will be creating Bookurier shipping method.

class WC_Bookurier_Courier_Shipping_Method extends WC_Shipping_Method {

    /**
     * Constructor for your shipping class
     *
     * @access public
     * @return void
     */
    public function __construct() {


        $this->id                 = 'wc_bookurier_courier_shipping_method'; // Id for your shipping method. Should be uunique.
        $this->method_title       = __( 'Bookurier Shipping', 'woo-cour' );  // Title shown in admin
        $this->method_description = __( 'Bookurier Shipping', 'woo-cour' ); // Description shown in admin

        // Availability & Countries
        $this->availability = 'including';

        // Shipping Method is only available for Romania Country
        $this->countries = array('RO');

        $this->init();

        $this->enabled = isset( $this->settings['enabled'] ) ? $this->settings['enabled'] : '';
        $this->title = isset( $this->settings['title'] ) ? $this->settings['title'] : __( 'Bookurier Shipping', 'woo-cour' );
    }

    /**
     * Init your settings
     *
     * @access public
     * @return void
     */
    function init() {
        // Load the settings API
        $this->init_form_fields(); 
        $this->init_settings();

        // Save settings in admin if you have any defined
        add_action( 'woocommerce_update_options_shipping_' . $this->id, array( $this, 'process_admin_options' ) );
    }

    /**
     * Define settings field for this shipping
     * @return void 
     */
    function init_form_fields() {

        // We will add our settings here

        $this->form_fields = array(

            'enabled' => array(
                            'title'         => __( 'Enable', 'woo-cour' ),
                            'type'          => 'checkbox',
                            'description'   => __( 'Enable this shipping.', 'woo-cour' ),
                            'default'       => 'no'
                        ),

            'title' => array(
                            'title'         => __( 'Title', 'woo-cour' ),
                            'type'          => 'text',
                            'description'   => __( 'Title to be display on site', 'woo-cour' ),
                            'default'       => __( 'Bookurier Shipping', 'woo-cour' )
                        ),


        );
    }
    /**
     * This function is used to calculate the shipping cost. Within this function we can check for weights, dimensions and other parameters.
     *
     * @access public
     * @param mixed $package
     * @return void
     */
    public function calculate_shipping( $package ) {

        // We will add the cost, rate and logics in here

    }
}

2. Adding shipping constant

It is required to define shipping constant which will define courier id.

Shipping constant file is located at couriers folder having file name as shipping-constant.php file.

For every courier, we can get the courier id from laravel. This id will be used to call api which will connect to that specific courier.

3. WooCommerce shipping identifier

We need to make sure that for every shipping courier, we need to provide unique identifer which will be used internally by WooCommerce shipping. Unique identifier can added inside public folder having file name as class-woocommerce-couriero-public.php inside method woo_cour_add_shipping_method

It's time to register new shipping method using WooCommerce woocommerce_shipping_methods filter hook.

Below code snippet shows how we can register new shipping method.

public function woo_cour_add_shipping_method( $methods ) {

    /**
     * This function is used to add new Woocommerce Shipping Method
     *
     *
     */
    $methods['wc_bookurier_courier_shipping_method']    = 'WC_Bookurier_Courier_Shipping_Method';

        return $methods;
}
add_filter( 'woocommerce_shipping_methods', 'woo_cour_add_shipping_method' );

4. Include Shipping file

After creating new shipping file and added unique identifier name, we can now include that shipping file. Shipping file can be included inside plugin root file having method name as woo_cour_shipping_method_init.

require plugin_dir_path(__FILE__) . 'couriers/Bookurier/class-woocommerce-bookurier-shipping.php';

5. Plugin Constant variable

Plugin constant variables are defined in plugin root file. We have added constant variables like API Base URL, Ajax URL, Front end base url which will be used throughout the plugin.

6. Git Flow

Before we integrate any new courier inside plugin make sure to create child branch from feature branch.

For example : If we need to integrate GLS courier in plugin then we will create child branch from feature branch. In our case child branch will be COUR-163 and feature branch will be COUR-68.

All the changes we need to push in relevant task branch which is COUR-163 and once all the integration completed then we always merge changes to feature branch. Once changes merged to feature branch then we need to make sure that all the functionality should work very well.

Once all the functionalities are working very well then we are ready to merge changes to develop branch.

Functionalities

1. Token Flow

1. Purchase Subscription

Before using Woocommerce Couriero plugin, we need to purchase subscription from here Marketing site.

2. Download plugin

Plugin zip file can be downloaded from Marketing site inside My Account » Downloads page.

3. Generate token/API key

Once subscription is purchased and if subscription status is Active then token will be generated automatically by calling laravel api from marketing site.

If for any reason token is not generated then we are providing an option inside My Account » Subscription page where user can generate token by clicking on Generate token button.

4. Validate token

To validate token, we need to add it inside Woocommerce Couriero plugin under Couriero Settings page in admin panel. Once we add token and click on Submit button, we will call validate_token laravel api which will check all the cases of that particular token and once validated it will redirect to same page which will list all couriers for integration.

5. Disconnect Domain

Once token is being validated, laravel will store Domain name as well as IP Address from where token was validated. We can see those information on Marketing site inside My Account » Subscription page.

It will show the Domain name as well as IP Address where token is being used currently.

If we want to use that some token to different domain then we can simply click on Disconnect Domain button from where token will be released and it is ready to use on another domain.

Disconnect Domain will call laravel api which will release domain and ip address for that specific subscription.

2. Couriero Settings

1. Setup Courier Token

A new admin page has been created called Couriero Settings which can be seen under WooCommerce menu in admin panel.

To add new token we will use Couriero Settings page and enter API key/token and validate the token.

Once token has been validated, we will store that token to plugin database table which is wp_options table having option name as woo_cour_api_token.

We will use this token everytime we call any laravel api like estimate cost, generate awb, download label, delete awb.

Whenever we call any laravel api, each time it will check whether token is valid or not, subscription is active or not. Failing any condition will gives error in result.

2. Import Courier Data

We have a button called Import Courier Data on Couriero Settings page which will import data from laravel to plugin database table.

For that, we had created two new database table named as wp_geolocations and wp_sameday_lockers.

These two new tables will be created automatically when activating WooCommerce Couriero Plugin.

3. Couriers List

All the couriers which has been implemented in laravel will be listed on couriers tab. So if any new courier integration will be done in laravel, then it will be listed at here.

1. Setup Bookurier
  • Adding Credentials

If you already have Bookurier credentials then you can add your credentials like Username, Password & Client Id into respective fields.

  • Select Pickup point

After credentials has been added, next step is to select pickup point from the dropdown. Pickup point selection is mandatory in-order to function Bookurier shipping.

  • Pricing table

We can manage pricing table for different weight per different county where custom amout can be added.

  • General settings

It is compulsory to add title of that particular shipping in a text field which will be displayed on cart/checkout page.

We also have different fields like maximum weight limit, cash on delivery fee limit, cash on delivery maximum limit, additional fee if weight goes beyond the maximum limit.

2. Setup Sameday
  • Adding Credentials

To setup Sameday courier you have to enter Sameday credentials like username and password and click on Save button.

  • Select Pickup point

After credentials has been added, next step is to select pickup point from the dropdown. Pickup point selection is mandatory in-order to function Sameday shipping.

3. Setup FanCourier
  • Adding Credentials

To setup FanCourier you have to enter FanCourier credentials like username, password & Client ID.

4. Setup GLS Courier
  • Adding Credentials

To setup GLS Courier you have to enter GLS courier credentials like username, password & Client ID.

  • Pricing table

For GLS courier, we have different fields to setup like maximum weight limit, maximum cash on delivery (cod) limit, pricing table for different weight and cash service table.

  • Pickup point

We have a functionality where you can create a new pickup point and can select anyone pickup point as a default pickup point which will be used while generating awb.

5. Setup UrgentCargus Courier
  • Adding Credentials

To setup UrgentCargus Courier you have to enter UrgentCargus courier credentials like username, password & Primary key. Once credential is being added and click on Save button.

  • Select pickup point

After credentials has been added, next step is to select pickup point from the dropdown. Pickup point selection is mandatory in-order to function UrgentCargus courier.

6. Extra Cost

We have a field called as Extra Cost (VAT) which we can added on the top of the shipping cost. Extra cost can be either percentage or fixed cost.

7. Enable/Disable Shipping Method

After credential has been added to respective field, we can enable/disable particular courier in-order to display shipping method on cart/checkout page

8. Adding dimensions to product

Shipping cost is calculated based on product weight and dimensions like weight, length, height and width. So we need to make sure that those dimensions should exist in product.

Add product dimensions

4. History of shipments

All the shipping order which has been placed of any courier will be listed on this tab. This will list all awb orders including AWB history as well.

5. Logs/Stats

This section will display all the logs/statistics of all awb generated inside the plugin.

It will be divided it into four different sections.

1. Total successful shipments

This will show total count of awb that has been delivered so far.

2. Total failed shipments

This will show total count of awb that has been deleted or has any error during shipment.

3. Total AWB in progress

This will show total number count of awb that has been generated except for any error or deleted status.

4. Total AWB generated

This will show total count of awb that has been generated.

3. Webhook for updating AWB Statuses

Custom webhook has been created in WooCommerce Couriero plugin which will accept bulk orders with updated awb status for each order. This will be triggerd from laravel using cron.

Laravel will send updated orders and updated awb status to custom webhook and in couriero plugin will update the awb of particular order.

Custom webhook has been defined in file name as class-woocommerce-couriero-public.php inside method woo_cour_sync_awb_status

AWB history for any specific order will be saved in wp_postmeta table with meta_key as woo_cour_awb_history

Structure of webhook

Webhook url : {{plugin_domain_url}}?syncCouriero=1

Headers : Authorization : Bearer {{token}}

As a token we need to send API key for that plugin domain. Use same token which was used while validating token.

Body :

Data needs to be send as a form-data. We need to send array of orders with following parameter.

  • awb_number

    • Type
      String
    • Description AWB number of that particular order.

  • courier_id

    • Type
      Integer
    • Description Courier id associated with order id.

  • order_id

    • Type
      Integer
    • Description Order id associated with particular awb number. This order id will be the one which will be used inside plugin while placing order.

  • status_id

    • Type
      Integer
    • Description Status id defines the current status of awb. Status id can be from 0 to 6.

  • status_description

  • Type
    Text

    • Description For every status id it defines status description. For example, status id 1 defines AWB was registered, 2 defines picked up from sender and so on..

  • updated_at

    • Type
      DateTime
    • Description Defines the DateTime (UTC) when the last status was updated.

Update order status to plugin

4. AWB Generator

AWB Generate button will be visible on order detail page once user place any new order from checkout page.

When admin user click on Generate AWB button, modal popup will be displayed which will show field as per different courier.

Modal popup which is displayed has been developed in Vue.js and can be treated as Single Page Application.

Once all the required data will be filled in and submit the form, an api will be triggered to laravel of specific courier to generate awb.

1. FanCourier Shipping

Following are the list of fields which needs to be filled-in for generating awb of FanCourier.

  • Number of parcel This field define total number of parcel require to ship this order.

  • Weight Total weight of the order

  • Number of envelopes This field define total number of envelopes require to ship this order.

  • Payment of shipment Need to select one option from dropdown. Possible value can be Expeditor, Sender & Receiver

  • Cash Reimbursement Cash reimbursement value

  • Reimbursement transport payment Need to select one option from dropdown. Possible value can be either Sender or Receiver

  • Declared value Total amount of the product

  • Insured Once checked this option, it will recalculate amount based on insured percentage(added in couriero settings) and will update the value in cash reimbursement field.

  • Observations Need to select one observations from dropdown

FanCourier AWB Generate

2. Sameday Shipping

Following are the list of fields which needs to be filled-in for generating awb of Sameday courier.

  • Number of parcels This field define total number of parcel require to ship this order. If we increase number of parcel then its relevant field will be displayed like length, width, height and weight depends on the number of parcels.

  • Length Length of the parcel

  • Width Width of the parcel

  • Height Heigth of the parcel

  • Weight Weight of the parcel

  • Package type Need to select one option from dropdown. Possible value can be Package, Small Package and Large Package.

  • Third party pickup Pickup from a third party, not one of the client's pickup points. Can be either true or false.

  • Third party person name Third party contact person name.

  • Third party phone number Third party contact person phone number.

  • Third party person type Third party person type. Can be either Individual or Business man.

  • Third party postal code Postal Code.

  • Third party address The address.

  • Third party county The county.

  • Third party city The city.

  • Cash Reimbursement Cash reimbursement value

  • Declared value Total amount of the product

  • Insured

    Once checked this option, it will recalculate amount based on insured percentage(added in couriero settings) and will update the value in cash reimbursement field.

Sameday AWB Generate

3. Bookurier Shipping

Following are the list of fields which needs to be filled-in for generating awb of Bookurier.

  • Number of parcels This field define total number of parcel require to ship this order.

  • Exchange pack Exchange pack value either yes or no

  • Weight Weight of the parcel

  • Cash Reimbursement Cash reimbursement value

  • Confirmation Confirmation value either yes or no.

  • Declared value Total amount of the product

  • Insured Once checked this option, it will recalculate amount based on insured percentage(added in couriero settings) and will update the value in cash reimbursement field.

  • Notes Any additional notes to send courier company while generating awb.

Bookurier AWB Generate

4. GLS Shipping

Following are the list of fields which needs to be filled-in for generating awb of GLS.

  • Number of parcels This field define total number of parcel require to ship this order.

  • Weight Weight of the parcel

  • Content Parcel content

  • Client reference Client reference

  • Pickup point Pickup point to be selected. Pickup point like add/delete can be managed from couriero settings.

GLS AWB Generate

5. UrgentCargus Shipping

Following are the list of fields which needs to be filled-in for generating awb of UrgentCargus courier.

  • Number of parcels This field define total number of parcel require to ship this order. If we increase number of parcel then its relevant field will be displayed like length, width, height and weight depends on the number of parcels.

  • Length Length of the parcel

  • Width Width of the parcel

  • Height Heigth of the parcel

  • Weight Weight of the parcel

  • Cash repayment/Bank repayment Repayment selection value either can be cash or bank.

  • Cash/bank reimbursement Cash reimbursement value

  • Declared value Total amount of the product

  • Notes Any additional notes to send courier company while generating awb.

  • Open package Open package can be either yes or no.

UrgentCargus AWB Generate

We will be storing awb number in order meta with meta name as couriero_awb_number

AWB number will be displayed on order detail page as well as on order listing page.

We will also be displaying AWB number for front-end user inside My Account » Orders page.

After AWB has been generated for particular order, we will now be having two button called Download AWB Label PDF and Delete AWB.

5. Download AWB

Admin user can generate label/download awb label pdf by clicking on Download AWB button. This will call laravel api of that specific courier.

We will also be showing PDF Icon on order listing page where admin user can quickly download awb pdf without going to order detail page.

6. Delete AWB

Admin user can also delete awb by just clicking on Delete AWB button. It will take confirmation first whether to download AWB or not. If yes, it will be deleted from laravel system.

If the status of AWB has been Picked up from sender from in that case Delete AWB button cannot be displayed.

End User Pages

1. Cart/Checkout page

On Cart/checkout page, we need to enter post code and on the basis of that, we will fetch respective county/city/street and will be autofill to the respective field.

This data will be fetched from wp_geolocations table which we have created in WooCommerce Couriero plugin.

2. FanCourier Shipping

In-order to see FanCourier on cart/checkout page, user needs to enter valid postcode and respective county/city and on the basis of that FanCourier shipping cost will be displayed.

3. Bookurier Shipping

Bookurier shipping provides two different services called Bucharest 24H and Bucharest Today which will be having different shipping cost for each service. User can select service as per their choice.

Shipping cost will also be changed if we select payment method as Cash on Delivery (COD).

4. Sameday Shipping

Sameday courier provides two different services called Delivery Pickup and Locker Pickup. Once we select Locker Pickup, we will be having an option to select related locker from dropdown and end user will pickup their parcel from that locker.

For Sameday Locker service, Cash on Delivery payment method will not be available.

Shipping cost will be different for Cash on Delivery payment method.

5. GLS Shipping

GLS Shipping provides two different services called 24H and Cash Service. Default 24H service will be implemented. Cash service will only be applicable if user select payment method as Cash on Delivery.

It is also possible that if user select payment method as Cash on Delivery then in that case GLS shipping will not be visible due to cash service limit set by admin user in admin panel but if user select payment method other than Cash on Delivery then GLS shipping will be visible.

6. UrgentCargus Shipping

UrgentCargus shipping will be visible once we enter valid county and its respective city.

7. My Account page

User can see their order awb number as well as AWB tracking information under My Account » View Order page.