YunExpress

YunExpress

This connector uses the YunExpress OMS API (云途物流, version 1.4.x) on http://oms.api.yunexpress.com: destination countries, shipping methods and goods types, freight quotes, shipment orders (waybills) with tracking numbers, labels, last-mile carriers, tracking and charged fees.

Setup (about 5 minutes)

1. Sign in to the YunExpress customer center (www.yunexpress.cn or your YunExpress customer portal) and open the API section. Note your customer code (客户编号, e.g. C12345) and the API secret (API密钥); apply for the key there if there is none.
2. YunExpress authenticates with Authorization: Basic <token>, where the token is the Base64 of customer code&API secret (an ampersand, not a colon). Compute it once on your computer, for example printf '%s' 'C12345&YourApiSecret' | base64, and paste the result into YUNEXPRESS_API_TOKEN. It is stored encrypted.
3. Install and run yunexpress_list_countries.

Note on the newer open platform: YunExpress also runs an open platform (open.yunexpress.cn, openapi.yunexpress.cn) that signs every request with a millisecond timestamp and an OAuth token. This connector uses the OMS API, which most accounts keep using; the OMS host answers over plain HTTP only.

Ship a parcel: yunexpress_list_countries and yunexpress_list_shipping_methods (with CountryCode) for the possible methods, yunexpress_list_goods_types for goods restrictions, yunexpress_get_price_quote for fees and delivery days, then yunexpress_create_orders (1 to 10 orders per call). Each result has Success, WayBillNumber, TrackingNumber and TrackType (1 tracking number available, 2 pending, 3 none). When the tracking number is pending, ask yunexpress_get_tracking_numbers later. Print with yunexpress_get_labels (temporary PDF URL).

After shipping: yunexpress_get_order (order data and status), yunexpress_get_sender, yunexpress_get_tracking (events as your display settings allow), yunexpress_get_full_tracking (whole history where supported), yunexpress_get_carriers (last-mile carrier and its number) and yunexpress_get_shipping_fee (fees charged). Change the forecast weight with yunexpress_update_weight, stop a parcel with yunexpress_intercept_order, and remove an order that YunExpress has not received with yunexpress_delete_order (switched off).

Writes: confirm first. Creating orders books real shipments, intercepting and deleting change them. Before each write show the user the orders (receiver, method, weight, customs declaration) and wait for a yes. After an unclear timeout on a write, read the order with yunexpress_get_order before trying again, so it is not booked twice.

Numbers and units: weights in kg (up to 3 decimals), dimensions in whole cm, declared values (UnitPrice) per unit in the stated CurrencyCode. OrderNumber accepts the YunExpress waybill number, your customer order number or the tracking number; for intercept and delete, OrderType says which one (1 waybill, 2 customer order, 3 tracking number).

Tracking codes: package state 0 unknown, 1 submitted, 2 in transit, 3 delivered, 4 received, 5 cancelled, 6 delivery failed, 7 returned. Tracking status 0 not found, 10 pre-advice, 20 in transit, 30 ready for pickup, 40 failed, 50 delivered, 60 exception, 80 unknown, 90 returned, 100 cancelled.

Answers and errors: every answer has Code (0000 success), Message, the data in Item or Items, and a RequestId to quote to YunExpress support. Common codes: 1001 submission failed, 1002 wrong customer code or secret, 1003 signature error, 1004 parameter error, 1006 no data, 1011 partial success, 2004 duplicate customer order number, 2005 order exists, 2006 no tracking number for this method, 2009 weight must be positive, 2010 the method does not serve the destination, 10000 request limit reached, 9999 platform error. A wrong token is answered with HTTP 421 and ResultCode 401.