ziptax-sales-tax

TotalClaw 作者 totalclaw

使用 ZipTax API 查找美国销售税率。当用户询问销售税率时使用，美国地址/邮政编码/坐标、运费或服务应税性的税务计算，司法管辖区级别的税收明细、使用税与销售税或需要整合销售税数据到应用程序中。还处理帐户使用指标和产品应税代码 (TIC)。支持 12,000 多个司法管辖区的地址级（门级）、纬度/经度和邮政编码查找。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw skills install shop:totalclaw:totalclaw~ericlakich-ziptax

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~ericlakich-ziptax/file -o ericlakich-ziptax.md

## 概述（中文）

使用 ZipTax API 查找美国销售税率。当用户询问销售税率时使用，
美国地址/邮政编码/坐标、运费或服务应税性的税务计算，
司法管辖区级别的税收明细、使用税与销售税或需要整合销售税
数据到应用程序中。还处理帐户使用指标和产品应税代码 (TIC)。
支持 12,000 多个司法管辖区的地址级（门级）、纬度/经度和邮政编码查找。

## 原文

# ZipTax Sales Tax Lookup

## Setup

Set `ZIPTAX_API_KEY` env variable with your API key from https://platform.zip.tax (DEVELOP > API Keys).
Free tier gives 100 calls/month. **Never share your API key publicly.**

## Quick Start

### Address Lookup (most accurate)
```bash
curl -s "https://api.zip-tax.com/request/v60?address=200+Spectrum+Center+Drive+Irvine+CA+92618" \
  -H "X-API-KEY: $ZIPTAX_API_KEY"
```

### Postal Code Lookup
```bash
curl -s "https://api.zip-tax.com/request/v60?postalcode=92618" \
  -H "X-API-KEY: $ZIPTAX_API_KEY"
```

### Lat/Lng Lookup
```bash
curl -s "https://api.zip-tax.com/request/v60?lat=33.6525&lng=-117.7479" \
  -H "X-API-KEY: $ZIPTAX_API_KEY"
```

## Workflow

1. Determine lookup type: address (best), lat/lng, or postal code
2. Use **v60** (latest) for full jurisdiction breakdowns; use v10 for simple combined rate
3. Make GET request to `https://api.zip-tax.com/request/v60` with auth header
4. Check `metadata.response.code` — 100 means success
5. Read `taxSummaries[0].rate` for total sales tax rate
6. Read `baseRates` array for state/county/city/district breakdown
7. Check `service.taxable` and `shipping.taxable` for service/freight taxability

## Key Points

- **Address > Postal code**: Address gives one exact result; postal code returns all rates in that ZIP
- **Auth**: Header `X-API-KEY` or query param `key`
- **Rate format**: Decimal (0.0775 = 7.75%)
- **Response code 100** = success; check `metadata.response.code`
- **Metrics endpoint** (`/account/metrics`) does not count against quota

## Bundled Resources

- **`scripts/lookup.sh`** — CLI wrapper for quick lookups. Run with `--address`, `--lat`/`--lng`, `--postalcode`, or `--metrics`
- **`references/api-reference.md`** — Full API reference with all endpoints, response schemas, code samples, response codes, and SDK links. Read when you need endpoint details or response field definitions.