"Ukrposhta API" - delivery module for OpenCart

Administrator features

• multi-store support
• export/import settings
• loading basic settings
• enable/disable debug mode
• input eCom Bearer, StatusTracking Bearer, and User token values of Ukrposhta
• uploading the transport company's logo
• choosing the logo display location
• configuring cURL connection and execution timeout
• delivery methods settings (Express to branch, Express by courier, Standard to branch, Standard by courier):
  • enable/disable delivery method
  • editable multilingual delivery name
  • choosing the geographical zone
  • choosing the tax class
  • setting the minimum order amount for which delivery will be available
  • setting the maximum order amount for which delivery will be available
  • setting the minimum order amount for which delivery will be free
  • editable multilingual free delivery text
  • enable/disable delivery cost calculation
  • enable/disable API cost calculation (used information for calculation: delivery type, sender's and recipient's postal codes, product cost, product weight, maximum side, registered letter)
  • enable/disable tariff cost calculation (can be used independently or if the API is unavailable. Used information for calculation: sender's and recipient's region, delivery type, product cost, product weight)
  • enable/disable delivery time calculation in days (used information for calculation: sender's and recipient's region, delivery type)
  • choosing the branch type
  • choosing the branch status
• setting tariffs and delivery times
• working with the database:
  • uploading/updating postal company directories
  • uploading/updating regions of Ukraine
  • uploading/updating settlements of Ukrposhta
  • uploading/updating branches of Ukrposhta
• configuring sender parameters: sender, sender type, tax number, EDRPOU, bank code, bank account, email, phone, region, city, street, house, apartment, postal code, address pickup
• configuring recipient parameters: recipient, recipient type, tax number, EDRPOU, phone, region, city, address, street, house, apartment, postal code
• configuring shipment parameters:
  • enable/disable volume accounting
  • choosing the volume accounting option
  • setting the default number of places
  • choosing the components for the declared value of the shipment
  • setting the default declared value
  • setting the minimum declared value
  • setting the default description of the shipment as a template using order and product macros
  • enable/disable registered letter
  • enable/disable SMS notification of the shipment arrival to the client
  • choosing the action in case of non-delivery
  • choosing the default parameter application method
  • setting the default weight
  • setting the minimum weight
  • setting the default dimensions
  • setting tolerances for shipment dimensions
• configuring payment parameters:
  • choosing the default payer of delivery
  • choosing the payment method for COD
  • setting the calculation of COD
  • setting the accounting of commission for declared value
  • choosing the default payer of return delivery
  • choosing the method of receiving money transfer
• configuring TTN integration:
  • enable/disable default bonus shipments
  • choosing the displayed information in the invoice list
  • setting up printing
  • choosing a compatible delivery method for creating invoices
  • enable/disable creation, editing, deletion, and assignment of invoices in the order
  • setting multilingual menu item names for working with invoices in the order
• Cron tasks:
  • setting the security key for executing Cron commands
  • automatic module database update (directories, regions, cities, branches)
  • automatic shipment tracking, order status change, and notifications
  • choosing order statuses for tracking
  • configuring dependencies for each shipment status and order status in the store
  • setting the execution delay for each shipment status
  • enable/disable notifications for the administrator and the customer
  • setting a multilingual message template for email and SMS notifications using order, product, and invoice macros
• and other standard delivery module options

Invoice management features

When viewing an order in the admin panel, if the client chose a compatible delivery method, a button for working with the invoice appears. It is possible to create an invoice based on the order or assign an existing one. When creating, the module fills out the form as much as possible automatically. If an invoice has already been created for the viewed order, the editing and deletion options will be available. You can also go to the list of all invoices when viewing orders. Available functionalities:

• creation, editing, and deletion of invoices
• adding/removing invoices to/from a group
• setting up invoice printing
• downloading the invoice and other accompanying documents in PDF format
• viewing the invoice list with the ability to filter by invoice and order number
• automatic filling of sender information according to the selected module settings with the possibility of data change directly before creating the invoice
• automatic filling of recipient parameters according to the order data, including the following functions:
  • enable/disable bonus shipment
  • choosing the delivery method (express or standard)
  • choosing the delivery type (branch or address)
  • loading recipient data by phone number
  • choosing the recipient type
  • input of the tax number
  • input of the EDRPOU code
  • input of the delivery address (region, city, branch, street, house, apartment, and postal code)
• automatic filling of shipment parameters:
  • weight
  • dimensions
  • possibility to set several places
  • declared value with the possibility of adjusting the components
  • description
• automatic filling of payment parameters:
  • delivery payer
  • return delivery amount if COD is chosen
  • return delivery payer
  • method of receiving money transfer
• additional shipment parameters:
  • registered letter
  • inspection upon delivery
  • SMS notification to the client about the arrival of the shipment
  • action in case of non-delivery
• fields are automatically filled by the module as much as possible according to the settings
• field validation during editing and before sending data to the postal company's server
• automatic verification of the client's existence in the database and creation if the result is negative
• automatic editing of the client's data
• automatic search for recipient addresses and creation of new ones if necessary

Upon successful creation or editing, there will be a redirection to the invoice with its highlighting in the general list.

Client features

• choosing the delivery type:
  • Ukrposhta Express. Delivery to branch
  • Ukrposhta Express. Delivery by courier to address
  • Ukrposhta Standard. Delivery to branch
  • Ukrposhta Standard. Delivery by courier to address
• specifying the delivery address
• choosing the receiving settlement:
  • drop-down list
  • search by city name
• choosing the branch:
  • drop-down list
  • search by index
• index search
• information about delivery cost
• information about delivery time

Following the instructions, install the extension on the domain for which you want to get a license. Then, go to the module settings, fill out, and send the purchase information. After verifying the purchase, the module will be activated automatically and an activation key will be sent to your email.

For test sites and subdomains, the key is provided for free. Test domains can be specified with a comma during the activation of the main or vice versa.

Update the ionCube Loader version.

Install/activate the free ionCube Loader library on your server/hosting. If, for example, in php_info, it shows that the library is installed but the error persists, it means you have incorrectly installed ionCube Loader.

• check if all module files were uploaded to the root directory of your online store
• check if your server parameters meet the module requirements
• check the server and OpenCart error logs for specific error details

• check if there are errors in the modification logs
• check if the "Shipping Cost" switch is set to "Yes"
• check "Free shipping from", maybe the amount in your cart is equal to or greater than the amount for free shipping
• check the weight of the item in the cart. If the weight is missing in the product card, you can set a default value in the module settings
• check the module settings and the correctness of the recipient's data
• sometimes some API methods of the postal company are unavailable, in this case, you can enable the tariff calculation in the module settings to display an approximate shipping cost or wait for the API to be restored

• check if there are errors in the modification logs
• check if the "Delivery time" switch is set to "Yes"
• check the module settings and the correctness of the recipient's data
• sometimes some API methods of the postal company are unavailable, in this case, you need to wait for the API to be restored

In the extra folder, there is a dump of countries and regions recovery_zone_and_country_tables_ru.sql and recovery_zone_and_country_tables_ua.sql with correct names for Ukraine, in Russian and Ukrainian respectively. They need to be uploaded through the store admin panel in the System → Tools → Backup / Restore section after checking the table prefixes, in the files they are oc_.

If a compatible shipping method was selected during the order placement, a button for working with the waybill will be available when viewing the order list or a specific order. Also, when viewing the order list, there will be a button to go to the waybill list.

Tracking in the module is carried out through the appropriate methods of the Ukrposhta API interface. Everything works on the principle of status changes. For better understanding, let's consider the work and setup on a specific example. Suppose we need to send a notification to the client with the waybill number when the order is shipped and complete the deal by setting the corresponding status "Deal completed".

1. First, you need to set up Cron using the command in the module. The Cron command is given as an example and may differ for different hostings. Tracking interval, for example, every hour.

   

2. Specify the statuses of your online store that will be tracked. The module will track orders with those statuses that you mark and for which a waybill will be created. For our example, this is "Processing" and "Shipped".
3. Set up the correspondence between Ukrposhta statuses and your online store statuses. The module checks the current status of the shipment with the corresponding store status, if the order status does not match, the module changes it to a new one. For our example, the module will work as follows:
   1. Selects all orders that have a waybill number and a status that matches "Processing" and "Shipped"
   2. Tracks the selected orders by waybill number
   3. If the store status of a specific order is "Processing", and the status in the Ukrposhta system has become "Shipment", the module changes the store status to "Shipped"
   4. If the store status of a specific order is "Shipped" or "Processing", and the status in the Ukrposhta system has become "Delivered", the module changes the store status to "Deal completed"