Automating ViettelPost: pickup booking, labels and tracking webhooks

Every manual shipping step is a daily tax. Copying addresses into the carrier portal, choosing services, requesting pickups, printing labels, pasting tracking numbers into messages — twenty orders a day means an hour of typing and at least one transcription error. ViettelPost's partner API lets you delete the whole ritual: a new Shopify order becomes a booked pickup at your registered warehouse, a printed label, and a tracking message to the customer, with no human in the loop. Here is the flow we build, and the production traps the documentation will not warn you about.

The happy path, end to end

1. Authenticate. The partner API issues a token against your ViettelPost account credentials. Treat it like any expiring credential: store it centrally, refresh proactively, and never let two workers race to refresh it at once.
2. Create the shipping order. Map the Shopify order to a ViettelPost order: receiver name and phone, normalized address codes, weight and dimensions, the service code you selected (economy vs express, and options like partial delivery), and the COD amount if the customer pays on delivery.
3. Request pickup at your kho. Your registered warehouse address (kho) is where the courier collects. Book against the next collection window rather than "now" — couriers work rounds, not on-demand.
4. Print the label. The API returns label data; a small local print agent on your warehouse machine receives it over a queue and prints A6 thermal labels. The person packing never opens a browser.
5. Consume status webhooks. ViettelPost pushes status changes; your handler maps carrier statuses to a small set of customer-facing events — picked up, in transit, out for delivery, delivered, delivery failed — and triggers Zalo ZNS or Messenger notifications for the ones customers care about.

If you run without your own warehouse and hand goods to the courier from home or a rented pickup point, the same flow applies with a twist — see our guide to warehouse-free ViettelPost pickups.

Address normalization: the #1 integration pain in Vietnam

ViettelPost — like every Vietnamese carrier — does not accept free-text addresses. It wants numeric codes for province/city, district, and ward/commune, plus the street-level remainder as text. Your customers type "P. Bến Nghé, Q1, HCM" or "quận 1 tp hcm" or leave the ward out entirely. Between the customer's keyboard and the booking call sits a normalization layer:

1. Parse the free-text address into candidate province/district/ward components (diacritic-insensitive, abbreviation-aware: HCM, TPHCM, Sài Gòn are one city).
2. Resolve components against the carrier's own code tables — fetched from their API and cached, never hard-coded.
3. Score confidence. High confidence books automatically; low confidence goes to a review queue or triggers a confirmation question through your support bot, which asks the customer to confirm their ward.

COD: get the fields right, then reconcile the money

For COD orders, the collect-amount field must equal what the customer owes — order total minus prepaid amounts — not the order total by reflex. Mixed payments (deposit via bank transfer, remainder COD) are where automation earns its keep, because humans get this wrong constantly. And collection is only half the story: the money arrives later, in batches, and matching remittance lines back to orders is its own automation problem — covered in full in our COD reconciliation deep dive.

The traps that only appear in production

1. Silent booking failures

The API accepts your booking, returns a tracking code — and no courier ever comes. No error, no webhook, nothing. The fix is a shadow reconciliation job: every few hours, compare bookings made against status updates received. Any shipment still statusless after its pickup window gets rebooked automatically and, on the second failure, escalates to a human with the courier hotline. This one background job is the difference between "automation" and "automation you can trust".

2. Token expiry at the worst moment

Tokens expire; your 18:00 booking burst is exactly when it will bite. Refresh proactively on a schedule, hold bookings in a retry queue when authentication fails, and never drop an order on the floor because of a 401.

3. Sandbox is not production

The sandbox environment differs from production in ways that matter: status sequences arrive in different orders or not at all, some service codes behave differently, webhook timing is unrealistic. Treat sandbox as a schema check, then run a controlled pilot in production — ten real orders with a human watching — before you trust the pipeline.

4. Webhooks arrive out of order, or twice

Design the status handler to be idempotent and order-tolerant: store the full status history, derive the customer-facing state from the highest-ranked status seen, and never send the same notification twice for one (shipment, event) pair.

What this buys you

Once this layer runs, shipping stops being a task and becomes a property of the system: orders flow out, statuses flow back, customers stay informed, and the only shipping work left is physically packing boxes. It is deliberately the first phase we build in the end-to-end automation stack, because it fires on every single order — nothing else you automate pays back faster.