What it does
Connects Odoo to Giao Hàng Tiết Kiệm over its public API, so a transfer becomes a
GHTK parcel without leaving Odoo.
Key Features
- Rates on the real route: GHTK prices the exact pickup and delivery
addresses, weight and declared value of the transfer.
- Booking keyed on the transfer, sent as GHTK's partner order id, so the
booking can be repeated without creating a second parcel.
- Address without a district: GHTK asks for a province and a ward and treats
the district as optional, which is exactly the two-level map Vietnam moved to
on 01/07/2025. Addresses captured either way are accepted.
- Cash on delivery, including GHTK's freeship flag so the recipient is
charged the shipping or not, as your pricing decides.
- Waybills in any of GHTK's paper sizes, attached to the transfer.
- Realtime status over webhooks, including the shipper-reported statuses
GHTK sends ahead of the confirmed ones, all mapped onto Odoo's vocabulary.
- COD reconciliation on GHTK's own terms: GHTK distinguishes "delivered, not
yet settled" from "settled", and the reconciliation reads exactly that, so
cash still owed to you is never counted as received.
- Surcharges kept: the fragile, bulky and food handling fees GHTK adds are
recorded per parcel rather than disappearing into a lump sum.
Editions Supported
- Community Edition
- Enterprise Edition
GHTK Shipping
This guide connects Odoo to Giao Hàng Tiết Kiệm. It assumes Vietnam Delivery Connectors is
installed, which happens automatically with this app; that app's guide covers addressing, rate
comparison and COD reconciliation in general, and this one covers what is specific to GHTK.
Installation
- Go to Apps, remove the default Apps filter, search for GHTK Shipping and click Install.
Getting your credentials
- Sign in to your GHTK business account and open the API section.
- Copy the API token, and the partner code if GHTK issued you one. The partner code is sent
as the X-Client-Source header and some accounts require it.
Configuration
- Go to Inventory > Configuration > Delivery Methods and create a method with Provider set to
Giao Hàng Tiết Kiệm.
- On the Vietnam Shipping tab, fill in GHTK Token and, if you have one, GHTK Partner Code.
- Give your warehouse contact a Vietnamese province and ward. GHTK asks where it is collecting
from on every call, including a price, and it will not accept an order without them.
- Click Test the connection. It lists the pickup points registered on your GHTK account; if you
set Pickup Address ID, it also checks that the one you named is really on the account.
GHTK addresses by name rather than by identifier, so there is no address catalogue to synchronise
for this carrier. It asks for a province and a ward and treats the district as optional - which is
already the two-level shape Vietnam moved to on 01/07/2025 - so addresses captured either way are
accepted.
There is no test environment
GHTK runs one service. They publish no sandbox - the staging host older integration guides name has
no DNS record at all - so every booking creates a real parcel, sends a real courier, and is
billed.
The connector does not pretend otherwise. While Test Environment is on you can do everything
that creates nothing: real prices, the pickup-address list, tracking, and the connection test. Only
booking is held back, with a message saying why. Turn the flag off when you are ready to ship, and
that is the moment you are agreeing that parcels are real.
If you want to prove the whole path before going live, book one small parcel with no cash to collect
and cancel it straight away from the transfer. GHTK accepts a cancellation until the courier has
collected.
Options worth setting
- Pickup Address ID - if your GHTK account has several registered pickup addresses, put the id
of the one to collect from here; Test the connection lists them. GHTK then collects from that
exact point. It does not excuse you from the warehouse province and ward: their documentation says
those become optional once the id is given, and measured against the live service they do not -
the request is refused until both are there.
- Transport - road or air.
- Shipping Fee Paid By, Recipient May Inspect, Handover - the defaults for every
parcel, changed per delivery in its Shipping block. The fee payer is GHTK's is_freeship
flag: the shop pays and GHTK takes the shipping out of what it remits, or the recipient pays it
at the door on top of the goods. The handover is GHTK's pick_option: a courier collects, or
the shop brings the parcel to a GHTK office. GHTK has no field for the inspection rule, so it is
written at the front of the courier note.
- GHTK Waybill Size - A5, A6, A7 or 50×72 mm.
Webhooks
- On the delivery method, click Generate a new secret and copy the Webhook URL.
- Append the secret to that URL as a hash parameter, so it reads
.../viin_delivery/webhook/ghtk/<id>?hash=<the secret>.
- Register the whole URL, hash included, as your callback address with GHTK.
GHTK does not sign its callbacks; knowing the hash in the URL is the proof that a callback is
genuine, which is why it is compared in constant time and why the secret should be long. GHTK also
posts its callbacks as a form rather than as JSON - Odoo reads both, so nothing needs configuring
for that.
Reconciling COD
GHTK is unusually honest about its own money, and this connector uses that. It distinguishes
status 5, "delivered but not yet reconciled", from status 6, "reconciled" - and only the
second means the cash has actually reached you.
Fetch from Carrier therefore reports only the parcels GHTK has moved to status 6. If none have,
it says how many are sitting at status 5 instead of returning an empty statement, so the gap between
"delivered" and "paid" is visible rather than silently missing. Counting status 5 as income is how a
shop concludes it has been paid when it has not.
Daily use
Click Send to Carrier on the delivery. The transfer name goes to GHTK as its partner order id, which it
de-duplicates on, so a retried booking resolves to the parcel that already exists.
GHTK sends two kinds of status: the confirmed one, and the one the courier reported from their phone
a little earlier (codes 123, 127, 128, 45, 49, 410). Both are recorded, and both map to the same
place in Odoo, so the timeline moves as soon as the courier says something rather than when the
back office catches up.
Troubleshooting
"Cần cung cấp token hợp lệ"
The token is missing or wrong. GHTK returns this inside an HTTP 200 with success: false, which
Odoo raises as an error rather than treating as success.
The recipient was charged more than expected
Check Shipping Included in COD. With it off, GHTK adds the shipping to what it collects at the
door.
A parcel is delivered but missing from the statement
GHTK has not reconciled it yet. It appears once GHTK moves it to status 6; the statement message
tells you how many parcels are waiting.
This software and associated files (the "Software") may only be
used
(executed, modified, executed after modifications) if you have
purchased a
valid license from the authors, typically via Odoo Apps,
or if you
have
received a written agreement from the authors of the
Software (see the
COPYRIGHT file).
You may develop Odoo modules that use the Software as a library
(typically
by depending on it, importing it and using its
resources), but
without
copying any source code or material from the
Software. You may distribute
those modules under the license of your
choice, provided that this
license
is compatible with the terms of
the Odoo Proprietary License (For
example:
LGPL, MIT, or proprietary
licenses similar to this one).
It is forbidden to publish, distribute, sublicense, or sell
copies of the
Software or modified copies of the Software.
The above copyright notice and this permission notice must be
included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT
SHALL THE
AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING
FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE
SOFTWARE.
