开发者门户

接入 Byte Orca

销售税计算与交易流水录入的公开 API 协议、参数说明和可直接使用的代码示例。

GET API

销售税 API

将外部系统接入 Byte Orca 的销售税税率查询与自动计税服务。

Endpoint

通过 HTTPS 发送税率查询。州和邮编为必填项；城市和 County 可提高地方税匹配精度。

GEThttps://{your_api_domain}/external/v1/tax-rate/query

API 安全认证

需要在请求 Header 中携带 X-API-Key。

X-API-Key: <your_api_key>

请求参数

请求参数
参数	必填	类型	说明
stateCode	必填	string	美国 2 位州代码，例如 CA、WA。
zipCode	必填	string	5 位 ZIP Code。
city	选填	string	城市名称，传入后可提高匹配精度。
county	选填	string	County（县/区），传入后可提高匹配精度。
amount	选填	decimal	商品金额；不传时仅返回税率。
shippingAmount	选填	decimal	运费金额，不传时默认为 0.00。
productType	选填	integer	商品类型编码，默认为 1（实体商品）。

请求示例

代码

1curl -i -G 'https://{your_api_domain}/external/v1/tax-rate/query' \2  -H 'X-API-Key: <your_api_key>' \3  -d 'stateCode=WA' \4  -d 'zipCode=98005' \5  -d 'amount=100.00' \6  -d 'shippingAmount=10.00'

成功响应

HTTP 200 OK · 响应格式

代码

1{2  "code": 200,3  "msg": "OK",4  "data": {5    "match": {6      "stateCode": "WA", "zipCode": "98005",7      "city": "Bellevue", "county": "King",8      "matchType": "STATE_ZIP", "confidence": "EXACT"9    },10    "rates": {11      "unit": "DECIMAL", "combinedRate": "0.103",12      "stateRate": "0.065", "countyRate": "0.024",13      "cityRate": "0", "specialRate": "0.014"14    },15    "calculation": {16      "amount": "100.00", "shippingAmount": "10.00",17      "taxableAmount": "110.00", "estimatedTax": "11.33",18      "totalAmount": "121.33"19    }20  }21}