Nova Poshta (old) 数据 API

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

Nova poshta (old) 是 ТОВ «Нова пошта» 推出的老牌安卓客户端。该公司是乌克兰最大的私营包裹承运商，这款应用沿用的是早于新品牌 NovaPost 的 Google Play 上架条目。用户通过 OAuth 登录（或忠诚卡 / 手机号登录）后，寄件人可以创建网络运单、为网点到网点或门到门的货件报价、凭 14 位 ТТН 追踪包裹、改派或退回包裹、预约快递员上门取件，并在地图上查看网点营业时间；同一会话中还保存着带条形码的忠诚卡、汇款单据、postomat（智能快递柜）取件 PIN 码、RedBox 订单以及 NovaPay 银行卡结算。乌克兰的普通家庭、电商卖家和小店在 Ukrposhta、Meest 与面向欧盟的 NovaPost 应用之外也会使用它；由于 Nova Poshta 正在把用户迁移到 novapost.com，而这款客户端仍在服务乌克兰国内网络，所以上架名称至今保留“old”后缀。

网络运单是记录的基本单位：每个 ТТН 带有 IntDocNumber、StatusCode、寄收双方所在城市、DocumentCost，以及 possibilityCreateReturn 等标记。运输节点分为 now / passed / future，快递柜投递暴露 postomatCode，货到付款则落在 moneyTransferAmount 加 moneyTransferCommission 上。

网点目录是由 WarehouseIndex、Latitude、Longitude 和重量上限构成的地理索引，忠诚卡则返回 loyaltyCardNumber、discount 以及流水 Scores。电商 ERP 用它对账发货，结账组件据此挑选放得下包裹的快递柜，记账机器人用它核对货到付款结算款——openData Studio 把这些字段变成可调用的开放数据。

应用截图

API 端点一览

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

追踪运单状态

POST /v1/novaposhtaa/track opendata

查询实时 ТТН 状态、寄收双方城市、网点、货到付款/银行卡标记以及 postomat PIN，支撑包裹追踪界面。

认证方式：已登录时在 JSON 请求体中携带忠诚卡密钥（card key）；公开追踪可省略。可选 Authorization: Bearer <session-token>。

Number
StatusCode
Status
CitySender
CityRecipient
WarehouseRecipient
RecipientDateTime
ScheduledDeliveryDate
DocumentCost
DocumentWeight
CargoDescriptionString
PayerType
PaymentMethod
possibilityCreateReturn
possibilityForRedirecting
postomatCode
CardMaskedNumber

POST /v1/novaposhtaa/track HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "documents": [
    {"documentNumber": "20450123456789", "phone": "380671234567"}
  ],
  "language": "UA"
}

{
  "success": true,
  "data": [{
    "Number": "20450123456789",
    "StatusCode": "7",
    "Status": "Arrived at the warehouse",
    "CitySender": "Київ",
    "CityRecipient": "Львів",
    "WarehouseRecipient": "Відділення №12",
    "RecipientDateTime": "12.10.2026 18:40:00",
    "ScheduledDeliveryDate": "12.10.2026",
    "DocumentCost": "85.00",
    "DocumentWeight": "2.4",
    "CargoDescriptionString": "Одяг",
    "PayerType": "Sender",
    "PaymentMethod": "Cash",
    "possibilityCreateReturn": true,
    "possibilityForRedirecting": true,
    "postomatCode": "4821",
    "CardMaskedNumber": "5168****1234"
  }]
}

列出网络运单

GET /v1/novaposhtaa/waybills opendata

分页返回已登录用户创建的运单（含尚未交运的货物），供货件列表使用。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

Ref
IntDocNumber
Cost
CostOnSite
CitySender
CityRecipient
RecipientFullName
RecipientsPhone
PayerType
PaymentMethod
ServiceType
SeatsAmount
Weight
State
DateTime

GET /v1/novaposhtaa/waybills?full=true&from=2026-09-01&to=2026-10-09&notSent=1 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "a1b2c3d4-1111-2222-3333-444455556666",
    "IntDocNumber": "20450123456789",
    "Cost": "1200",
    "CostOnSite": 85,
    "CitySender": "Київ",
    "CityRecipient": "Одеса",
    "RecipientFullName": "Іван Петренко",
    "RecipientsPhone": "380931112233",
    "PayerType": "Sender",
    "PaymentMethod": "Cash",
    "ServiceType": "WarehouseWarehouse",
    "SeatsAmount": "1",
    "Weight": "1.5",
    "State": "1",
    "DateTime": "08.10.2026 14:22:00"
  }]
}

创建网络运单

POST /v1/novaposhtaa/waybills opendata

在寄件流程中创建（或更新）网络运单，返回 ТТН 单号及网站资费。

认证方式：忠诚卡密钥置于 JSON 请求体中。可选 Bearer <session-token>。

PayerType
PaymentMethod
CargoType
Weight
ServiceType
SeatsAmount
Description
Cost
CitySender
Sender
SendersPhone
CityRecipient
Recipient
RecipientsPhone
OptionsSeat
Ref
IntDocNumber
CostOnSite
EstimatedDeliveryDate

POST /v1/novaposhtaa/waybills HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "payerType": "Sender",
  "paymentMethod": "Cash",
  "cargoType": "Cargo",
  "weight": "2.4",
  "serviceType": "WarehouseWarehouse",
  "seatsAmount": "1",
  "description": "Одяг",
  "cost": "1200",
  "citySender": "<city_ref>",
  "sender": "<counterparty_ref>",
  "senderAddress": "<warehouse_ref>",
  "sendersPhone": "380671234567",
  "cityRecipient": "<city_ref>",
  "recipient": "<recipient_ref>",
  "recipientAddress": "<recipient_warehouse_ref>",
  "recipientsPhone": "380931112233",
  "optionsSeat": [{
    "volumetricWidth": "20",
    "volumetricLength": "30",
    "volumetricHeight": "15",
    "weight": "2.4"
  }]
}

{
  "success": true,
  "data": {
    "Ref": "a1b2c3d4-1111-2222-3333-444455556666",
    "IntDocNumber": "20450123456789",
    "CostOnSite": 85,
    "EstimatedDeliveryDate": "12.10.2026",
    "TypeDocument": "InternetDocument"
  }
}

运单价格试算

POST /v1/novaposhtaa/quote opendata

返回 CalculateCargo / 货件价格步骤所需的网站资费（以及货到付款/回款附加费）。

认证方式：忠诚卡密钥置于 JSON 请求体中。可选 Bearer <session-token>。

CitySender
CityRecipient
Weight
ServiceType
Cost
CargoType
SeatsAmount
RedeliveryCalculate
CostRedelivery
AssessedCost
CostPack

POST /v1/novaposhtaa/quote HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "citySender": "<city_ref>",
  "cityRecipient": "<city_ref>",
  "weight": "2.4",
  "serviceType": "WarehouseWarehouse",
  "cost": "1200",
  "cargoType": "Cargo",
  "seatsAmount": "1",
  "redeliveryCalculate": {
    "cargoType": "Money",
    "amount": "1200"
  }
}

{
  "success": true,
  "data": {
    "Cost": 85,
    "CostRedelivery": 20,
    "AssessedCost": 1200,
    "CostPack": 0
  }
}

运单轨迹时间线

GET /v1/novaposhtaa/waybills/{number}/legs opendata

返回已过、当前和即将经过的运输节点，填充 EW 轨迹地图与历史界面。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

Number
now
passed
future
Status
StatusCode
Date
City
Warehouse

GET /v1/novaposhtaa/waybills/20450123456789/legs?format=timeline HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": {
    "Number": "20450123456789",
    "now": [{
      "Status": "Arrived at the warehouse",
      "StatusCode": "7",
      "Date": "12.10.2026 18:40:00",
      "City": "Львів",
      "Warehouse": "Відділення №12"
    }],
    "passed": [{
      "Status": "Departed from sender warehouse",
      "StatusCode": "5",
      "Date": "10.10.2026 09:15:00",
      "City": "Київ"
    }],
    "future": [{
      "Status": "Received by the recipient"
    }]
  }
}

按手机号查询未结运单

GET /v1/novaposhtaa/inbox opendata

列出与忠诚卡手机号关联、仍未关闭的运单，供收/发包裹收件箱使用。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

Phone
Page
Limit
IntDocNumber
CityRecipient
RecipientFullName
StatusCode
DocumentCost
DateTime

GET /v1/novaposhtaa/inbox?phone=380671234567&page=1&limit=100 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "IntDocNumber": "20450123456789",
    "CityRecipient": "Львів",
    "RecipientFullName": "Іван Петренко",
    "StatusCode": "7",
    "DocumentCost": "85.00",
    "DateTime": "08.10.2026 14:22:00"
  }]
}

忠诚卡资料

GET /v1/novaposhtaa/card osint

加载已登录的忠诚卡持有人信息（条形码、折扣、交易对手、手机号），填充 Cabinet 与 ShowDiscountCard。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

loyaltyCardNumber
loyaltyCardBarcode
loyaltyCardType
discount
phone
email
fullName
counterpartyRef
cityRef
cid
additionalPhones

GET /v1/novaposhtaa/card HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": {
    "loyaltyCardNumber": "9000123456789",
    "loyaltyCardBarcode": "9000123456789",
    "loyaltyCardType": "Personal",
    "discount": 2.0,
    "phone": "380671234567",
    "email": "[email protected]",
    "fullName": "Іван Петренко",
    "counterpartyRef": "c0ffee00-1111-2222-3333-444455556666",
    "cityRef": "<city_ref>",
    "cid": "cid_88421",
    "additionalPhones": ["380931112233"]
  }
}

忠诚卡流水

GET /v1/novaposhtaa/card/ledger openfinance

返回忠诚卡下的运单流水（金额、积分、交易对手），供 TransactionHistory 界面使用。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

DateFrom
DateTo
Document
Date
Sum
Scores
Type
CitySender
CityRecipient
Sender
Recipient
CargoType
PaymentMethod

GET /v1/novaposhtaa/card/ledger?from=2026-01-01&to=2026-10-09 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Document": "20450123456789",
    "Date": "08.10.2026",
    "Sum": "85.00",
    "Scores": "2",
    "Type": "Shipment",
    "CitySender": "Київ",
    "CityRecipient": "Львів",
    "Sender": "Іван Петренко",
    "Recipient": "Олена Коваль",
    "CargoType": "Cargo",
    "PaymentMethod": "Cash"
  }]
}

汇款单据

GET /v1/novaposhtaa/transfers openfinance

分页返回货到付款 / 汇款单据（金额、手续费、cash2card），供 MoneyTransferDocumentsActivity 使用。

认证方式：忠诚卡密钥，另可选 Bearer <session-token>。

Page
Limit
DateFrom
DateTo
Ref
Number
moneyTransferNumber
moneyTransferAmount
moneyTransferCommission
moneyTransferPayerCommission
moneyTransferPayerType
moneyTransferPaymentMethod
moneyTransferStatus
moneyTransferStatusDateTime
moneyTransferCash2Card

GET /v1/novaposhtaa/transfers?page=1&limit=50&from=2025-10-09&to=2026-10-09 HTTP/1.1
Authorization: Bearer <session-token>
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "d0c0ffee-aaaa-bbbb-cccc-ddddeeeeffff",
    "Number": "20450999887766",
    "moneyTransferNumber": "MT-88421",
    "moneyTransferAmount": "3500.00",
    "moneyTransferCommission": "35.00",
    "moneyTransferPayerCommission": "Sender",
    "moneyTransferPayerType": "Sender",
    "moneyTransferPaymentMethod": "Cash",
    "moneyTransferStatus": "Issued",
    "moneyTransferStatusDateTime": "08.10.2026 16:05:00",
    "moneyTransferCash2Card": false,
    "moneyTransferCreationDate": "07.10.2026 11:20:00"
  }]
}

发起运单支付

POST /v1/novaposhtaa/checkout openfinance

从 ChoosePaymentActivity 为运单（运费或事后付款）发起 NovaPay / 银行卡结算。

认证方式：忠诚卡密钥置于 JSON 请求体中。可选 Bearer <session-token>。

Document
Phone
Services
AfterPayments
TransactionId
PaymentSystem
Amount
SuccessUrl
ErrorUrl

POST /v1/novaposhtaa/checkout HTTP/1.1
Content-Type: application/json
Authorization: Bearer <session-token>

{
  "cardKey": "<card_key>",
  "document": "20450123456789",
  "phone": "380671234567",
  "services": [{"serviceCode": "Delivery", "amount": "85.00"}],
  "afterPayments": []
}

{
  "success": true,
  "data": {
    "TransactionId": "npay_9f21a",
    "PaymentSystem": "NovaPay",
    "Amount": "85.00",
    "Document": "20450123456789",
    "SuccessUrl": "https://pay.example.com/result",
    "ErrorUrl": "https://pay.example.com/result"
  }
}

网点目录

GET /v1/novaposhtaa/branches opendata

返回网点 / postomat 记录（邮编索引、地理坐标、重量上限、POS 与 PostFinance 标记），供 FindOffice 与本地网点库使用。

认证方式：共享或用户个人的卡密钥。目录下载也可在未登录的后台客户端上运行。

CityRef
Language
Ref
SiteKey
Description
DescriptionRu
ShortAddress
CityDescription
Number
WarehouseIndex
TypeOfWarehouse
CategoryOfWarehouse
Latitude
Longitude
TotalMaxWeightAllowed
PlaceMaxWeightAllowed
PosTerminal
PostFinance
BicycleParking
InternationalShipping

GET /v1/novaposhtaa/branches?city=<city_ref>&language=UA HTTP/1.1
X-Card-Key: <card_key>

{
  "success": true,
  "data": [{
    "Ref": "1ec09d2b-e1c2-11e3-8c4a-0050568002cf",
    "SiteKey": 10122,
    "Description": "Відділення №12: вул. Городоцька, 174",
    "DescriptionRu": "Отделение №12: ул. Городоцкая, 174",
    "ShortAddress": "Львів, Городоцька, 174",
    "CityRef": "<city_ref>",
    "CityDescription": "Львів",
    "Number": "12",
    "WarehouseIndex": "79000",
    "TypeOfWarehouse": "9a68df70-0267-42ba-8dd1-badd982d3dcb",
    "CategoryOfWarehouse": "Branch",
    "Latitude": "49.8397",
    "Longitude": "24.0297",
    "TotalMaxWeightAllowed": 1000,
    "PlaceMaxWeightAllowed": 30,
    "PosTerminal": "1",
    "PostFinance": "1",
    "BicycleParking": "1",
    "InternationalShipping": "1"
  }]
}

搜索居民点

GET /v1/novaposhtaa/cities opendata

乌克兰居民点自动补全，供 SearchCityFromNpServer 与货件城市选择器使用。

认证方式：城市选择器可在没有卡密钥的情况下运行。

CityName
Limit
TotalCount
Addresses
Present
Warehouses
MainDescription
Area
Region
SettlementRef
DeliveryCity

GET /v1/novaposhtaa/cities?q=%D0%9B%D1%8C%D0%B2%D1%96%D0%B2&limit=20 HTTP/1.1

{
  "success": true,
  "data": {
    "TotalCount": 3,
    "Addresses": [{
      "Present": "м. Львів, Львівська обл.",
      "Warehouses": 142,
      "MainDescription": "Львів",
      "Area": "Львівська",
      "Region": "Львівський",
      "SettlementRef": "<city_ref>",
      "DeliveryCity": "<city_ref>"
    }]
  }
}

数据类别

运单
包裹追踪
网点
忠诚卡
汇款
支付

数据使用场景与案例

电商发货对账
卖家的 ERP 按手机号拉取未结运单，并读取按日期范围的单据列表，再把 IntDocNumber、DocumentCost 和 StatusCode 与订单逐一比对，在截单前标出尚未付款或尚未交运的包裹。
结账页网点选择
结账组件先搜索居民点，再列出带 WarehouseIndex、Latitude/Longitude 与 PlaceMaxWeightAllowed 的网点，让买家选出真正能收下该包裹的快递柜或网点。
货到付款与忠诚卡账目
记账机器人分页读取汇款单据（moneyTransferAmount、moneyTransferCommission、moneyTransferCash2Card）和忠诚卡流水（Sum、Scores），把货到付款的结算款与持卡人的折扣核对。
收件人预计到达与快递柜 PIN
收件人机器人追踪 ТТН，读取 ScheduledDeliveryDate、RecipientDateTime 和 postomatCode，在包裹到达快递柜且仍可退回或改派时通知买家。

常见问题

Nova Poshta 的数据 API 如何标识一个包裹？

每张网络运单由 IntDocNumber（14 位 ТТН）加一个 Ref 标识。追踪接口按 DocumentNumber（可选加收件人 Phone）查询；创建运单则返回 IntDocNumber、CostOnSite 和 EstimatedDeliveryDate。

结账集成可以读取哪些网点字段？

网点目录返回 Ref、WarehouseIndex、Description、CityDescription、Latitude、Longitude、TypeOfWarehouse、PlaceMaxWeightAllowed、PosTerminal 和 PostFinance，买家因此可以选出收得下该重量且带 POS 的网点或 postomat。

这款应用除了追踪，还暴露忠诚卡和汇款数据吗？

是的。忠诚卡返回 loyaltyCardNumber、discount、phone 和 counterpartyRef；卡片流水分页返回 Sum 和 Scores。汇款单据返回 moneyTransferAmount、moneyTransferCommission 和 moneyTransferCash2Card。

已登录会话如何认证？

大多数调用把用户的卡密钥放在 JSON 信封里，并附带 MobileApp 系统标识。OAuth 登录后还会附上 Bearer 会话令牌。城市搜索可以不带卡密钥。

与 Nova poshta (old) 相似的应用

Ukrposhta — 乌克兰国家邮政 Ukrposhta 提供包裹、快递和在线追踪，依托全国邮局网点；维基百科将其列为新邮的主要竞争对手。
Nova Post — Nova Post 是 novaposhta.ua 上列出的现行 Android 客户端（eu.novapost），用于创建运单、查看详情并管理包裹，对应国际品牌 Nova Post。
Meest — Meest 是乌克兰邮政物流运营商，通过自有及合作网点办理国内包裹和发往 70 多个国家的国际件，并提供追踪用手机应用。
Justin — Justin 是乌克兰末端配送服务，把电商包裹送到 Silpo 超市收银台取件点，而不是独立网点。
Delivery Auto — Delivery Auto 是乌克兰货运公司，在全国运送从纸箱到托盘的货物，提供在线追踪、上门取件以及管理回执和运单的手机应用。
UPS — UPS 是联合包裹的 Android 客户端，用于追踪包裹、预约取件和查找交寄点，覆盖国际线路上同类寄件操作。
Packeta — Packeta（Zásilkovna）是中欧电商取件点和智能柜网络，官网将乌克兰列为可送达目的地之一。

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

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

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

获取报价

Nova Poshta (old) 数据 API

应用截图

API 端点一览

追踪运单状态

列出网络运单

创建网络运单

运单价格试算

运单轨迹时间线

按手机号查询未结运单

忠诚卡资料

忠诚卡流水

汇款单据

发起运单支付

网点目录

搜索居民点

数据类别

数据使用场景与案例

电商发货对账

结账页网点选择

货到付款与忠诚卡账目

收件人预计到达与快递柜 PIN

常见问题

与 Nova poshta (old) 相似的应用

更多出行类应用

99 Motorista e Entregador

Amazon Flex

Australia Post

Borzo: Courier Delivery App

相关主题

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

Nova Poshta (old) 数据 API

应用截图

API 端点一览

追踪运单状态

列出网络运单

创建网络运单

运单价格试算

运单轨迹时间线

按手机号查询未结运单

忠诚卡资料

忠诚卡流水

汇款单据

发起运单支付

网点目录

搜索居民点

数据类别

数据使用场景与案例

电商发货对账

结账页网点选择

货到付款与忠诚卡账目

收件人预计到达与快递柜 PIN

常见问题

相关应用

与 Nova poshta (old) 相似的应用

更多出行类应用

99 Motorista e Entregador

Amazon Flex

Australia Post

Borzo: Courier Delivery App

相关主题

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