自动化

如何在 easySales 中设置 webhook:把订单、快递标签和库存变化发送到你的系统

如何在 easySales 中设置 webhook:把订单、快递标签和库存变化发送到你的系统

在新订单、快递标签、发票和库存变化等 easySales 事件发生的同时,把它们发送到你自己的系统,并让订阅持续正常运行。

webhook 能做什么

webhook 会在 easySales 中发生某件事的同时通知另一个系统。当有新订单进来、生成了快递标签或库存发生变化时,easySales 会把详情发送到你指定的地址,这样你的 ERP、财务软件或网店就能立即做出反应,而不必每隔几分钟去查询一次 easySales。

登录后打开 easy-sales.com/webhooks 页面。页面上的每一行都是一个 订阅:一个事件,发送到一个地址。

先了解三点:

  • 接收地址需要由你或你的开发人员搭建。 easySales 负责发送数据,该地址上的系统决定如何处理这些数据。
  • 持续失败的订阅会自动关闭。 失败 100 次后,easySales 会停止发送并发邮件通知你。订阅不会自行重新开启。
  • 订阅关闭期间的事件不会保留。 重新开启后,从那一刻起才恢复发送。

订阅事件

Webhooks 页面:Subscribe to webhook 按钮,以及按事件分组的四个订阅:Order created 和 Order updated 显示 Success,Invoice created 显示 Failed,Product stock updated 显示 Failed 并带有 Enable 按钮;每个订阅都显示 URL、密钥、方法和 More details。
每个事件和地址对应一个订阅。
  1. 点击 Subscribe to webhook。
  2. 在 Url 中输入接收数据的地址。请使用 https 地址。
  3. HTTP method 保持为 POST。
  4. 在 Webhook 中选择事件。
  5. 在 Secret 中输入至少 24 个字符的密钥。你的系统用它来确认数据确实来自 easySales。
  6. 点击 Save。

订阅会显示在其事件名称下。如果要把同一事件也发送给第二个系统,请用另一个地址再订阅一次。同一个地址对每个事件只能添加一次。

事件 发送时机
Order created 任意渠道有新订单进来,或手动添加了订单。
Order updated 订单发生任何变化,例如状态、商品或地址。此事件发送频繁。
Awb created 通过 easySales 中的快递公司为订单生成了快递标签。
Delivery status updated 快递公司报告了某个包裹的新配送状态。
Invoice created, Storno invoice created 为订单开具了发票或红冲发票。
Return created, Return updated 创建了退货,或退货的状态、商品、备注、包裹或发票发生变化。
Product created, Product updated 添加或修改了商品,包括价格变化。
Product stock updated 商品库存发生变化。
Category created / updated, Characteristic created / updated 添加或修改了类目或属性。
Products refresh requested, Stock refresh requested 为网店请求刷新商品或库存。
Ticket created, Ticket updated 在 顾客 → 工单 中开始了与买家的对话,或已有对话发生变化。
Account suspended, Account activated easySales 账户被暂停或重新激活。
可订阅的事件

查看发送记录

展开 More details 的 Invoice created 订阅:作为 payload 发送的发票数据,以及响应 Service Unavailable,并带有 Attempt 2 of 3、下次尝试时间和状态码 503 的标记。
最近发送的事件以及你的地址返回的内容。

每个订阅都会显示最近一次发送的事件是 Success 还是 Failed,以及发送时间。点击 More details... 查看该事件:

  • Payload 是 easySales 发送的数据。
  • Response 是你的地址返回的内容及其状态码。
  • Attempt 2 of 3 | Next attempt: … 表示该事件发送失败,将会重新发送。Final attempt has been made 表示该事件不会再重试。

这里只显示每个订阅的最后一个事件。

修改、暂停或删除订阅

webhook 表单,包含 Url、HTTP method POST、Webhook Invoice created、Secret 和 Save。
地址、方法、事件和密钥。
  • Edit 可修改地址、HTTP 方法或密钥。要发送其他事件,请订阅该事件并删除旧订阅。
  • Disable 暂停订阅,Enable 重新启动。暂停期间不会发送任何内容,这段时间的事件之后也不会补发。
  • Unsubscribe 会立即删除订阅。

你的系统需要做什么

详情
格式 JSON,事件数据位于 payload 下,订阅 ID 和事件名称位于 webhook 下。
签名 Signature 请求头包含用你的密钥对请求体计算出的 HMAC-SHA256。请按收到的原样请求体进行计算。
响应 3 秒内返回任意 2xx 状态。先响应,再处理数据。
证书 https 地址必须使用有效的证书。
重试 每个事件最多尝试三次:第二次在第一次之后约 10 秒,第三次再过约 100 秒。
到达顺序 由于存在重试,事件可能不按顺序到达。请以 payload 中的数据为准,而不是到达时间。
easySales 发送什么、期望什么

订阅自动关闭时

每次失败的尝试都会计数:返回错误、3 秒内没有响应或证书有问题。失败 100 次后,订阅会被关闭,你会收到邮件“Webhook 已禁用”。邮件中的 查看 webhook 按钮会打开此页面。

  1. 修复接收地址上的问题。
  2. 点击该订阅的 Enable。
  3. 通过 easySales API 获取错过的变更,例如这段时间内被修改的订单。
📖
继续阅读
如何连接 easySales API:OAuth 客户端和个人访问令牌
为 easySales API 创建 OAuth 客户端和个人访问令牌,选择合适的授权类型和作用域,避免各个连接互相挤掉登录。
→
📖
继续阅读
如何通过 API 将自定义商店接入 easySales
通过 API 把任意自定义或尚未支持的商店平台接入 easySales:需要的两个凭据、推送产品与库存、送入订单,以及把变化取回去。
→

团队成员如何使用 webhook

团队成员需要 查看 webhook 权限才能打开该页面。有了这项权限,就可以添加、修改、暂停和删除订阅。

出现问题时

现象 处理方法
不再收到任何数据,订阅上显示 Enable 订阅因多次失败已被关闭。修复地址,点击 Enable,然后通过 API 获取错过的变更。
最后一个事件显示 Failed 打开 More details...,查看状态码和你的地址返回的内容。
“The secret must be at least 24 characters.” 输入至少 24 个字符的密钥。
“The url has already been taken.” 该地址已经在接收此事件。请改为编辑现有订阅。
收不到红冲发票 订阅 Storno invoice created;Invoice created 只涵盖普通发票。
接收系统被大量订单更新淹没 Order updated 在每次变化时都会发送。请快速响应,并在后台处理数据。
常见问题

常见问题

登录后打开 easy-sales.com/webhooks。“Webhook 已禁用”邮件中也有该页面的链接。

失败 100 次后,easySales 会关闭该订阅并发邮件通知你。修复接收地址后点击 Enable。

不会。请通过 easySales API 获取这段时间内的变更。

用你的密钥对请求体计算 HMAC-SHA256,并与 Signature 请求头进行比较。

3 秒内,并返回 2xx 状态。否则该次尝试计为失败,并会重试。

可以,只要拥有“查看 webhook”权限。

本指南对你有帮助吗?