taxcloud
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTaxCloud Integration Skill
TaxCloud集成技能
TaxCloud is a Certified Streamlined Sales Tax (SST) provider for US sales tax — real-time calculation, compliance reporting, and automated filing across 11,000+ jurisdictions.
OpenAPI spec: /
Base URL:
Full docs:
Support email: service@taxcloud.net
https://docs.taxcloud.com/openapi.jsonhttps://docs.taxcloud.com/openapi.yamlBase URL:
https://api.v3.taxcloud.com/tax/connections/{connectionId}Full docs:
https://docs.taxcloud.comSupport email: service@taxcloud.net
TaxCloud是美国销售税领域的认证简化销售税（SST）提供商——支持在11000+辖区内进行实时计算、合规报告和自动化申报。
OpenAPI规范： /
基础URL：
完整文档：
支持邮箱：service@taxcloud.net
https://docs.taxcloud.com/openapi.jsonhttps://docs.taxcloud.com/openapi.yaml基础URL：
https://api.v3.taxcloud.com/tax/connections/{connectionId}完整文档：
https://docs.taxcloud.com支持邮箱：service@taxcloud.net
Which Reference to Read First
首先阅读哪个参考文档
| Task | Reference file |
|---|---|
| First-time setup, credentials, test vs prod | |
| Understand nexus, sourcing, how tax is calculated | |
| Real-time tax quote during checkout, discounts, exemptions | |
| Importing orders from Square, POS, ERPs, marketplaces | |
| Customer returns, partial refunds, standalone credits | |
| Product classification, TIC search API | |
| Tax-exempt customers, exemption certificates | |
| Address verification, address field formats | |
| Error handling, retry patterns, rate limits | |
| Generating a TypeScript/Node.js typed client | |
| Migrating an existing v1 integration to v3 | |
| Growing nexus over time, economic thresholds, adding states | |
| Vue.js integration patterns, testing, mocking, data storage | |
| 任务 | 参考文档 |
|---|---|
| 首次设置、凭证、测试环境与生产环境 | |
| 理解纳税关联（nexus）、税源、计税方式 | |
| 结账时实时税报价、折扣、免税处理 | |
| 从Square、POS、ERP、电商平台导入订单 | |
| 客户退货、部分退款、独立税收抵免 | |
| 产品分类、TIC搜索API | |
| 免税客户、免税证明 | |
| 地址验证、地址字段格式 | |
| 错误处理、重试模式、速率限制 | |
| 生成TypeScript/Node.js类型化客户端 | |
| 将现有v1集成迁移至v3 | |
| 纳税关联扩展、经济阈值、添加州 | |
| Vue.js集成模式、测试、模拟、数据存储 | |
Two Core Workflows at a Glance
两大核心工作流概览
Real-Time API Flow (online checkout)
实时API流程（在线结账）
POST /carts → calculate tax, get cartId
↓ (customer checks out)
POST /carts/orders → convert cart → order (completed: true or false)
↓ (if deferred)
PATCH /orders/{id} → set completedDate to lock in filing periodPOST /carts → 计算税费，获取cartId
↓（客户完成结账）
POST /carts/orders → 将购物车转换为订单（completed: true或false）
↓（若延迟处理）
PATCH /orders/{id} → 设置completedDate以锁定申报周期Order Upload Flow (external/imported orders)
订单上传流程（外部/导入订单）
POST /orders → create order directly (with tax amounts you calculated)
or
POST /orders (kind: "credit") → standalone tax credit not tied to any orderPOST /orders → 直接创建订单（包含你计算的税费金额）
或
POST /orders (kind: "credit") → 独立税收抵免，不关联任何订单Key Rules to Always Follow
必须遵循的关键规则
- drives tax filing period, not
completedDate. Set it to the date of actual delivery/ownership transfer.transactionDate - Only completed orders create tax liability and appear in filings.
- One cart/order per unique destination address — TaxCloud does not support multi-destination within a single request.
- Sending the same overwrites the existing cart entirely (UPSERT semantics).
cartId - Never convert a cart before payment is confirmed — it creates irrevocable tax records.
- Send all transactions to TaxCloud even when tax is zero — no-nexus states still contribute to economic nexus threshold tracking.
- on imported orders that were already filed elsewhere to prevent double-filing.
excludeFromFiling: true - Direct attach is preferred over
exemptionIdauto-match — auto-match leaves orders "Exempt—No certificate" if no cert is found.isExempt: true
- 决定税务申报周期，而非
completedDate。将其设置为实际交付/所有权转移的日期。transactionDate - 仅已完成订单会产生纳税义务并出现在申报记录中。
- 每个唯一目标地址对应一个购物车/订单——TaxCloud不支持单个请求中包含多个目标地址。
- 发送相同的会完全覆盖现有购物车（UPSERT语义）。
cartId - 确认付款前切勿将购物车转换为订单——这会创建不可撤销的税务记录。
- 即使税费为零，也要将所有交易发送至TaxCloud——无纳税关联的州仍会影响经济纳税关联阈值的追踪。
- 对已在其他地方完成申报的导入订单设置，以避免重复申报。
excludeFromFiling: true - 优先直接附加，而非使用
exemptionId自动匹配——若未找到证明，自动匹配会将订单标记为“免税——无证明”。isExempt: true
Endpoint Quick Reference
端点速查
| Operation | Method | Path |
|---|---|---|
| Health check | GET | |
| Calculate tax / create cart | POST | |
| Convert cart to order | POST | |
| Create order (upload) | POST | |
| Get order | GET | |
| Update order (complete) | PATCH | |
| Refund order | POST | |
| Create exemption certificate | POST | |
| Get exemption certificates | GET | |
| Get certificate by ID | GET | |
| Disable certificate | DELETE | |
| TIC search | POST | |
| Verify address | POST | |
| 操作 | 请求方法 | 路径 |
|---|---|---|
| 健康检查 | GET | |
| 计算税费/创建购物车 | POST | |
| 将购物车转换为订单 | POST | |
| 创建订单（上传） | POST | |
| 获取订单 | GET | |
| 更新订单（标记完成） | PATCH | |
| 退款订单 | POST | |
| 创建免税证明 | POST | |
| 获取免税证明 | GET | |
| 通过ID获取证明 | GET | |
| 禁用证明 | DELETE | |
| TIC搜索 | POST | |
| 地址验证 | POST | |
Two API Base URLs
两个API基础URL
The Sales Tax API and the Management API have different base URLs:
| API | Base URL | Auth | Used for |
|---|---|---|---|
| Sales Tax API | | | All cart/order/refund/exemption operations |
| Management API | | Special scoped key (contact support) | Product catalog, access key management |
| Health check | | None | Service status (no auth needed) |
⚠️ Management API requires special API keys — standard dashboard-generated keys do not have the necessary scopes. Contact TaxCloud support (service@taxcloud.net) to have them provisioned.
销售税API和管理API拥有不同的基础URL：
| API | 基础URL | 认证方式 | 用途 |
|---|---|---|---|
| 销售税API | | | 所有购物车/订单/退款/免税操作 |
| 管理API | | 特殊范围密钥（联系支持） | 产品目录、访问密钥管理 |
| 健康检查 | | 无 | 服务状态（无需认证） |
⚠️ 管理API需要特殊API密钥——标准控制台生成的密钥不具备必要的权限范围。请联系TaxCloud支持（service@taxcloud.net）获取。
Security: Server-Side Only
安全：仅在服务端调用
Never call TaxCloud from browser JavaScript. Your must never be exposed to the client. In a Vue.js app, all TaxCloud calls go through your Node.js backend. Your Vue components call your own API endpoints (e.g., , ), which then call TaxCloud server-side.
X-API-KEYPOST /api/cart/taxPOST /api/orders切勿从浏览器JavaScript中调用TaxCloud。你的绝不能暴露给客户端。在Vue.js应用中，所有TaxCloud调用都需通过你的Node.js后端进行。Vue组件调用你自己的API端点（如、），再由后端服务端调用TaxCloud。
X-API-KEYPOST /api/cart/taxPOST /api/ordersCommon Patterns (TypeScript)
常见模式（TypeScript）
typescript
// server-side only — never in Vue components
const BASE_URL = `https://api.v3.taxcloud.com/tax/connections/${process.env.TAXCLOUD_CONNECTION_ID}`;
const HEADERS = {
'X-API-KEY': process.env.TAXCLOUD_API_KEY!,
'Content-Type': 'application/json',
};
async function taxcloud<T>(path: string, method = 'GET', body?: unknown): Promise<T> {
const res = await fetch(`${BASE_URL}${path}`, {
method,
headers: HEADERS,
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw Object.assign(new Error(`TaxCloud ${res.status}: ${err.detail ?? res.statusText}`), { status: res.status, body: err });
}
return res.json();
}For a fully typed client generated from the OpenAPI spec, see .
references/10-typescript-client.mdtypescript
// server-side only — never in Vue components
const BASE_URL = `https://api.v3.taxcloud.com/tax/connections/${process.env.TAXCLOUD_CONNECTION_ID}`;
const HEADERS = {
'X-API-KEY': process.env.TAXCLOUD_API_KEY!,
'Content-Type': 'application/json',
};
async function taxcloud<T>(path: string, method = 'GET', body?: unknown): Promise<T> {
const res = await fetch(`${BASE_URL}${path}`, {
method,
headers: HEADERS,
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw Object.assign(new Error(`TaxCloud ${res.status}: ${err.detail ?? res.statusText}`), { status: res.status, body: err });
}
return res.json();
}如需从OpenAPI规范生成完整的类型化客户端，请查看。
references/10-typescript-client.md