mcpField
T
tax-compliance-automation

tax-compliance-automation

github.com/finsilabs其他60117 次安装6 天前更新
代码仓库

关于 tax-compliance-automation

面向电商税务合规自动化的技能,覆盖税务关联跟踪、结账时税额计算、免税证明管理、申报和审计记录。内容说明了如何在不同平台使用 TaxJar、Avalara 等方案。

主要功能

  1. 01跟踪税务关联门槛
  2. 02结账时实时计算税额
  3. 03管理 B2B 免税证明
  4. 04自动申报销售税及 VAT
  5. 05生成可审计的税务记录

适用场景

  1. 01判断在美国哪些州需要注册
  2. 02为欧洲订单处理 OSS/IOSS VAT
  3. 03管理 B2B 客户免税证明
  4. 04准备可核对的审计税务记录

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/finsilabs/awesome-ecommerce-skills --skill tax-compliance-automation

安装后在 Claude Code 中输入/tax-compliance-automation确认已加载。

包含的文件

除 SKILL.md 外,安装时一起下载的参考资料和脚本。

tile.json
evals/audit-ready-tax-reporting-and-exemption-/
criteria.json
task.md
evals/eu-vat-calculation-and-oss-quarterly-rep/
criteria.json
task.md
evals/us-economic-nexus-threshold-tracking/
criteria.json
task.md

详细介绍

税务合规自动化

概述

对于电商业务而言,税务合规是规模化运营中最复杂的挑战之一。仅在美国,就有超过 13,000 个征税辖区,各自拥有不同的税率、商品应税规则、申报频率和经济关联门槛。在国际市场,增值税(欧洲、英国、澳大利亚)和商品及服务税(加拿大、印度、新西兰)又增加了额外的合规层级,各自都有注册门槛、发票要求和申报义务。

此技能涵盖完整的税务合规生命周期:跟踪关联门槛,以了解何时必须在新的辖区注册;在结账时实时计算税款;为 B2B 客户管理免税证明;自动申报;以及生成可供审计的报告。所有主流平台都与 TaxJar 和 Avalara 直接集成,无需编写自定义代码即可处理这些事项。

何时使用此技能

  • 当您的商店向美国多个州的客户发货,且不确定关联义务时
  • 当您需要根据 OSS/IOSS 为欧洲客户征收欧盟增值税时
  • 当您构建需要管理免税证明的 B2B 电商业务时
  • 当当前税率是硬编码的,且已超过 12 个月未更新时
  • 当您准备接受审计,需要有据可查且可核对的税务记录时
  • 当您在新国家/地区开展业务,需要了解增值税/商品及服务税注册要求时

核心说明

第 1 步:确定您的平台并选择合适的税务合规工具
平台推荐工具备注
ShopifyShopify Tax(内置)+ TaxJar 或 Avalara AvaTax(Shopify 应用商店)Shopify Tax 涵盖基本的美国经济关联;TaxJar 和 Avalara 还提供自动申报、免税证明管理和国际增值税支持
WooCommerceTaxJar for WooCommerce(免费插件)或 Avalara AvaTax for WooCommerceTaxJar 是最受欢迎的 WooCommerce 税务插件;可从 Avalara 网站获取 Avalara 插件
BigCommerceAvalara AvaTax(原生集成)或 TaxJar(通过 BigCommerce 应用市场)BigCommerce 提供原生 Avalara 连接器;应用市场也提供 TaxJar
自定义 / 无头架构TaxJar API 或 Avalara AvaTax API在结账时调用 API 获取实时税率;付款后提交交易,以便留存申报记录

自动申报方面:

  • TaxJar AutoFile:TaxJar Plus 和 Professional 计划提供此功能;可在已注册的州自动申报纳税申报表
  • Avalara Returns:Avalara 订阅中内置此功能;可处理美国和国际申报
  • Vertex:适用于商品应税规则复杂的大型零售商的企业级方案;成本显著高于 TaxJar 或 Avalara

第 2 步:设置关联注册和实时税款计算

Shopify

步骤 1:在 Shopify 中登记关联州

  1. 前往 Settings → Taxes and duties → United States
  2. 点击 Collect sales tax,并选择您有关联关系的州
  3. 输入该州的销售税许可证编号——Shopify 会将其用于您的税款汇缴记录
  4. 对您有关联关系的每个州(实体或经济关联)重复上述操作
  5. 对于欧盟:点击税区下的 European Union,并配置您的 VAT 注册号(OSS 或按国家/地区注册)

步骤 2:安装 TaxJar,实现全面合规自动化

  1. 从 Shopify App Store 安装 TaxJar(搜索“TaxJar”)
  2. 在 taxjar.com 注册,并从 Account → TaxJar API 获取 API 令牌
  3. 在 TaxJar Shopify 应用中输入 API 令牌,然后点击 Connect
  4. 在 TaxJar 中配置您的关联州:前往 TaxJar Dashboard → Account → States with Nexus,添加您已注册的每个州
  5. 在 TaxJar 应用中启用 Transaction Sync——已完成的 Shopify 订单会自动发送至 TaxJar,以供申报记录使用
  6. 如果希望 TaxJar 代表您提交申报表,请在 TaxJar → Account → AutoFile 中启用 AutoFile(需要 TaxJar Plus 或 Professional 方案)

Shopify 上的免税证明:

  1. 从 Shopify App Store 安装 Avalara CertCapture,或使用 TaxJar 在 TaxJar → Exemptions 下的证明管理功能
  2. B2B 客户可以通过托管门户上传免税证明;审核通过后,系统会自动将其应用于后续订单

Shopify 上的欧盟 VAT:

  • 前往 Settings → Taxes and duties → European Union
  • 添加您的 OSS 注册号(格式:EU + 您所在国家/地区的 VAT 编号)
  • Shopify 会根据客户的收货地址,自动应用相应欧盟国家/地区的 VAT 税率
  • 对于 IOSS(适用于从欧盟以外寄出、金额低于 €150 的订单的进口 OSS):在 Settings → Taxes → Duties and import taxes 中输入您的 IOSS 编号

WooCommerce

步骤 1:安装并配置 TaxJar

  1. 在 taxjar.com 注册并获取 API 令牌
  2. 安装 TaxJar for WooCommerce 插件(免费,可从 WordPress.org 获取——搜索“TaxJar”)
  3. 前往 WooCommerce → TaxJar 并输入 API 令牌
  4. 启用 Automatic Tax Calculation——TaxJar 会在结账时实时计算正确税率
  5. 启用 Transaction Sync——已完成的订单会自动发送至 TaxJar,以供申报记录使用
  6. 输入您的发货地址(仓库地址)——该地址将用于确定关联关系的起始地

步骤 2:在 TaxJar 中配置关联州

  1. 登录 taxjar.com → Account → States with Nexus
  2. 添加您持有销售税许可证的每个美国州
  3. 对于每个关联州,输入您的销售税注册号
  4. TaxJar 只会为寄往关联州的订单计算并记录税款

步骤 3:启用申报自动化

  1. 升级至 TaxJar Plus 或 Professional,以使用 AutoFile
  2. 前往 TaxJar → Account → AutoFile,并为每个州启用 AutoFile
  3. TaxJar 会在到期日之前代表您自动提交申报并汇缴税款

WooCommerce 上的免税证明:

  • 安装 WooCommerce B2B 插件,或使用 TaxJar 的证明管理功能:前往 TaxJar → Exemptions,按电子邮件地址或客户类型添加免税客户
  • 拥有“wholesale”或“reseller”角色的客户可以被自动标记为免税

WooCommerce 上的欧盟 VAT:

  • 安装 WooCommerce EU VAT Assistant 或 WooCommerce Germanized(用于符合德国特定的合规要求)
  • 前往 WooCommerce → Settings → Tax → EU VAT,并输入您的 OSS 注册号
  • 插件会自动应用相应欧盟国家/地区的 VAT 税率,并生成合规发票

BigCommerce

步骤 1:连接 Avalara AvaTax(推荐)

  1. 前往 Settings → Tax → Tax Provider
  2. 选择 Avalara AvaTax — BigCommerce 提供原生 Avalara 连接器
  3. 点击 Connect 并登录 Avalara 账户(如有需要,请在 avalara.com 注册)
  4. Avalara 会自动用实时合规税率取代 BigCommerce 内置的税务引擎

步骤 2:在 Avalara 中配置纳税关联

  1. 登录 Avalara Dashboard → Settings → Company → Nexus
  2. 添加您已注册的每个美国州或国家/地区
  3. 输入您在各管辖区的注册编号
  4. Avalara 只会针对您有纳税关联的管辖区计算并记录税款

步骤 3:启用 Avalara Returns

  1. 在 Avalara Dashboard → Returns 中,为每个有纳税关联的州启用 Managed Returns
  2. Avalara 会自动准备并提交申报表;对于您希望在提交前审核的州,请使用 Unmanaged Returns(Avalara 会为您准备申报表,供您提交)

BigCommerce 上的免税证明管理:

  • 使用 Avalara CertCapture — 前往 Avalara Dashboard → CertCapture 并配置证明收集门户
  • 客户会收到上传免税证明的链接;在 CertCapture 中审核通过后,后续订单会自动免税

BigCommerce 上的欧盟增值税:

  • 前往 Store Setup → Tax → VAT 并启用 VAT by country
  • 输入您的 OSS 或各国增值税注册编号
  • 如需全面符合 OSS 规定并自动申报,请使用 Avalara 的 VAT Reporting 模块 — 联系 Avalara 设置国际增值税

自定义 / 无头架构

使用 TaxJar API 或 Avalara AvaTax API 进行实时计算并记录申报信息:

TaxJar 在结账时进行实时计算:

const Taxjar = require('taxjar');
const taxjar = new Taxjar({ apiKey: process.env.TAXJAR_API_KEY });

async function calculateTaxForOrder({ fromAddress, toAddress, lineItems, shippingCost }) {
  const response = await taxjar.taxForOrder({
    from_country: fromAddress.country,
    from_zip: fromAddress.zip,
    from_state: fromAddress.state,
    to_country: toAddress.country,
    to_zip: toAddress.zip,
    to_state: toAddress.state,
    to_city: toAddress.city,
    amount: lineItems.reduce((sum, i) => sum + i.unit_price * i.quantity, 0),
    shipping: shippingCost,
    line_items: lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.unit_price,
      product_tax_code: item.taxCode ?? null, // e.g., '20010' for general goods
      exemption_type: item.exemptionType ?? null,
    })),
    exemption_type: customer.exemptionType ?? null, // 'wholesale', 'government', etc.
  });

  return {
    totalTax: response.tax.amount_to_collect,
    taxRate: response.tax.rate,
    hasNexus: response.tax.has_nexus,   // false = no tax to collect in this jurisdiction
    breakdown: response.tax.breakdown,
  };
}

付款后提交交易(申报记录所必需):

async function commitTaxTransaction(order) {
  await taxjar.createOrder({
    transaction_id: order.id,
    transaction_date: new Date().toISOString().split('T')[0],
    from_country: WAREHOUSE_ADDRESS.country,
    from_zip: WAREHOUSE_ADDRESS.zip,
    from_state: WAREHOUSE_ADDRESS.state,
    to_country: order.shippingAddress.country,
    to_zip: order.shippingAddress.zip,
    to_state: order.shippingAddress.state,
    amount: order.subtotal,
    shipping: order.shippingCost,
    sales_tax: order.taxAmount,
    line_items: order.lineItems.map(item => ({
      id: item.id,
      quantity: item.quantity,
      unit_price: item.price,
      sales_tax: item.taxAmount,
    })),
  });
}

// On refund: void the transaction so it is excluded from filing reports
async function voidTaxTransaction(orderId) {
  await taxjar.deleteOrder(orderId);
}

欧盟 B2B 增值税反向征收 — 通过 VIES 验证增值税编号:

async function validateEUVATNumber(vatNumber) {
  const countryCode = vatNumber.slice(0, 2);
  const number = vatNumber.slice(2);
  const res = await fetch(
    `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${countryCode}/vat/${number}`
  );
  const data = await res.json();
  return data.isValid === true;
  // If valid: apply zero-rate (reverse charge); if invalid: charge local VAT rate
}

纳税关联门槛监控: TaxJar 在 TaxJar Dashboard 中提供 Economic Nexus Insights 功能,可自动跟踪您在各州的销售额,并在您接近门槛时发出提醒。在 TaxJar Dashboard → Economic Nexus Insights 中访问此功能 — 这样便无需构建自定义门槛跟踪代码。


步骤 3:验证并管理免税证明

美国 B2B 销售:对客户适用零税率前,必须收集并验证免税证明。不得仅凭客户自行声明就给予免税。

  • Avalara CertCapture:最全面的解决方案 — 可处理证明收集、验证、续期提醒以及各州特定的表格要求。可作为任何 Avalara 订阅的附加服务使用。
  • TaxJar Exemptions:更简便的选项 — 在 TaxJar Dashboard → Customers → Exemptions 中按电子邮件、客户 ID 或客户类型添加免税客户。TaxJar 会自动跳过这些客户的税额计算。
  • 对于 WooCommerce:WooCommerce B2B 插件或 WooCommerce Tax Exemptions 插件可在批发客户结账时要求上传免税证明。

证明存储要求:

  • 保存证明至少 4 年(大多数州的要求),或保存至您在签发州与该客户的最后一笔交易发生后 3 年
  • 存储在可搜索的系统中 — 审计期间,您可能需要在短时间内提供证明

步骤 4:设置自动申报
申报方式适用场景
TaxJar AutoFile使用 TaxJar 的美国商店;适用于 Plus/Professional 计划;涵盖全部 50 个州
Avalara Managed ReturnsAvalara 客户;可处理美国各州和部分国际司法管辖区的申报
Avalara VAT Reporting欧盟/英国/澳大利亚增值税申报;Avalara 会为你准备 OSS 申报表
使用 TaxJar 报告手动申报适用于申报频率较低的用户(每季度或每年);导出 TaxJar 预填的州申报数据,然后在各州税务机关网站上手动申报

申报日历设置:

  1. 登录 TaxJar 或 Avalara 控制面板,并确认每个已注册州的申报频率(每月、每季度或每年,由各州根据你的销售额确定)
  2. 为每个州启用 AutoFile 或 Managed Returns
  3. 确认银行账户已连接,以便自动汇缴税款——前往 TaxJar → Account → AutoFile → Payment Method 或 Avalara → Settings → Bank Accounts
  4. 在账户通知设置中设置申报确认邮件提醒

最佳实践

  • 切勿自行建立税率表——税率会不断变化。API 成本远低于因收取错误金额或遗漏税率更新而产生的风险。
  • 在达到经济关联门槛前完成注册——一旦触发经济关联,你可能需要从触发日期起追溯缴税。监控 TaxJar Economic Nexus Insights 控制面板,并在达到某州门槛的 80% 时完成注册。
  • 付款后再提交交易,而不是付款前——只有已提交的交易才会显示在申报报告中。应在确认付款后提交,而不是在创建订单时提交。
  • 退款时作废税务交易——发起退款时,请在 TaxJar 或 Avalara 中作废相应的税务交易,以免申报时多报。
  • 应用零税率前验证免税证明——使用 Avalara CertCapture 或 TaxJar Exemptions 管理证明;没有存档证明时,切勿接受免税申请。
  • 单独处理数字商品——美国大多数州和所有欧盟国家对数字商品、SaaS 和流媒体都有特殊的应税规则。为每种数字商品设置正确的 TaxJar 商品税代码(例如,SaaS 使用 DC010100)或 Avalara 税码。

常见问题

问题解决方案
结账时已计算税额,但未提交到 TaxJar/Avalara确认平台插件的 Transaction Sync 设置已启用;在服务提供商的交易控制面板中检查是否有遗漏订单
欧盟跨境 B2B 销售被收取增值税应用反向征税前,通过 VIES 验证买方的增值税号;如果验证失败,则按 B2C 交易收取增值税
含增值税与不含增值税的定价方式混淆预先决定价格是否含增值税(欧盟 B2C 的常见做法)或不含增值税(美国的常见做法);将平台税务设置配置为与之匹配——混用两种方式会导致结账总额错误
收购尽职调查期间发现遗漏的经济关联注册使用 TaxJar 的 Nexus Insights 每年审查经济关联情况;收购方会将未披露的税务负债视为重大风险
B2B 客户声称免税,但档案中没有有效证明应用免税前务必收集并存档证明;使用 Avalara CertCapture 或 TaxJar Exemptions 在结账时强制执行此要求
欧盟 VAT OSS 申报的货币兑换OSS 季度申报必须以 EUR 提交;使用申报期的 ECB 汇率,而不是每笔交易日期的汇率——Avalara 的 VAT Reporting 模块会自动处理
安装 TaxJar 后 Shopify 显示税额为 $0确认 TaxJar API 密钥正确;检查 TaxJar 控制面板和 Shopify 应用设置中是否都已配置经济关联州;确认仓库地址设置正确

Related Skills

  • @tax-calculation
  • @payment-reconciliation-automation
  • @invoice-generation-automation
  • @checkout-flow-optimization
  • @multi-currency

评论

支持 Markdown