README

这是一个适用于 OpenMage 和 Magento 1 (CE 或 EE) 的扩展程序，它简化了 OpenMage/Magento 与 ShipStream OpenMage/Magento 插件之间的库存、订单和跟踪信息同步。此扩展程序在未在 ShipStream 中配置相应的插件订阅之前将没有任何效果。

此扩展程序为我的 OpenMage/Magento 店铺添加了哪些功能？

在“服务”>“ShipStream 同步”中添加了一个“系统”>“配置”部分
- 常规 > 启用实时订单同步
- 常规 > 发送新运货邮件
添加了三个新的订单状态：“准备发货”、“提交失败”和“已提交”
添加了 API 端点 shipstream.info
添加了 API 端点 shipstream.set_config
添加了 API 端点 shipstream.sync_inventory
添加了 API 端点 shipstream_stock_item.adjust
添加了 API 端点 shipstream_order_shipment.info
添加了 API 端点 shipstream_order_shipment.createWithTracking
添加了对 sales_order_save_commit_after 事件的观察者，以便在订单保存时触发订单同步
添加一个 cron 作业，每小时进行一次完整的库存同步（带短随机睡眠时间）
将 ShipStream 远程 URL 存储在 core_flag 表中

为什么需要这个？OpenMage/Magento 不是已经有了 API 吗？

是的，但这个扩展程序解决了几个不足之处

在通过基本 HTTP 协议同步远程系统时，在库存数量已知和更新之间没有锁定，因此设置精确的库存水平容易产生竞争条件。添加“adjust”方法允许 ShipStream 推送库存调整（例如 +20 或 -10），而不是绝对值，这大大降低了因竞争条件引起的错误。
OpenMage 商品目录库存 API 不使用数据库级别的正确锁定，因此也容易产生本地竞争条件。此模块使用 SELECT ... FOR UPDATE 来确保在数据库级别更新是原子的。
此模块实现了一个“拉”机制，使 OpenMage 能够在本地和远程锁定库存，然后在一个数据库事务中同步库存数量。这确保了库存不会因竞争条件而漂移或跳跃。对于高流量店铺，这些问题比您想象的要频繁得多。
OpenMage API shipment.info 方法返回的 SKU 不反映 ShipStream 使用的简单产品 SKU。此扩展程序返回适用于 WMS 使用的 SKU。
使用 shipstream_order_shipment.createWithTracking 方法可以将四个或更多的 API 调用减少为一个，该方法还允许轻松自定义（例如接收和存储序列号或批号数据）。

API 端点是使用 Magento 提供的 SOAP/XML-RPC API 实现的，因此这些端点不会创建任何额外的安全漏洞暴露。

新状态的意义是什么？

没有“处理”和“完成”之间的状态，否则很难判断订单是否已准备好提交到仓库，是否已成功提交到仓库，或者订单是否已在仓库中处理。

“准备发货”状态可以手动或通过程序（使用一些自定义代码和自己的业务逻辑）设置，以指示订单何时准备好发货。如果您不想使用此状态，只需忽略它，并将ShipStream配置为从“处理中”状态拉取订单。

“提交失败”状态表示在仓库创建订单时出现错误。

“已提交”状态表示已成功提交到仓库，但尚未完全发货。一旦完全发货，订单状态将自动升级到“完成”。

注意：请随意更改这些新状态的状态标签，但请不要更改状态代码，以免破坏集成。

如果ShipStream插件配置为同步处于“准备发货”状态的订单，订单状态进度将如以下所示。请注意，这需要在同步之前，由用户或某些自定义代码将订单状态从“处理中”升级到“准备发货”。

如果ShipStream插件配置为同步处于“处理中”状态的订单，订单状态进度将如以下所示。此配置将在收到付款后自动同步订单，无需用户交互。

还可以配置ShipStream插件以使用任何其他状态，如果您希望创建自定义工作流程。

安装

您可以使用Composer、modman、zip文件或tar文件安装此扩展。

安装后，刷新OpenMage缓存以激活扩展。

modman

$ modman init
$ modman clone https://github.com/ShipStream/openmage-sync

Composer

运行 composer require 将扩展拉入您的Composer环境。

$ composer require shipstream/openmage-sync

Zip文件

从发布页面下载最新版本，或点击这里获取最新的夜间构建。
将下载文件的文件内容提取到干净的目录中。
将openmage-sync-master/app目录中的文件移动到您的OpenMage/Magento根目录的app目录。

Linux命令行（tar文件）

cd <your-Magento-root>
curl -fsSL -o /tmp/openmage-sync-master.tar.gz https://github.com/ShipStream/openmage-sync/archive/refs/heads/master.tar.gz
tar -xzv openmage-sync-master/app --strip-components=1 -f /tmp/openmage-sync-master.tar.gz
rm /tmp/openmage-sync-master.tar.gz

设置

一旦安装此扩展并刷新了Magento缓存，您只需进行三个步骤

在OpenMage/Magento中配置插件
创建API角色和API用户
在ShipStream中设置插件订阅

以下将提供每个步骤的更多详细信息。

配置

在“系统 > 配置 > 服务 > ShipStream同步 > 通用”部分调整配置以满足您的需求。

创建API用户

此扩展除了创建ShipStream插件的API角色和API用户之外，无需进行其他设置。

导航到“系统 > 网络服务 > SOAP/XML-RPC - 角色”
点击“添加新角色”
提供名称“ShipStream”和您当前的管理员密码
点击“角色资源”选项卡，并选择以下部分中列出的资源
点击“保存角色”
导航到“系统 > 网络服务 > SOAP/XML-RPC - 用户”
点击“添加新用户”
填写表单字段，选择安全的API密钥，并记录“用户名”和“API密钥”以供以后使用
点击“用户角色”选项卡，并选择之前步骤中创建的“ShipStream”角色
点击“保存用户”
将用户名和API密钥提供给ShipStream订阅配置中的ShipStream

所需的API角色资源

以下角色资源对于与ShipStream插件的最佳操作是必需的

销售 / 订单 / 修改状态，添加评论
- 在履行后设置订单状态为完成所需的
销售 / 订单 / 获取订单信息
- 获取与履行相关的基本订单信息所需的
ShipStream同步
- 使用由本扩展添加的自定义API方法

ShipStream设置

ShipStream插件需要以下信息

您的商店的API URL，应为Magento管理站点基础URL加上/api/soap/
API用户名和API密码（在上一步中创建）
用于自动导入的订单状态名称（例如，“处理中”或“准备发货”）

自定义

请随意修改此源代码以适应您的特定需求。例如，如果您有多个履行提供商，您可能想向订单添加一些元数据，这样它们就不会自动导入。

支持

如需帮助，请通过电子邮件发送至 help@shipstream.io！

shipstream / openmage-sync

维护者

详细信息