README

使用自定义商店集成将Craft Commerce与ShipStation集成。

安装

注意：此插件是为Craft 2.x编写的。它可能在Craft 3+中无法正常工作。

使用composer安装此软件包

composer require onedesign/oneshipstation

使用composer安装后，请转到Craft控制面板插件页面以安装和配置插件设置。

Craft配置

CSRF保护

如果您在应用程序中启用了CSRF保护，则需要在其为ShipStation POST发货通知时禁用它。

在craft/config/general.php中，如果您将enableCsrfProtection设置为true（或在Craft 3+中，如果没有将其设置为false），则需要添加以下内容

return array(
    //...
    'enableCsrfProtection' => !isset($_REQUEST['p']) || $_REQUEST['p'] != '/actions/oneShipStation/orders/process'
)

这将确保对所有不是ShipStation POST的路由启用CSRF保护。

"Action"命名冲突

由于ShipStation和Craft都使用了参数action，因此它们之间发生了路由冲突。ShipStation使用?action=export来读取订单数据，使用?action=shipnotify来更新发货数据。这与Craft保留的单词action冲突，该单词用于描述一个"action请求"，该请求旨在简化路由配置。

因此，ShipStation用于其自定义商店集成的路由必须以您的Craft配置的"actionTrigger"（在craft/config/general.php中）开头，默认为字符串"actions"。

例如，如果您的actionTrigger设置为"actions"，则提供给ShipStation的URL应为

https://{yourdomain.com}/actions/oneShipStation/orders/process

如果您的actionTrigger设置为"myCustomActionTrigger"，则它将是

https://{yourdomain.com}/myCustomActionTrigger/oneShipStation/orders/process

注意：上述URL区分大小写！由于Craft的段匹配，URL中的oneShipStation段必须是oneShipStation，不能是oneshipstation或ONESHIPSTATION。

ShipStation配置

订单状态

当ShipStation将订单标记为已发货时，它会回调Craft以更新订单。此插件假定Craft Commerce中已定义了一个名为"shipped"的订单状态。

身份验证

一旦您已配置Craft应用程序的OneShipStation，您需要通过配置您的ShipStation "自定义商店"集成来完成此过程。

在那里，您将需要提供一个用户名、密码以及ShipStation将用来联系您的应用程序的URL。这些可以在Craft控制面板的插件设置中找到。

在您的站点模板中使用OneShipStation

跟踪信息

One ShipStation提供了一个辅助方法，可以添加到您的模板中，以便向客户提供跟踪发货的链接。

{% for shipmentInfo in order.shippingInfo %}
  {% set tracking = craft.oneShipStation.trackingNumberLinkHTML(shipmentInfo) %}
  {% if tracking|length %}
    Track shipment: {{ tracking|raw }}
  {% endif %}
{% endfor %}

挂钩/自定义

自定义字段 & 订单备注

Shipstation允许向订单添加额外数据。这些字段在ShipStation中显示为customField1、customField2、customField3、internalNotes、customerNotes、gift和giftMessage。

您可以通过在自定义站点插件中"挂接到" Craft 插件钩子来填充这些字段。

您的插件应该返回一个回调，该回调接受一个参数 $order，即订单实例。它应该返回一个单一值。

在此示例中，插件 MyPlugin 将将值 我的自定义值 发送到所有具有 customField1 参数的 ShipStation 订单。

class MyPlugin extends BasePlugin {

    public function oneShipStationCustomField1() {
        return function($order) {
            return 'my custom value';
        };
    }

}

注意：OneShipStation 将为每个响应钩子的插件添加一个 CustomFieldX 子项。因此，为了避免冲突，请确保只使用一个钩子。

对于内部备注，如果插件响应了钩子，则将键添加。响应如下：

class MyPlugin extends BasePlugin {

    public function oneShipStationInternalNotes() {
        return function($order) {
            return 'internal notes for this order';
        };
    }

}

重写运输方式

默认情况下，One Shipstation 会将每个订单上的 ShippingMethod 的运输方式处理程序发送到 Shipstation。

您可以通过添加自定义字段或内部备注的方式重写此操作。在您的插件中定义一个函数 oneShipStationShippingMethod()，该函数返回一个接受订单并返回字符串的回调。例如，如果您想为所有美国客户将运输方式称为 Ground，您可以声明如下方法：

class MyPlugin extends BasePlugin {

    public function oneShipStationShippingMethod() {
        return function($order) {
            if ($order->getShippingAddress()->country == 'US') {
                return 'Ground';
            }
        }
    }

}

如果您返回 null 或 void，OneShipstation 将将运输方式分配为默认的运输方式处理程序。

重写跟踪URL

目前 One ShipStation 只提供常见承运人的链接。如果您的承运人未定义，或者您想要不同的URL，您可以重写：

class MyPlugin extends BasePlugin {

    public function oneShipStation_trackingURL($shippingInfo) {
        return 'https://mycustomlink?tracking=' . urlencode($shippingInfo->trackingNumber);
    }

}

开发

在任意的 Craft 2.x 项目中，导航到 craft/plugins 并克隆存储库。

$ cd craft/plugins
$ git clone git@github.com:onedesign/oneshipstation.git

请确保如果适用，将 craft/plugins/oneshipstation 添加到您的其他项目的 gitignore 中。

# .gitignore
craft/plugins/oneshipstation

错误/问题

通过https://github.com/onedesign/oneshipstation/issues提交错误报告和问题。提交错误报告时请尽可能详细。

贡献

1. 在 GitHub 上分叉存储库
2. 将项目克隆到您的机器上
3. 将更改提交到您的分支上
4. 将您的作品推回到您的分叉中
5. 提交拉取请求以便我们审查您的更改

注意：在提交拉取请求之前，请确保合并 "upstream" 的最新更改！