集成

Postman 合集

我们提供了开箱即用的 Postman 合集，帮助你快速探索和测试 V2 API。

通过 Postman 快速上手

下载并解压下方的 ZIP 文件
打开 Postman → 点击左上角 Import
将解压后的 3 个 JSON 文件拖入，或点击 Choose Files 选择
在右上角环境下拉菜单中选择 ShipSaving V2 — SANDBOX 或 PROD
点击环境下拉旁的 眼睛图标 → 填入你的 appKey 和 appSecret
先运行 Get Access Token — Bearer token 会自动保存
即可开始发送请求

下载： ShipSaving API V2 Postman 合集 (ZIP)

ZIP 包含 API 合集及两个环境文件（Sandbox 和 Production）。

ShipSaving API 提供两种创建运单面单的集成方式：

两步式集成 —— 适用于在购买面单前需要查看并选择服务等级的场景。

第一步：请求所有可用的运费报价。
第二步：使用选定的运费报价购买面单。

一步式集成 —— 适用于全自动化工作流，将运费查询和面单购买合并为一次 API 调用。

两步式集成

如需获取所有可用运费报价并基于所选报价购买面单，请按以下步骤操作：

第一步 —— 获取运费报价

调用 /api/shipment/get_rates 接口以创建运单并获取运费报价选项。
请求体必须包含以下内容：

两个地址对象：from_address_data 和 to_address_data
package_data 对象
可选：custom_data
可选：option_data
可选：shipment_rate_carrier_data —— 允许按承运商和服务等级筛选运费报价，以加快查询速度：
- 使用 provider_id 指定一个或多个承运商
- 使用 service_levels 数组指定一个或多个服务等级
- 示例：
```
"shipment_rate_carrier_data": [
  {
      "provider_id": "USPS_X",
      "service_levels": ["USPS_GROUND_ADVANTAGE"]
  }
]
```
  INFO
  按指定承运商和服务等级进行筛选可减少运费查询次数，从而提升整体性能。

请求样例：

curl --location 'https://x-api.shipsaving.us/api/shipment/get_rates' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0OTQ2MDc3LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ5NDc4NzcsImlhdCI6MTc1NDk0NjA3NywidGVzdF9tb2RlbCI6ZmFsc2V9.ZZTr3HBLjlrKMck2YeQmpkh-6c8r7Z9aqLLVRLioKkcD7c3M41GMDx3qb-LG3XvAJicJe-BYX64pcJ0heCpP7uG6sSq0P7pLR--VdysbinCRB4Bz1VIWRjFkmsMtab2Gi3YToPR4JRV99zVWFI6cKqmaqWIBLyVkWmgAUMIi4PTmFgMUyouqo_GJ6FFmwKb-Av1JrrUe8t5DhDMBuXRl8Da-eLqZSRsQyQ1WV5-uLP7ESYM0k0h5R6I7u-7uT8vf8NR8U8jUYIkzcMb47PuWUxsaWn5ngFLTq03H28g1QV10gxFkBMFgzKEPumxadzzttfDbFXtSd7ALzvC7pXigxA' \
--data-raw '{
    "to_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "it@shipsaving.com"
    },
    "from_address_data": {
        "city": "City Of Industry",
        "country": "US",
        "state": "CA",
        "street": "17XXX Castleton Street",
        "street2": "STE 500",
        "zip_code": "91XXX",
        "first_name": "Alice",
        "last_name": "Li",
        "phone": "1234567890",
        "email": "it@shipsaving.com"
    },
    "package_data": {
        "width": 3,
        "length": 6,
        "height": 0.25,
        "dimension_unit": "in",
        "weight": 2,
        "weight_unit": "oz",
        "type": "my_package" 
    },
    "custom_data": {
        "signing_person": "Ray",
        "content_type": "merchandise",
        "tax_ids": [
            {
                "tax_id_type": "TIN",
                "tax_id_number": "tin2888",
                "country_code": "US"
            }
        ],
        "eel_pfc_type": "EXEMPTION_CODE",
        "eel_pfc_code": "NOEEI 30.37(a)",
        "undeliverable_option": "return_to_sender",
        "item_data_list": [
            {
                "description": "cloth",
                "quantity": 1,
                "origin": "CN",
                "weight": 1,
                "unit_cost": 10.1,
                "weight_unit": "lb"
            }
        ]
    },
    "option_data": {
        "signature": null,
        "custom_text_on_label_1": "",
        "custom_text_on_label_2": "",
        "hazardous_materials": false,
        "additional_handling": false
    },
    "shipment_rate_carrier_data": [
        {
            "provider_id": "UPS_SS_DNI",
            "service_levels": ["UPS_GROUND"]
        }
    ],
    "ship_date": "2025-08-15T00:00:00+08:00"
}'

/api/shipment/get_rates 接口响应中包含：

你账户下所有已启用的承运商及服务等级的运费报价
按最快、最便宜等条件排序的结果
无法提供运费报价的承运商或服务等级对应的 error_info

返回样例：

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "fastest": null,
        "cheapest": {
            "zone": "1",
            "currency": "USD",
            "price_details": null,
            "cubic": false,
            "rate_id": "f3bfa0b5-3dde-4ccb-822f-f995d7e512c6",
            "carrier_code": "GOFO_EXPRESS",
            "provider_id": "GOFO_EXPRESS_A",
            "service_name": "Gofo Express ECO",
            "service_level": "GOFO_EXPRESS_ECO",
            "service_level_desc": "ECO",
            "returned_package_code": "my_package",
            "delivery_days": "2-3",
            "delivery_date": null,
            "delivery_weekday": null,
            "service_detail": "ECO",
            "price": 2.75,
            "origin_price": null,
            "retail_price": null,
            "discount_text": null,
            "insurance_info": null,
            "ship_date": "2025-08-08T00:00:00+08:00",
            "saturday_delivery": false,
            "one_rate": false
        },
        "shipment_rate_data": [
            {
                "zone": "1",
                "currency": "USD",
                "price_details": null,
                "cubic": false,
                "rate_id": "5d73c5d9-3379-44b3-94b0-79c0d17c87e5",
                "carrier_code": "USPS",
                "provider_id": "USPS_X",
                "service_name": "USPS Media Mail",
                "service_level": "USPS_MEDIA_MAIL",
                "service_level_desc": "A cost-effective way to send eligible books, media, and educational materials.",
                "returned_package_code": "my_package",
                "delivery_days": "4",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "A cost-effective way to send eligible books, media, and educational materials.",
                "price": 4.47,
                "origin_price": null,
                "retail_price": 4.47,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            },
            {
                "zone": "1",
                "currency": "USD",
                "price_details": null,
                "cubic": false,
                "rate_id": "f1ed77b3-4525-47f9-b536-8964a8681251",
                "carrier_code": "USPS",
                "provider_id": "USPS_X",
                "service_name": "USPS Ground Advantage",
                "service_level": "USPS_GROUND_ADVANTAGE",
                "service_level_desc": "Low rates for packages with expected delivery in 2-5 business days.",
                "returned_package_code": "my_package",
                "delivery_days": "2",
                "delivery_date": null,
                "delivery_weekday": null,
                "service_detail": "Low rates for packages with expected delivery in 2-5 business days.",
                "price": 5.91,
                "origin_price": null,
                "retail_price": 8.70,
                "discount_text": null,
                "insurance_info": null,
                "ship_date": "2025-08-08T00:00:00+08:00",
                "saturday_delivery": false,
                "one_rate": false
            }
        ],
        "fastest_and_cheapest": null,
        "error_info": {
            "USPS": [
                {
                    "code": "invalid_request_params",
                    "message": "cannot be in the past or more than 30 days in the future"
                }
            ]
        }
    }
}

第二步 —— 购买面单

从 /api/shipment/get_rates 接口的响应中选择一个 rate_id 后，调用 /api/shipment/create_and_buy 接口购买运单面单。
如适用，也可在请求中一并提供 insurance_data。

请求样例：

curl --location 'https://x-api.shipsaving.us/api/shipment/create_and_pay' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX2RYbzNPeTlXRXFLWTRmcHVDT013Q3pDX1BqcElEd3VKc1dDZiIsImF1ZCI6IlNTX0xJVkVfZFhvM095OVdFcUtZNGZwdUNPTXdDekNfUGpwSUR3dUpzV0NmIiwibmJmIjoxNzU0NzAxNjA4LCJjb21wYW55X2lkIjoiMTgxOCIsInVzZXJfaWQiOiIyNDAyIiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQ3MDM0MDgsImlhdCI6MTc1NDcwMTYwOCwidGVzdF9tb2RlbCI6ZmFsc2V9.oi14AMVCn_yGYEDCnBaYeci5FDRfAiO-VKSG_pMRCJEwM7zBJ93m0_-uUS1xmrFV7f3f4OPNeiHzSmNLhS0L2YYn5NXwU8PxMgpVhPGZgCWu31B6VIMaX2nnE5bB26sOrHDObE5wQeB1Yp0geG4KZ_2H5wwrK9fGfRWEH48GbOduQKgS5llIGDilUY0zvFKyeB7HTjDY0kO-hR0F7g0x77PVEk5PVvkBWiN1rOUlT7tAmMdtP-xHpM28U8xKQPOplcbdn4A8t9K2l3TZE84YvsJCzrtmQjr5Qj9m_uadmUNhSyzw5p3KvpI0-l_FWxHC3stkD2Q8CAoCs2Kb3Ur6bg' \
--data '{
    "platform_uk_id": "c_eDQCbv=2YVGw)7#$v_aCI9%ynJEa2O",
    "rate_id": "d9437e43-5283-4289-9ed3-5ef306bb50dd",
    "insurance_data": {
        "rate_id": "50c4685e-5045-4f85-aadc-1a58ff24e147"
    },
    "label_print_type": "common"
}'

返回样例：

{
    "code": "ok",
    "msg": "ok",
    "data": {
        "shipment_no": "1222243143",
        "tracking_no": "1ZXXXXXXXXXXXXXXXX",
        "total_fee": 34.81,
        "label_fee": 34.81,
        "insurance_fee": null,
        "label_urls": [
            "https://xxx.amazonaws.com/labels/2025-08-11/8f6558b8fbb44fd2bdf826c645c9778e_0.png"
        ],
        "commercial_urls": null,
        "label_print_type": "common"
    }
}

一步式集成

该模式适用于全自动化工作流，通过调用 /api/shipment/direct_buy 接口，在一次 API 请求中同时完成运费查询和运单面单购买。你需要在请求中提供所有必需的运单信息，并通过 service_level 字段指定要购买的具体服务等级，从而省略单独的运费选择步骤。如需同时购买运单保险，也可在同一请求中提供 insurance_data 对象。当服务等级已预先确定时，该方式可减少 API 调用次数，并简化整体集成流程。

请求样例：

{
  "service_level": "USPS_GROUND_ADVANTAGE",
  "from_address_data": {
    "phone": "7819991234",
    "email": null,
    "street": "xxxx Castleton Street",
    "street2": "xxxxx",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "company_name": "Shipsaving02",
    "first_name": "Alice",
    "last_name": "Green",
    "zip_code": "91xxx",
    "address_type": "residential"
  },
  "to_address_data": {
    "first_name": "GU",
    "last_name": "GU",
    "country": "US",
    "phone": "9898912324",
    "street": "1328 Pale San Vitores Road, Tumon",
    "city": "Tamuning",
    "state": "GU",
    "zip_code": "96913",
    "street2": ""
  },
  "package_data": {
    "type": "my_package",
    "length": 12,
    "width": 11,
    "height": 5,
    "weight": 1,
    "dimension_unit": "in",
    "weight_unit": "lb"
  },
  "custom_data": {
    "signing_person": "Ray",
    "content_type": "merchandise",
    "tax_ids": [
      {
        "tax_id_type": "TIN",
        "tax_id_number": "tin2888",
        "country_code": "US"
      }
    ],
    "eel_pfc_type": "ITN",
    "eel_pfc_code": "X20250719123456",
    "undeliverable_option": "return_to_sender",
    "item_data_list": [
      {
        "description": "Dazy Plus Plus Size Retro French Fashion Plaid 2 Pieces Set, Chic Outfit For Summer",
        "quantity": 1,
        "origin": "CN",
        "weight": 10,
        "unit_cost": 14.4,
        "weight_unit": "oz",
        "hs_tariff_number": "10.1234"
      }
    ]
  },
  "option_data": {
    "signature": null,
    "custom_text_on_label_1": "text1",
    "custom_text_on_label_2": "text2",
    "hazardous_materials": true,
    "additional_handling": false
  },
  "ship_date": "2025-08-15T00:00:00+08:00",
  "platform_uk_id": "platform_2344343535353",
  "insurance_data": {
    "rate_id": "57e8c472-e699-4900-9e0b-673b2b2034a5"
  },
  "label_print_type": "common"
}