README

Craft CMS 4.x 的 TaxCloud 插件

Craft Commerce 的 TaxCloud 集成

⚠️ TaxCloud API 只支持美国目的地。此插件将接管内置的税引擎，因此安装后 Commerce 不会计算非美国税费或使用自定义税规则。

要求

此插件需要 Craft Commerce (Pro 版本) 4.0 或更高版本。

安装

要安装插件，请按照以下说明操作。

打开您的终端并转到您的 Craft 项目
```
 cd /path/to/project
```

然后告诉 Composer 加载插件

 composer require surprisehighway/craft-taxcloud

在控制面板中，转到设置 → 插件，然后点击 TaxCloud 的“安装”按钮。

配置 TaxCloud

步骤 1：配置插件

添加您的 API 连接设置和插件默认值

在您的 .env 文件中定义 TAXCLOUD_API_ID 和 TAXCLOUD_API_KEY 环境变量。

# Set your TaxCloud API ID
TAXCLOUD_API_ID="xxxxxxxx"

# Set your TaxCloud API Key
TAXCLOUD_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

使用位于 vendor/surprisehighway/taxcloud/config.php 的示例创建一个 config/taxcloud.php 文件

<?php

return [
	'apiId' => getenv('TAXCLOUD_API_ID'),
	'apiKey' => getenv('TAXCLOUD_API_KEY'),
	'verifyAddress' => false,
	'enableCapture' => true,
	'defaultShippingTic' => '11010',
];

提示： 您可以通过导航到 [your_cp_url]/actions/taxcloud/categories/ping 来检查您的连接设置

步骤 2：同步您的税类别

要同步您的税类别与 TaxCloud 的 TICs，请转到控制面板中的 Commerce → Tax → Tax Categories 并点击“同步 TaxCloud 类别”按钮。

同步完成后，将您将使用的类别分配给您的 产品类型，以便在产品条目中可供选择。您可能还想设置一个默认类别，例如“未分类 - 00000”。

警告： 不要更改税类别处理程序，因为它们用于保持类别同步，您可能会造成重复。注意，处理程序是实际发送到 TaxCloud 的 TIC 代码值。您可以更改名称和描述。

步骤 3：检查您的商店位置

转到 Commerce → Store Settings → Store Location 并确保地址已正确设置。这将被 TaxCloud 用作运输起点，并且是必需的。

使用 TaxCloud

一旦一切设置完成，税费调整将根据产品条目中的税类别自动添加到新订单。

注意： TaxCloud 返回每行的销售税，并且插件将总税额设置为订单调整。

完整的 TaxCloud API 响应在 craft_commerce_orderadjustments 数据库表中的订单调整的 sourceSnapshot 中存储。

关于地址验证的说明

TaxCloud 服务依赖于有效的地址来计算销售税。如果您没有以其他方式执行地址验证，您可以在插件中启用地址验证，通过设置配置选项 "verifyAddress" => true。

如果启用了地址验证，插件将尝试使用 TaxCloud API 验证地址，如果 TaxCloud 返回已验证的地址，后续的税查找将使用已验证的地址。例如，已验证的地址将包含 zip+4，即使用户没有输入它，也会使税费计算更准确。 如果未匹配已验证的地址，将根据 TaxCloud 的指南提交税查找。

关于销售和折扣的说明

TaxCloud 不接受单独的行项目折扣或调整。Craft 中的促销商品会自动将销售价格发送到 TaxCloud 进行税务计算。折扣将通过插件计算，并将减价后的行项目价格发送到 TaxCloud 进行税务计算，具体操作请按照 TaxCloud 指引进行点击这里。

TaxCloud 路线图

一些待办事项和潜在功能的想法

发布它
替换 Craft Commerce 内置的税务引擎
使用从 TaxCloud 同步的税务类别管理产品 TICs
来自 TaxCloud 的实时税率
在 TaxCloud 中授权和捕获订单以进行报告
处理折扣
处理退款

由 Surprise Highway 提供

信用

此插件在代码上主要基于第一方 TaxJar 插件，并采用使用税务类别而不是 TICs 字段的方法。

surprisehighway / craft-taxcloud

维护者

详细信息