Nova Post 运单与快递柜数据 API

ТОВ «Нова пошта» · 出行

Nova Post 是 ТОВ «Нова пошта»（Nova Poshta）面向家庭用户和小型寄件方推出的官方 Android 应用，服务于其乌克兰快递业务及国际 Nova Post 网络。用户可以创建运单、跟踪收寄包裹、选择营业网点或 postomat 快递柜、预约快递员上门取件，并通过 NovaPay 或会员积分支付运费。首页汇总包裹动态、快递柜取件卡、附近服务网点、促销优惠及海关申报账单。应用提供乌克兰语、英语和其他欧洲语言选项，方便网络覆盖范围内的寄件人使用。它是当前的第一方客户端，与旧版 Nova poshta (old) 应用并存，并非汇集多家承运商的包裹追踪工具。

运单时间线通过 onlineTrackingStatusCode 关联带日期的 event_name 事件记录、settlement_name 和 scheduledDeliveryDate。运单记录还包含寄件人与收件人信息、包裹重量、申报价值及可用操作。运费以 totalCost 和 currencyCode 表示，paymentStatus 与 moneyTransferStatus 则分别反映结算进度和货到付款款项的划转状态。

服务网点记录将 lat、lon 与 divisionCategory、营业状态及警报标记结合；快递柜可用状态由 isAvailablePostomat 补充，取件卡则包含 recipientCode、uploadCode 和有效期。已预约的上门取件记录通过 pickedTimeFrom、pickedTimeTo 关联快递员信息、车辆位置与对应运单。已保存地址、符合条件的促销优惠及带版本号的包裹更新，进一步补充了这些配送记录。

电商平台的订单系统可将配送事件与发货节点匹配，仓库团队可结合服务网点可用状态与取件时段安排作业，财务团队则可核对运费及货到付款状态。openData Studio 将这些记录转化为可调用的开放数据，为上述集成提供支持。下方 API 路径及示例值仅作示意；关联账户的联系方式、快递柜访问码和快递员信息均需获得授权后访问。

应用截图

API 端点一览

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

按标识查询包裹物流

GET /v1/parcels/{id}/timeline opendata

返回物流追踪页面所展示运单的实时物流时间线及状态码。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

id
number
onlineTracking
tracking_status_code
short_description
long_description
label
tracking
event
event_name
event_status
settlement_name
country_code
onlineTrackingStatusCode
onlineTrackingShortDescription
scheduledDeliveryDate
status

GET /v1/parcels/{id}/timeline HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "parcel-demo-001",
  "number": "DEMO-WAYBILL-001",
  "onlineTracking": {
    "tracking_status_code": 1,
    "short_description": "Awaiting handover",
    "long_description": "The sender has created the waybill and has not handed over the parcel.",
    "info": "",
    "label": "orange"
  },
  "tracking": [
    {
      "number": "DEMO-WAYBILL-001",
      "date": "2026-10-27T09:00:00Z",
      "division": "point-demo-001",
      "event": "CreateID",
      "event_status": "now",
      "country_code": "UA",
      "code": "1",
      "settlement_name": "Kyiv",
      "event_name": "Waybill created; parcel not yet handed over"
    }
  ],
  "onlineTrackingStatusCode": 1,
  "onlineTrackingShortDescription": "Awaiting handover",
  "scheduledDeliveryDate": "2026-10-28T16:00:00Z",
  "status": "ReadyToShip"
}

获取运单详情

GET /v1/parcels/{id}/details opendata

加载运单详情页面使用的完整运单，包括寄收双方、尺寸、汇总数值和可用操作标记。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

id
number
status
paymentStatus
currencyCode
parcelsAmount
payerType
sender
recipient
phone
countryCode
settlement_id
settlement_name
divisionId
divisionCategory
serviceType
parcels
cargo_category_group
insurance_cost
actual_weight
totalWeight
totalInsuranceCost
totalCost
moneyTransferStatus
parcel_actions
canPay

GET /v1/parcels/{id}/details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "parcel-demo-001",
  "number": "DEMO-WAYBILL-001",
  "status": "ReadyToShip",
  "paymentStatus": "NeedPay",
  "currencyCode": "UAH",
  "parcelsAmount": 1,
  "payerType": "Sender",
  "sender": {
    "phone": "<sender-phone>",
    "name": "Example Sender",
    "countryCode": "UA",
    "settlement_id": "city-demo-001",
    "settlement_name": "Kyiv",
    "divisionId": "point-demo-001",
    "division_name": "Example branch 1",
    "divisionCategory": "PostBranch",
    "serviceType": "Division"
  },
  "recipient": {
    "phone": "<recipient-phone>",
    "name": "Example Recipient",
    "countryCode": "UA",
    "settlement_id": "city-demo-002",
    "settlement_name": "Lviv",
    "divisionId": "point-demo-002",
    "divisionCategory": "PostBranch",
    "serviceType": "Division"
  },
  "parcels": [
    {
      "number": "DEMO-WAYBILL-001",
      "cargo_category_group": "document",
      "insurance_cost": 300,
      "length": 30,
      "width": 20,
      "height": 2,
      "actual_weight": 0.8
    }
  ],
  "totalWeight": 0.8,
  "totalInsuranceCost": 300,
  "totalCost": 80,
  "moneyTransferStatus": null,
  "parcel_actions": {
    "canPay": true,
    "canPrint": true,
    "canEdit": true
  }
}

计算寄件费用

POST /v1/rates/estimate opendata

在创建包裹向导提交运单前，提供运费与附加服务的报价。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

senderCountryCode
recipientCountryCode
senderServiceType
recipientServiceType
actual_weight
insurance_cost
payerType
currencyCode
totalCost
totalInsuranceCost
totalWeight
services
service_type
service_name
cost
price
discount
payment_status

POST /v1/rates/estimate HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "senderCountryCode": "UA",
  "recipientCountryCode": "UA",
  "senderServiceType": "Division",
  "recipientServiceType": "Postomat",
  "actual_weight": 1.2,
  "length": 25,
  "width": 20,
  "height": 12,
  "insurance_cost": 400,
  "payerType": "Sender",
  "currencyCode": "UAH"
}

{
  "currencyCode": "UAH",
  "totalCost": 85.0,
  "totalInsuranceCost": 400.0,
  "totalWeight": 1.2,
  "services": [
    {
      "service_type": "MainService",
      "service_name": "Example domestic parcel delivery",
      "cost": 85.0,
      "price": 85.0,
      "discount": 0,
      "payer_type": "Sender",
      "payment_status": "NeedPay",
      "currency_code": "UAH"
    }
  ]
}

postomat 快递柜开柜码

GET /v1/locker-access/{number}/codes opendata

提供用于打开 postomat 快递柜格口的收件 PIN、投件码和蓝牙 MAC 地址。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

shipmentNumber
recipientCode
uploadCode
bluetoothMacAddress
expirationDate
isQrGenerated
postomatProducer

GET /v1/locker-access/{number}/codes HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "shipmentNumber": "DEMO-WAYBILL-001",
  "recipientCode": "<pickup-pin>",
  "uploadCode": "<dropoff-code>",
  "bluetoothMacAddress": "<locker-bluetooth-address>",
  "expirationDate": "2026-10-29T18:00:00Z",
  "isQrGenerated": true,
  "postomatProducer": "Example locker provider"
}

查询可用快递柜

GET /v1/locker-locations/availability opendata

列出仍有空闲格口、可供当前包裹寄送或改投的快递柜。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

id
titleName
titleNumber
divisionCategory
address
lat
lon
settlement
countryCode
isAvailablePostomat
postomatProducer
maxInsuranceCost
scheduleList

GET /v1/locker-locations/availability HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "id": "locker-demo-001",
      "titleName": "Example locker 7",
      "titleNumber": "7",
      "divisionCategory": "Postomat",
      "address": "Example Street 10, Kyiv",
      "lat": 50.45,
      "lon": 30.52,
      "settlement": "Kyiv",
      "countryCode": "UA",
      "isAvailablePostomat": true,
      "postomatProducer": "Example locker provider",
      "maxInsuranceCost": 12000.0,
      "scheduleList": [
        "08:00-20:00"
      ]
    }
  ]
}

查询快递车辆坐标
GET /v1/delivery-runs/{shipmentNumber}/position opendata
持续提供地图追踪卡片所使用的快递车辆位置。
认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email
- shipmentNumber
- latitude
- longitude
- coordinatesStatus
- canGetCourierRoute
```
GET /v1/delivery-runs/{shipmentNumber}/position HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
```
```
{
  "shipmentNumber": "DEMO-WAYBILL-001",
  "latitude": 50.451,
  "longitude": 30.521,
  "coordinatesStatus": "live",
  "canGetCourierRoute": true
}
```
查询网点警报状态
GET /v1/service-points/availability opendata
标记已关闭或处于警报状态的网点，便于地图与取件向导跳过这些网点。
认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email
- divisions
- id
- titleName
- alarm
- isDivisionOpen
- countryCode
- settlement
- lat
- lon
```
GET /v1/service-points/availability HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
```
```
{
  "divisions": [
    {
      "id": "point-demo-001",
      "titleName": "Example branch 1",
      "alarm": false,
      "isDivisionOpen": true,
      "countryCode": "UA",
      "settlement": "Kyiv",
      "lat": 50.45,
      "lon": 30.52
    }
  ]
}
```

查询上门取件订单

GET /v1/collections/{id}/details opendata

返回已预约的上门取件记录，包括取件时段、已分配的快递员及关联运单。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

id
number
status
statusDateTime
countryCode
fullName
phone
settlementName
settlementId
pickedTimeFrom
pickedTimeTo
isExpressDelivery
cargoType
weight
volumetricWeight
parcelsAmount
payerType
paymentMethod
courier
courierId
courierName
courierPhone
vehicleNumber
shipments
shipmentId
shipmentNumber

GET /v1/collections/{id}/details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "id": "collection-demo-001",
  "number": "DEMO-COLLECTION-001",
  "status": "Assigned",
  "statusDateTime": "2026-10-27T08:00:00Z",
  "countryCode": "UA",
  "fullName": "Example Sender",
  "phone": "<sender-phone>",
  "settlementName": "Kyiv",
  "settlementId": 100001,
  "pickedTimeFrom": "2026-10-28T09:00:00Z",
  "pickedTimeTo": "2026-10-28T12:00:00Z",
  "isExpressDelivery": false,
  "cargoType": "Parcel",
  "weight": 1.2,
  "volumetricWeight": 1.5,
  "parcelsAmount": 1,
  "payerType": "Sender",
  "paymentMethod": "Cash",
  "courier": {
    "courierId": "courier-demo-001",
    "courierName": "Example Courier",
    "courierPhone": "<courier-phone>",
    "vehicleNumber": "<vehicle-registration>"
  },
  "shipments": [
    {
      "shipmentId": "parcel-demo-001",
      "shipmentNumber": "DEMO-WAYBILL-001"
    }
  ]
}

查询快递员取件时段
GET /v1/collection-slots opendata
列出创建包裹及改期流程中可预约的快递员上门取件时段。
认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email
- date
- number
- start
- end
- boundaryTime
- deliveryPartner
- minutesToPickUp
```
GET /v1/collection-slots HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
```
```
{
  "items": [
    {
      "date": "2026-10-28",
      "number": "1",
      "start": "09:00",
      "end": "12:00",
      "boundaryTime": "08:15",
      "deliveryPartner": "NovaPoshta",
      "minutesToPickUp": 45
    }
  ]
}
```

查询客户资料

GET /v1/account/contact-details osint

读取已登录寄件人的个人资料，用于预填创建包裹表单和常用网点。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

phone
name
email
countryCode
eoriCode
favoriteAddresses
favoriteAddressId
settlementName
address
divisionId

GET /v1/account/contact-details HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "phone": "<sender-phone>",
  "name": "Example Sender",
  "email": "<sender-email>",
  "countryCode": "UA",
  "eoriCode": null,
  "favoriteAddresses": [
    {
      "favoriteAddressId": "address-demo-001",
      "settlementName": "Kyiv",
      "address": "Example Street 10, Kyiv",
      "divisionId": null
    }
  ]
}

查询常用收寄地址

GET /v1/address-book/entries opendata

列出已保存、可一键选择的寄件人或收件人地址。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

favoriteAddresses
favoriteAddressId
city
street
building
postCode
countryCode
latitude
longitude
addressId

GET /v1/address-book/entries HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "favoriteAddresses": [
    {
      "favoriteAddressId": "address-demo-001",
      "city": "Kyiv",
      "street": "Example Street",
      "building": "10",
      "postCode": "01001",
      "countryCode": "UA",
      "latitude": 50.45,
      "longitude": 30.52,
      "addressId": "address-demo-001"
    }
  ]
}

查询运单支付状态

GET /v1/postage/{number}/payment-state openbanking

读取运单的 NovaPay 结算状态，包括货到付款的款项划转状态。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

number
paymentStatus
currencyCode
totalCost
payerType
isPaymentProcessing
moneyTransferStatus
payments
source
amount
status

GET /v1/postage/{number}/payment-state HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "number": "DEMO-WAYBILL-001",
  "paymentStatus": "NeedPay",
  "currencyCode": "UAH",
  "totalCost": 80.0,
  "payerType": "Sender",
  "isPaymentProcessing": false,
  "moneyTransferStatus": null,
  "payments": [
    {
      "source": "NovaPay",
      "amount": 80.0,
      "status": "NeedPay"
    }
  ]
}

使用会员积分支付

POST /v1/postage/{number}/redeem-points openfinance

使用寄件人的 Nova Poshta 会员卡结算运费，而不是通过 NovaPay 支付。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

loyaltyCardNumber
number
paymentStatus
currencyCode
totalCost

POST /v1/postage/{number}/redeem-points HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "loyaltyCardNumber": "DEMO-LOYALTY-001",
  "number": "DEMO-WAYBILL-001"
}

{
  "number": "DEMO-WAYBILL-001",
  "paymentStatus": "Paid",
  "loyaltyCardNumber": "DEMO-LOYALTY-001",
  "currencyCode": "UAH",
  "totalCost": 0.0
}

查询寄件优惠码

GET /v1/delivery-offers opendata

列出运单应用优惠码菜单中展示的可用优惠码。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

promoCode
dateOfEnding
note
auto
deliveryChanel
details
Valid

GET /v1/delivery-offers HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "promoCode": "DEMO-OFFER-15",
      "dateOfEnding": "2026-11-30",
      "note": "Illustrative 15% discount on eligible parcels",
      "auto": "false",
      "deliveryChanel": "mobile",
      "details": [
        "domestic",
        "eligible parcels"
      ],
      "Valid": true
    }
  ]
}

同步运单版本

GET /v1/parcel-updates opendata

分页获取增量运单版本，让后台同步过程能够刷新本地保存的运单记录。

认证方式：通过 OpenID Connect 登录后使用 Bearer 访问令牌；授权范围为 openid、offline、name、phone、email

items
id
number
version
updatedAt
deletedAt
status
current_page
per_page
last_page
total

GET /v1/parcel-updates HTTP/1.1
Authorization: Bearer <access-token>
Accept: application/json

{
  "items": [
    {
      "id": "parcel-demo-001",
      "number": "DEMO-WAYBILL-001",
      "version": 12,
      "updatedAt": "2026-10-27T09:05:00Z",
      "deletedAt": null,
      "status": "ReadyToShip"
    }
  ],
  "current_page": 1,
  "per_page": 15,
  "last_page": 1,
  "total": 1
}

数据类别

物流追踪
运单
营业网点
快递柜
上门取件
支付
地址
个人资料
优惠码

数据使用场景与案例

电商平台运单追踪
已能打印 Nova Poshta 条码的结算后端可轮询 onlineTrackingStatusCode、event_name 和 scheduledDeliveryDate，将订单从 ReadyToShip 更新为已送达，而不必抓取公开的物流查询页面。
快递柜与网点地图叠加
末端配送地图可将网点的 lat、lon、divisionCategory 和 isAvailablePostomat 与 recipientCode、uploadCode 结合，让购物者看到哪些 postomat 快递柜仍有空闲格口，并在抵达后开柜。
NovaPay 与货到付款对账
财务任务可将 paymentStatus、totalCost、currencyCode 和 moneyTransferStatus 与商户账本匹配，使未支付运单与货到付款的款项划付状态保持同步。
快递员上门取件时段
仓库调度系统可读取 pickedTimeFrom、pickedTimeTo 及实时 latitude、longitude，把预约取件时段与正在接近的车辆位置展示在同一运营看板上。

常见问题

哪些 Nova Post 物流追踪和 NovaPay 支付字段可用于订单对账？

运单追踪包含 onlineTrackingStatusCode，以及带有 event、event_name、settlement_name 和 country_code 的时间线。运单详情还提供 scheduledDeliveryDate、包裹状态、寄件人与收件人信息及 totalCost。支付记录提供 paymentStatus、totalCost、currencyCode、payerType、isPaymentProcessing 和 moneyTransferStatus；积分支付则将 loyaltyCardNumber 与运单 number 及支付后的 paymentStatus 关联。这些字段可供订单和财务系统核对配送节点、运费及货到付款状态。此处展示的路径、金额和标识符仅作示意，并非实时运价或支付结果。

哪些字段描述 postomat 快递柜的访问方式与可用状态？

快递柜访问记录包含取件用的 recipientCode、投件用的 uploadCode、bluetoothMacAddress 和 expirationDate。快递柜可用状态记录还包含 lat、lon、isAvailablePostomat、postomatProducer 和 scheduleList。访问码属于经授权的运单操作流程，并非公开可用 PIN 码的目录。

如何认证对 Nova Post 账户关联数据的访问？

账户流程使用 OpenID Connect 登录与 Bearer 访问令牌。示例采用令牌占位符和通用化路径，不提供可直接使用的登录配置。联系方式、已保存地址及特定运单的快递柜访问功能均需相应授权。

能否结合网点位置与快递员取件时段？

服务网点记录提供 id、lat、lon、alarm 和 isDivisionOpen。已预约的上门取件记录包含 pickedTimeFrom、pickedTimeTo、courierName、vehicleNumber 和关联的 shipmentNumber 值。可预约时段还提供 start、end、boundaryTime 和 minutesToPickUp，用于安排取件。

与 Nova Post 相似的应用

Nova poshta (old) — Nova poshta（旧版）是同一开发商 ТОВ «Нова пошта» 的长期安卓客户端，用于创建、追踪、支付和改派新邮运单，并可一键叫快递员。
Ukrposhta — 乌克兰国家邮政 Ukrposhta 为全资国有，在全国提供邮政、物流、金融和快递服务，包括平信、特快邮件和包裹。
Meest Poshta — Meest POSHTA 是 Meest 在乌克兰及境外寄递的官方安卓应用，可在线创建运单、全天候追踪、在线支付运费，并在地图上查找网点和包裹柜。
Delivery Auto — Delivery Auto 是乌克兰货运公司，承运从纸箱到托盘的货物；其安卓应用可按回执号追踪、查询代表处，并估算运费与时效。
Justin — Justin 是乌克兰包裹服务，取件点设在 Silpo 超市内，购物者可在日常买菜的地方收发订单。
UPS — UPS 是联合包裹的官方安卓应用，用于制作运单标签、追踪进出港包裹、查询运费并查找交寄点。
DHL Express Mobile — DHL Express Mobile 是 DHL Express 的官方安卓应用，用于追踪快件、管理投递、查找服务点并查询运费。
Packeta — Packeta（Zásilkovna）是中欧取件点与 Z-BOX 包裹柜网络，其捷克站点将乌克兰列为可通过取件点或上门派送送达的目的地。

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

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

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

获取报价

Nova Post 运单与快递柜数据 API

应用截图

API 端点一览

按标识查询包裹物流

获取运单详情

计算寄件费用

postomat 快递柜开柜码

查询可用快递柜

查询快递车辆坐标

查询网点警报状态

查询上门取件订单

查询快递员取件时段

查询客户资料

查询常用收寄地址

查询运单支付状态

使用会员积分支付

查询寄件优惠码

同步运单版本

数据类别

数据使用场景与案例

电商平台运单追踪

快递柜与网点地图叠加

NovaPay 与货到付款对账

快递员上门取件时段

常见问题

与 Nova Post 相似的应用

更多出行类应用

Careem Captain

Delhivery: Courier App

DiDi Driver: Drive & Earn Cash

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

相关主题

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

Nova Post 运单与快递柜数据 API

应用截图

API 端点一览

按标识查询包裹物流

获取运单详情

计算寄件费用

postomat 快递柜开柜码

查询可用快递柜

查询快递车辆坐标

查询网点警报状态

查询上门取件订单

查询快递员取件时段

查询客户资料

查询常用收寄地址

查询运单支付状态

使用会员积分支付

查询寄件优惠码

同步运单版本

数据类别

数据使用场景与案例

电商平台运单追踪

快递柜与网点地图叠加

NovaPay 与货到付款对账

快递员上门取件时段

常见问题

相关应用

与 Nova Post 相似的应用

更多出行类应用

Careem Captain

Delhivery: Courier App

DiDi Driver: Drive & Earn Cash

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

相关主题

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