{"items":[{"type":"link","label":"ShipSaving New API","link":"/zh-hans/v2/openapi","routeSlug":"/zh-hans/v2/openapi","content":{"contentType":"overview","meta":{"name":"ShipSaving New API"},"children":[{"nodeType":"container","panels":[{"title":"Overview","titleTranslationKey":"info.title","children":[{"kind":"externallink","title":"License","titleTranslationKey":"info.license","label":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}]},{"title":"Languages","titleTranslationKey":"languages.title","children":[{"kind":"languages","options":[{"key":"curl","title":"curl","lang":"curl"},{"key":"javascript","title":"JavaScript","lang":"JavaScript"},{"key":"node","title":"Node.js","lang":"Node.js"},{"key":"python","title":"Python","lang":"Python"},{"key":"java","title":"Java","lang":"Java"},{"key":"csharp","title":"C#","lang":"C#"},{"key":"php","title":"PHP","lang":"PHP"},{"key":"go","title":"Go","lang":"Go"},{"key":"ruby","title":"Ruby","lang":"Ruby"},{"key":"r","title":"R","lang":"R"},{"key":"payload","title":"Payload","lang":"Payload"}]}]},{"title":"Servers","titleTranslationKey":"servers.title","children":[{"kind":"servers","servers":[{"url":"https://x-api.shipsaving.com"}],"mode":"default"}]}],"children":[{"nodeType":"overview-section-wrapper","children":[{"nodeType":"header","level":1,"label":"ShipSaving New API (v2)","showPageActions":true}],"sectionId":"/zh-hans/v2/openapi"}]}]}},{"type":"group","label":"认证与授权","link":"/zh-hans/v2/openapi/认证与授权","routeSlug":"/zh-hans/v2/openapi/认证与授权","items":[{"label":"获取访问令牌","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/认证与授权/getaccesstoken","routeSlug":"/zh-hans/v2/openapi/认证与授权/getaccesstoken","metadata":{"seo":{"title":"获取访问令牌","description":"使用 OAuth 2.1 Client Credentials 授权模式签发一个短期有效的访问令牌。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getAccessToken","name":"获取访问令牌","isWebhook":false,"pointer":"/paths/~1oauth2~1token/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"获取访问令牌","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"使用 OAuth 2.1 "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Client Credentials"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 授权模式签发一个"},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"短期有效的访问令牌"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"请在请求中提供以下信息："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Authorization: Basic base64(AppKey:AppSecret)"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"Content-Type: application/x-www-form-urlencoded"},"children":[]}]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"basicAuth","scopes":[],"type":"http","scheme":"basic","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"使用AppKey/AppSecret的基础认证。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/x-www-form-urlencoded"],"mediaTypeSchemas":{"application/x-www-form-urlencoded":{"schemaId":"schema_184","exampleIds":["paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"]}},"schemaId":"schema_184","exampleIds":["paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"],"pointer":"/paths/~1oauth2~1token/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/oauth2/token","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"basicAuth","type":"http","scheme":"basic"}],"scopes":[]}],"requestBody":{"application/x-www-form-urlencoded":{"schemaId":"schema_184","exampleIds":["paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"]}},"responseCodes":["200","400","401"],"pointer":"/oauth2/token","href":"认证与授权/getaccesstoken","openApiOperationId":"getAccessToken","summary":"获取访问令牌"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"schema_184","exampleIds":["paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"],"mediaTypes":["application/x-www-form-urlencoded"],"mediaTypeSchemas":{"application/x-www-form-urlencoded":{"schemaId":"schema_184","exampleIds":["paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"]}},"examples":[{}]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"已签发访问令牌"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/TokenResponse","exampleIds":["paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success"]}},"schemaId":"components/schemas/TokenResponse","exampleIds":["paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success"]},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"非法请求"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/OAuthError","exampleIds":["paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope"]}},"schemaId":"components/schemas/OAuthError","exampleIds":["paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope"]},{"code":"401","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"客户端凭证无效，或使用了已过期/无效的访问令牌。"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/OAuthError"}},"schemaId":"components/schemas/OAuthError"}],"pointer":"/paths/~1oauth2~1token/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/TokenResponse","exampleIds":["paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/TokenResponse","exampleIds":["paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success"]}}},{"code":"400","schemaId":"components/schemas/OAuthError","exampleIds":["paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/OAuthError","exampleIds":["paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType","paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope"]}}},{"code":"401","schemaId":"components/schemas/OAuthError","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/OAuthError"}}}],"examples":[]}]}]}]},"httpPath":"/oauth2/token"}],"content":{"contentType":"group","meta":{"name":"认证与授权"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"认证与授权","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/oauth2/token","summary":"获取访问令牌","prefix":{"name":"post","color":"post"},"badges":[],"link":"/认证与授权/getaccesstoken","deprecated":false}]}]}]}]}},{"type":"group","label":"运单","link":"/zh-hans/v2/openapi/运单","routeSlug":"/zh-hans/v2/openapi/运单","items":[{"label":"批量快速报价","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/batchquickrate","routeSlug":"/zh-hans/v2/openapi/运单/batchquickrate","metadata":{"seo":{"title":"批量快速报价","description":"该接口允许通过提供 from_address_data、to_address_data、package_data 和 ship_date 快速获取运单运费报价。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"batchQuickRate","name":"批量快速报价","isWebhook":false,"pointer":"/paths/~1api~1shipment~1batch~1quick_rate/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"批量快速报价","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口允许通过提供 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"from_address_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"to_address_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"package_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 和 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ship_date"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 快速获取运单运费报价。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"每次 API 调用最多可包含10个独立的运费报价请求。"},"children":[]}]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"此前，该接口仅返回USPS Ground Advantage的运费报价。现在，你可以通过 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipment_rate_carrier_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 字段可选地指定额外的承运商及服务等级。有关该参数的详细使用说明，请参见请求schema。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若未提供 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipment_rate_carrier_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：系统将仅返回USPS Ground Advantage的运费报价（默认行为）。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若提供了 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipment_rate_carrier_data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：系统将仅返回所指定的承运商及服务等级对应的运费报价。支持在单个请求中提交多个承运商与服务等级的组合。"},"children":[]}]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BatchQuickRateRequest"}},"schemaId":"components/schemas/BatchQuickRateRequest","pointer":"/paths/~1api~1shipment~1batch~1quick_rate/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/batch/quick_rate","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/BatchQuickRateRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/batch/quick_rate","href":"运单/batchquickrate","openApiOperationId":"batchQuickRate","summary":"批量快速报价"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/BatchQuickRateRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BatchQuickRateRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/BatchQuickRateResponse"}},"schemaId":"components/schemas/BatchQuickRateResponse"}],"pointer":"/paths/~1api~1shipment~1batch~1quick_rate/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/BatchQuickRateResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/BatchQuickRateResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/batch/quick_rate"},{"label":"查询报价","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/getrates","routeSlug":"/zh-hans/v2/openapi/运单/getrates","metadata":{"seo":{"title":"查询报价","description":"获取你账户下所有启用的承运商及服务等级的运费报价，并可按指定的承运商和服务等级进行可选筛选。返回结果将按照最快、最便宜等条件进行排序，同时包含适用的错误信息（如有）。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getRates","name":"查询报价","isWebhook":false,"pointer":"/paths/~1api~1shipment~1get_rates/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"查询报价","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"获取你账户下所有启用的承运商及服务等级的运费报价，并可按指定的承运商和服务等级进行可选筛选。返回结果将按照最快、最便宜等条件进行排序，同时包含适用的错误信息（如有）。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ShipmentRateRequest"}},"schemaId":"components/schemas/ShipmentRateRequest","pointer":"/paths/~1api~1shipment~1get_rates/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/get_rates","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/ShipmentRateRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/get_rates","href":"运单/getrates","openApiOperationId":"getRates","summary":"查询报价"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/ShipmentRateRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ShipmentRateRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/GetRatesResponse"}},"schemaId":"components/schemas/GetRatesResponse"}],"pointer":"/paths/~1api~1shipment~1get_rates/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/GetRatesResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/GetRatesResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/get_rates"},{"label":"购买运单","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/createandpay","routeSlug":"/zh-hans/v2/openapi/运单/createandpay","metadata":{"seo":{"title":"购买运单","description":"使用先前 get_rates 接口返回的 rate_id 创建并支付运单面单。该接口还支持在同一次请求中购买运单保险（保险不可单独购买）。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"createAndPay","name":"购买运单","isWebhook":false,"pointer":"/paths/~1api~1shipment~1create_and_pay/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"购买运单","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"使用先前 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"get_rates"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 接口返回的 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"rate_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 创建并支付运单面单。该接口还支持在同一次请求中购买运单保险（保险不可单独购买）。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为防止因网络波动或重试导致的重复购买，API会检查在指定的 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"platform_uk_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 下是否已存在对应的运单。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若发现已存在相关运单，则直接返回该运单信息，并将响应中的 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"duplicate_label"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 字段设置为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若不存在相关运单，则按正常流程创建新的运单，且 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"duplicate_label"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 字段为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"false"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BuyLabelRequest"}},"schemaId":"components/schemas/BuyLabelRequest","pointer":"/paths/~1api~1shipment~1create_and_pay/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/create_and_pay","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/BuyLabelRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/create_and_pay","href":"运单/createandpay","openApiOperationId":"createAndPay","summary":"购买运单"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/BuyLabelRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BuyLabelRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentPurchaseResponse"}},"schemaId":"components/schemas/ShipmentPurchaseResponse"}],"pointer":"/paths/~1api~1shipment~1create_and_pay/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/ShipmentPurchaseResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentPurchaseResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/create_and_pay"},{"label":"直接购买运单","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/directbuy","routeSlug":"/zh-hans/v2/openapi/运单/directbuy","metadata":{"seo":{"title":"直接购买运单","description":"无需单独调用 get_rates 接口，即可一步完成运单面单的创建与购买。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"directBuy","name":"直接购买运单","isWebhook":false,"pointer":"/paths/~1api~1shipment~1direct_buy/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"直接购买运单","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"无需单独调用 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"get_rates"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 接口，即可一步完成运单面单的创建与购买。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口当前支持 USPS Returns 服务类型，完整的支持列表请参阅附录（Appendix）。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为防止因网络波动或重试导致的重复购买，API会检查在指定的 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"platform_uk_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 下是否已存在对应的运单。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若发现已存在相关运单，则直接返回该运单信息，并将响应中的 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"duplicate_label"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 字段设置为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若不存在相关运单，则按正常流程创建新的运单，且 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"duplicate_label"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 字段为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"false"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/DirectBuyShipmentRequest"}},"schemaId":"components/schemas/DirectBuyShipmentRequest","pointer":"/paths/~1api~1shipment~1direct_buy/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/direct_buy","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/DirectBuyShipmentRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/direct_buy","href":"运单/directbuy","openApiOperationId":"directBuy","summary":"直接购买运单"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/DirectBuyShipmentRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/DirectBuyShipmentRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentPurchaseResponse"}},"schemaId":"components/schemas/ShipmentPurchaseResponse"}],"pointer":"/paths/~1api~1shipment~1direct_buy/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/ShipmentPurchaseResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ShipmentPurchaseResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/direct_buy"},{"label":"作废运单","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/voidlabel","routeSlug":"/zh-hans/v2/openapi/运单/voidlabel","metadata":{"seo":{"title":"作废运单","description":"该接口支持通过 以下任一方式 作废运单面单：shipment_no 或 platform_uk_id。仅需提供其中一个参数即可唯一标识一条运单。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"voidLabel","name":"作废运单","isWebhook":false,"pointer":"/paths/~1api~1shipment~1void_label/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"作废运单","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口支持通过 "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"以下任一方式"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 作废运单面单："},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipment_no"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 或 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"platform_uk_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。仅需提供其中一个参数即可唯一标识一条运单。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ShipmentVoidRequest"}},"schemaId":"components/schemas/ShipmentVoidRequest","pointer":"/paths/~1api~1shipment~1void_label/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/void_label","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/ShipmentVoidRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/void_label","href":"运单/voidlabel","openApiOperationId":"voidLabel","summary":"作废运单"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/ShipmentVoidRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ShipmentVoidRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CommonServiceResponse"}},"schemaId":"components/schemas/CommonServiceResponse"}],"pointer":"/paths/~1api~1shipment~1void_label/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/CommonServiceResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CommonServiceResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/void_label"},{"label":"查询保险报价","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/运单/paths/~1api~1shipment~1insurance~1rate/get","routeSlug":"/zh-hans/v2/openapi/运单/paths/~1api~1shipment~1insurance~1rate/get","metadata":{"seo":{"title":"查询保险报价","description":"查询保险报价"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"name":"查询保险报价","isWebhook":false,"pointer":"/paths/~1api~1shipment~1insurance~1rate/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"查询保险报价","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"declared_value","in":"query","schemaId":"schema_185","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"运单保险的申报金额（美元）"},"children":[]}]}]}],"required":true,"example":200},{"name":"service_level","in":"query","schemaId":"schema_186","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"保险报价请求必须指定 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"service_level"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。不同的服务等级对应不同的定价。"},"children":[]}]}]}],"required":true,"example":"USPS_GROUND_ADVANTAGE"}],"pointer":"/paths/~1api~1shipment~1insurance~1rate/get/parameters"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/shipment/insurance/rate","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[{"name":"declared_value","in":"query","required":true,"example":200,"schemaId":"schema_185"},{"name":"service_level","in":"query","required":true,"example":"USPS_GROUND_ADVANTAGE","schemaId":"schema_186"}],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"responseCodes":["200"],"pointer":"/api/shipment/insurance/rate","href":"运单/paths/~1api~1shipment~1insurance~1rate/get","summary":"查询保险报价"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/InsuranceRateResponse"}},"schemaId":"components/schemas/InsuranceRateResponse"}],"pointer":"/paths/~1api~1shipment~1insurance~1rate/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/InsuranceRateResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/InsuranceRateResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/insurance/rate"}],"content":{"contentType":"group","meta":{"name":"运单"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"运单","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/shipment/batch/quick_rate","summary":"批量快速报价","prefix":{"name":"post","color":"post"},"badges":[],"link":"/运单/batchquickrate","deprecated":false},{"title":"/api/shipment/get_rates","summary":"查询报价","prefix":{"name":"post","color":"post"},"badges":[],"link":"/运单/getrates","deprecated":false},{"title":"/api/shipment/create_and_pay","summary":"购买运单","prefix":{"name":"post","color":"post"},"badges":[],"link":"/运单/createandpay","deprecated":false},{"title":"/api/shipment/direct_buy","summary":"直接购买运单","prefix":{"name":"post","color":"post"},"badges":[],"link":"/运单/directbuy","deprecated":false},{"title":"/api/shipment/void_label","summary":"作废运单","prefix":{"name":"post","color":"post"},"badges":[],"link":"/运单/voidlabel","deprecated":false},{"title":"/api/shipment/insurance/rate","summary":"查询保险报价","prefix":{"name":"get","color":"get"},"badges":[],"link":"/运单/paths/~1api~1shipment~1insurance~1rate/get","deprecated":false}]}]}]}]}},{"type":"group","label":"物流轨迹","link":"/zh-hans/v2/openapi/物流轨迹","routeSlug":"/zh-hans/v2/openapi/物流轨迹","items":[{"label":"通过运单号查询物流状态（包含UTC偏移量）","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/物流轨迹/getshipmenttrackingwithutcoffset","routeSlug":"/zh-hans/v2/openapi/物流轨迹/getshipmenttrackingwithutcoffset","metadata":{"seo":{"title":"通过运单号查询物流状态（包含UTC偏移量）","description":"获取承运商上报的当前运单追踪事件、首次扫描事件以及完整的物流追踪事件历史。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getShipmentTrackingWithUtcOffset","name":"通过运单号查询物流状态（包含UTC偏移量）","isWebhook":false,"pointer":"/paths/~1api~1shipment~1direct~1tracking_by_tracking_no/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"通过运单号查询物流状态（包含UTC偏移量）","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"获取承运商上报的当前运单追踪事件、首次扫描事件以及完整的物流追踪事件历史。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口返回的所有物流事件时间戳均采用包含UTC偏移量的ISO 8601格式，"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"以便客户端在不同时区环境下准确解析和还原事件发生的本地时间。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"tracking_no","in":"query","schemaId":"schema_186","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"运单追踪号"},"children":[]}]}]}],"required":true,"example":940013620842281000000},{"name":"carrier_code","in":"query","schemaId":"schema_187","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商代码"},"children":[]}]}]}],"required":true}],"pointer":"/paths/~1api~1shipment~1direct~1tracking_by_tracking_no/get/parameters"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/shipment/direct/tracking_by_tracking_no","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[{"name":"tracking_no","in":"query","required":true,"example":940013620842281000000,"schemaId":"schema_186"},{"name":"carrier_code","in":"query","required":true,"example":"USPS","schemaId":"schema_187"}],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"responseCodes":["200"],"pointer":"/api/shipment/direct/tracking_by_tracking_no","href":"物流轨迹/getshipmenttrackingwithutcoffset","openApiOperationId":"getShipmentTrackingWithUtcOffset","summary":"通过运单号查询物流状态（包含UTC偏移量）"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"请求成功"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/TrackingStatusWithUtcOffsetResponse"}},"schemaId":"components/schemas/TrackingStatusWithUtcOffsetResponse"}],"pointer":"/paths/~1api~1shipment~1direct~1tracking_by_tracking_no/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/TrackingStatusWithUtcOffsetResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/TrackingStatusWithUtcOffsetResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/direct/tracking_by_tracking_no"},{"label":"提交 Proof of Delivery（签收凭证）","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/物流轨迹/submitpod","routeSlug":"/zh-hans/v2/openapi/物流轨迹/submitpod","metadata":{"seo":{"title":"提交 Proof of Delivery（签收凭证）","description":"为已送达的运单提交 Proof of Delivery（签收凭证）请求。目前仅支持 USPS（carrier_code = USPS），其他承运商会返回业务错误。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"submitPod","name":"提交 Proof of Delivery（签收凭证）","isWebhook":false,"pointer":"/paths/~1api~1shipment~1submit_pod/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"提交 Proof of Delivery（签收凭证）","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为已送达的运单提交 Proof of Delivery（签收凭证）请求。目前仅支持 USPS（"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_code = USPS"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"），其他承运商会返回业务错误。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/PodSubmitRequest"}},"schemaId":"components/schemas/PodSubmitRequest","pointer":"/paths/~1api~1shipment~1submit_pod/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/submit_pod","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/PodSubmitRequest"}},"responseCodes":["200"],"pointer":"/api/shipment/submit_pod","href":"物流轨迹/submitpod","openApiOperationId":"submitPod","summary":"提交 Proof of Delivery（签收凭证）"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/PodSubmitRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/PodSubmitRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"成功"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/PodSubmitResponseEnvelope"}},"schemaId":"components/schemas/PodSubmitResponseEnvelope"}],"pointer":"/paths/~1api~1shipment~1submit_pod/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/PodSubmitResponseEnvelope","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/PodSubmitResponseEnvelope"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/submit_pod"}],"content":{"contentType":"group","meta":{"name":"物流轨迹"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"物流轨迹","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/shipment/direct/tracking_by_tracking_no","summary":"通过运单号查询物流状态（包含UTC偏移量）","prefix":{"name":"get","color":"get"},"badges":[],"link":"/物流轨迹/getshipmenttrackingwithutcoffset","deprecated":false},{"title":"/api/shipment/submit_pod","summary":"提交 Proof of Delivery（签收凭证）","prefix":{"name":"post","color":"post"},"badges":[],"link":"/物流轨迹/submitpod","deprecated":false}]}]}]}]}},{"type":"group","label":"预约取件","link":"/zh-hans/v2/openapi/预约取件","routeSlug":"/zh-hans/v2/openapi/预约取件","items":[{"label":"预约取件","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/预约取件/addpickupbyshipment","routeSlug":"/zh-hans/v2/openapi/预约取件/addpickupbyshipment","metadata":{"seo":{"title":"预约取件","description":"使用已有的发货信息创建 USPS 承运商取件请求。该接口会安排 USPS 快递员在下一个 USPS 投递日上门取走符合条件的包裹。该接口可能返回的全部错误码，请参见附录 — 预约取件错误码。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"addPickupByShipment","name":"预约取件","isWebhook":false,"pointer":"/paths/~1api~1shipment~1pickup~1add/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"预约取件","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"使用已有的发货信息创建 USPS 承运商取件请求。该接口会安排 USPS 快递员在"},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"下一个 USPS 投递日"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"上门取走符合条件的包裹。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口可能返回的全部错误码，请参见"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://docs.shipsaving.com/zh-hans/v2/appendix#post-apishipmentpickupadd"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"附录 — 预约取件错误码"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/AddPickUpByShipmentRequest"}},"schemaId":"components/schemas/AddPickUpByShipmentRequest","pointer":"/paths/~1api~1shipment~1pickup~1add/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/pickup/add","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/AddPickUpByShipmentRequest"}},"responseCodes":["200","400"],"pointer":"/api/shipment/pickup/add","href":"预约取件/addpickupbyshipment","openApiOperationId":"addPickupByShipment","summary":"预约取件"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/AddPickUpByShipmentRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/AddPickUpByShipmentRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_188"}},"schemaId":"schema_188"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"请求错误"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress"]}},"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress"]}],"pointer":"/paths/~1api~1shipment~1pickup~1add/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"schema_188","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_188"}}},{"code":"400","schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields","paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress"]}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/pickup/add"},{"label":"取消预约取件","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/预约取件/cancelpickup","routeSlug":"/zh-hans/v2/openapi/预约取件/cancelpickup","metadata":{"seo":{"title":"取消预约取件","description":"取消先前已预约的承运商取件。取件一旦被取消，将无法再次更新或取消。该接口除 pickup_no 外不需要提供任何其他参数。取消成功后，取件状态将变更为 CANCELED。该接口可能返回的全部错误码，请参见附录 — 预约取件错误码。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"cancelPickup","name":"取消预约取件","isWebhook":false,"pointer":"/paths/~1api~1shipment~1pickup~1cancel/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"取消预约取件","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"取消先前已预约的承运商取件。取件一旦被取消，将无法再次更新或取消。该接口除 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"pickup_no"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 外不需要提供任何其他参数。取消成功后，取件状态将变更为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"CANCELED"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该接口可能返回的全部错误码，请参见"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://docs.shipsaving.com/zh-hans/v2/appendix#post-apishipmentpickupcancel"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"附录 — 预约取件错误码"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/CancelPickupRequest"}},"schemaId":"components/schemas/CancelPickupRequest","pointer":"/paths/~1api~1shipment~1pickup~1cancel/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/shipment/pickup/cancel","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/CancelPickupRequest"}},"responseCodes":["200","400"],"pointer":"/api/shipment/pickup/cancel","href":"预约取件/cancelpickup","openApiOperationId":"cancelPickup","summary":"取消预约取件"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/CancelPickupRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/CancelPickupRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CommonServiceResponse"}},"schemaId":"components/schemas/CommonServiceResponse"},{"code":"400","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"请求错误"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled"]}},"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled"]}],"pointer":"/paths/~1api~1shipment~1pickup~1cancel/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/CommonServiceResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/CommonServiceResponse"}}},{"code":"400","schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled"],"mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"schema_189","exampleIds":["paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled"]}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/pickup/cancel"},{"label":"查询历史预约取件记录","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/预约取件/getpickuplist","routeSlug":"/zh-hans/v2/openapi/预约取件/getpickuplist","metadata":{"seo":{"title":"查询历史预约取件记录","description":"获取系统中已创建的取件记录分页列表。该接口支持按USPS确认号、取件状态以及承运商代码等条件进行可选筛选。分页参数（page和page_size）用于控制返回数据集的大小，order_by参数用于指定结果的排序方式。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getPickupList","name":"查询历史预约取件记录","isWebhook":false,"pointer":"/paths/~1api~1shipment~1pickup~1list/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"查询历史预约取件记录","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"获取系统中已创建的取件记录分页列表。该接口支持按USPS确认号、取件状态以及承运商代码等条件进行可选筛选。分页参数（"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"page"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"和"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"page_size"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"）用于控制返回数据集的大小，"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"order_by"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"参数用于指定结果的排序方式。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"query","label":"Query","labelTranslationKey":"query","parameters":[{"name":"confirmation_number","in":"query","schemaId":"schema_190"},{"name":"status","in":"query","schemaId":"schema_191","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"取件状态筛选条件"},"children":[]}]}]}]},{"name":"carrier_code","in":"query","schemaId":"schema_192"},{"name":"page","in":"query","schemaId":"schema_193","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"分页结果的页码（从1开始）"},"children":[]}]}]}]},{"name":"page_size","in":"query","schemaId":"schema_194","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"每页返回的结果数量"},"children":[]}]}]}]},{"name":"order_by","in":"query","schemaId":"schema_195","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于控制时间排序的标志："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：按时间正序排列（最早→最新）"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"false"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：按时间倒序排列（最新→最早）"},"children":[]}]}]}]}],"required":true}],"pointer":"/paths/~1api~1shipment~1pickup~1list/get/parameters"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/shipment/pickup/list","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[{"name":"confirmation_number","in":"query","required":false,"example":"WTC65384000","schemaId":"components/schemas/PickUpConfirmationNo"},{"name":"status","in":"query","required":false,"schemaId":"schema_191"},{"name":"carrier_code","in":"query","required":false,"example":"USPS","schemaId":"components/schemas/PickUpCarrierCodeEnum"},{"name":"page","in":"query","required":false,"schemaId":"schema_193"},{"name":"page_size","in":"query","required":false,"schemaId":"schema_194"},{"name":"order_by","in":"query","required":true,"schemaId":"schema_195"}],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"responseCodes":["200"],"pointer":"/api/shipment/pickup/list","href":"预约取件/getpickuplist","openApiOperationId":"getPickupList","summary":"查询历史预约取件记录"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/QueryPickupResponse"}},"schemaId":"components/schemas/QueryPickupResponse"}],"pointer":"/paths/~1api~1shipment~1pickup~1list/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/QueryPickupResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/QueryPickupResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/pickup/list"},{"label":"查询包裹位置","deprecated":false,"httpVerb":"get","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/预约取件/getpackagelocation","routeSlug":"/zh-hans/v2/openapi/预约取件/getpackagelocation","metadata":{"seo":{"title":"查询包裹位置","description":"返回有效的包裹放置位置枚举值列表。这些枚举值用于指示在预约取件时，包裹将被放置在取件地址的具体位置，供USPS邮政投递员上门取件。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"getPackageLocation","name":"查询包裹位置","isWebhook":false,"pointer":"/paths/~1api~1shipment~1pickup~1package~1location~1list/get","hasSamples":false},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"查询包裹位置","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"返回有效的包裹放置位置枚举值列表。这些枚举值用于指示在预约取件时，包裹将被放置在取件地址的具体位置，供USPS邮政投递员上门取件。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"GET","path":"/api/shipment/pickup/package/location/list","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"responseCodes":["200"],"pointer":"/api/shipment/pickup/package/location/list","href":"预约取件/getpackagelocation","openApiOperationId":"getPackageLocation","summary":"查询包裹位置"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"OK","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/QueryPackageLocationResponse"}},"schemaId":"components/schemas/QueryPackageLocationResponse"}],"pointer":"/paths/~1api~1shipment~1pickup~1package~1location~1list/get/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/QueryPackageLocationResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/QueryPackageLocationResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/shipment/pickup/package/location/list"}],"content":{"contentType":"group","meta":{"name":"预约取件"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"预约取件","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/shipment/pickup/add","summary":"预约取件","prefix":{"name":"post","color":"post"},"badges":[],"link":"/预约取件/addpickupbyshipment","deprecated":false},{"title":"/api/shipment/pickup/cancel","summary":"取消预约取件","prefix":{"name":"post","color":"post"},"badges":[],"link":"/预约取件/cancelpickup","deprecated":false},{"title":"/api/shipment/pickup/list","summary":"查询历史预约取件记录","prefix":{"name":"get","color":"get"},"badges":[],"link":"/预约取件/getpickuplist","deprecated":false},{"title":"/api/shipment/pickup/package/location/list","summary":"查询包裹位置","prefix":{"name":"get","color":"get"},"badges":[],"link":"/预约取件/getpackagelocation","deprecated":false}]}]}]}]}},{"type":"group","label":"地址验证","link":"/zh-hans/v2/openapi/地址验证","routeSlug":"/zh-hans/v2/openapi/地址验证","items":[{"label":"地址验证","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/地址验证/validateaddress","routeSlug":"/zh-hans/v2/openapi/地址验证/validateaddress","metadata":{"seo":{"title":"地址验证","description":"地址校验接口用于校验美国国内地址的有效性，并按照 USPS® 地址规范返回标准化后的地址组成部分。该API有助于提升投递准确率、减少无法投递的包裹，并为物流与运费计算提供一致且可靠的地址基础。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"validateAddress","name":"地址验证","isWebhook":false,"pointer":"/paths/~1api~1address~1validate/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"地址验证","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址校验接口用于校验"},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"美国国内地址"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"的有效性，并按照 "},"children":[]},{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"USPS® 地址规范"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"返回标准化后的地址组成部分。该API有助于提升投递准确率、减少无法投递的包裹，并为物流与运费计算提供一致且可靠的地址基础。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BasicAddress"}},"schemaId":"components/schemas/BasicAddress","pointer":"/paths/~1api~1address~1validate/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/address/validate","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/BasicAddress"}},"responseCodes":["200"],"pointer":"/api/address/validate","href":"地址验证/validateaddress","openApiOperationId":"validateAddress","summary":"地址验证"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/BasicAddress","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/BasicAddress"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":"ok","mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/AddressValidateResponse"}},"schemaId":"components/schemas/AddressValidateResponse"}],"pointer":"/paths/~1api~1address~1validate/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/AddressValidateResponse","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/AddressValidateResponse"}}}],"examples":[]}]}]}]},"httpPath":"/api/address/validate"}],"content":{"contentType":"group","meta":{"name":"地址验证"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"地址验证","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/address/validate","summary":"地址验证","prefix":{"name":"post","color":"post"},"badges":[],"link":"/地址验证/validateaddress","deprecated":false}]}]}]}]}},{"type":"group","label":"SCAN Form","link":"/zh-hans/v2/openapi/scan-form","routeSlug":"/zh-hans/v2/openapi/scan-form","items":[{"label":"创建 SCAN Form","deprecated":false,"httpVerb":"post","isAdditionalOperation":false,"isWebhook":false,"type":"link","link":"/zh-hans/v2/openapi/scan-form/createscanform","routeSlug":"/zh-hans/v2/openapi/scan-form/createscanform","metadata":{"seo":{"title":"创建 SCAN Form","description":"为一组已购买的运单创建 USPS SCAN Form（PS Form 5630），并返回生成的清单 PDF 的 URL。SCAN Form 是一张把多个运单合并到一起的清单条码，承运商在揽收时扫描这一张即可一次性接收整批运单。"}},"content":{"contentType":"item","itemVariant":"httpItem","meta":{"sourceId":"createScanForm","name":"创建 SCAN Form","isWebhook":false,"pointer":"/paths/~1api~1scan_form~1create_scan_form/post","hasSamples":true},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"创建 SCAN Form","isWebhook":false,"showPageActions":true}],"panels":[]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Request","labelTranslationKey":"request","deepLinkSuffix":"request"},{"nodeType":"markdoc","content":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为一组已购买的运单创建 USPS SCAN Form（PS Form 5630），并返回生成的清单 PDF 的 URL。SCAN Form 是一张把多个运单合并到一起的清单条码，承运商在揽收时扫描这一张即可一次性接收整批运单。"},"children":[]}]}]}]},{"nodeType":"security","requirements":[{"schemes":[{"name":"BearerAuth","scopes":[],"type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]}]}]},{"nodeType":"item-content","variant":"body","label":"Request Body","labelTranslationKey":"body","required":true,"mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ScanFormCreateRequest"}},"schemaId":"components/schemas/ScanFormCreateRequest","pointer":"/paths/~1api~1scan_form~1create_scan_form/post/requestBody"}],"panels":[{"children":[{"kind":"code-sample","source":{"kind":"code-sample","operationType":"http","method":"POST","path":"/api/scan_form/create_scan_form","servers":[{"url":"https://x-api.shipsaving.com"}],"parameters":{"path":[],"query":[],"querystring":[],"header":[],"cookie":[]},"security":[{"schemes":[{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT"}],"scopes":[]}],"requestBody":{"application/json":{"schemaId":"components/schemas/ScanFormCreateRequest"}},"responseCodes":["200"],"pointer":"/api/scan_form/create_scan_form","href":"scan-form/createscanform","openApiOperationId":"createScanForm","summary":"创建 SCAN Form"},"isWebhook":false,"hideReplay":false,"servers":[{"url":"https://x-api.shipsaving.com"}],"schemaId":"components/schemas/ScanFormCreateRequest","mediaTypes":["application/json"],"mediaTypeSchemas":{"application/json":{"schemaId":"components/schemas/ScanFormCreateRequest"}},"examples":[]}]}]},{"nodeType":"container","children":[{"nodeType":"header","level":4,"label":"Responses","labelTranslationKey":"responses","deepLinkSuffix":"responses"},{"nodeType":"item-content","variant":"responses","responses":[{"code":"200","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"成功"},"children":[]}]}]}],"mediaType":"application/json","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ScanFormCreateResponseEnvelope"}},"schemaId":"components/schemas/ScanFormCreateResponseEnvelope"}],"pointer":"/paths/~1api~1scan_form~1create_scan_form/post/responses"}],"panels":[{"children":[{"kind":"response","headerTitle":"Response","responseCodes":[{"code":"200","schemaId":"components/schemas/ScanFormCreateResponseEnvelope","mediaTypes":["application/json"],"mediaTypeContent":{"application/json":{"schemaId":"components/schemas/ScanFormCreateResponseEnvelope"}}}],"examples":[]}]}]}]},"httpPath":"/api/scan_form/create_scan_form"}],"content":{"contentType":"group","meta":{"name":"SCAN Form"},"children":[{"nodeType":"container","children":[{"nodeType":"header","level":2,"label":"SCAN Form","showPageActions":true}],"panels":[{"children":[{"kind":"group-items","title":"Operations","titleTranslationKey":"operations","items":[{"title":"/api/scan_form/create_scan_form","summary":"创建 SCAN Form","prefix":{"name":"post","color":"post"},"badges":[],"link":"/scan-form/createscanform","deprecated":false}]}]}]}]}}],"store":{"schemaStore":{"components/schemas/TokenResponse":{"id":"components/schemas/TokenResponse","kind":"json-schema","title":"TokenResponse","data":{"type":"object","properties":{"access_token":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"JWT访问令牌。"},"children":[]}]}]}]},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","format":"int32","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"过期时间（秒，默认1800）。"},"children":[]}]}]}]},"scope":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"已授予的作用域（如有返回）。"},"children":[]}]}]}]}}}},"components/schemas/OAuthError":{"id":"components/schemas/OAuthError","kind":"json-schema","title":"OAuthError","data":{"type":"object","properties":{"error":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"OAuth 2.0错误代码"},"children":[]}]}]}],"example":"invalid_request"},"error_description":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"人类可读的说明"},"children":[]}]}]}]},"error_uri":{"type":"string"}}}},"components/schemas/RequestUniqueId":{"id":"components/schemas/RequestUniqueId","kind":"json-schema","title":"RequestUniqueId","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"由请求方生成的唯一标识，用于标记批量请求中的单个运费报价请求。该值将在对应的响应中原样返回，以确保请求与响应之间的一一对应关系。"},"children":[]}]}]}],"example":"unique_uuid_001"}},"components/schemas/BasicAddress":{"id":"components/schemas/BasicAddress","kind":"json-schema","title":"BasicAddress","data":{"required":["street","city","state","country","zip_code"],"type":"object","properties":{"street":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"建筑物门牌号及其所在的道路或街道名称。"},"children":[]}]}]}],"example":"xxxx Olive Street"},"street2":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址的次级单元标识，例如公寓号（APT）或套房号（STE），用于明确建筑物内的具体位置。"},"children":[]}]}]}],"example":"STE XXX"},"city":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址所属的城市名称。"},"children":[]}]}]}],"example":"Los Angeles"},"state":{"type":"string","description":[{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"对于美国地址，该字段必须为有效的两位州代码（例如“CA”表示加利福尼亚州，“NY”表示纽约州）。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"对于非美国地址，该字段的取值不作限制。"},"children":[]}]}]}]}],"example":"CA"},"zip_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址对应的邮政编码。"},"children":[]}]}]}],"example":"021XX"},"country":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"国家两位字母代码。该字段的值应为"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 two-digit code"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"两位国家代码。"},"children":[]}]}]}],"example":"US"}}}},"components/schemas/AddressFrom":{"id":"components/schemas/AddressFrom","kind":"json-schema","title":"AddressFrom","data":{"allOf":[{"type":"object","required":["first_name","last_name","zip_code"],"properties":{"first_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的名字。对于批量快速运费报价API，该参数为可选项。"},"children":[]}]}]}],"example":"Alice"},"last_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的姓氏。对于批量快速运费报价API，该参数为可选项。"},"children":[]}]}]}],"example":"Green"},"company_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的公司或商户名称。"},"children":[]}]}]}],"example":"ShipSaving"},"phone":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"发件人或收件人的电话号码。国际运单为必填项。强烈建议为所有运单提供电话号码，以确保准确投递并在需要时便于承运商联系。"},"children":[]}]}]}],"example":"1234567890"},"email":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"发件人或收件人的电子邮箱地址。承运商可能会使用该邮箱发送投递通知或用于问题处理。"},"children":[]}]}]}],"example":"it@shipsaving.com"}}},{"$ref":"#/components/schemas/BasicAddress"}]}},"components/schemas/AddressTo":{"id":"components/schemas/AddressTo","kind":"json-schema","title":"AddressTo","data":{"allOf":[{"$ref":"#/components/schemas/AddressFrom"},{"type":"object","required":["address_type"],"properties":{"address_type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示目的地地址是住宅地址还是商业地址。该标志用于确定承运商特定的附加费用（例如UPS住宅投递附加费）。"},"children":[]}]}]}],"example":"residential","enum":["residential","commercial"]}}}]}},"components/schemas/CarrierPackageCodeEnum":{"id":"components/schemas/CarrierPackageCodeEnum","kind":"json-schema","title":"CarrierPackageCodeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商包装代码标识符。请参阅 附录 - 承运商包装代码，以了解 ShipSaving 新版 API（v2）中支持的取值。"},"children":[]}]}]}],"example":"USPS_SMALL_FLAT_RATE_BOX","enum":["USPS_LETTER","USPS_LARGE_ENVELOPE_OR_FLAT","USPS_THICK_ENVELOPE","USPS_SMALL_FLAT_RATE_BOX","USPS_MEDIUM_FLAT_RATE_BOX","USPS_LARGE_FLAT_RATE_BOX","USPS_FLAT_RATE_ENVELOPE","USPS_PADDED_FLAT_RATE_ENVELOPE","USPS_LEGAL_FLAT_RATE_ENVELOPE","UPS_LETTER","UPS_25KG_BOX","UPS_10KG_BOX","UPS_TUBE","UPS_PAK","UPS_EXPRESS_BOX_SMALL","UPS_EXPRESS_BOX_MEDIUM","UPS_EXPRESS_BOX_LARGE","FEDEX_ENVELOPE","FEDEX_PAK","FEDEX_TUBE","FEDEX_EXTRA_SMALL_BOX","FEDEX_SMALL_BOX","FEDEX_MEDIUM_BOX","FEDEX_LARGE_BOX","FEDEX_EXTRA_LARGE_BOX","FEDEX_BOX","FEDEX_10KG_BOX","FEDEX_25KG_BOX","UPS_CANADA_LETTER","UPS_CANADA_25KG_BOX","UPS_CANADA_10KG_BOX","UPS_CANADA_TUBE","UPS_CANADA_PAK","UPS_CANADA_EXPRESS_BOX_SMALL","UPS_CANADA_EXPRESS_BOX_MEDIUM","UPS_CANADA_EXPRESS_BOX_LARGE","UPS_CANADA_EXPRESS_BOX"]}},"components/schemas/DimensionUnitEnum":{"id":"components/schemas/DimensionUnitEnum","kind":"json-schema","title":"DimensionUnitEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"所选尺寸单位。"},"children":[]}]}]}],"example":"in","enum":["in","cm"]}},"components/schemas/WeightUnitEnum":{"id":"components/schemas/WeightUnitEnum","kind":"json-schema","title":"WeightUnitEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"所选择的重量单位。"},"children":[]}]}]}],"example":"lb","enum":["lb","oz","kg","g"]}},"components/schemas/ShipmentPackageData":{"id":"components/schemas/ShipmentPackageData","kind":"json-schema","title":"ShipmentPackageData","data":{"type":"object","properties":{"type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于定义所寄送包裹的类型。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"my_package"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：当需要指定自定义包裹尺寸时使用。需要提供"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"width"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"length"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"height"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"dimension_unit"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"weight"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"和"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"weight_unit"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"predefined"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：当选择承运商预定义的包裹类型时使用。仅需提供"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_package_code"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"和重量相关字段；尺寸字段将被忽略。"},"children":[]}]}]}]}],"example":"my_package","enum":["my_package","predefined"]},"length":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹在所选单位下的长度。"},"children":[]}]}]}],"example":10},"width":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹在所选单位下的宽度。"},"children":[]}]}]}],"example":10},"height":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹在所选单位下的高度。"},"children":[]}]}]}],"example":10},"weight":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹在所选单位下的重量。"},"children":[]}]}]}],"example":10},"carrier_package_code":{"$ref":"#/components/schemas/CarrierPackageCodeEnum"},"dimension_unit":{"$ref":"#/components/schemas/DimensionUnitEnum"},"weight_unit":{"$ref":"#/components/schemas/WeightUnitEnum"}}}},"components/schemas/SignatureTypeEnum":{"id":"components/schemas/SignatureTypeEnum","kind":"json-schema","title":"SignatureTypeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"请求投递签名确认。取值："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"signature"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" = 签名确认；"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"adult_signature"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" = 成人签名；"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_signature_restricted"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" = 限制投递的签名确认"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"（仅投递给指定收件人本人或其授权代理人）；"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"usps_adult_signature_restricted"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" = 限制投递的成人签名（需 21 岁及以上）"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"（收件人须为 21 岁及以上且为指定本人）。"},"children":[]}]}]}]}],"enum":["signature","adult_signature","usps_signature_restricted","usps_adult_signature_restricted"]}},"components/schemas/CustomPrint":{"id":"components/schemas/CustomPrint","kind":"json-schema","title":"CustomPrint","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"面单上的自定义打印内容。若面单本身支持自定义打印，该字段内容将被打印在面单上。"},"children":[]}]}]}],"example":"Please put the package in the locker."}},"components/schemas/ShipmentOptionData":{"id":"components/schemas/ShipmentOptionData","kind":"json-schema","title":"ShipmentOptionData","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"附加运输选项。"},"children":[]}]}]}],"properties":{"signature":{"$ref":"#/components/schemas/SignatureTypeEnum"},"custom_text_on_label_1":{"$ref":"#/components/schemas/CustomPrint"},"custom_text_on_label_2":{"$ref":"#/components/schemas/CustomPrint"},"hazardous_materials":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示该运单是否包含危险品或有害物质（仅适用于USPS Ground Advantage服务）。"},"children":[]}]}]}],"example":true},"is_lithium_battery":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示包裹是否包含锂电池。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"注意"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当该字段为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时，"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"hazardous_materials"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"将被强制覆盖为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"寄往或寄自美国外岛地区（如关岛、波多黎各）的运单，通常需要将该字段设为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，才能寄递锂电池。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"寄递前请查阅USPS关于锂电池的寄递规定。"},"children":[]}]}]}]}],"example":false},"additional_handling":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示包裹是否因尺寸、重量或包装不符合标准运输规范而需要额外处理。当该值为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时，承运商可能会收取额外费用。"},"children":[]}]}]}],"example":false},"require_saturday_delivery":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当值为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"true"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时，仅返回支持周六送达的运费报价。若为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"false"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"或未提供，则返回所有可用的运费报价，不区分是否支持周六送达。"},"children":[]}]}]},{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"注意"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"实际是否支持周六送达取决于承运商及具体服务等级——部分承运商或服务可能不支持。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"启用该偏好设置后，若所选服务等级对周六送达收取额外费用，可能会产生承运商附加费或更高的运费成本。"},"children":[]}]}]}]}],"example":false}}}},"components/schemas/ShipDate":{"id":"components/schemas/ShipDate","kind":"json-schema","title":"ShipDate","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 8601格式的时间戳，包含本地时间及时间偏移量。"},"children":[]}]}]}],"example":"2025-07-31T00:00:00+08:00"}},"components/schemas/BasicRateRequest":{"id":"components/schemas/BasicRateRequest","kind":"json-schema","title":"BasicRateRequest","data":{"required":["from_address_data","to_address_data","package_data","ship_date"],"type":"object","properties":{"from_address_data":{"$ref":"#/components/schemas/AddressFrom"},"to_address_data":{"$ref":"#/components/schemas/AddressTo"},"package_data":{"$ref":"#/components/schemas/ShipmentPackageData"},"option_data":{"$ref":"#/components/schemas/ShipmentOptionData"},"ship_date":{"$ref":"#/components/schemas/ShipDate"}}}},"components/schemas/IsReturnLabel":{"id":"components/schemas/IsReturnLabel","kind":"json-schema","title":"IsReturnLabel","data":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示该面单是否为退货运单。"},"children":[]}]}]}],"default":false,"example":false}},"components/schemas/ProviderIdEnum":{"id":"components/schemas/ProviderIdEnum","kind":"json-schema","title":"ProviderIdEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商ID"},"children":[]}]}]}],"example":"USPS_X","enum":["UPS_SS_DNI","USPS_X","FEDEX_X","DHL_A","GOFO_EXPRESS_A","SWIFTX","UPS_CANADA"]}},"components/schemas/ServiceLevelEnum":{"id":"components/schemas/ServiceLevelEnum","kind":"json-schema","title":"ServiceLevelEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商服务级别。请参阅 附录 - 承运商服务类型，以了解 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"carrier_code"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"provider_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 与 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"service_level"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 之间的有效对应关系。"},"children":[]}]}]}],"example":"USPS_GROUND_ADVANTAGE","enum":["USPS_FIRST_CLASS_MAIL","USPS_GROUND_ADVANTAGE","USPS_PRIORITY_MAIL","USPS_PRIORITY_MAIL_EXPRESS","USPS_MEDIA_MAIL","USPS_LIBRARY_MAIL","USPS_FIRST_CLASS_MAIL_INTERNATIONAL","USPS_PRIORITY_MAIL_INTERNATIONAL","USPS_PRIORITY_MAIL_EXPRESS_INTERNATIONAL","UPS_GROUND","UPS_GROUND_SAVER","UPS_NEXT_DAY_AIR","UPS_NEXT_DAY_AIR_SAVER","UPS_NEXT_DAY_AIR_EARLY","UPS_2ND_DAY_AIR","UPS_2ND_DAY_AIR_AM","UPS_3_DAY_SELECT","UPS_STANDARD","UPS_WORLDWIDE_SAVER","UPS_WORLDWIDE_EXPRESS","UPS_WORLDWIDE_EXPRESS_PLUS","UPS_WORLDWIDE_EXPEDITED","UPS_SUREPOST_LESS_THAN_1_LB","UPS_SUREPOST_1_LB_OR_GREATER","FEDEX_GROUND","FEDEX_2_DAY","FEDEX_2_DAY_AM","FEDEX_EXPRESS_SAVER","FEDEX_STANDARD_OVERNIGHT","FEDEX_FIRST_OVERNIGHT","FEDEX_PRIORITY_OVERNIGHT","FEDEX_INTERNATIONAL_ECONOMY","FEDEX_INTERNATIONAL_FIRST","FEDEX_INTERNATIONAL_PRIORITY","FEDEX_HOME_DELIVERY","FEDEX_SMARTPOST","FEDEX_STANDARD_OVERNIGHT_EXTRA_HOURS","FEDEX_FIRST_OVERNIGHT_EXTRA_HOURS","FEDEX_PRIORITY_OVERNIGHT_EXTRA_HOURS","FEDEX_INTERNATIONAL_PRIORITY_EXPRESS","FEDEX_INTERNATIONAL_CONNECT_PLUS","FEDEX_DATE_CERTAIN_HOME_DELIVERY","FEDEX_EVENING_HOME_DELIVERY","FEDEX_APPOINTMENT_HOME_DELIVERY","FEDEX_INTERNATIONAL_PRIORITY_PR","DHL_EXPRESS_WORLDWIDE_B2C","DHL_EXPRESS_WORLDWIDE_B2C_NONDOC","DHL_EXPRESS_JET_LINE_NONDOC","DHL_EXPRESS_SPRINT_LINE","DHL_EXPRESS_EURO_PACK_DOC","DHL_EXPRESS_BREAK_BULK_EXPRESS","DHL_EXPRESS_MEDICAL_EXPRESS","DHL_EXPRESS_WORLDWIDE_DOC","DHL_EXPRESS_0900_NONDOC","DHL_EXPRESS_FREIGHT_WORLDWIDE_NONDOC","DHL_EXPRESS_DOMESTIC_ECONOMY_SELECT","DHL_EXPRESS_ECONOMY_SELECT_NONDOC","DHL_EXPRESS_DOMESTIC_EXPRESS_0900","DHL_EXPRESS_JUMBO_BOX_NONDOC","DHL_EXPRESS_0900","DHL_EXPRESS_1030","DHL_EXPRESS_1030_NONDOC","DHL_EXPRESS_DOMESTIC_EXPRESS","DHL_EXPRESS_DOMESTIC_EXPRESS_1030","DHL_EXPRESS_WORLDWIDE_NONDOC","DHL_EXPRESS_MEDICAL_EXPRESS_NODOC","DHL_EXPRESS_GLOBAL_MAIL_BUSINESS","DHL_EXPRESS_SAME_DAY","DHL_EXPRESS_1200_DOC","DHL_EXPRESS_WORLDWIDE_ECX","DHL_EXPRESS_EURO_PACK_NONDOC","DHL_EXPRESS_ECONOMY_SELECT","DHL_EXPRESS_ENVELOPE","DHL_EXPRESS_1200_NONDOC","DHL_EXPRESS_DOMESTIC_EXPRESS_1200","GOFO_EXPRESS_ECO","SWIFTX_EXP","UPS_CANADA_EXPEDITED","UPS_CANADA_EXPRESS_EARLY","UPS_CANADA_EXPRESS_SAVER","UPS_CANADA_EXPRESS","UPS_CANADA_STANDARD","UPS_CANADA_3_DAY_SELECT","UPS_CANADA_EXPRESS_EARLY_SM","UPS_CANADA_WORLDWIDE_EXPEDITED_SM","UPS_CANADA_WORLDWIDE_EXPRESS_PLUS_SM","UPS_CANADA_WORLDWIDE_EXPRESS_SM","UPS_CANADA_EXPRESS_SAVER_SM"]}},"components/schemas/ShipmentRateCarrierData":{"id":"components/schemas/ShipmentRateCarrierData","kind":"json-schema","title":"ShipmentRateCarrierData","data":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"指定该参数可按承运商和服务等级筛选运费报价，从而加快查询速度。"},"children":[]}]}]}],"items":{"type":"object","properties":{"provider_id":{"$ref":"#/components/schemas/ProviderIdEnum"},"service_levels":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商服务等级。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/ServiceLevelEnum"}}}}}},"components/schemas/BatchQuickRateRequestItem":{"id":"components/schemas/BatchQuickRateRequestItem","kind":"json-schema","title":"BatchQuickRateRequestItem","data":{"allOf":[{"type":"object","required":["request_unique_id"],"properties":{"request_unique_id":{"$ref":"#/components/schemas/RequestUniqueId"}}},{"$ref":"#/components/schemas/BasicRateRequest"},{"type":"object","properties":{"is_return_label":{"$ref":"#/components/schemas/IsReturnLabel"},"shipment_rate_carrier_data":{"$ref":"#/components/schemas/ShipmentRateCarrierData"}}}]}},"components/schemas/BatchQuickRateRequest":{"id":"components/schemas/BatchQuickRateRequest","kind":"json-schema","title":"BatchQuickRateRequest","data":{"type":"object","required":["rate_requests"],"properties":{"rate_requests":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"单条运费询价请求的列表。每次调用最多可包含 10 条。"},"children":[]}]}]}],"maxItems":10,"items":{"$ref":"#/components/schemas/BatchQuickRateRequestItem"}}}}},"components/schemas/ShipmentRateId":{"id":"components/schemas/ShipmentRateId","kind":"json-schema","title":"ShipmentRateId","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"由"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"get_rates"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"接口返回的运费报价唯一标识。使用该值在购买面单时引用指定的运费报价。"},"children":[]}]}]}],"example":"dc288147-f7dd-494d-9353-5ce00020c7aa"}},"components/schemas/CarrierCodeEnum":{"id":"components/schemas/CarrierCodeEnum","kind":"json-schema","title":"CarrierCodeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商代码标识"},"children":[]}]}]}],"example":"USPS","enum":["USPS","UPS","FEDEX","DHL_EXPRESS","SWIFTX","GOFO_EXPRESS","UPS_CANADA"]}},"components/schemas/BaseRateItem":{"id":"components/schemas/BaseRateItem","kind":"json-schema","title":"BaseRateItem","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示承运商收取的基础运费。"},"children":[]}]}]}],"properties":{"amount":{"type":"number","format":"float","example":33.21},"currency":{"type":"string","example":"USD"},"list_amount":{"type":"number","format":"float","example":33.21},"retail_amount":{"type":"number","format":"float","example":59.55}}}},"components/schemas/SurchargeItem":{"id":"components/schemas/SurchargeItem","kind":"json-schema","title":"SurchargeItem","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示应用于运单或运费报价的单个附加费用项。"},"children":[]}]}]}],"nullable":true,"properties":{"object":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于标识对象类型，表示该对象为附加费用项。"},"children":[]}]}]}]},"type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于标识具体附加费用类型的代码。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"例如，"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"nonstandard_22"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 可能表示非标准包裹处理附加费。"},"children":[]}]}]}],"example":"nonstandard_22"},"category":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于对附加费用进行分类，将相似的费用类型归为一组。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"常见示例包括 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"HANDLING"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"FUEL"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 等。"},"children":[]}]}]}],"example":"HANDLING"},"amount":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该费用项收取的附加费用总金额。"},"children":[]}]}]}],"example":4},"currency":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"附加费用所使用的三位字母货币代码（ISO 4217）。"},"children":[]}]}]}],"example":"USD"},"list_amount":{"type":"number","format":"float","example":4},"retail_amount":{"type":"number","format":"float","example":4}}}},"components/schemas/PriceDetailItem":{"id":"components/schemas/PriceDetailItem","kind":"json-schema","title":"PriceDetailItem","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示运费报价中的单条费用明细。FedEx 独有。"},"children":[]}]}]}],"properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于标识费用组成部分的代码。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"常见示例包括 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"BASE_CHARGE"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"FUEL"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"RESIDENTIAL_DELIVERY"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"DEMAND_OVERSIZE"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"DEMAND"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"OVERSIZE"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"、"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"DELIVERY_AREA"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 等。"},"children":[]}]}]}],"example":"BASE_CHARGE"},"description":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该费用组成部分的可读描述。"},"children":[]}]}]}],"example":"Shipping Label Charge"},"price":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该费用组成部分所收取的金额。"},"children":[]}]}]}],"example":99.31}}}},"components/schemas/RateItem":{"id":"components/schemas/RateItem","kind":"json-schema","title":"RateItem","data":{"type":"object","properties":{"zone":{"type":"string","nullable":true,"example":"8Rural"},"currency":{"type":"string","example":"USD"},"cubic":{"type":"boolean","example":false},"rate_id":{"$ref":"#/components/schemas/ShipmentRateId"},"carrier_code":{"$ref":"#/components/schemas/CarrierCodeEnum"},"provider_id":{"$ref":"#/components/schemas/ProviderIdEnum"},"service_name":{"type":"string","example":"USPS Media Mail"},"service_level":{"type":"string","example":"USPS_MEDIA_MAIL"},"service_level_desc":{"type":"string","example":"A cost-effective way to send eligible books, media, and educational materials."},"returned_package_code":{"type":"string","nullable":true,"example":"my_package"},"delivery_days":{"type":"string","nullable":true,"example":"2"},"delivery_date":{"type":"string","nullable":true,"example":"2025-08-08T00:00:00+08:00"},"delivery_weekday":{"type":"string","nullable":true,"example":"MONDAY"},"service_detail":{"type":"string","nullable":true,"example":"Low rates for packages with expected delivery in 2-5 business days."},"price":{"type":"number","format":"float","example":5.91},"origin_price":{"type":"number","format":"float","nullable":true,"example":null},"retail_price":{"type":"number","format":"float","nullable":true,"example":8.7},"discount_text":{"type":"string","nullable":true},"insurance_info":{"type":"string","nullable":true},"ship_date":{"$ref":"#/components/schemas/ShipDate"},"saturday_delivery":{"type":"boolean","example":false},"one_rate":{"type":"boolean","example":false},"base_rate":{"$ref":"#/components/schemas/BaseRateItem"},"surcharges":{"$ref":"#/components/schemas/SurchargeItem"},"usps_dim_rate_type":{"type":"string","example":"dim-weight"},"price_details":{"type":"array","nullable":true,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"运费报价的逐项费用明细。FedEx 独有。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/PriceDetailItem"}}}}},"components/schemas/RateErrorInfo":{"id":"components/schemas/RateErrorInfo","kind":"json-schema","title":"RateErrorInfo","data":{"type":"object"}},"components/schemas/BatchQuickRateItem":{"id":"components/schemas/BatchQuickRateItem","kind":"json-schema","title":"BatchQuickRateItem","data":{"type":"object","properties":{"request_unique_id":{"$ref":"#/components/schemas/RequestUniqueId"},"shipment_rate_data":{"type":"array","items":{"$ref":"#/components/schemas/RateItem"}},"error_info":{"$ref":"#/components/schemas/RateErrorInfo"}}}},"components/schemas/BatchQuickRateResponse":{"id":"components/schemas/BatchQuickRateResponse","kind":"json-schema","title":"BatchQuickRateResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"type":"array","items":{"$ref":"#/components/schemas/BatchQuickRateItem"}}}}},"components/schemas/AddressReturn":{"id":"components/schemas/AddressReturn","kind":"json-schema","title":"AddressReturn","data":{"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当包裹无法投递或被退回给发件人时，用于指定包裹应退回的地址。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"注意：目前仅 USPS 支持在运单标签上打印独立的退货地址。"},"children":[]}]}]}],"allOf":[{"$ref":"#/components/schemas/AddressFrom"}]}},"components/schemas/BasicRateReqWithReturnAddress":{"id":"components/schemas/BasicRateReqWithReturnAddress","kind":"json-schema","title":"BasicRateReqWithReturnAddress","data":{"allOf":[{"type":"object","properties":{"return_address_data":{"$ref":"#/components/schemas/AddressReturn"}}},{"$ref":"#/components/schemas/BasicRateRequest"}]}},"components/schemas/ContentTypeEnum":{"id":"components/schemas/ContentTypeEnum","kind":"json-schema","title":"ContentTypeEnum","data":{"type":"string","example":"merchandise","enum":["merchandise","documents","return_merchandise","sample","gift"]}},"components/schemas/TaxIdTypeEnum":{"id":"components/schemas/TaxIdTypeEnum","kind":"json-schema","title":"TaxIdTypeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"税务识别号类型。"},"children":[]}]}]}],"example":"TIN","enum":["TIN","EIN","SSN","VAT","EORI","IOSS","PAN"]}},"components/schemas/ShipmentCustomTaxData":{"id":"components/schemas/ShipmentCustomTaxData","kind":"json-schema","title":"ShipmentCustomTaxData","data":{"type":"object","properties":{"tax_id_type":{"$ref":"#/components/schemas/TaxIdTypeEnum"},"tax_id_number":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"税务识别号。"},"children":[]}]}]}],"example":"tin2888"},"country_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"国家两位字母代码。该字段的值应为 "},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 两位国家代码"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}],"example":"US"}}}},"components/schemas/EelPfcTypeEnum":{"id":"components/schemas/EelPfcTypeEnum","kind":"json-schema","title":"EelPfcTypeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示该运单的电子出口信息（EEI）申报方式。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若在完成AES申报后已获得内部交易编号（ITN），请使用 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ITN"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"若该运单符合EEI申报豁免条件，请使用 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"EXEMPTION_CODE"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]}],"enum":["ITN","EXEMPTION_CODE"],"example":"ITN"}},"components/schemas/UndeliveryOptionEnum":{"id":"components/schemas/UndeliveryOptionEnum","kind":"json-schema","title":"UndeliveryOptionEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于定义运单无法投递时所采取的处理方式。"},"children":[]}]}]}],"example":"return_to_sender","enum":["return_to_sender","abandon"]}},"components/schemas/ShipmentCustomItemData":{"id":"components/schemas/ShipmentCustomItemData","kind":"json-schema","title":"ShipmentCustomItemData","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"海关申报物品清单（国际运单必填）"},"children":[]}]}]}],"properties":{"description":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"所寄送物品的描述。请提供准确、清晰的信息以便完成海关清关。"},"children":[]}]}]}],"example":"cloth"},"quantity":{"type":"integer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该条目中相同物品的总数量。"},"children":[]}]}]}],"format":"int32","example":10},"origin":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"原产国两位字母代码。该字段的值应为"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 两位国家代码"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"US"},"weight":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"物品在所选单位下的重量。"},"children":[]}]}]}],"example":10},"unit_cost":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"物品的申报价值（美元），指该物品的单价。"},"children":[]}]}]}],"example":19.99},"weight_unit":{"$ref":"#/components/schemas/WeightUnitEnum"},"hs_tariff_number":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"物品的HS编码。"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://uscensus.prod.3ceonline.com/ui/"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"查找我的HS编码"},"children":[]}]}]}]}],"example":"xx"}}}},"components/schemas/ShipmentCustomData":{"id":"components/schemas/ShipmentCustomData","kind":"json-schema","title":"ShipmentCustomData","data":{"type":"object","description":"custom data","properties":{"signing_person":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"在海关申报表上签字的个人姓名，通常为发件人或其授权代理，用于确认所申报的所有信息真实准确，并符合适用的海关法规要求。"},"children":[]}]}]}],"example":"Ray"},"content_type":{"$ref":"#/components/schemas/ContentTypeEnum"},"tax_ids":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"发件人的税务信息"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/ShipmentCustomTaxData"}},"eel_pfc_type":{"$ref":"#/components/schemas/EelPfcTypeEnum"},"eel_pfc_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"本次货件的 EEI 申报标识符。请提供从 AES 获取的内部交易编号（ITN），或在无需进行 EEI 申报时提供相应的豁免代码。请参阅 "},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"/appendix"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"附录 – 豁免代码名称表"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"X20250719123456"},"undeliverable_option":{"$ref":"#/components/schemas/UndeliveryOptionEnum"},"item_data_list":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentCustomItemData"}}}}},"components/schemas/ShipmentRateRequest":{"id":"components/schemas/ShipmentRateRequest","kind":"json-schema","title":"ShipmentRateRequest","data":{"allOf":[{"$ref":"#/components/schemas/BasicRateReqWithReturnAddress"},{"type":"object","properties":{"shipment_rate_carrier_data":{"$ref":"#/components/schemas/ShipmentRateCarrierData"},"custom_data":{"$ref":"#/components/schemas/ShipmentCustomData"}}}]}},"components/schemas/GetRatesResponse":{"id":"components/schemas/GetRatesResponse","kind":"json-schema","title":"GetRatesResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"fastest":{"nullable":true,"$ref":"#/components/schemas/RateItem"},"cheapest":{"nullable":true,"$ref":"#/components/schemas/RateItem"},"shipment_rate_data":{"type":"array","items":{"$ref":"#/components/schemas/RateItem"}},"fastest_and_cheapest":{"type":"object","nullable":true,"$ref":"#/components/schemas/RateItem"},"error_info":{"$ref":"#/components/schemas/RateErrorInfo"}}}}}},"components/schemas/PlatformUkId":{"id":"components/schemas/PlatformUkId","kind":"json-schema","title":"PlatformUkId","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"由调用方提供的唯一标识（例如调用方的订单号）。每个"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"platform_uk_id"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"必须且仅能对应一个运单，且不得在多个运单之间复用。"},"children":[]}]}]}],"example":"platformUkId175377917713"}},"components/schemas/InsuranceRateId":{"id":"components/schemas/InsuranceRateId","kind":"json-schema","title":"InsuranceRateId","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"由"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"/api/shipment/insurance/rate"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"接口返回的保险费率唯一标识。使用该值为运单购买保险。"},"children":[]}]}]}],"example":"dc288147-f7dd-494d-9353-5ce00020c7aa"}},"components/schemas/InsuranceData":{"id":"components/schemas/InsuranceData","kind":"json-schema","title":"InsuranceData","data":{"type":"object","properties":{"rate_id":{"$ref":"#/components/schemas/InsuranceRateId"}}}},"components/schemas/LabelPrintTypeEnum":{"id":"components/schemas/LabelPrintTypeEnum","kind":"json-schema","title":"LabelPrintTypeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于定义面单的打印格式。支持的格式因承运商而异，且可能取决于所选的服务等级。例如，USPS和FedEx可能支持 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"qrcode"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，而UPS可能支持 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"barcode"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"common","enum":["common","qrcode","barcode"]}},"components/schemas/IsExchangeLabel":{"id":"components/schemas/IsExchangeLabel","kind":"json-schema","title":"IsExchangeLabel","data":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示该运单面单是否属于平台特定的换货或退货流程。该字段适用于部分电商平台集成场景，并将被内部存储在"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"tag"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"字段中。"},"children":[]}]}]}],"example":false,"default":false}},"components/schemas/BuyLabelRequest":{"id":"components/schemas/BuyLabelRequest","kind":"json-schema","title":"BuyLabelRequest","data":{"type":"object","required":["rate_id","platform_uk_id","label_print_type"],"properties":{"rate_id":{"$ref":"#/components/schemas/ShipmentRateId"},"platform_uk_id":{"$ref":"#/components/schemas/PlatformUkId"},"insurance_data":{"$ref":"#/components/schemas/InsuranceData"},"label_print_type":{"$ref":"#/components/schemas/LabelPrintTypeEnum"},"is_return_label":{"$ref":"#/components/schemas/IsReturnLabel"},"is_exchange_label":{"$ref":"#/components/schemas/IsExchangeLabel"}}}},"components/schemas/ShipmentNo":{"id":"components/schemas/ShipmentNo","kind":"json-schema","title":"ShipmentNo","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"已创建运单的唯一标识。"},"children":[]}]}]}],"example":"1222243159"}},"components/schemas/TrackingNo":{"id":"components/schemas/TrackingNo","kind":"json-schema","title":"TrackingNo","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商提供的用于追踪运单的追踪号码。仅当该运费报价对应的运单支持追踪，且相关交易已成功处理时，才会返回该值。"},"children":[]}]}]}],"example":"9234690381085700XXXXX"}},"components/schemas/ShipmentItem":{"id":"components/schemas/ShipmentItem","kind":"json-schema","title":"ShipmentItem","data":{"type":"object","properties":{"zone":{"type":"string","example":"1"},"currency":{"type":"string","example":"USD"},"shipment_no":{"$ref":"#/components/schemas/ShipmentNo"},"tracking_no":{"$ref":"#/components/schemas/TrackingNo"},"total_fee":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"实际收取的总金额（包含面单费用及保险费用（如适用）），不含 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"label_processing_fee"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":39.39},"label_fee":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"运单面单的收费金额。"},"children":[]}]}]}],"example":39.39},"insurance_fee":{"type":"number","format":"float","nullable":true,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"保险费用金额；如未购买保险则为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":null},"label_processing_fee":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"创建面单所产生的固定手续费。"},"children":[]}]}]}],"example":0.05},"label_urls":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于下载或打印的面单文件URL列表（PNG格式）。"},"children":[]}]}]}],"items":{"type":"string","format":"uri"},"example":["https://xxxxxx.amazonaws.com/labels/2025-08-11/b0dd99909e2e7b03_0.png"]},"qrcode_urls":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于下载或打印二维码面单的PNG文件URL列表。该字段为可选项，仅适用于USPS二维码面单。"},"children":[]}]}]}],"items":{"type":"string","format":"uri"},"example":["https://xxxxxx.amazonaws.com/labels/2025-08-11/b0dd99909e2e7b03_0.png"]},"commercial_urls":{"type":"array","nullable":true,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"商业发票URL列表；如不适用则为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"items":{"type":"string","format":"uri"},"example":null},"duplicate_label":{"type":"boolean","nullable":true,"example":true},"label_print_type":{"$ref":"#/components/schemas/LabelPrintTypeEnum"}}}},"components/schemas/ShipmentPurchaseResponse":{"id":"components/schemas/ShipmentPurchaseResponse","kind":"json-schema","title":"ShipmentPurchaseResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/ShipmentItem"}}}},"components/schemas/DirectBuyShipmentRequest":{"id":"components/schemas/DirectBuyShipmentRequest","kind":"json-schema","title":"DirectBuyShipmentRequest","data":{"allOf":[{"type":"object","required":["platform_uk_id","carrier_code","service_level"],"properties":{"platform_uk_id":{"$ref":"#/components/schemas/PlatformUkId"},"carrier_code":{"$ref":"#/components/schemas/CarrierCodeEnum"},"service_level":{"$ref":"#/components/schemas/ServiceLevelEnum"}}},{"$ref":"#/components/schemas/BasicRateReqWithReturnAddress"},{"type":"object","required":["label_print_type"],"properties":{"custom_data":{"$ref":"#/components/schemas/ShipmentCustomData"},"insurance_data":{"$ref":"#/components/schemas/InsuranceData"},"label_print_type":{"$ref":"#/components/schemas/LabelPrintTypeEnum"},"is_return_label":{"$ref":"#/components/schemas/IsReturnLabel"},"is_exchange_label":{"$ref":"#/components/schemas/IsExchangeLabel"}}}]}},"components/schemas/ShipmentVoidRequest":{"id":"components/schemas/ShipmentVoidRequest","kind":"json-schema","title":"ShipmentVoidRequest","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"You only need to provide either shipment_no or platform_uk_id when calling the API, and the system will be able to uniquely locate and process the corresponding shipment."},"children":[]}]}]}],"properties":{"shipment_no":{"$ref":"#/components/schemas/ShipmentNo"},"platform_uk_id":{"$ref":"#/components/schemas/PlatformUkId"}}}},"components/schemas/CommonServiceResponse":{"id":"components/schemas/CommonServiceResponse","kind":"json-schema","title":"CommonServiceResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"type":"object","example":{}}}}},"components/schemas/InsuranceRateItem":{"id":"components/schemas/InsuranceRateItem","kind":"json-schema","title":"InsuranceRateItem","data":{"type":"object","properties":{"carrier":{"$ref":"#/components/schemas/CarrierCodeEnum"},"rate_id":{"$ref":"#/components/schemas/InsuranceRateId"},"service_level":{"$ref":"#/components/schemas/ServiceLevelEnum"},"rate":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"针对指定服务等级和申报价值计算的保险费用。"},"children":[]}]}]}],"example":1.98},"declared_value":{"type":"number","format":"float","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于计算保险保障金额的运单申报价值。"},"children":[]}]}]}],"example":200}}}},"components/schemas/InsuranceRateResponse":{"id":"components/schemas/InsuranceRateResponse","kind":"json-schema","title":"InsuranceRateResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/InsuranceRateItem"}}}},"components/schemas/TrackingStatusEnum":{"id":"components/schemas/TrackingStatusEnum","kind":"json-schema","title":"TrackingStatusEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当前运单状态。可能的取值包括："},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"created"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：运单面单已生成，但尚未被承运商扫描。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示发运流程尚未开始。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"available_for_pickup"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：包裹已到达指定地点，正在等待收件人领取。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示需要收件人采取行动取件。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"in_transit"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：包裹正在运输途中，经过不同的处理中心或检查节点。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示运单正在途中，尚未到达目的地。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"out_for_delivery"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：包裹已交由配送员，正在进行最后一公里派送。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示运单已进入末端配送阶段。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"delivered"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：包裹已成功投递并由收件人签收。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示发运流程已完成。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"return_to_sender"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：由于投递失败或其他原因，包裹正在退回给发件人。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示进入逆向物流流程。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"voided"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：运单面单已作废，包裹将不再被处理。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示该运单已被取消或失效。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"error"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：运单处理过程中发生错误。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示承运商侧出现问题，可能需要人工介入处理。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"seized_by_law_enforcement"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：包裹被执法机关扣押。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示运单受到合规或法律问题影响。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"strong","inline":true,"attributes":{"marker":"**"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"unknown"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"：运单状态未知，或承运商未提供有效的状态更新。"},"children":[]},{"$$mdtype":"Node","type":"hardbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示当前暂无可用的物流追踪信息。"},"children":[]}]}]}]}],"enum":["created","available_for_pickup","in_transit","out_for_delivery","delivered","return_to_sender","voided","error","seized_by_law_enforcement","unknown"],"example":"in_transit"}},"components/schemas/TrackingLocation":{"id":"components/schemas/TrackingLocation","kind":"json-schema","title":"TrackingLocation","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商提供的物流轨迹位置信息。不同的承运商，可能会返回城市、州、邮政编码和国家等字段。"},"children":[]}]}]}],"properties":{"city":{"type":"string","example":"BROOKLYN"},"state":{"type":"string","example":"NY"},"zipcode":{"type":"string","example":"91777"},"country":{"type":"string"}}}},"components/schemas/ReturnToSenderFlag":{"id":"components/schemas/ReturnToSenderFlag","kind":"json-schema","title":"ReturnToSenderFlag","data":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"表示该运单是否已被退回给发件人（Return to Sender）。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当接口返回状态码为 200 时，该字段始终会出现在响应中，且不受当前追踪状态影响。"},"children":[]}]}]},{"$$mdtype":"Node","type":"list","attributes":{"ordered":false,"marker":"-"},"children":[{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"false：运单尚未被退回给发件人。"},"children":[]}]}]},{"$$mdtype":"Node","type":"item","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"true：运单已被退回给发件人。"},"children":[]}]}]}]}],"example":true,"default":false}},"components/schemas/TrackingEventWUtcOffset":{"id":"components/schemas/TrackingEventWUtcOffset","kind":"json-schema","title":"TrackingEventWUtcOffset","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"单条物流追踪事件。"},"children":[]}]}]}],"properties":{"status":{"type":"string","example":"in_transit"},"message":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"人类可读的事件描述。"},"children":[]}]}]}],"example":"Arrived at USPS Facility"},"event_time":{"type":"string","format":"date-time","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"物流事件发生的时间戳，采用包含UTC偏移量的ISO 8601格式返回，"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于表示事件发生地的本地时间。"},"children":[]}]}]}],"example":"2025-09-15T09:22:36-05:00"},"location":{"$ref":"#/components/schemas/TrackingLocation"}}}},"components/schemas/TrackingDataWUtcOffset":{"id":"components/schemas/TrackingDataWUtcOffset","kind":"json-schema","title":"TrackingDataWUtcOffset","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"最新的物流追踪记录。"},"children":[]}]}]}],"properties":{"status":{"$ref":"#/components/schemas/TrackingStatusEnum"},"message":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"状态的人类可读描述。"},"children":[]}]}]}],"example":"USPS in possession of item"},"status_summary":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"状态摘要。"},"children":[]}]}]}],"example":"Your item has been delivered and is available at xxx at 9:00 am on xxx in xxxx, xx 20000."},"recipient_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"签收人姓名（如果有）。"},"children":[]}]}]}],"example":"Alice"},"scanned_time":{"type":"string","format":"date-time","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹被扫描的时间戳，采用包含UTC偏移量的ISO 8601格式返回，"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于表示事件发生地的本地时间。"},"children":[]}]}]}],"example":"2025-12-16T10:48:28-05:00"},"location":{"$ref":"#/components/schemas/TrackingLocation"},"return_to_sender":{"$ref":"#/components/schemas/ReturnToSenderFlag"},"first_scan_date":{"type":"string","format":"date-time","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"运单首次被承运商扫描的时间戳，用于表示包裹最初被承运商接收或处理的时间。"},"children":[]},{"$$mdtype":"Node","type":"softbreak","inline":true,"attributes":{},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"返回值采用包含UTC偏移量的ISO 8601格式，以表示事件发生地的本地时间。"},"children":[]}]}]}],"example":"2025-11-14T14:07:33-05:00"},"first_scan_description":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"首次承运商扫描事件的描述，用于指示运单在首次扫描时记录的初始状态或处理信息。"},"children":[]}]}]}],"example":"Package is in transit to a UPS facility"},"first_scan_location":{"$ref":"#/components/schemas/TrackingLocation"},"tracking_events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEventWUtcOffset"}}}}},"components/schemas/TrackingStatusWithUtcOffsetResponse":{"id":"components/schemas/TrackingStatusWithUtcOffsetResponse","kind":"json-schema","title":"TrackingStatusWithUtcOffsetResponse","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"物流状态查询响应的标准封装结构。"},"children":[]}]}]}],"properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"API 响应状态码；"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ok"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 表示请求成功。"},"children":[]}]}]}],"example":"ok"},"msg":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"人类可读的响应信息。"},"children":[]}]}]}],"example":"ok"},"data":{"$ref":"#/components/schemas/TrackingDataWUtcOffset"}}}},"components/schemas/PodRecipient":{"id":"components/schemas/PodRecipient","kind":"json-schema","title":"PodRecipient","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"单个 POD 邮件收件人。"},"children":[]}]}]}],"required":["email","first_name","last_name"],"properties":{"email":{"type":"string","format":"email","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"接收 POD 信件的收件人邮箱地址。"},"children":[]}]}]}],"example":"xxxxxxx@gmail.com"},"first_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"收件人名字。"},"children":[]}]}]}],"example":"Lisa"},"last_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"收件人姓氏。"},"children":[]}]}]}],"example":"Green"}}}},"components/schemas/PodSubmitRequest":{"id":"components/schemas/PodSubmitRequest","kind":"json-schema","title":"PodSubmitRequest","data":{"type":"object","required":["tracking_number","carrier_code","recipients"],"properties":{"tracking_number":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"需要申请 POD 的运单的承运商跟踪单号。"},"children":[]}]}]}],"example":"940XXXXXXXXXXXXXXXXX"},"carrier_code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"承运商代码。目前仅支持 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"USPS"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，其他取值会返回 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"shipment.carrier_code_illegal"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 错误。"},"children":[]}]}]}],"enum":["USPS"],"example":"USPS"},"recipients":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"通过邮件接收 POD 信件的收件人。必须包含 1 到 3 位收件人。"},"children":[]}]}]}],"minItems":1,"maxItems":3,"items":{"$ref":"#/components/schemas/PodRecipient"}},"letter_type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"要生成的 POD 信件类型，会透传给承运商。当前使用的取值为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"PROOF_OF_DELIVERY"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"PROOF_OF_DELIVERY"}}}},"components/schemas/PodSubmitResponse":{"id":"components/schemas/PodSubmitResponse","kind":"json-schema","title":"PodSubmitResponse","data":{"type":"object","properties":{"transaction_message":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"可读的确认信息，表示 POD 请求已被受理并进入处理流程。"},"children":[]}]}]}],"example":"Your Proof of Delivery record is complete and will be processed shortly."}}}},"components/schemas/PodSubmitResponseEnvelope":{"id":"components/schemas/PodSubmitResponseEnvelope","kind":"json-schema","title":"PodSubmitResponseEnvelope","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"submit POD 接口的标准 API 响应封装。"},"children":[]}]}]}],"properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"结果码。"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ok"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 表示成功；其他任何值表示业务错误，此时 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"ok"},"msg":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"可读的结果信息。"},"children":[]}]}]}],"example":"ok"},"data":{"allOf":[{"$ref":"#/components/schemas/PodSubmitResponse"}],"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"响应负载；当 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"code"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 不为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ok"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 时为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]}}}},"components/schemas/PickupAddress":{"id":"components/schemas/PickupAddress","kind":"json-schema","title":"PickupAddress","data":{"required":["phone","street","city","state","country","zip_code","address_type"],"type":"object","properties":{"first_name":{"type":"string","maxLength":50,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的名字。当未提供"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"company_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时为必填项。"},"children":[]}]}]}],"example":"Alice"},"last_name":{"type":"string","maxLength":50,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的姓氏。当未提供"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"company_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时为必填项。"},"children":[]}]}]}],"example":"Green"},"company_name":{"type":"string","maxLength":50,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与地址对应的公司或商户名称。当未提供"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"first_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"和"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"last_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时为必填项。"},"children":[]}]}]}],"example":"ShipSaving"},"phone":{"type":"string","pattern":"^\\d{10}$","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"取件地联系人电话号码，必须为10位数字。"},"children":[]}]}]}],"example":"1234567890"},"email":{"type":"string","format":"email","maxLength":50,"pattern":"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"取件地联系人电子邮箱地址，必须为合法的邮箱格式（例如"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"name@example.com"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"）。"},"children":[]}]}]}],"example":"it@shipsaving.com"},"street":{"type":"string","minLength":1,"maxLength":50,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"建筑物门牌号及其所在的道路或街道名称。"},"children":[]}]}]}],"example":"xxxx Olive Street"},"street2":{"type":"string","maxLength":50,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址的次级单元标识，例如公寓号（APT）或套房号（STE），用于明确建筑物内的具体位置。"},"children":[]}]}]}],"example":"STE XXX"},"city":{"type":"string","minLength":1,"maxLength":28,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址所属的城市名称。"},"children":[]}]}]}],"example":"San Francisco"},"state":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址对应的州名或两位州代码。请求中可使用完整的州名或两位州代码。"},"children":[]}]}]}],"example":"CA"},"zip_code":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址对应的邮政编码。必须为5位数字邮编（例如"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"900XX"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"）或ZIP+4格式（例如"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"900XX-XXXX"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"）。"},"children":[]}]}]}],"example":"941XX"},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"国家两位字母代码。该字段的值应为"},"children":[]},{"$$mdtype":"Node","type":"link","inline":true,"attributes":{"href":"https://en.wikipedia.org/wiki/ISO_3166-1"},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 two-digit code"},"children":[]}]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"两位国家代码。"},"children":[]}]}]}],"example":"US"},"address_type":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示取件地址是住宅地址还是商业地址。该标志用于确定承运商特定的附加费用（例如UPS住宅投递附加费）。"},"children":[]}]}]}],"example":"residential","enum":["residential","commercial"]}},"anyOf":[{"required":["first_name","last_name"]},{"required":["company_name"]}]}},"components/schemas/PackageLocationEnum":{"id":"components/schemas/PackageLocationEnum","kind":"json-schema","title":"PackageLocationEnum","data":{"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于指示在取件地址处已准备好供取件的包裹放置位置。"},"children":[]}]}]}],"type":"string","enum":["front_door","back_door","side_door","knock_on_door_ring_bell","mail_room","office","reception","in_at_mail_box","other"]}},"components/schemas/PickUpCarrierCodeEnum":{"id":"components/schemas/PickUpCarrierCodeEnum","kind":"json-schema","title":"PickUpCarrierCodeEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于标识取件所使用的快递承运商或物流服务商的代码。该值用于确定由哪个物流服务商处理取件或运单请求。目前仅支持USPS，未来可能支持其他承运商代码（例如UPS、FedEx）。"},"children":[]}]}]}],"enum":["USPS"],"example":"USPS"}},"components/schemas/AddPickUpByShipmentRequest":{"id":"components/schemas/AddPickUpByShipmentRequest","kind":"json-schema","title":"AddPickUpByShipmentRequest","data":{"required":["package_location","carrier_code","tracking_nos"],"type":"object","properties":{"pickup_date":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"预约取件日期，格式为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"YYYY-MM-DD"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。若未提供，则无论请求提交时间为何，系统都会基于America/Los_Angeles时区自动设置为下一个自然日。"},"children":[]}]}]}]},"pickup_location":{"$ref":"#/components/schemas/PickupAddress"},"package_location":{"$ref":"#/components/schemas/PackageLocationEnum"},"package_location_ext":{"type":"string","maxLength":255,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"包裹取件位置的补充说明。当"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"package_location"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"other"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"时，该字段为必填。不支持中文字符。"},"children":[]}]}]}]},"carrier_code":{"$ref":"#/components/schemas/PickUpCarrierCodeEnum"},"tracking_nos":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与本次取件请求关联的运单追踪号列表。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/TrackingNo"}}}}},"components/schemas/PickUpNo":{"id":"components/schemas/PickUpNo","kind":"json-schema","title":"PickUpNo","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于标识先前已预约的USPS取件请求的内部取件记录编号。该值会在创建取件时返回，并且在取消对应取件订单时必须提供。"},"children":[]}]}]}],"example":"10000000000"}},"components/schemas/PickUpConfirmationNo":{"id":"components/schemas/PickUpConfirmationNo","kind":"json-schema","title":"PickUpConfirmationNo","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"这是由USPS分配的取件确认号码。"},"children":[]}]}]}],"example":"WTC65384000"}},"components/schemas/AddPickupResult":{"id":"components/schemas/AddPickupResult","kind":"json-schema","title":"AddPickupResult","data":{"type":"object","properties":{"pickup_no":{"$ref":"#/components/schemas/PickUpNo"},"pickup_date":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"预约取件日期（YYYY-MM-DD）。"},"children":[]}]}]}],"example":"2025-11-21"},"package_total_num":{"type":"integer","format":"int32","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"本次取件请求中包含的包裹总数量。"},"children":[]}]}]}],"example":1},"package_total_weight":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"本次取件中所有包裹的总重量（磅，lb）。"},"children":[]}]}]}],"example":0.1},"carrier_code":{"$ref":"#/components/schemas/PickUpCarrierCodeEnum"},"carrier_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"负责执行取件的承运商名称。"},"children":[]}]}]}],"example":"USPS"},"confirmation_number":{"$ref":"#/components/schemas/PickUpConfirmationNo"}}}},"components/schemas/CancelPickupRequest":{"id":"components/schemas/CancelPickupRequest","kind":"json-schema","title":"CancelPickupRequest","data":{"type":"object","required":["pickup_no"],"properties":{"pickup_no":{"$ref":"#/components/schemas/PickUpNo"}}}},"components/schemas/PickUpStatusEnum":{"id":"components/schemas/PickUpStatusEnum","kind":"json-schema","title":"PickUpStatusEnum","data":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"当前USPS取件请求的状态。"},"children":[]}]}]}],"enum":["CONFIRMED","CANCELED"],"example":"CONFIRMED"}},"components/schemas/PickupVO":{"id":"components/schemas/PickupVO","kind":"json-schema","title":"PickupVO","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"预约取件记录信息。"},"children":[]}]}]}],"properties":{"status":{"$ref":"#/components/schemas/PickUpStatusEnum"},"pickup_no":{"$ref":"#/components/schemas/PickUpNo"},"pickup_date":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"预约取件日期，格式为YYYY-MM-DD。"},"children":[]}]}]}],"example":"2025-11-21"},"package_total_num":{"type":"integer","format":"int32","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"本次取件请求中包含的包裹总数量。"},"children":[]}]}]}],"example":1},"package_total_weight":{"type":"number","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"本次取件中所有包裹的总重量（磅，lb）。"},"children":[]}]}]}],"example":0.1},"carrier_code":{"$ref":"#/components/schemas/PickUpCarrierCodeEnum"},"carrier_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"负责执行取件的承运商名称。"},"children":[]}]}]}],"example":"USPS"},"confirmation_number":{"$ref":"#/components/schemas/PickUpConfirmationNo"},"pickup_location_ext":{"$ref":"#/components/schemas/AddressTo"},"package_location":{"$ref":"#/components/schemas/PackageLocationEnum"},"package_location_ext":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"描述包裹放置位置的补充信息。"},"children":[]}]}]}],"example":"Left behind the plant"},"tracking_nos":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"与本次取件关联的运单追踪号列表。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/TrackingNo"},"example":["94055XXXXXXXXX123","92055XXXXXXXXX456"]}}}},"components/schemas/QueryPickupResponse":{"id":"components/schemas/QueryPickupResponse","kind":"json-schema","title":"QueryPickupResponse","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"用于查询取件记录分页结果的响应对象。"},"children":[]}]}]}],"properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"type":"object","properties":{"pickup_data_list":{"type":"array","items":{"$ref":"#/components/schemas/PickupVO"}},"total_count":{"type":"integer","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"符合查询条件的取件记录总数量。"},"children":[]}]}]}],"format":"int32"}}}}}},"components/schemas/QueryPackageLocationResponse":{"id":"components/schemas/QueryPackageLocationResponse","kind":"json-schema","title":"QueryPackageLocationResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageLocationEnum"}}}}},"components/schemas/AddressIssue":{"id":"components/schemas/AddressIssue","kind":"json-schema","title":"AddressIssue","data":{"type":"object","properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"机器可读的代码"},"children":[]}]}]}],"example":"ADDRESS.SECONDARY.MISSING"},"message":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"面向用户的可读描述"},"children":[]}]}]}],"example":"High-rise address missing secondary number"}}}},"components/schemas/AddressCorrection":{"id":"components/schemas/AddressCorrection","kind":"json-schema","title":"AddressCorrection","data":{"type":"object","properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"机器可读代码"},"children":[]}]}]}],"example":"ADDRESS.COMPONENT.CHANGED"},"message":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"面向用户的可读描述"},"children":[]}]}]}],"example":"An address component (i.e., directional or suffix only) was changed"}}}},"components/schemas/ValidatedAddress":{"id":"components/schemas/ValidatedAddress","kind":"json-schema","title":"ValidatedAddress","data":{"allOf":[{"type":"object","properties":{"street":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"标准化后的主街道地址行。"},"children":[]}]}]}],"example":"17XXX Tremont ST"},"street2":{"type":"string","nullable":true,"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"标准化后的次级地址行（如有）。"},"children":[]}]}]}],"example":null},"city":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"标准化后的城市或地区名称（大写）。"},"children":[]}]}]}],"example":"Los Angeles"},"state":{"type":"string","example":"CA"},"zip":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"标准化后的ZIP或ZIP+4邮政编码。"},"children":[]}]}]}],"example":"02111-XXXX"},"country":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"ISO 3166-1 alpha-2国家代码。"},"children":[]}]}]}],"example":"US"},"residential":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该地址是否被归类为住宅地址。"},"children":[]}]}]}],"example":true},"errored":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址校验过程中是否遇到一个或多个错误。"},"children":[]}]}]}],"example":true},"corrected":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"是否有任一地址组件被校验器修正。"},"children":[]}]}]}],"example":true},"standardized":{"type":"boolean","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"地址是否已完全标准化。"},"children":[]}]}]}],"example":false},"errors":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"处理过程中发现的地址校验错误。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/AddressIssue"}},"corrections":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"已应用的修正或改进建议。"},"children":[]}]}]}],"items":{"$ref":"#/components/schemas/AddressCorrection"}}}}]}},"components/schemas/AddressValidateResponse":{"id":"components/schemas/AddressValidateResponse","kind":"json-schema","title":"AddressValidateResponse","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"面向用户的可读描述。"},"children":[]}]}]}],"example":"ok"},"data":{"$ref":"#/components/schemas/ValidatedAddress"}}}},"components/schemas/ScanFormAddress":{"id":"components/schemas/ScanFormAddress","kind":"json-schema","title":"ScanFormAddress","data":{"allOf":[{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"打印在 SCAN Form 上的发货（寄件）地址。"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"company_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 与 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"first_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" + "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"last_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 两者中至少要提供一项。"},"children":[]}]}]}],"properties":{"company_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"公司/商户名称。若未提供 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"first_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"/"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"last_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，则此项必填。"},"children":[]}]}]}],"example":"ShipSaving"},"first_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"联系人名字。若未提供 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"company_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，则此项与 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"last_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 一起必填。"},"children":[]}]}]}],"example":"Alice"},"last_name":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"联系人姓氏。若未提供 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"company_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"，则此项与 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"first_name"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 一起必填。"},"children":[]}]}]}],"example":"Green"},"phone":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"联系电话。可选，但建议提供，以便承运商在需要时联系。"},"children":[]}]}]}],"example":"1234567890"},"email":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"联系邮箱。可选。"},"children":[]}]}]}],"example":"it@shipsaving.com"}}},{"$ref":"#/components/schemas/BasicAddress"}]}},"components/schemas/ScanFormCreateRequest":{"id":"components/schemas/ScanFormCreateRequest","kind":"json-schema","title":"ScanFormCreateRequest","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"为一组已购买的运单创建 USPS SCAN Form（PS Form 5630）的请求。"},"children":[]}]}]}],"required":["address_data","tracking_nos"],"properties":{"address_data":{"$ref":"#/components/schemas/ScanFormAddress"},"tracking_nos":{"type":"array","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"要加入 SCAN Form 的已购买运单的 tracking number。每个运单都必须属于 USPS， 且处于已购买、尚未发货的状态；同一运单只能出现在一个 SCAN Form 中。"},"children":[]}]}]}],"minItems":1,"items":{"$ref":"#/components/schemas/TrackingNo"}},"ship_date":{"type":"string","format":"date","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"邮寄日期——即关联 SCAN Form 中的包裹被交到收寄点（entry facility）的日期。 采用 ISO 8601 full-date 格式的日历日期（YYYY-MM-DD），不含时间与时区。 可选；不传时默认为当天。"},"children":[]}]}]}],"example":"2026-07-21"}}}},"components/schemas/ScanFormCreateResponse":{"id":"components/schemas/ScanFormCreateResponse","kind":"json-schema","title":"ScanFormCreateResponse","data":{"type":"object","properties":{"scan_form_image":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"生成的 SCAN Form PDF 的 URL。"},"children":[]}]}]}],"example":"https://xxxxx/forms/2026-07-16/92XXXXXXXXX00000010794.pdf"}}}},"components/schemas/ScanFormCreateResponseEnvelope":{"id":"components/schemas/ScanFormCreateResponseEnvelope","kind":"json-schema","title":"ScanFormCreateResponseEnvelope","data":{"type":"object","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"创建 SCAN Form 接口的标准 API 响应封装。"},"children":[]}]}]}],"properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"结果码。"},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ok"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 表示成功；其他任何值表示业务错误，此时 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"data"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}],"example":"ok"},"msg":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"可读的结果信息。"},"children":[]}]}]}],"example":"ok"},"data":{"allOf":[{"$ref":"#/components/schemas/ScanFormCreateResponse"}],"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"响应负载；当 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"code"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 不为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"ok"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":" 时为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"null"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"。"},"children":[]}]}]}]}}}},"schema_184":{"kind":"json-schema","data":{"type":"object","properties":{"grant_type":{"type":"string","enum":["client_credentials"],"description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"该值必须为 "},"children":[]},{"$$mdtype":"Node","type":"code","inline":true,"attributes":{"content":"client_credentials"},"children":[]},{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"."},"children":[]}]}]}]},"scope":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"可选的作用域列表，多个作用域之间以空格分隔。"},"children":[]}]}]}],"example":"API"}},"required":["grant_type"]},"id":"schema_184"},"schema_185":{"kind":"json-schema","data":{"type":"number"},"id":"schema_185"},"schema_186":{"kind":"json-schema","data":{"type":"string"},"id":"schema_186"},"schema_187":{"kind":"json-schema","data":{"type":"string","example":"USPS"},"id":"schema_187"},"schema_188":{"kind":"json-schema","data":{"type":"object","properties":{"code":{"type":"string","example":"ok"},"msg":{"type":"string","example":"ok"},"data":{"$ref":"#/components/schemas/AddPickupResult"}}},"id":"schema_188"},"schema_189":{"kind":"json-schema","data":{"type":"object","properties":{"code":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"错误码，采用点分隔的命名格式。"},"children":[]}]}]}]},"msg":{"type":"string","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"错误说明信息。"},"children":[]}]}]}]},"data":{"example":null}}},"id":"schema_189"},"schema_190":{"kind":"json-schema","data":{"$ref":"#/components/schemas/PickUpConfirmationNo"},"id":"schema_190"},"schema_191":{"kind":"json-schema","data":{"type":"string","enum":["CONFIRMED","CANCELED"]},"id":"schema_191"},"schema_192":{"kind":"json-schema","data":{"$ref":"#/components/schemas/PickUpCarrierCodeEnum"},"id":"schema_192"},"schema_193":{"kind":"json-schema","data":{"type":"integer","format":"int32","default":1},"id":"schema_193"},"schema_194":{"kind":"json-schema","data":{"type":"integer","format":"int32","default":50},"id":"schema_194"},"schema_195":{"kind":"json-schema","data":{"type":"boolean"},"id":"schema_195"}},"exampleStore":{"paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample":{"value":{"grant_type":"client_credentials","scope":"API"},"key":"curlExample","summary":"Client Credentials 请求","id":"paths/~1oauth2~1token/post/requestBody/content/application~1x-www-form-urlencoded/examples/curlExample"},"paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success":{"value":{"access_token":"eyJraWQiOiIxIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJTU19MSVZFX3RoNXE5S0pUZTBrdllsM3pRSFFmU0Q3NW5ETGlZQ2s4dlowSSIsImF1ZCI6IlNTX0xJVkVfdGg1cTlLSlRlMGt2WWwzelFIUWZTRDc1bkRMaVlDazh2WjBJIiwibmJmIjoxNzU0MzU1MzM0LCJjb21wYW55X2lkIjoiMTgyMyIsInVzZXJfaWQiOiIyNDA3Iiwic2NvcGUiOlsiQVBJIl0sImlzX3ZhbGlkIjp0cnVlLCJpc3MiOiJodHRwczovL3gtYXBpLnNoaXBzYXZpbmcudXMiLCJleHAiOjE3NTQzNTcxMzQsImlhdCI6MTc1NDM1NTMzNCwidGVzdF9tb2RlbCI6ZmFsc2V9.CsOfJozZUmd5cFrSodxGuDH0xxRQjau_qKwyOuJBPWigJeZXeoB_FgOl7r2kDfVndrru7IkXw5XCEmePkTJ25nyTD7RiysInBOuU0a89mfj4czedC8qHIHU-EI1CfRopHan2dCHfSog5skNT6edAmQfSNndj6mV18Pr0AclnhEgIG-CsfYkxZXRITXeqFKqiLfbUt8A4YsqT9zhXHqqttk42rBNzSddgBcBkHNGdys-qltEPc7xB_NpV02tZbsfl-hcHbHZYt_ufT4u4BLy5g7p6bd4Tt2vgUbRrVx-umCWuT3dad5di2Loj9vs2boywSCQshM1Aj4Fxzg8Sk-GsBw","scope":"API","token_type":"Bearer","expires_in":1799},"key":"success","summary":"成功响应","id":"paths/~1oauth2~1token/post/responses/200/content/application~1json/examples/success"},"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType":{"value":{"error_description":"OAuth 2.0 Parameter: grant_type","error":"invalid_request","error_uri":"https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"},"key":"badContentType","summary":"Content-Type 非 form-encoded","id":"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badContentType"},"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType":{"value":{"error_description":"OAuth 2.0 Parameter: grant_type","error":"unsupported_grant_type","error_uri":"https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"},"key":"badGrantType","summary":"不支持的 grant_type","id":"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/badGrantType"},"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope":{"value":{"error":"invalid_scope"},"key":"invalidScope","summary":"无效的 scope 值","id":"paths/~1oauth2~1token/post/responses/400/content/application~1json/examples/invalidScope"},"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup":{"value":{"code":"pickup.shipment_already_in_pickup","msg":"Shipment is already in pickup (tracking no: {tracking_no}).","data":null},"key":"shipmentAlreadyInPickup","summary":"该运单已经创建过取件","id":"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentAlreadyInPickup"},"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist":{"value":{"code":"pickup.shipment_not_exist","msg":"Shipment does not exist.","data":null},"key":"shipmentNotExist","summary":"运单号不存在","id":"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/shipmentNotExist"},"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields":{"value":{"code":"invalid_request_params","msg":"Missing or invalid request parameters\nInvalid request, 'address' requires a valid 'street1', 'city', 'state', 'zip', 'phone', and 'name' or 'company'.","data":null},"key":"missingAddressFields","summary":"地址必填字段缺失（例如缺少电话）","id":"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/missingAddressFields"},"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress":{"value":{"code":"invalid_request_params","msg":"Missing or invalid request parameters\nAPI Version: /pickup/v3/, Error Code: 400, An invalid address was entered. Please verify address, including apartment, suite, etc.: An invalid address was entered. Please verify address, including apartment, suite, etc., Source Parameter: No parameter provided., USPS Error Code: 1007","data":null},"key":"invalidAddress","summary":"地址未通过承运商校验","id":"paths/~1api~1shipment~1pickup~1add/post/responses/400/content/application~1json/examples/invalidAddress"},"paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled":{"value":{"code":"pickup.pickup_is_canceled","msg":"Pickup is already canceled.","data":null},"key":"pickupAlreadyCanceled","summary":"该取件已被取消","id":"paths/~1api~1shipment~1pickup~1cancel/post/responses/400/content/application~1json/examples/pickupAlreadyCanceled"}},"securitySchemeStore":{"BearerAuth":{"id":"BearerAuth","type":"http","scheme":"bearer","bearerFormat":"JWT","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"Bearer令牌认证（JWT）。"},"children":[]}]}]}]},"basicAuth":{"id":"basicAuth","type":"http","scheme":"basic","description":[{"$$mdtype":"Node","type":"paragraph","attributes":{},"children":[{"$$mdtype":"Node","type":"inline","attributes":{},"children":[{"$$mdtype":"Node","type":"text","inline":true,"attributes":{"content":"使用AppKey/AppSecret的基础认证。"},"children":[]}]}]}]}},"servers":[{"url":"https://x-api.shipsaving.com"}]},"options":{"hideDownloadButtons":true,"hideReplay":true,"feedback":{"hide":true,"settings":{"label":""}},"hideSidebar":true,"mockServer":{"off":true},"disableRouter":true,"downloadUrls":[{"url":"/_bundle/@l10n/zh-Hans/v2/openapi.json?download"},{"url":"/_bundle/@l10n/zh-Hans/v2/openapi.yaml?download"}],"excludeFromSearch":false,"specType":"openapi","markdocOptions":{"tags":{},"nodes":{},"components":{}},"metadata":{"title":"ShipSaving New API"}},"baseSlug":"/zh-hans/v2/openapi","routesMapping":{}}