Magento 2 + AtoShip
将 Magento 2 店铺的订单自动拉入 atoship，购买折扣价的 USPS / UPS / FedEx 面单， 再把物流单号回写到店铺 — 还能在 Magento 后台内直接看到完整的物流追踪面板。
工作原理
这套集成由两部分组成：一个 Magento 2 扩展，为店铺增加物流追踪展示与 webhook 处理能力； 以及从 atoship 控制台发起的 OAuth 连接，自动同步订单并回写物流数据。
Magento 出现新订单
买家在你的店铺下单
订单同步到 atoship
自动导入买家信息、商品和重量
购买面单，单号回写
物流单号、承运商和进度写回 Magento 订单
安装步骤
第 1 步 — 安装 Magento 扩展
从右侧栏（或下方按钮）下载 atoship-for-magento.zip 文件， 解压到你的 Magento 安装目录：
方式 A：复制到 app/code（推荐）
# 解压并复制到 Magento 根目录
unzip atoship-for-magento.zip
cp -r atoship-shipping/ <magento-root>/app/code/Atoship/Shipping/
# 启用模块
cd <magento-root>
php bin/magento module:enable Atoship_Shipping
php bin/magento setup:upgrade
php bin/magento cache:flush运行 setup:upgrade 后， 模块会自动创建 atoship_tracking 数据表 并注册 webhook 路由。
第 2 步 — 通过 OAuth 集成连接
在 Magento 后台，进入 System → Integrations，点击 Add New Integration。填写以下内容：
https://atoship.com/api/channels/magento/callbackhttps://atoship.com/api/channels/magento/identity
填写 Name、Callback URL 和 Identity Link URL。Email 字段为可选。
第 3 步 — 设置 API 权限
点击左侧的 API标签。在 "Resource Access" 中， 选择 All，或对以下具体资源授予访问权限：
- Sales — 订单、发票、发货单、贷记单
- Catalog — 商品（用于获取重量和尺寸）
- Stores — 店铺配置与视图
提示：选择 "All" 最简单，可确保所有同步功能正常工作。 之后如有需要，可以再收紧权限。
第 4 步 — 保存并激活
点击 Save 创建该集成。然后在列表中找到它，点击Activate链接。Magento 会要求你确认 — 点击 Allow。
点击 atoship 集成旁的 Activate 链接，开始 OAuth 握手流程。
重要提示：点击 Activate 之前，请确保你已在同一浏览器中登录 atoship 账户。 Magento 会将浏览器重定向到 atoship 的 Identity Link URL， atoship 需要你的会话来把店铺关联到你的账户。
第 5 步 — 配置扩展
进入 Stores → Configuration → Sales → AtoShip， 填入你的 webhook 密钥（可在 atoship 的 Channels 页面找到）。并配置通知和 自动完成相关的偏好设置。
atoship 集成会在 Magento 的 System → Integrations 列表中显示为 Active。
扩展设置
所有设置都位于 Stores → Configuration → Sales → AtoShip。各项含义如下：
General
- Enable — 扩展的总开关。关闭时，webhook 将被忽略，物流追踪面板也会隐藏。
- Webhook Secret — 用于校验来自 atoship 的 webhook 的 HMAC-SHA256 密钥。请从 atoship 的 Channels 页面复制。
- Debug Logging — 将详细日志写入
var/log/atoship.log。生产环境请保持关闭。
Tracking
- Auto Complete on Delivery — 当承运商的物流追踪确认签收后，自动将订单标记为 "Complete"。
- Notify Customer on Ship — 购买面单后，向买家发送含物流追踪链接的发货通知邮件。
- Notify Customer on Delivery — 包裹送达后，向买家发送签收确认邮件。
同步哪些内容
Magento → atoship
- 订单号、日期、总额
- 账单地址与收货地址
- 含 SKU、数量、重量的商品明细
- 买家姓名与邮箱
- 订单状态与支付信息
atoship → Magento
- 物流单号、承运商 + 服务名称
- 可视化进度条（已创建面单 → 已揽收 → 运输中 → 已送达）
- 含事件与地点的完整物流时间轴
- 面单费用与面单 PDF 链接
- 在订单上创建发货单
- 订单状态更新（→ Complete）
- 签收与异常通知
物流追踪数据存储在 atoship_tracking数据表中， 并在后台的订单详情页和发货单详情页上以精美的物流追踪面板呈现 — 无需额外安装任何物流追踪扩展。
订单物流追踪面板
在 atoship 购买面单后，扩展会在后台订单详情页和发货单详情页都加上一个精美的 AtoShip Tracking 面板。 买家也能在自己的 My Account 订单页面看到物流进度。
承运商与服务
显示真实的承运商 logo（FedEx、UPS、USPS、DHL）、承运商名称和服务等级（Ground、Priority、Express）。
进度条
可视化四步进度指示：已创建面单 → 已揽收 → 运输中 → 已送达。 随物流状态变化自动更新。
物流时间轴
可折叠的逐条事件时间轴，含时间戳和地点，按最新在前排序。
快捷操作
在 atoship 追踪页查询、跳转到承运商官网查看、面单费用展示（仅后台可见）。
物流单号会链接到 atoship 追踪页以查看详情。物流追踪数据通过 webhook 实时推送。
Webhook 事件
扩展会在 /atoship/webhook/receive 接收来自 atoship 的 webhook 事件。 所有请求都会用你的 webhook 密钥通过 HMAC-SHA256 签名进行校验。
| 事件 | 动作 |
|---|---|
label.created | 保存物流追踪记录，在订单后台添加备注 |
label.purchased | 保存物流追踪，将订单转为 Processing，并通知买家 |
label.voided | 将物流追踪标记为已作废，并添加后台备注 |
tracking.updated | 更新状态和事件时间轴，添加买家可见的备注 |
tracking.delivered | 标记为已送达，自动完成订单（若已启用），并通知买家 |
tracking.exception | 记录警告，添加仅后台可见的告警备注 |
备选方案：手动输入令牌
如果你已经创建过集成，并拥有 4 个 API 令牌（Consumer Key、 Consumer Secret、Access Token、Access Token Secret），可以直接手动输入：
- 进入 atoship → Channels → Add Channel → Magento
- 切换到 Manual Tokens 标签
- 填入你的店铺 URL 和全部 4 个令牌
- 点击 Connect
如果你的 Magento 店铺无法访问外网（例如位于防火墙后的预发布环境）， 或者你更倾向于手动管理令牌，这个方式会很有用。
断开连接
你可以从任意一端断开连接：
- 从 atoship 端：进入 Channels，找到你的 Magento 店铺，点击 Disconnect。
- 从 Magento 端：进入 System → Integrations，找到 "AtoShip"，点击 Delete 或 Reset。
断开连接不会删除店铺中已有的任何订单、发货单或物流追踪数据， 只会停止后续同步。扩展本身可通过 module:disable Atoship_Shipping 单独卸载。
故障排查
"State not found or expired" 错误
OAuth 握手必须在 10 分钟内完成。如果你在 Save 和 Activate 之间耗时过久， 请在 Magento 中删除该集成并重新创建。
跳转到了登录页
在 Magento 中点击 Activate 之前，你需要在同一浏览器里已登录 atoship。 请先登录 atoship，再重试 Activate（可能需要重新创建集成）。
物流追踪面板不显示
确保扩展已启用（php bin/magento module:status | grep Atoship）， 并且在 Stores → Configuration → Sales → AtoShip 中将 "Enable" 设置为 Yes。 任何配置更改后，请运行 cache:flush。
收不到 Webhook 事件
确认 atoship 与你的 Magento 配置中的 webhook 密钥一致。查看var/log/atoship.log（需开启 Debug Logging） 是否有签名校验失败的记录。你的店铺必须能从外网访问。
订单未导入
确认店铺在你的 Channels 页面显示为 "Active"。 检查该集成是否拥有所需的 API 权限（Sales、Catalog、Stores）。 订单同步按计划任务运行 — 新下的订单可能需要几分钟才会出现。
环境要求
- Magento 2.4+（Open Source 或 Commerce）
- PHP 8.1+
- 已启用 REST API（默认启用）
- 必须使用 HTTPS
- 拥有创建集成和安装扩展的后台管理权限
app/code/Atoship/Shipping/。Callback URL
https://atoship.com/api/channels/magento/callbackIdentity Link URL
https://atoship.com/api/channels/magento/identity