VibeFox Sameday Easybox for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Sameday API username and password: API access is part of a Sameday business account in Romania, Hungary or Bulgaria. Ask your Sameday account manager or the Sameday integration team. The credentials are often the same as for the eAWB portal (eawb.sameday.ro, .hu or .bg). For the demo API Sameday gives separate test credentials. Without an API username and password the method is not offered, because the customer could not choose a locker.

Country and counties: the country of your Sameday account must be enabled in System > Localisation > Countries. The Sameday estimate needs the county of the delivery address (the Region / State field). OpenCart has the counties of Romania and Bulgaria, but OpenCart 3 has none for Hungary (OpenCart 4.1 has them). The extension can add them for you (see easybox lockers below). Without them, prices come from your table or fallback cost.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_sameday_easybox-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_sameday_easybox.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_sameday_easybox-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Sameday Easybox and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

5. Enter your Sameday API username and API password, choose the Sameday country, turn on Enable/Disable and click Save. The page should show "Connected to Sameday ... easybox lockers". Pickup point and Easybox service are filled in from your account.

6. Set your prices: Exchange rate of the estimate if your store currency differs from the Sameday currency, and a Country prices row (for example * Default) or a Fallback cost.

7. If the page says OpenCart has no counties for your Sameday country, click Add counties in the easybox lockers section.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_sameday_easybox.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Sameday Easybox, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 7 for OpenCart 3. The settings page and its fields are the same in both versions. Only the cron URL is different (see easybox lockers).

After install the method is off until you turn on Enable/Disable and save. If you install the extension again after an uninstall, the settings you kept are used again, but the method starts switched off.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Only admin users with the modify permission for this extension can save the settings.

Above the settings the page shows the connection status: the Sameday host, the number of easybox lockers and when the list was updated, or that Sameday rejected the username or password. It also lists configuration problems, for example no credentials, no price, no exchange rate for the estimate, no counties, no kilogram weight class, or selected countries outside your Sameday country.

Some errors stop the save, and nothing is saved: Enter a valid name (1-64 characters, without < > ; = # { })., Sort order must be a whole number., an invalid tax class or geo zone. Other problems only keep one value: all prices and limits accept a comma or a point as the decimal separator (4,99 or 4.99), and an invalid or negative number is not saved. A warning names the field, and the previous value is kept.

General

Enable/Disable: shows or hides the method at checkout. It is the status of the extension in Extensions > Extensions > Shipping. Default: off.

Name: the shipping method name shown to the customer. Default: Sameday easybox. Up to 64 characters.

Tax class: --- None --- (default) means the price is final. With a tax class, OpenCart adds the tax of this class on top of the price.

Sort order: the position of the method among the shipping methods at checkout. A whole number.

Sameday account (API)

When you save, the extension logs in to Sameday and loads your services, pickup points and the easybox locker list. The list is refreshed daily.

API username: your Sameday API username.

API password: your Sameday API password. It is never shown again: leave the field empty to keep the saved one. Emptying the username removes the password too. If Sameday rejects it, it is not tried again for 10 minutes.

Sameday country: the country of your Sameday account: Romania (api.sameday.ro) (default), Hungary (api.sameday.hu) or Bulgaria (api.sameday.bg). Its lockers are offered, and the method is shown for this destination country only.

Test mode: uses the Sameday demo API (sameday-api.demo.zitec.com) with demo credentials.

Prices (the section title shows your store default currency)

The order of use is: the Sameday estimate (when Pickup point and Easybox service are set), then the country prices table, then the fallback cost. Table prices are entered in the store default currency. Customers who pay in another currency see the price converted.

Pickup point: your Sameday pickup point, where Sameday collects the parcels. After a successful login it is a list of the pickup points of your account, and the default one is chosen automatically. Before that it is a field for the ID. Needed for the Sameday estimate. Choose - not set (price table only) - to use only the price table.

Easybox service: the Sameday service for easybox delivery, usually "Locker NextDay" (code LN), which is chosen automatically. Needed for the Sameday estimate.

Exchange rate of the estimate: Sameday estimates in the currency of your Sameday country: RON, HUF or BGN (EUR for Bulgarian stores that sell in euro). If your store sells in another currency, enter the value of 1 unit of the Sameday currency in your store currency, for example 0.20. The rate must be above 0. Without it the estimate is not used and the price table applies. Lev and euro are converted at the fixed rate automatically.

Table price: Per order charges the price once. Per item (price x quantity) multiplies it by the number of items. This applies to the table price and the fallback cost. The Sameday estimate is always for the whole parcel.

Country prices: a price per destination country and parcel weight. Click Add country to add a row and the remove button to delete one. Each row has a Price and weight columns: XS up to 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg and XL over 5 kg. A weight column left at 0 or empty uses the Price column. The * Default row is used for countries without their own row. A new row starts as * Default with all prices at 0, which means free shipping. Choose the country and enter the prices before you save, or remove the row. If the same country is in two rows, only the first one is kept when you save, and a warning says so. If a cell is not a number of 0 or more, the table is not saved.

Fallback cost: used when there is no Sameday estimate and the country table has no row for the destination. Leave it empty to not offer the method then.

Free shipping from: the cart subtotal (products that need shipping, after discounts, without tax) from which easybox delivery is free. When the subtotal reaches it, the method is offered at no cost and no price is looked up. Leave empty to never offer free shipping.

Availability

Minimum weight (kg): hide the method when the cart weighs less. The weight is converted from the weight class of the products. Empty or 0 means no limit.

Maximum weight (kg): parcels heavier than this are not offered easybox delivery. Default: 30. Check the limit of your Sameday contract and the easybox box sizes. Empty or 0 means no limit. A minimum weight above the maximum weight is not saved: a warning says so, and the previous values are kept.

Minimum cart subtotal: offer the method only when the cart subtotal (products that need shipping, after discounts, without tax) reaches this amount. Empty means no minimum.

Geo zone: offer the method only for addresses in this geo zone. All Zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. It is not checked when Ignore shipping zones is on.

Ignore shipping zones: when on, the geo zone is not checked, and the method is offered for the countries selected below (the Sameday country when the list is empty). When off, only the geo zone above applies.

Countries (ignore zones mode): the destination countries for that mode. Countries other than the Sameday country are skipped, and the page warns about them. This field is used only when Ignore shipping zones is on.

easybox lockers

Locker list: shows how many easybox lockers in how many cities are loaded and when. Refresh the locker list now loads it again. The list is refreshed when the settings are saved and, once it is older than a day, after a checkout request (at most once an hour). For a fixed daily refresh, call the URL shown here once a day from a cron job of your server. On OpenCart 3 it looks like https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token), on OpenCart 4 like https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token). Copy the URL exactly as the settings show it. The URL contains a secret token. Without the right token it answers with an error and does not contact Sameday. It also does nothing while the method is disabled.

Counties: shows how many counties OpenCart has for your Sameday country. If it has none, click Add counties. The extension adds the counties of that country to System > Localisation > Zones, and the Region / State field of the address form then lists them. Counties that already exist are not added twice. OpenCart 4.1 already has the counties of all three countries, so the button is not needed there.

Advanced

Debug log: writes rate calculations, API calls and locker choices to storage/logs/vfd_sdeb_debug.log.php, which cannot be read from the web. API errors are always logged. No password, token or customer personal data is logged. When the file reaches 5 MB, a new log is started. Turn the log off when you are done.

Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes the settings, the cached Sameday data and the log. When off (default), the settings are kept. The locker list and caches are always removed. The locker saved in orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API password is not exported.

Import: paste previously exported JSON and click Import. The values pass the same checks as the form. The saved password is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Sameday easybox price. The extension checks the geo zone (or the countries of Ignore shipping zones), the delivery country of your Sameday account, the API credentials and a usable locker list, the cart weight and the minimum cart subtotal. Only products with Requires Shipping set to Yes count. The subtotal is the price of these products without tax, after the coupon discount. If free shipping applies, the customer sees the method at no cost.

Otherwise the extension asks Sameday for an estimate, once the customer has entered a city and a county. It sends your pickup point and service, the parcel weight and the customer's street address, city, county and postcode. No name, e-mail or phone number is sent. Bucharest is sent as "Sector 1", like the official Sameday plugin. The estimate is converted to your store currency. If there is no estimate (not set up, no city or county yet, error, no exchange rate), the price comes from the country table, then from the fallback cost. If there is no price, the method is hidden. The price is shown in the customer's currency with the tax of the selected Tax class.

Sameday problems never break the checkout. The estimate is cached for 1 hour. An error is cached for 10 minutes. After a timeout or a server error no estimate is asked for 5 minutes. Requests time out after 15 seconds. During checkout the locker list is read from your server, not from Sameday.

The extension does not create AWBs (shipments), print labels, track parcels or handle cash on delivery. It has no home courier delivery and no Sameday map widget. Create the AWB in the Sameday eAWB portal or your usual tool with the locker ID shown on the order.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Sameday easybox in the window Shipping method options. The prices are the same as on OpenCart 3.

Pickup points

When the customer selects the method, an easybox locker block appears below it with two lists: - Select city - and - Select easybox locker -. The city of the delivery address is pre-selected when it has lockers. Each locker shows its name and address. The choice is saved for the checkout at once, so it stays when the delivery step is opened again.

The locker is required. Without one, the customer cannot continue and sees "Please choose a Sameday easybox locker." When the customer clicks Continue, the server checks that the chosen locker is in the list. A forged or removed locker ID is refused with "The selected easybox locker is not available any more. Please choose another easybox locker." If the list cannot be loaded, the customer sees "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method." The name and address saved with the order come from the list, not from the browser.

Order pages, e-mails and invoice: the locker is added to the shipping method of the order, for example "Sameday easybox: name - address" (the method name, then the locker). The customer sees it on the order confirmation, in the order history and in the order e-mails, and you see it on the invoice.

Admin order page: in Sales > Orders, the order page has a Sameday easybox locker panel with the name and address and the Locker ID for the Sameday AWB. If an easybox order has no locker, the panel says "No easybox locker was selected for this order." The panel is also shown while the method is switched off.

On OpenCart 4 the easybox locker block appears in the window Shipping method options, under the Sameday easybox option, and the city list is loaded again each time the window opens, because the address can change on the one-page checkout. The Continue button of the window does not go on without a valid locker, with the same messages. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the locker of the order is updated with it. The panel of the admin order page is shown above the History section.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Sameday Easybox is the first block on Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-shipping-sameday-easybox and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the Sameday easybox shipping method is not shown to customers at checkout and no price is requested or calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Sameday easybox does not appear at checkout: check that the license is active, Enable/Disable is on, the API username and password are entered and the settings page says "Connected to Sameday", and the destination country is the country of your Sameday account. Check that a price is available (Sameday estimate, country row, * Default row or Fallback cost), the weight and subtotal limits, Geo zone and the countries of Ignore shipping zones. Check that the products have Requires Shipping set to Yes. Turn on Debug log to see the reason in the Log field.

Sameday rejected the API username or password: check them and save again. Demo credentials work only with Test mode on, production credentials only with it off. Until then the stored locker list is offered, if there is one, and the Sameday estimate is not used.

The price comes from my table, not from Sameday: the estimate needs a Pickup point, the Easybox service, counties for your Sameday country and, when your store currency differs from the Sameday currency, the Exchange rate of the estimate. It is asked only after the customer has entered a city and a county. When Sameday is unreachable or returns an error, the table or fallback cost is used; the reason is in the log.

The locker list is old or missing: click Refresh the locker list now or save the settings. If a refresh fails, the previous list is used and the status says so.

Shipping is free by mistake: check Free shipping from and the Country prices rows with a Price of 0, especially a * Default row added with Add country and left unfilled.

Weight limits or weight columns do not match: if the page warns that there is no weight class with the unit "kg", add a kilogram weight class in System > Localisation > Weight Classes.

The page says "Warning: You do not have permission to modify VibeFox Sameday Easybox!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_sameday_easybox (OpenCart 3) or extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox (OpenCart 4) in System > Users > User Groups.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Sameday Easybox. The license key and license status of this extension are always removed. OpenCart always resets Enable/Disable, Sort order, Tax class and Geo zone. The stored locker list, the account check result and all caches are always removed. If Remove data on uninstall is on, the other settings, the cron token and the log are deleted as well. If it is off, they are kept and are used again when you install the extension again. Existing orders keep the saved locker.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Sameday Easybox in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Sameday and easybox are trademarks of their respective owners. This extension is not affiliated with or endorsed by Sameday.