README

使用Avalara的AvaTax服务计算并将销售税添加到订单的基础税中。

要求

此插件需要Craft CMS 3.1.0或更高版本以及Craft Commerce 2.0或更高版本。

相关：本插件的Craft 2.x Commerce 1.x 版本已不再积极维护，但仍受支持。

安装

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

打开您的终端并转到您的Craft项目
```
 cd /path/to/project
```
然后告诉Composer加载插件
```
 composer require unionco/craft-avatax
```
在控制面板中，转到设置 → 插件，并点击Avatax的“安装”按钮。

设置概述

设置和配置的详细信息如下，但以下是一个快速概述，说明您需要做什么才能开始

使用您的Avalara账户信息和测试连接配置插件设置。
使用您的原始地址和默认税代码配置插件设置。
将“Avatax”税类别设置为可用的产品类型。
将“Avatax”税类别分配给您的产品。
可选：将特定于产品的税代码字段添加到您的产品类型字段中，以允许每个产品的税代码。
可选：将客户使用类型字段添加到您的用户字段中，以设置免税客户。

配置AvaTax账户连接

访问设置页面“设置 → Avatax”
为每个环境输入您的账户ID、许可证密钥和公司代码凭据。
选择“沙盒”或“生产”将启用所选环境。
单击“测试连接”按钮以验证您的连接。
单击“保存”按钮以保存您的设置。

配置AvaTax发货原地址

指定一个有效的发货地址。
单击“保存”按钮以保存您的设置。

配置AvaTax插件选项

访问设置页面“设置 → Avatax”
启用税计算 - 独立于其他设置启用或禁用税计算。
启用提交 - 启用或禁用文档提交。
启用地址验证 - 启用或禁用Avalara的地址验证。
启用调试 - 在设置和测试时启用调试以记录所有API交互。务必在上线时禁用。
单击“保存”按钮以保存您的设置。

使用AvaTax

访问“商业 → 设置 → 税率类别”。应该存在一个处理程序为“avatax”的税率类别，如果不存在，则创建一个。
单击Avatax税率类别。检查Avalara税率将可用到的产品类型。

完成安装和配置后，AvaTax将为所有具有有效发货地址且选择AvaTax税率类别的产品的订单计算并应用销售税。

税代码

例如，'P0000000' - 有形个人财产（TPP）.

您可以通过在插件设置中设置默认税代码值来设置默认的Avalara税代码。这是将发送到Avalara的所有产品的默认税代码。

您还可以通过向您的产品添加自定义字段来为每个产品设置特定的税代码。

设置产品字段

访问设置 → 字段。您应该会看到一个名为 "AvaTax 税码" 的字段，这是在插件安装过程中创建的。如果没有创建，请创建一个。注意，"名称" 字段可以是您想要的任何内容，例如 "AvaTax 税码" 或 "产品税码"，但 "处理" 字段必须与 avataxTaxCode 匹配，并且区分大小写。
访问商务 → 设置 → 产品类型，然后点击您产品类型的名称。
点击 产品字段 选项卡。
添加 AvaTax 税码字段并保存。

在您的产品条目中，您现在可以输入任何文本作为 AvaTax 税码发送。如果此字段不存在或留空，则将使用配置文件中的默认税码设置。

提示：默认情况下，该字段是纯文本，但只要处理保持不变，您可以将它更改为具有预配置值的下拉列表，以适应您的用例。

运费代码

例如 'FR' - 仅运费 - 公共承运人 - 目的地 FOB。

运费作为单独的行项发送给 AvaTax。您可以通过设置插件设置中的默认 Avalara 税码为运费设置默认值。

免税客户

您可以通过添加自定义字段到您的用户设置中，用于指定一个 Avalara 实体/用途代码来指定一个免税客户。

设置用户字段

访问设置 → 字段。您应该会看到一个名为 "AvaTax 客户用途类型" 的字段，这是在插件安装过程中创建的。如果没有创建，请创建一个。注意，"名称" 字段可以是您想要的任何内容，例如 "AvaTax 客户用途类型" 或 "实体/用途代码"，但 "处理" 字段必须与 avataxCustomerUsageType 匹配，并且区分大小写。
访问设置 → 用户 → 字段。
添加 AvaTax 客户用途类型字段并保存。

在您的用户账户中，您现在可以设置一个实体/用途代码以发送给 Avalara。如果您允许用户在前端编辑自己的个人资料，则如何实现这一点取决于您，但在大多数情况下，这很可能是管理任务。

这要求在结账时登录的用户必须是已注册的用户，而不是匿名结账。

提示：默认情况下，此下拉字段包含所有默认的 Avalara 实体/用途代码，但您可以根据自己的用例或如果您已在 AvaTax 网站上设置了自定义代码来编辑选项。

促销活动

促销活动受支持。对于销售，销售价格将简单地作为行项金额发送给 Avalara。折扣将作为使用 默认折扣代码 插件设置作为 Avalara 税码的单独行项发送。

退款

Craft Commerce 支持已完成交易的退款，如果支付网关支持退款。如果订单支持退款，Commerce 将在订单的交易历史中显示 "退款" 按钮。

从 Commerce 2.0 开始，可以从管理员控制面板多次启动部分退款。触发全额退款以原订单的准确金额将生成对应 AvaTax 交易的全额退货发票。请注意，触发部分退款将生成对应 AvaTax 客户的部分金额退货发票，但不与原始交易相关联。这是因为 AvaTax 只对交易全额、特定行项或百分比进行退款。

客户代码

默认情况下，插件会将订单电子邮件地址作为客户代码发送给Avalara。通过这个“隐藏”功能，您可以选择覆盖此行为，使用具有特定处理器的用户或订单字段中保存的值。此字段在您安装插件时不会自动创建，您必须手动创建它。

设置字段

创建一个名为“Avatax客户号码”的用户或订单字段，处理器为avataxCustomerCode。处理器必须完全匹配，并且区分大小写。

请注意，您有权自行决定如何保存或验证字段值。如果字段为空或不存在，插件将简单地使用字段值（如果可用），否则将默认使用订单电子邮件地址。

配置覆盖

您可以使用Craft的插件配置文件支持来覆盖控制面板中许多插件设置。这很方便用于“锁定”某些设置，并且还可以提供按环境设置。

将avataxtax目录中的config.php复制到您的craft/config文件夹，并将其重命名为avatax.php
在avatax.php中更新值并保存。

AJAX示例

您可以使用JSON控制器端点进行前端AJAX查找/验证。目前唯一的端点是地址验证和通过客户号码进行CertCapture客户查找。

AJAX地址验证

您可以使用前端AJAX查找来调用AvaTax的解析地址API。注意，如果您在前端实现此功能，则可能希望禁用插件设置中的地址验证，以避免结账过程中进行更多API调用（JSON端点仍然有效）。

此示例使用默认的Commerce 2地址表单字段和jQuery执行AJAX调用，以提供起点，但jQuery不是必需的，您必须根据您的结账流程来实现。

{% js %}

    $('#address-form').on('submit.addressValidation', function(e) {

        e.preventDefault();

        var $form = $(this);

        var data = {
            address1   : $('[name="shippingAddress[address1]"]').val(),
            address2   : $('[name="shippingAddress[address2]"]').val(),
            city       : $('[name="shippingAddress[city]"]').val(),
            zipCode    : $('[name="shippingAddress[zipCode]"]').val(),
            stateValue : $('[name="shippingAddress[stateValue]"]').val(),
            countryId  : $('[name="shippingAddress[countryId]"]').val()
        };

        var csrfTokenName  = "{{ craft.app.config.general.csrfTokenName }}";
        var csrfTokenValue = "{{ craft.app.request.csrfToken }}";

        data[csrfTokenName] = csrfTokenValue;

        $.ajax({
            type: 'post',
            url: '/actions/avatax/json/validate-address', 
            data: data,
            dataType: 'json'            
        }).done(function(data){

            console.log(data);

            if(data.success) {
                // valid address
                $form.off('submit.addressValidation').submit();
            } else {

                // handle error here...

                return false;
            }
        });
    });

{% endjs %}

CertCapture客户查找

将自定义客户代码传递给AvaTax的一个示例用例是，如果在一个连接的CertCapture帐户中找到匹配的客户，则基于该客户的证书自动应用AvaTax中的免税税额。

在这种情况下，您可能希望在将客户号码传递给AvaTax之前，先在CertCapture中验证客户号码字段，看是否找到匹配的客户。

在使用此API之前，您需要将CertCapture凭据添加到您的config/avatax.php文件中。

<?php

return [

    // ... other settings ...

    'certCaptureUsername' => 'username',
    'certCapturePassword' => 'password',
    'certCaptureClientId' => '123456',

];

此示例演示了一个潜在的按钮点击处理器，该处理器通过向插件的JSON端点发送AJAX请求来触发CertCapture中的客户号码查找。如果找到匹配的客户，插件将返回成功和CertCapture响应以及客户信息；如果没有找到匹配项，则返回错误。请注意，CertCapture客户号码区分大小写。jQuery不是必需的，您必须根据您的结账流程来实现。

{% js %}
    
    $('button.validate-customer').on('click', function(e) {

        e.preventDefault();

        var data = { number: $('[name="fields[avataxCustomerCode]"]').val() };

        var csrfTokenName  = "{{ craft.app.config.general.csrfTokenName }}";
        var csrfTokenValue = "{{ craft.app.request.csrfToken }}";

        data[csrfTokenName] = csrfTokenValue;

        $.ajax({
            type: 'post',
            url: '/actions/avatax/json/cert-capture-customer', 
            data: data,
            dataType: 'json'            
        }).done(function(data){

            console.log(data);

            if(data.success) {

                // customer found, show valid state or submit form...

            } else {

                // invalid customer number, handle error here...
            }
        });
    });

{% endjs %}

AvaTax插件路线图

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

更好的异常处理
在产品类型级别设置默认税码的配置设置。

由Surprise Highway提供

abryrath / craft-avatax

维护者

详细信息