端点
请求运输报价
POST | https://api.iglobalstores.com/2.0/shipping-quotes - 创建一个新的请求，以获取购物车中物品的运输报价，包括进口关税和税费以及物品限制筛选信息。
HTTPS 请求
| 字段 | 备注 |
|---|---|
| HTTP 方法 | POST |
| 端点 URL | https://api.iglobalstores.com/2.0/shipping-quotes |
| 协议 | HTTPS |
| 消息格式 | JSON |
| 接受 HTTP 头 | Accept: application/json |
| 安全令牌 HTTP 头 | serviceToken: your-test-token-value在您的 HTTPS 请求中添加一个名为 serviceToken 的头，值为您的测试安全 API 令牌。（请联系您的客户经理以获取此令牌） |
| 内容类型 HTTP 头 | Content-Type: application/json因为您将向服务发布 JSON 数据，所以在您的 HTTPS 请求中添加一个名为 Content-Type 的头，值为 application/json |
请求体中的 JSON 键/值对
消息格式: JSON
示例请求
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"boxCount": null,
"items": [
{
"cartItemId": 1,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675234",
"sku": "oakley-123",
"unitPrice": 199.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
},
{
"cartItemId": 2,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675235",
"sku": "oakley-125",
"unitPrice": 179.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
}
],
"shippingAmountOverride": null,
"shipFromAddress": null,
"shipToAddress": {
"name": "John Doe",
"address1": "123 S West Elm St",
"address2": null,
"address3": null,
"city": "Calgary",
"state": "Alberta",
"stateCode": "AB",
"postalCode": "T2P 5G8",
"countryCode": "CA"
}
}
请求 JSON 定义
| 字段 | 备注 |
|---|---|
boxCount | 此字段描述将用于发货订单的箱子数量。商家在下订单时不必知道这一点；但是，如果已知，可以以以下特定格式传递。示例值：22x15x15(1),8x8x4(2),32x22x14(1)格式：用逗号分隔的箱子尺寸和数量列表。在上面的示例中，总共有 4 个箱子。列表中的第一个箱子将是 22 英寸长，15 英寸宽，15 英寸高。该尺寸只会使用一个箱子。将有两个尺寸为 8x8x4 英寸的箱子。如果这样做对您来说更简单，可以多次传递相同的箱子尺寸，例如：“22x15x15(1),22x15x15(1)”，这意味着 2 个尺寸为 22x15x15 英寸的箱子。 |
items 必填 | 项目映射的列表 |
items[index].brandName | 特定项目的品牌名称将帮助我们的规则引擎最佳确定该项目是否适用于目的国的限制。即使项目的品牌名称与特定限制在文本上匹配或不匹配，我们的规则引擎也将使用项目的 SKU 和/或 productId 来更好地决定该项目是否确实受到目的国的限制。如果可用，请发送品牌名称。示例值：“Oakley”或“Nike”或 null |
items[index].cartItemId 必填 | 此字段是识别项目所必需的，特别是在项目列表中。它可以是简单的索引值。我们将使用此 cartItemId 来识别 JSON 响应中受限的项目。因此，请确保您能够通过传递给我们的 cartItemId 识别购物车中的相同项目。示例值：1 或 2 或 3 |
items[index].category | 产品类别 - 它所属于的特定产品。类别将帮助我们的规则引擎最佳确定该项目是否适用于目的国的限制。即使项目的类别与特定限制在文本上匹配或不匹配，我们的规则引擎也将使用项目的 SKU 和/或 productId 来更好地决定该项目是否确实受到目的国的限制。格式：用管道分隔的类别名称列表。每个类别名称可以是一个或多个单词。如果一个项目存在于多个类别中，请将它们用管道“”字符分隔列出。示例值：“Sunglasses”或“Evening AccessoriesHandbags” |
items[index].countryOfOrigin | 原产国是指商品制造或最初来源的国家。原产国将帮助我们的规则引擎最佳判断该商品是否适用于目的国的限制。一些国家不允许特定类型的商品来自其他特定国家。示例值：“CN”代表中国或“US”代表美国或null |
items[index].detailedDescription REQUIRED | 此字段仅为文本，但应尽可能包含有关所购商品的详细信息。例如，适用时的完整名称和商品代码、所选颜色或其他选项、材料成分以及您对该商品的任何描述文本。不同国家对进口商品有许多不同类型的限制，例如意大利对皮鞋的限制。有时，捕捉这些受限商品的唯一方法是通过 detailedDescription。注意：即使商品的 detailedDescription 在文本上与特定限制不匹配，我们的规则引擎仍将使用商品的SKU和/或 productId 更好地判断该商品是否确实受到目的国的限制。为了获得最佳效果，请在 detailedDescription 字段中提供尽可能多的信息。示例值：“Tory Burch, Robinson – Double Zip’ Tote, 颜色：新狂欢节，材料成分：皮革，色彩丰富的皮革赋予整齐结构的手提包引人注目的吸引力，配有标志性五金和卷曲手柄，展现出完全精致的外观。磁扣闭合，带有双拉链隔层。内部拉链、墙壁和手机口袋。保护性金属脚。皮革。由Tory Burch设计；进口。” |
items[index].height | 这是您商品的高度。还有一个名为 dimensionalUnits 的字段，您可以在其中指定此测量的英寸或厘米。请提供不带逗号且最多两位小数的值。示例值：25.5如果您提供此字段，您的运费将更准确。 |
items[index].hsCode | 这是识别商品在外国的HS编码。传递 hsCode 将有助于正确识别特定商品的进口关税 rate。如果不可用，则不需要提供 - 如果您没有，我们会处理。格式：可以是10位或6位代码；可以包含分隔的“.”字符或不包含。示例值：“20.4560.0000”或“20.4560”或“204560”（接受10位或6位代码） |
items[index].length | 这是您商品的长度。还有一个名为 dimensionalUnits 的字段，您可以在其中指定此测量的英寸或厘米。请提供不带逗号且最多两位小数的值。示例值：25.5如果您提供此字段，您的运费将更准确。 |
items[index].productId | 这是您特定商品的产品ID。我们的规则引擎将使用此值作为ID，将学习到的商品信息与您的商品关联。示例值：“17898-675235”请至少传递 productID 或SKU。优先传递两者。 |
items[index].quantity REQUIRED | 这是特定商品的购买数量。请提供为正整数，不带逗号且没有小数位。示例值：1或9999（我们更希望您销售更多商品而不是更少！） |
items[index].sku | 这是您特定商品的SKU。我们的规则引擎将使用此值作为ID，将学习到的商品信息与您的商品关联。示例值：“oakley-125”请至少传递 productId 或SKU。优先传递两者。 |
items[index].unitPrice REQUIRED | 这是您商品的单价，以美元（USD）计。请提供不带逗号、不带美元符号“$”且保留两位小数。示例值：2102.99 |
items[index].weight | 这是您物品的重量。还有一个名为 weightUnits 的字段，您可以在其中指定磅、盎司、克或千克作为此测量的单位。请提供不带逗号且最多保留两位小数。示例值：4.2如果您传递此字段，您的运费将是最准确的。 |
items[index].weightUnits | 默认值为“LB”，表示磅。重量值的计量单位。如果设置为 null，将假定为“LB”（磅）。示例值：“LB”表示磅或“OZ”表示盎司或“G”表示克或“KG”表示千克或 null |
items[index].width | 这是您物品的宽度。还有一个名为 dimensionalUnits 的字段，您可以在其中指定英寸或厘米作为此测量的单位。请提供不带逗号且最多保留两位小数。示例值：25.5如果您传递此字段，您的运费将是最准确的。 |
shipFromAddress | 如果传递为 null，我们将使用与您的商户账户关联的默认 shipFromAddress。这是订单将从中发货的地址，即您的仓库。这是一个包含以下地址字段的映射：address1、address2、address3、city、state、stateCode、postalCode、countryCode。这些字段的要求与否取决于国家。定位端点返回每个国家所需的具体地址字段。注意：stateCode 始终不是必需的，并且在定位端点中未声明。如果可用，您可以传递 stateCode。 |
shippingAmountOverride | 仅在您在调用 API 之前知道运费时使用。以美元（USD）为单位。请提供不带逗号、不带美元符号“$”，并保留两位小数。此功能在未与 Zonos 代表设置的情况下将无法工作。示例值：212.99 |
shipToAddress REQUIRED | 这是订单将发货到的地址。这是一个包含以下地址字段的映射：name、address1、address2、address3、city、state、stateCode、postalCode、countryCode。这些字段的要求与否取决于国家。定位端点返回每个国家所需的具体地址字段。注意：name 和 stateCode 始终不是必需的，并且在定位端点中未声明。如果可用，您可以传递 name 和/或 stateCode。 |
HTTPS 响应
消息格式：JSON
仅针对加拿大和澳大利亚的示例响应
注意： 实际响应将包含所有支持的国家。
示例请求
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
"shippingQuotes": [
{
"id": "bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a",
"carrier": "UPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Express Air 2-4 Day Delivery",
"duty": 10.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 29.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 23.62,
"taxOrVat": 9.18
},
{
"id": "80c57724-ab4e-4997-8477-08b668fef103",
"carrier": "USPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Post 5-10 Day Delivery",
"duty": 9.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 27.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 13.62,
"taxOrVat": 8.18
}
]
}
响应 JSON 定义
| 字段 | 备注 |
|---|---|
shippingQuotes | 这是一个运输报价映射的列表。 |
shippingQuotes[index].carrier | 该运输报价特定的承运人。仅在商家要求设置通用运输档案时才设置为null，而不是特定于某个承运人。运输报价不需要特定于某个承运人；但可以是。请联系您的客户经理以获取设置运输档案的帮助。示例值：UPS 或 FEDEX 或 DHL 或 USPS 或 CAPOST 或 null |
shippingQuotes[index].displayName | 适合展示给购物者的运输选项的显示名称。这些值可以为商家自定义。请联系您的客户经理以进行自定义。示例值：“快递空运 2-4 天送达” |
shippingQuotes[index].duty | 包含在 dutyTaxTotal 中的进口关税金额。该金额以美元计，不包含逗号，并包含两位小数。示例值：8.29 |
shippingQuotes[index] .dutyTaxBrokerageFee | 这是外国进口代理商处理您的进口关税和税费所收取的费用。该金额包含在 dutyTaxTotal 中。该金额以美元计，不包含逗号，并包含两位小数。示例值：5.00 |
shippingQuotes[index] .duyTaxCarrierPrepaymentFee | 这是承运人收取的费用，用于prepay 进口国的关税和税费。该金额包含在 dutyTaxTotal 中。该金额以美元计，不包含逗号，并包含两位小数。示例值：5.00 |
shippingQuotes[index] .duyTaxEnabled | 此运输报价是否允许购物者prepay 他们的进口关税和税费。如果设置为false，则应忽略 dutyTaxTotal。示例值：true 或 false |
shippingQuotes[index] .duyTaxForced | 此运输报价是否强制购物者prepay 他们的进口关税和税费。如果设置为true，则应在订单中包含 dutyTaxTotal，并向购物者解释这是该特定运输选项所需的。如果设置为false，则可以允许购物者选择是否要prepay 他们的进口关税和税费。示例值：true 或 false |
shippingQuotes[index].dutyTaxTotal | 给定运输报价的关税和税费总成本。对于给定的运输报价，关税和税费可能是可选的、不可用的或强制的。该金额不包含在 shippingTotal 中。该金额以美元计，不包含逗号，并包含两位小数。示例值：19.55 |
shippingQuotes[index] .dutyTaxUnderDeMinimis | 使用此特定运输选项的订单总额是否低于税/VAT 的最低限额和关税的最低限额。如果设置为true，则 dutyTaxTotal 将设置为0.00，并且您应告知客户他们的订单不需要支付任何进口关税或税费。此外，强制预付关税和税费，因为费用为0.00。 |
shippingQuotes[index].id | 特定运输报价的标识符；一个36字符的UUID示例值：bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a |
shippingQuotes[index].restrictedItems | 这是一个包含地图的列表，包含有关购物车中使用此特定运输报价限制的任何物品的详细信息。每个受限项目都有一个 reasonCode。原因可能与运输选项相关，也可能无关。物品限制的一些原因是由于国家进口法律、品牌限制或甚至商家创建的规则。每次购物者选择运输选项时，购物车中的物品应与运输报价的 restrictedItems 列表进行交叉引用。如果购物车中的任何物品受到限制，则应向购物者显示一条消息，并且应从订单总额中删除受限物品等。 |
shippingQuotes[index] .restrictedItems[index].cartItemId | 这是受限购物车项目请求 JSON 中的 cartItemId。您应该能够将此 cartItemId 关联回购物者购物车中的特定项目。示例值：1 或 2 或 3 |
shippingQuotes[index] .restrictedItems[index].message | 这是可能显示给购物者的消息，说明物品为何受到限制。这些消息可以由商家自定义。请联系您的 Zonos 代表以获取详细信息。示例值：“我们无法向您的国家销售 Oakley 产品。” |
shippingQuotes[index] .restrictedItems[index].reasonCode | 这是物品受到限制的原因代码。限制始终是特定于国家的，我们的原因代码使这一点显而易见。示例值： BRAND_COUNTRY 或 IMPORT_COUNTRY 或 EXPORT_COUNTRY 或 CARRIER_COUNTRY 或 MERCHANT_COUNTRY BRAND_COUNTRY 意味着您已指定不能将某个品牌销售给特定国家。IMPORT_COUNTRY 意味着进口国不允许该物品进口。EXPORT_COUNTRY 意味着出口国（通常是美国）不允许该物品出口。CARRIER_COUNTRY 意味着特定承运人不承运该物品。MERCHANT_COUNTRY 意味着您设置了一个自定义限制规则，该物品已触发。 |
shippingQuotes[index] .shippingTotal | 给定运输报价的总运费。运输报价还可能有一个 dutyTaxTotal 金额，该金额不包括在此 shippingTotal 中。该金额以美元计，不包含逗号，并包含两位小数。示例值：25.82 |
shippingQuotes[index].taxOrVat | 包含在 dutyTaxTotal 中的税或增值税金额。对于某些国家，这是税；对于其他国家，这是增值税。该金额以美元计，不包含逗号，并包含两位小数。示例值：4.35 |
Landed Cost API 遗留
了解遗留Landed Cost API 的工作原理。以下信息适用于我们的遗留Landed Cost API。请参阅我们Landed Cost API以获取最新版本。
shipping-quotes 端点接受有关您的购物者购物车的详细信息，返回包含进口关税和税费报价的运输报价，并筛选物品的限制。这些返回的运输报价基于在使用此 API 端点之前设置的运输配置文件。
我们有默认的运输配置文件供测试使用，但您需要与您的客户经理合作，以设置您的公司希望使用的实际运输配置文件和设置。