README

ShipStation Connect for Craft CMS 4 和 Commerce 4

用于与 ShipStation 自定义商店集成的 Craft Commerce 插件。

要求

此插件需要 Craft CMS 4 和 Commerce 4 或更高版本。

安装

从插件商店或使用 Composer 安装 ShipStation Connect。

从插件商店安装

转到项目控制面板中的插件商店，搜索“ShipStation Connect”。在其模态窗口中点击“安装”按钮。

使用 Composer

打开终端（命令行）并运行以下命令

# go to the project directory
cd /path/to/my-project

# tell Composer to load the plugin
composer require fostercommerce/shipstationconnect

# tell Craft to install the plugin
./craft install/plugin shipstationconnect

安装后，转到 Craft 控制面板插件设置页面以配置插件设置。

自定义商店配置

按照以下说明在 ShipStation 中配置您的连接： ShipStation "自定义商店" 集成。

将您的 Craft 商店连接到 ShipStation

“自定义 XML 页面的 URL”显示在 Craft 的 ShipStation Connect 设置视图中。

用户名/密码

ShipStation 允许您为已连接的商店设置自定义用户名和密码组合。此组合应与 Craft 控制面板中 ShipStation Connect 设置视图中的存储值匹配。

注意：这些不是您的 ShipStation 凭证，也不是您的 Craft 用户凭证。

截至版本 1.2.4，这些值可以用环境变量设置。

使用 Craft 的基本身份验证

截至 Craft 3.5.0，可以使用基本身份验证头通过设置 enableBasicHttpAuth 配置设置将 true。

如果您的网站启用了基本身份验证，ShipStation Connect 将假设对其的请求已经经过身份验证并继续处理。使用此功能可删除在设置中设置用户名/密码的要求，并建议创建具有 shipstationconnect-processOrders 权限的专用用户以访问 ShipStation Connect。

当 enableBasicHttpAuth 为 false 时，插件将读取身份验证头并验证与 ShipStation Connect 设置中配置的用户名/密码。

调试 Apache 身份验证错误

远程服务器返回错误

如果您看到 400 错误（特别是 401 或 404）并且您正在运行 Apache，请尝试将以下内容添加到您的 Apache 配置中。

CGIPassAuth On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

订单状态

确保 Craft Commerce 和 ShipStation 中的发货状态匹配。您需要编辑每个平台以使用自定义状态，并且 ShipStation 可以根据需要将多个 Craft 状态匹配到单个 ShipStation 状态。

商业集成

矩阵字段

ShipStation Connect 需要一个矩阵字段来存储发货信息。

该矩阵字段应具有以下文本字段的块类型：

• 承运人
• 服务
• 跟踪号码

在ShipStation Connnect设置中，选择矩阵字段，并输入块类型和文本字段的句柄。

当收到ShipStation订单的发货通知时，插件将发货信息添加到订单的“发货信息”字段，并将订单设置为与ShipStation商店的“已发货”状态相对应的Craft状态。

将电话号码添加到发送给Shipstation的地址

地址现在是Craft的一部分，而不是Commerce的一部分，电话号码字段已从地址模型中删除。现在需要在地址字段中添加一个自定义字段来存储电话号码。

插件设置为您提供选项，以设置您用于电话号码的字段句柄。然后，该字段的内文将在订单数据的地址部分发送到Shipstation。

自定义字段

您可以通过在自定义模块或插件中监听OrderFieldEvent事件来自定义发送到ShipStation的数据，并按字段设置您想要的值，如下例所示

use yii\base\Event;
use fostercommerce\shipstationconnect\services\Xml;
use fostercommerce\shipstationconnect\events\OrderFieldEvent;

Event::on(
    Xml::class,
    Xml::ORDER_FIELD_EVENT,
    function (OrderFieldEvent $e) {
        $fieldName = $e->field;
        $order = $e->order;

        if ($fieldName === OrderFieldEvent::FIELD_ORDER_NUMBER) {
            // Set ShipStation's order number to the order ID, instead of the default reference number
            $e->value = $order->id;
        } elseif ($fieldName === OrderFieldEvent::FIELD_CUSTOM_FIELD_1) {
            // Store the reference number in a custom field
            $e->value = 'Order Reference: ' . $order->reference;
        }
    }
);

OrderFieldEvent属性

• field - 自定义字段名称，以下之一
• order - 当前订单数据。
• value - 要设置在此字段上的数据。
• cdata - 是否将值包裹在CDATA块中。

如果您已将OrderFieldEvent::FIELD_ORDER_NUMBER字段更改为除订单参考号之外的任何内容，您需要监听OrdersController::FIND_ORDER_EVENT以使用您自己的查询来获取订单。在上面的示例中，我们将其更改为订单ID，因此我们需要通过ID获取订单

use yii\base\Event;
use fostercommerce\shipstationconnect\controllers\OrdersController;
use fostercommerce\shipstationconnect\events\FindOrderEvent;

Event::on(
    OrdersController::class,
    OrdersController::FIND_ORDER_EVENT,
    function (FindOrderEvent $e) {
        $order = Order::find()->id($e->orderNumber)->one();

        if ($order) {
            $e->order = $order;
        }
    }
);

FindOrderEvent属性

• orderNumber - ShipStation发送的订单号。
• order - 将更新发货信息的订单。