Before installing this module, please ensure the following dependency modules are installed:

• Download the Vietnam Address Base module here
• Download the Shipping Methods Base module here

Then install the Viettel Post Integration module:

The module includes a comprehensive, interactive dashboard that provides a complete view of your delivery operations. Access it by navigating to: Delivery → Dashboard.

The dashboard features three distinct viewing modes, selectable from the top-left dropdown:

1. Delivery Analytics

This is the default view, providing an overview of all your delivery orders across all carriers.

• Status Overview Cards: Color-coded KPI cards showing order counts by status (Draft, Confirmed, In Transit, Delivered, Cancelled, Failed, etc.), each card is clickable to drill down into filtered order lists.
• Carrier Breakdown Table: A detailed table listing each carrier with total orders, average and total shipping costs, paid/unpaid amounts, COD (Cash on Delivery) orders and amounts, and delivery success rate.
• Status Distribution Chart: A doughnut chart visualizing the proportion of orders in each delivery status.
• Order Trends Chart: A line chart showing daily order volumes over the selected period to identify trends and peak times.
• Cost Comparison Chart: A bar chart comparing estimated shipping costs versus actual costs by carrier, helping you identify cost discrepancies.

2. Webhook Monitoring

This view focuses on the health and performance of your webhook integrations.

• Webhook KPI Cards: Six cards showing total webhooks received, successful, errors, ignored, success rate percentage, and average response time in milliseconds.
• Webhook Volume Chart: A line chart tracking daily webhook traffic over time.
• Status Distribution Chart: A doughnut chart showing the ratio of success, error, and ignored webhooks.
• Response Time by Carrier: A horizontal bar chart comparing average webhook processing times across different carriers.
• Webhook by Carrier Table: Detailed breakdown of webhook statistics per carrier, including total, success, error counts, average response time, and success rate.
• Recent Webhook Errors: A list of the latest webhook failures with carrier type, tracking reference, error message, and processing time for quick troubleshooting.

3. Performance Analytics

This view helps you evaluate and compare carrier performance to make data-driven decisions.

• Carrier Scorecard: A comprehensive ranking table scoring each carrier on four dimensions - Success Rate, Speed, Cost Efficiency, and Reliability - with a weighted final score. Top carriers are highlighted with trophy badges.
• Carrier Comparison Radar Chart: A radar/spider chart visually comparing carrier scores across all four performance dimensions for easy side-by-side comparison.
• Cost Efficiency Table: Detailed cost analysis per carrier including total orders, delivered/failed counts, average cost per shipment, true cost per successful delivery, cost overrun percentage, and success rate.
• Delivery Speed & SLA Table: Speed metrics per carrier including average, median, fastest, and slowest delivery times, plus SLA 48-hour compliance percentage.
• Failure Trend Chart: A weekly line chart tracking failure counts over time to identify patterns.
• Failure Reasons: A breakdown of failure reasons per carrier with progress bars showing the proportion of each failure type.
• Geographic Performance Table: Province-level delivery performance data showing total orders, delivered/failed counts, average cost, and success rate per carrier and region.

In this section, you will configure the connection parameters and authenticate with the Viettel Post server to obtain an access token. This token is required for all subsequent API communications with Viettel Post.

Step 1: Navigate to: Delivery → Configuration → Integration → Carriers → Viettel Post → Integrated Configuration tab.

Step 2: Enter your Viettel Post credentials:

• Username: Your Viettel Post account username
• Password: Your Viettel Post account password

Step 3: Click the [Get Access Token] button to retrieve your access token.

Step 4: Configure the default parameters for delivery orders:

Weight Unit: The unit of measurement for your shipment weight. The default is Grams, as required by Viettel Post's system.

Promo Code: Enter the promotional code provided by Viettel Post (if applicable).

Payment Type: Select the payment collection method for your deliveries:

• No collection
• Collect payment for both goods and delivery fee
• Collect payment for goods only
• Collect delivery fee only

Product Type: Select the type of items being shipped:

• Goods
• Letter

Shipment Type: Specify whether the delivery is domestic or international:

• Domestic
• International

Print Order Paper: Choose the default paper size for printing shipping labels:

• A5 (148 x 210 mm)
• A6 (105 x 148 mm)
• A7 (74 x 105 mm)

Service and Extended Service: Select the Viettel Post service type and any additional extended services required for your orders.

Step 5: Configure webhook integration to receive real-time order status updates from Viettel Post.

Enable "Authentication", then click the [Generate Access Token] button to generate an access token. This adds a security layer to protect your Odoo webhook endpoint. If you do not require webhook authentication, you may skip this step.

Next, go to the Viettel Post Portal at Viettel Post Account Configuration.

Navigate to: Personal Information → Information to receive journey

• Copy the [Webhook URL] from Odoo and paste it into the [API Path] field.
• Enable the [Authentication Needed] toggle.
• Copy the [Access Token] from Odoo and paste it into the [Secret Parameters] field.

Step 6: Configure API routes for flexibility. If Viettel Post updates their API endpoints, you can easily update them without modifying any code.

Navigate to the Routes tab. Here you can edit the HTTP method, headers, path, and other properties for each API endpoint.

Congratulations! You have successfully configured all the necessary components to connect your Odoo system with Viettel Post.

The module uses a three-tier status system to standardize delivery tracking across different carriers. This allows you to compare delivery performance, build unified dashboards, and manage orders consistently - regardless of which carrier is used.

1. Standard Statuses

Standard Statuses are a unified, carrier-agnostic set of delivery stages that represent the common lifecycle of any shipment. They are pre-configured with the module and used across the dashboard, analytics, and carrier reference orders.

Navigate to: Delivery → Configuration → Statuses → Standard Statuses.

The following standard statuses are provided by default:

Each standard status has configurable properties:

• Color: Hex color code used for dashboard cards and visual indicators
• Show on Dashboard: Toggle whether this status appears as a KPI card on the delivery dashboard
• Active: Archive or restore statuses as needed
• Sequence: Drag to reorder the display sequence

2. Delivery Statuses (Carrier-Specific)

Delivery Statuses represent the carrier's own status codes. Each carrier has its own set of status codes and labels. For Viettel Post, 32 statuses are pre-configured automatically upon module installation, covering the full delivery lifecycle.

You can view all carrier statuses in two ways:

• From the carrier form: Navigate to the Status tab on the Viettel Post shipping method form
• From the menu: Delivery → Configuration → Statuses → Delivery Statuses (grouped by provider by default)

Each status record contains:

• Name: The carrier's label for this status
• Code: The carrier's numeric or string code

3. Status Mapping

Status Mapping is the bridge between carrier-specific statuses and the unified standard statuses. Each mapping links one carrier status to one standard status, allowing the system to translate carrier updates into a normalized format.

You can configure mappings in two ways:

• From the carrier form: Navigate to the Status Mapping tab on the Viettel Post shipping method form
• From the menu: Delivery → Configuration → Statuses → Status Mapping (grouped by provider by default)

Each mapping record contains:

• Carrier Status: The carrier-specific status (filtered by the selected provider)
• Carrier Code: The status code (auto-filled from the carrier status)
• Standard Status: The unified standard status to map to
• Sequence: Drag to reorder the mapping priority

For Viettel Post, all 32 status mappings are pre-configured. Here are some key examples:

Step 1: Navigate to: Contacts → Create

Fill in the following required fields:

• Name: The customer's full name
• Street: The street address
• State: The province/city
• Ward: The ward/commune
• Phone: The customer's phone number

Done! You have successfully created your first customer contact.

After creating your customer, you can estimate the shipping costs for a sales order before confirming it.

Step 1: Navigate to: Sales → Orders → Create a new sales order.

Step 2: Click the [Add Shipping] button to open the [Add a Shipping Method] popup.

Step 3: Select the Shipping Method, Service, Extended Service, Shipment Type, and Product Type.

Step 4: Click the [Get Rate] button to retrieve the estimated shipping cost from Viettel Post.

Step 5: Click the [Add] button to add the shipping cost to the sales order.

Done! You have successfully estimated and added the shipping cost to your sales order.

Once the shipping cost has been estimated and the sales order is confirmed by your customer, you can proceed to create a delivery order with Viettel Post.

Step 1: Navigate to: Inventory → Delivery Orders, then select the delivery order you want to process.

Step 2: Review and fill in the delivery details in the Additional Info tab.

Step 3: Click the [Validate] button. The system will validate the picking and automatically submit the order to Viettel Post.

Done! You have successfully booked a delivery order with Viettel Post.

To cancel a delivery order, click the [→ Cancel] button. This will cancel the order on both Odoo and Viettel Post simultaneously.

Click the [Tracking] button to open the Viettel Post tracking portal and monitor your shipment's progress in real time.

Click the [Print] button to generate and print the Viettel Post shipping label for the selected order.

Available paper sizes:

• A5 (148 x 210 mm)

• A6 (105 x 148 mm)

• A7 (74 x 105 mm)

Done! You have successfully printed the shipping label.

Publish the Viettel Post carrier on your website:

Once published, your customers can select Viettel Post as a shipping option during the checkout process on your website.

The corresponding sales order in the back-end:

The delivery order in the back-end:

Done! You have successfully enabled Viettel Post as a shipping option on your website.

The Carrier Reference Orders screen provides a centralized view to manage and monitor all delivery orders across carriers. Each record is automatically created when a delivery is booked and continuously updated via webhook notifications.

Step 1: Navigate to: Delivery → Operations → Delivery Orders.

Each carrier reference order contains the following information:

• Tracking Reference: The unique bill code assigned by the carrier
• Carrier & Service: The shipping carrier and service type used
• Delivery Status: Real-time status from the carrier (via webhook)
• Mapped Status: Standardized status for cross-carrier comparison
• COD Amount: Cash on delivery amount to be collected
• Estimated vs Actual Cost: Compare quoted shipping cost with actual carrier charges
• Driver Information: Name, phone number, and license plate of the delivery driver
• Purchase Order & Payment Status: Linked PO with invoice and payment tracking
• COD Reconciliation Status: Matched, Mismatched, or Pending after reconciliation

Step 2: Use the powerful search and filter options to manage your orders:

• Filter by carrier, delivery status, payment status, or COD reconciliation status
• Group by carrier, mapped status, payment status, or date
• Search by tracking reference, sale order, or carrier name

This feature allows you to create Purchase Orders (POs) from your delivery records, enabling proper accounting and reconciliation of carrier shipping fees within Odoo's purchase workflow.

Step 1: Navigate to: Delivery → Operations → Delivery Orders.

This view lists all carrier reference orders with their tracking references, delivery statuses, estimated and actual shipping costs, and payment status.

Step 2: Select the carrier reference orders you want to create a Purchase Order for. You can select multiple records at once using the checkboxes.

Step 3: From the Action menu, click [Create / Merge PO].

The system will:

• Group selected orders by their shipping carrier
• Create one Purchase Order per carrier (or merge into an existing draft PO)
• Add a line item for each delivery order with the actual shipping cost as the unit price
• Link each carrier reference order to its corresponding Purchase Order
• Log a chatter message on each record confirming the PO creation

Step 4: After creation, the system will redirect you to the generated Purchase Order(s). You can then:

• Review and confirm the PO
• Create vendor bills for payment processing
• Track the payment status directly from the carrier reference order list

The carrier reference order list view displays payment-related fields including:

• Purchase Order: Link to the associated PO
• Invoice Status: Shows if the PO has been invoiced
• Payment Status: Tracks whether the carrier fee has been paid (Not Paid, In Payment, Paid, Partially Paid)

Done! You have successfully created Purchase Orders to manage and reconcile your carrier shipping fees.

This feature allows you to automatically reconcile COD (Cash on Delivery) amounts and shipping fees by importing ViettelPost's Excel reconciliation report (BangKeChiCod). The system parses the report, validates all bill codes against your existing delivery records, matches each entry, and identifies any discrepancies between the carrier-reported data and your system data.

Step 1: Navigate to: Delivery → Operations → COD Reconciliation.

The list view displays all reconciliation records with their reference number, carrier, import/reconciliation dates, total COD, total shipping fees, and current status. Each status is shown as a color-coded badge (Draft, Imported, Reconciled, Cancelled).

Step 2: Click the [Import File] button in the list view header to open the import wizard.

Step 3: In the import wizard, fill in the following:

• Carrier: Select Viettel Post (only carriers that support auto COD reconciliation are shown)
• Import File: Upload the ViettelPost Excel reconciliation file (BangKeChiCod)
• Auto Reconcile After Import: When enabled (default), the system will automatically perform the reconciliation immediately after parsing the file. If disabled, the file will be imported and parsed, but you can manually trigger reconciliation later from the form view

Step 4: Click "Import & Reconcile" (or "Import" if auto reconcile is disabled). The system will:

• Parse the Excel file header to extract period date and customer information
• Parse all COD amount data from Section I
• Parse all shipping fee data from Section II and merge with COD data by bill code
• Extract the carrier-reported summary totals from the "KET LUAN DOI SOAT" section
• Create a new reconciliation record with status Imported
• If auto reconcile is enabled, immediately proceed to match each bill code against Carrier Reference Orders and compare amounts

Step 5: During reconciliation, each line is evaluated and marked with one of the following statuses:

• Matched - Both COD amount and shipping fee differences are less than 1.0 (fully matched)
• Mismatched - COD amount and/or shipping fee differ by 1.0 or more, with detailed notes explaining the discrepancy (e.g., "COD difference: 5000 (Carrier: 150000, System: 145000)")
• Not Found - The bill code could not be matched to any carrier reference order in the system

After reconciliation, the system also updates the linked Carrier Reference Orders with the COD reconciliation status and updates the actual shipping cost if it differs from the carrier report.

Step 6: Review the reconciliation results in the form view:

• General Information: Carrier, import date, reconciliation date, period date, and imported filename
• Reconciliation Summary (visible after import) - Three comparison groups:
  • COD: Carrier Total COD vs System Total COD, with COD Difference (highlighted in red if non-zero, green if zero)
  • Shipping Fee: Carrier Total Shipping Fee vs System Total Shipping Fee, with Fee Difference
  • Net Amount: Carrier Net Amount vs System Net Amount (COD - Fees), with Net Amount Difference
• All Lines tab: Detailed line-by-line view showing Bill Code, Send Date, Carrier COD vs System COD, COD Diff, Carrier Fee vs System Fee, Fee Diff, linked Ref Order, linked Sale Order, and reconciliation status badge
• Notes tab: Add internal notes about the reconciliation
• Chatter: Full audit trail of import and reconciliation events with match statistics and any not-found bill codes

Step 7: Use the status bar buttons to manage the reconciliation workflow:

• Reconcile: Available only in Imported state - manually trigger reconciliation if auto reconcile was disabled
• Reset to Draft: Clear all reconciliation lines and reset to draft state (also clears COD status on linked carrier reference orders)
• Cancel: Cancel the reconciliation (clears COD status on linked carrier reference orders)

Done! You have successfully reconciled your COD amounts and shipping fees with ViettelPost.