Viettel Post 数据 API：运单、代收与智能柜

Viettel Media Inc · 出行 4.4 ★

Viettel Post 是越军电信集团邮政物流臂 Viettel Post 的官方 Android 客户端，由 Viettel Media Inc 面向在越南全国寄件的家庭与店主发行。手机 OTP（可选密码或 MFA）登录后，寄件人询价运费、创建带代收货款的运单、跟踪包裹、查找附近邮局、用 VTPay 付款，并可租赁智能柜。Viettel Media Inc 位于河内 Trung Van 坊 The Light Building 4 层；Play 上约 12.2 万条评价给出 4.4 分，下载量 500 万+。它是承运商自有客户应用而不是多承运商跟踪器，与 UPS、Почта России 同属国家邮政客户端，并与 Porter 这类民营最后一公里应用并列。

国内运单保存 ORDER_NUMBER、ORDER_STATUS 与运费 MONEY_TOTALFEE。收件人区块是 RECEIVER_FULLNAME、RECEIVER_PHONE 与 RECEIVER_ADDRESS；货件带 PRODUCT_WEIGHT、PRODUCT_PRICE 与 PRODUCT_HEIGHT。代收货款落在 COD 看板的 MONEY_COLLECTION，TRACKINGS 行暴露 TRANG_THAI。附近网点以 postOfficeCode 与 fullName 为键；智能柜租赁从 boxSize 开始。

电商结算先询价再存运单；3PL 盯 ORDER_STATUS 与 TRANG_THAI；店主会计把 MONEY_COLLECTION 对上 VTPay 回执——openData Studio 把这条邮政闭环变成可调用的开放数据。

应用截图

API 端点一览

以下端点与请求/响应示例均依据应用界面推导重构，为示意说明，并非实际抓包。

发送登录 OTP
POST /v1/viettelpost/otp osint
向 Viettel Post 登录界面使用的手机号发送短信 OTP。
认证方式：无需登录。请求体为 phoneNumber。短信 OTP 随后提交到 POST /v1/viettelpost/session。
- phoneNumber
- status
- message
```
POST /v1/viettelpost/otp HTTP/1.1
Content-Type: application/json

{
  "phoneNumber": "0987654321"
}
```
```
{
  "status": true,
  "message": "OTP sent"
}
```
校验 OTP 换取 access token
POST /v1/viettelpost/session osint
用短信 OTP 换取后续运单、代收与报价请求使用的 accessToken。
认证方式：无需登录。请求体为 phoneNumber 加上 POST /v1/viettelpost/otp 发来的短信 OTP。返回的 accessToken 作为后续请求的 Authorization: Bearer；refreshToken 续期会话。
- phoneNumber
- OTP
- accessToken
- refreshToken
- CUS_ID
- fullName
```
POST /v1/viettelpost/session HTTP/1.1
Content-Type: application/json

{
  "phoneNumber": "0987654321",
  "OTP": "482193"
}
```
```
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "rt-9f3a",
  "CUS_ID": "441021",
  "fullName": "Nguyen Van A"
}
```

登录账户资料

GET /v1/viettelpost/me osint

返回账户界面使用的登录寄件人资料。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

CUS_ID
fullName
phoneNumber
email
GROUPADDRESS_ID

GET /v1/viettelpost/me HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{
  "CUS_ID": "441021",
  "fullName": "Nguyen Van A",
  "phoneNumber": "0987654321",
  "email": "[email protected]",
  "GROUPADDRESS_ID": "ga-12"
}

创建包裹运单

POST /v1/viettelpost/parcels opendata

下国内运单，返回 ORDER_NUMBER、ORDER_STATUS、DELIVERY_CODE 与 MONEY_TOTALFEE。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

CUS_ID
GROUPADDRESS_ID
SENDER_FULLNAME
SENDER_PHONE
SENDER_ADDRESS
RECEIVER_FULLNAME
RECEIVER_PHONE
RECEIVER_ADDRESS
PRODUCT_NAME
PRODUCT_WEIGHT
PRODUCT_LENGTH
PRODUCT_WIDTH
PRODUCT_HEIGHT
PRODUCT_PRICE
MONEY_COLLECTION
ORDER_NOTE
ORDER_NUMBER
ORDER_STATUS
DELIVERY_CODE
MONEY_TOTALFEE

POST /v1/viettelpost/parcels HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "CUS_ID": "441021",
  "GROUPADDRESS_ID": "ga-12",
  "SENDER_FULLNAME": "Nguyen Van A",
  "SENDER_PHONE": "0987654321",
  "SENDER_ADDRESS": "12 Nguyen Trai, Ha Noi",
  "RECEIVER_FULLNAME": "Tran Thi B",
  "RECEIVER_PHONE": "0912345678",
  "RECEIVER_ADDRESS": "88 Le Loi, Da Nang",
  "PRODUCT_NAME": "Documents",
  "PRODUCT_WEIGHT": 500,
  "PRODUCT_LENGTH": 20,
  "PRODUCT_WIDTH": 15,
  "PRODUCT_HEIGHT": 10,
  "PRODUCT_PRICE": 150000,
  "MONEY_COLLECTION": 250000,
  "ORDER_NOTE": "Call before delivery"
}

{
  "ORDER_NUMBER": "VTP2401000123",
  "ORDER_STATUS": "CREATED",
  "DELIVERY_CODE": "DC-7781",
  "MONEY_TOTALFEE": 32000,
  "MONEY_COLLECTION": 250000
}

列出我的运单

GET /v1/viettelpost/parcels opendata

按 ORDER_STATUS 分页登录寄件人的运单。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

ORDER_STATUS
items
ORDER_NUMBER
RECEIVER_FULLNAME
RECEIVER_PHONE
MONEY_COLLECTION
MONEY_TOTALFEE

GET /v1/viettelpost/parcels?ORDER_STATUS=CREATED HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{
  "items": [{
    "ORDER_NUMBER": "VTP2401000123",
    "ORDER_STATUS": "CREATED",
    "RECEIVER_FULLNAME": "Tran Thi B",
    "RECEIVER_PHONE": "0912345678",
    "MONEY_COLLECTION": 250000,
    "MONEY_TOTALFEE": 32000
  }]
}

作废运单

POST /v1/viettelpost/parcels/{orderNumber}/void opendata

取消已创建运单，返回更新后的 ORDER_STATUS。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

ORDER_NUMBER
CUS_ID
ORDER_STATUS

POST /v1/viettelpost/parcels/VTP2401000123/void HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "ORDER_NUMBER": "VTP2401000123",
  "CUS_ID": "441021"
}

{
  "ORDER_NUMBER": "VTP2401000123",
  "ORDER_STATUS": "CANCELLED"
}

询价运费

POST /v1/viettelpost/quote openfinance

按重量、尺寸与代收金额在两个省之间报价 MONEY_TOTALFEE。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

PRODUCT_WEIGHT
PRODUCT_LENGTH
PRODUCT_WIDTH
PRODUCT_HEIGHT
MONEY_COLLECTION
sender_provinceId
receiver_provinceId
serviceCode
MONEY_TOTALFEE

POST /v1/viettelpost/quote HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "PRODUCT_WEIGHT": 500,
  "PRODUCT_LENGTH": 20,
  "PRODUCT_WIDTH": 15,
  "PRODUCT_HEIGHT": 10,
  "MONEY_COLLECTION": 250000,
  "sender_provinceId": 1,
  "receiver_provinceId": 48
}

{
  "serviceCode": "VCN",
  "MONEY_TOTALFEE": 32000,
  "MONEY_COLLECTION": 250000
}

跟踪运单
GET /v1/viettelpost/track/{orderNumber} opendata
水合跟踪时间线：ORDER_STATUS 以及带 TRANG_THAI 的 TRACKINGS 行。
认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。仅凭 ORDER_NUMBER 的游客查询仍可用。
- ORDER_NUMBER
- ORDER_STATUS
- TRACKINGS
- TRANG_THAI
- THOI_GIAN
```
GET /v1/viettelpost/track/VTP2401000123 HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json
```
```
{
  "ORDER_NUMBER": "VTP2401000123",
  "ORDER_STATUS": "TRANSIT",
  "TRACKINGS": [{
    "TRANG_THAI": "Da lay hang",
    "THOI_GIAN": "2026-10-02T09:14:00"
  }]
}
```
代收货款看板
GET /v1/viettelpost/cod openfinance
返回寄件人代收看板：已收 MONEY_COLLECTION 对已收运费 MONEY_TOTALFEE。
认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。
- CUS_ID
- MONEY_COLLECTION
- MONEY_TOTALFEE
- unpaidBalance
```
GET /v1/viettelpost/cod HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json
```
```
{
  "CUS_ID": "441021",
  "MONEY_COLLECTION": 1850000,
  "MONEY_TOTALFEE": 128000,
  "unpaidBalance": 420000
}
```

代收账单列表

GET /v1/viettelpost/cod/bills openfinance

按 billCode 与 ORDER_NUMBER 分页代收结算账单。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

items
ORDER_NUMBER
billCode
MONEY_COLLECTION
ORDER_STATUS

GET /v1/viettelpost/cod/bills HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{
  "items": [{
    "ORDER_NUMBER": "VTP2401000123",
    "billCode": "BILL-9001",
    "MONEY_COLLECTION": 250000,
    "ORDER_STATUS": "DELIVERED"
  }]
}

列出邮政网点

GET /v1/viettelpost/offices opendata

按 provinceId 返回网点行（postOfficeCode、fullName、坐标）。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

provinceId
items
postOfficeCode
fullName
latitude
longitude

GET /v1/viettelpost/offices?provinceId=1 HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{
  "items": [{
    "postOfficeCode": "HN-01",
    "fullName": "Buu dien Ha Noi 1",
    "provinceId": 1,
    "latitude": 21.0285,
    "longitude": 105.8542
  }]
}

搜索地址

GET /v1/viettelpost/places opendata

寄件/收件地址自动完成：provinceId、districtId、wardId 与坐标。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

q
items
address
provinceId
districtId
wardId
latitude
longitude

GET /v1/viettelpost/places?q=12%20Nguyen%20Trai HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json

{
  "items": [{
    "address": "12 Nguyen Trai, Thanh Xuan, Ha Noi",
    "provinceId": 1,
    "districtId": 6,
    "wardId": 42,
    "latitude": 21.0012,
    "longitude": 105.8198
  }]
}

发起 VTPay 扣款

POST /v1/viettelpost/pay openbanking

为 MONEY_TOTALFEE 发起 VTPay 扣款，返回 qrCode 与 paymentStatus。

认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。

ORDER_NUMBER
MONEY_TOTALFEE
CUS_ID
qrCode
paymentStatus

POST /v1/viettelpost/pay HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "ORDER_NUMBER": "VTP2401000123",
  "MONEY_TOTALFEE": 32000,
  "CUS_ID": "441021"
}

{
  "ORDER_NUMBER": "VTP2401000123",
  "qrCode": "000201010212...",
  "paymentStatus": "PENDING"
}

列出智能柜尺寸
GET /v1/viettelpost/lockers opendata
返回智能柜 boxSize 行及其尺寸与租赁 MONEY_TOTALFEE。
认证方式： POST /v1/viettelpost/session 签发的 Bearer accessToken。
- items
- boxSize
- PRODUCT_LENGTH
- PRODUCT_WIDTH
- PRODUCT_HEIGHT
- MONEY_TOTALFEE
```
GET /v1/viettelpost/lockers HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Accept: application/json
```
```
{
  "items": [{
    "boxSize": "M",
    "PRODUCT_LENGTH": 40,
    "PRODUCT_WIDTH": 30,
    "PRODUCT_HEIGHT": 20,
    "MONEY_TOTALFEE": 15000
  }]
}
```

数据类别

包裹运单
代收货款
运费报价
物流跟踪
邮政网点
地址
VTPay
智能柜
登录会话

数据使用场景与案例

电商结算接到国家承运商
店铺结算先 POST /v1/viettelpost/quote（PRODUCT_WEIGHT、MONEY_COLLECTION），再 POST /v1/viettelpost/parcels，并保存返回的 ORDER_NUMBER 与 MONEY_TOTALFEE。
最后一公里异常台
3PL 机器人分页 GET /v1/viettelpost/parcels 与 GET /v1/viettelpost/track/{orderNumber}，用 TRANG_THAI 与 ORDER_STATUS 驱动取件/退件工单。
代收对账进 ERP
店主会计读取 GET /v1/viettelpost/cod（MONEY_COLLECTION）与 GET /v1/viettelpost/cod/bills（billCode），再对上 POST /v1/viettelpost/pay 的 VTPay 回执。
网点与智能柜叠加
地图叠加 GET /v1/viettelpost/offices（postOfficeCode、fullName）与 GET /v1/viettelpost/lockers（boxSize），让卖家选择交寄柜台或租赁柜。

常见问题

Viettel Post 如何认证 API 调用？

POST /v1/viettelpost/otp 向 phoneNumber 发送 OTP。POST /v1/viettelpost/session 用 phoneNumber 加该 OTP 换取 accessToken、refreshToken 与 CUS_ID。之后的请求以该 accessToken 发送 Authorization: Bearer。

哪些端点暴露运单、报价与跟踪？

POST /v1/viettelpost/parcels 创建运单并返回 ORDER_NUMBER、ORDER_STATUS、DELIVERY_CODE 与 MONEY_TOTALFEE。GET /v1/viettelpost/parcels 分页这些行。POST /v1/viettelpost/quote 按重量与代收金额返回 MONEY_TOTALFEE。GET /v1/viettelpost/track/{orderNumber} 水合带 TRANG_THAI 的 TRACKINGS。

返回哪些代收与支付字段？

GET /v1/viettelpost/cod 返回 MONEY_COLLECTION 与 MONEY_TOTALFEE。GET /v1/viettelpost/cod/bills 列出 billCode 行。POST /v1/viettelpost/pay 发起 VTPay 扣款并返回 qrCode 与 paymentStatus。

API 是否覆盖网点与智能柜？

覆盖。GET /v1/viettelpost/offices 返回 postOfficeCode、fullName、latitude 与 longitude。GET /v1/viettelpost/places 自动完成 provinceId、districtId 与 wardId。GET /v1/viettelpost/lockers 列出带租赁 MONEY_TOTALFEE 的 boxSize 行。

与 Viettel Post 相似的应用

UPS — UPS 是国际承运商，其移动应用跟踪包裹、报价并查找交寄点，相当于 Viettel Post 国内运单客户端的跨境对照。
Почта России — Почта России 是俄罗斯国家邮政客户应用：条码跟踪、网点地图与邮资下单，与 Viettel Post 在越南扮演的角色相同。
Porter - Logistics Service App — Porter 是面向需要即时货车的商家的同城物流应用，以自有车队模式重叠 Viettel Post 的店主寄件受众。
Giao Hàng Nhanh (GHN) — GHN（Giao Hàng Nhanh）是越南主要民营快递，店主常与 Viettel Post 并用处理国内包裹与代收货款。
J&T Express — J&T Express 是在越南网点密集的区域包裹网络，作为 Viettel Post 国家邮政的民营承运对照。
Vietnam Post (VNPost) — VNPost（越南邮政）是越南国家邮政运营商，与 Viettel Post 并列的另一套全国网点网络。
Ahamove — Ahamove 是河内与胡志明市的即时摩托/货车配送应用，覆盖 Viettel Post 以预约包裹出售的同一段店到门最后一公里。

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

每个项目均签 NDA 与 SOW
3–7 天交付
验收通过后才付款
仅在授权范围内作业

获取报价

Viettel Post 数据 API：运单、代收与智能柜

应用截图

API 端点一览

发送登录 OTP

校验 OTP 换取 access token

登录账户资料

创建包裹运单

列出我的运单

作废运单

询价运费

跟踪运单

代收货款看板

代收账单列表

列出邮政网点

搜索地址

发起 VTPay 扣款

列出智能柜尺寸

数据类别

数据使用场景与案例

电商结算接到国家承运商

最后一公里异常台

代收对账进 ERP

网点与智能柜叠加

常见问题

与 Viettel Post 相似的应用

更多出行类应用

Careem Captain

Dostavista — работа курьером

Lyft Driver

Ola Driver App

相关主题

需要集成这个 App 的数据 API？

Viettel Post 数据 API：运单、代收与智能柜

应用截图

API 端点一览

发送登录 OTP

校验 OTP 换取 access token

登录账户资料

创建包裹运单

列出我的运单

作废运单

询价运费

跟踪运单

代收货款看板

代收账单列表

列出邮政网点

搜索地址

发起 VTPay 扣款

列出智能柜尺寸

数据类别

数据使用场景与案例

电商结算接到国家承运商

最后一公里异常台

代收对账进 ERP

网点与智能柜叠加

常见问题

相关应用

与 Viettel Post 相似的应用

更多出行类应用

Careem Captain

Dostavista — работа курьером

Lyft Driver

Ola Driver App

相关主题

需要集成这个 App 的数据 API？