ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Activepieces 集成指南:Shippo 物流 Pieces 的构建、认证与自动化流程

Activepieces 集成指南:Shippo 物流 Pieces 的构建、认证与自动化流程 Activepieces 集成指南Shippo 物流 Pieces 的构建、认证与自动化流程【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读本篇文章聚焦 Activepieces 开源仓库中 Shippo 多承运商物流集成 Piecesactivepieces/piece-shippo的完整实现涵盖从本地构建、API Token 认证校验到订单创建/查询、运单标签查询与轮询触发器的核心用法。读完本文你将掌握该 Piece 提供的 3 个 Action 与 2 个 Trigger 的字段含义、底层 HTTP 调用路径并能在 Activepieces 流程中搭建新订单 → 查标签 → 同步到下游系统的典型物流自动化方案。一、Shippo Piece 概览与源码结构Shippo 是一家面向多承运商的物流平台提供实时运费报价、运单标签与物流追踪 API。Activepieces 以官方 Piece 的形式将其封装为可视化流程积木定义入口位于 src/index.tsexport const shippo createPiece({ displayName: Shippo, description: Multi-carrier shipping platform for real-time rates, labels, and tracking, auth: shippoAuth, minimumSupportedRelease: 0.36.1, logoUrl: https://cdn.activepieces.com/pieces/shippo.png, authors: [SinghaAnirban005, sanket-a11y], actions: [createOrder, findOrder, findShippingLabel], triggers: [newShippingLabel, newOrder], });从源码结构看该 Piece 由五个模块构成模块文件路径职责认证src/lib/auth.tsAPI Token 的声明与实时校验HTTP 客户端src/lib/client.ts封装 Shippo REST API 调用类型定义src/lib/common.ts订单、地址、行项目、标签等 TypeScript 接口Actionssrc/lib/actions/创建订单、查询订单、查询运单标签Triggerssrc/lib/triggers/新订单、新运单标签轮询触发器它声明了minimumSupportedRelease: 0.36.1意味着该 Piece 需要 Activepieces 0.36.1 及以上版本才能正常加载。二、本地构建Building原仓库 README 给出了该库的构建命令turbo run build --filteractivepieces/piece-shippo该命令通过 Turborepo 增量构建系统仅对activepieces/piece-shippo及其依赖执行构建。包名与过滤条件对应 package.json 中的name: activepieces/piece-shippo当前版本为0.1.6。构建脚本定义在同文件的scripts.build中build: tsc -p tsconfig.lib.json cp package.json dist/即先用 TypeScript 编译器按 tsconfig.lib.json 编译到dist/再把package.json复制进产物目录保证产物可被 Activepieces 运行时直接消费。仓库根目录的 turbo.json 定义了各包的任务编排使用--filter可避免全量构建、缩短迭代时间。2.1 依赖说明activepieces/piece-shippo的运行时依赖全部来自 Activepieces 工作区自身见 package.jsonactivepieces/pieces-framework提供createPiece、createAction、createTrigger、Property、PieceAuth等 APIactivepieces/pieces-common提供httpClient、HttpMethod、pollingHelper、DedupeStrategy等通用能力dayjs1.11.9用于触发器中的时间戳换算与去重比对activepieces/core-piece-types与activepieces/core-utils核心类型与工具。因此构建前需确保工作区依赖已就绪仓库根目录执行bun install或按 CONTRIBUTING.md 的引导安装再执行上述 turbo 命令。三、认证API Token 的声明与自动校验所有 Shippo 操作都依赖 API Token。该 Piece 使用PieceAuth.SecretText声明一个秘密文本类型的认证字段见 src/lib/auth.tsexport const shippoAuth PieceAuth.SecretText({ displayName: API Token, description: Your Shippo API token, required: true, validate: async ({ auth }) { if (auth) { try { await httpClient.sendRequest({ method: HttpMethod.GET, url: https://api.goshippo.com/orders/, headers: { Authorization: ShippoToken ${auth} }, }); return { valid: true }; } catch (error) { return { valid: false, error: Invalid Api Key }; } } return { valid: false, error: Invalid Api Key }; }, });值得注意的实现细节请求头格式Shippo 官方认证方式是在Authorization头携带ShippoToken token而非常见的Bearer该格式在 client.ts 与 auth 校验中被一致使用实时校验在流程编辑器中保存连接时Activepieces 会执行validate回调向GET https://api.goshippo.com/orders/发起探测请求成功即通过失败返回Invalid Api Key避免无效凭据进入流程SecretText 类型Token 以密文形式存储不会在流程日志中明文暴露。在 Activepieces 界面中用户只需在连接Connections里新增 Shippo 连接并粘贴 Token之后所有 Action/Trigger 都会自动带上context.auth.secret_text中的值。四、底层 HTTP 客户端一次封装覆盖 REST APIsrc/lib/client.ts 是全部业务操作的统一入口其基址为https://api.goshippo.com通过makeRequest统一注入认证头与Content-Type: application/json方法HTTP 方法与端点说明createOrderPOST /orders创建订单getOrderGET /orders/{id}?fields按 ID 查询订单可裁剪字段listOrdersGET /orders分页列出订单支持page、results_per_page、order_status、placed_at_gtupdateOrderPATCH /orders/{id}更新订单客户端已实现Piece 层暂未暴露deleteOrderDELETE /orders/{id}删除订单客户端已实现Piece 层暂未暴露getShippingLabelGET /transactions/{id}按 ID 查询运单标签事务listShippingLabelsGET /transactions分页列出标签createShippingLabelPOST /transactions创建标签客户端已实现Piece 层暂未暴露createShipmentPOST /shipments创建货件预留扩展getRatesGET /shipments/{id}/rates获取运费报价预留扩展trackShippingLabelGET /tracks/{carrier}/{trackingNumber}按承运商与运单号追踪预留扩展在 Shippo 的 API 语义中运单标签Shipping Label对应Transaction资源因此查询标签实际走/transactions端点。客户端中还预留了创建货件、获取报价、追踪等额外有用方法目前尚未在 Piece 的 Action 层暴露属于未来可扩展能力——这一点是从源码结构得出的推断。五、Actions三个可拖拽的操作积木5.1 Create Order创建订单create-order.ts 是该 Piece 最复杂的 Action用于把一笔电商订单登记进 Shippo供后续生成货件与标签。其入参按功能分组必填字段字段类型说明order_numberShortText订单自定义参考号order_statusStaticDropdown状态可选UNKNOWN / AWAITPAY / PAID / REFUNDED / CANCELLED / PARTIALLY_FULFILLED / SHIPPED默认AWAITPAYplaced_atDateTime下单时间格式如2025-10-31T11:56:29.244Ztotal_priceShortText含运费与税的总价以字符串传递金额currencyShortText币种代码默认USDto_name / to_street1 / to_city / to_state / to_zip / to_countryShortText收件人地址必填六要素国家为两位字母代码weightShortText包裹总重量如2.5可选字段寄件人地址from_*系列共 10 个字段源码中只有当from_name from_street1 from_city from_state from_zip from_country全部提供时才会写入from_address见 create-order.ts避免生成残缺地址对象金额类subtotal_price、total_tax、shipping_cost、shipping_cost_currency行项目Line Items支持两种方式——扁平字段line_item_title line_item_quantity line_item_total_price传单个商品可附line_item_sku / line_item_weight / line_item_weight_unit单位支持lb/oz/kg/gadditional_line_itemsJSON 数组批量追加商品示例[{title: Product 2, quantity: 2, total_price: 20.00}]每个元素可含title / quantity / total_price / currency / sku / weight / weight_unit其中quantity与total_price会被强制数值化兜底配送信息shipping_method如USPS First Class Package、weight_unit默认lb。实现要点run中通过context.auth.secret_text实例化ShippoClient把 UI 扁平字段组装成符合CreateOrderRequest的嵌套结构后调用POST /orders。该 Action 声明了aiMetadata幂等性为 false明确每次调用都会创建新订单因此在重试场景下可能产生重复订单设计流程时应注意去重。5.2 Find Order查询订单find-order.ts 只有一个必填字段order_id订单 object ID内部调用client.getOrder(order_id)请求GET /orders/{id}。需要特别说明该 Action 只能按 Shippo 的object_id精确查找不能按订单号order_number搜索若流程中只有订单号应先用 Create Order 的返回结果或 New Order 触发器拿到 object_id 再查询。该操作只读且幂等aiMetadata.idempotent: true。5.3 Find Shipping Label查询运单标签find-shipping-label.ts 提供必填字段label_id内部调用client.getShippingLabel(label_id)请求GET /transactions/{id}。返回的标签对象见 common.ts 的ShippingLabel接口包含字段用途tracking_number运单号tracking_status/tracking_url_provider当前状态与承运商追踪链接label_url可下载的 PDF/PNG 标签地址carrier_account/servicelevel_token承运商账号与服务水平rate/parcel关联的费率与包裹对象 IDtest是否为测试标签它同样只支持按 ID 精确查询不能按运单号检索。六、Triggers两个轮询触发器两个触发器均采用TriggerStrategy.POLLINGDedupeStrategy.TIMEBASED基于时间戳去重由pollingHelper统一管理启停与调度天然适合无需 Webhook 配置的场景。6.1 New Order新订单new-order.ts 每次轮询调用listOrders({ results_per_page: 100 })然后以dayjs(order.placed_at)与lastFetchEpochMS比较只返回上次拉取之后创建的订单并以placed_at的时间戳作为去重键。它内置了完整sampleData示例订单展示了一个典型的 Shippo 订单结构object_id、order_number: #1068、order_status: PAID、to_address含is_complete、validation_results等字段、line_items含 SKU、数量、单价、重量、shipping_method、total_price等可直接作为流程后续步骤的字段引用参考。6.2 New Shipping Label新运单标签new-shipping-label.ts 轮询listShippingLabels({ results_per_page: 100 })按object_created时间过滤新增标签并额外提供一个布尔属性属性类型默认值说明test_modeInclude Test LabelsCheckboxfalse是否包含测试标签默认情况下源码会执行filteredLabels.filter((label) !label.test)剔除测试环境生成的标签见 new-shipping-label.ts勾选后则全部包含。其sampleData展示了完整标签结构label_urlS3 签名地址、qr_code_url、tracking_number、tracking_status: DELIVERED、status: SUCCESS、test: true等。6.3 触发器的通用实现模式两个触发器都遵循同一套pollingHelper契约——实现items回调返回{ epochMilliSeconds, data }[]再在test / onEnable / onDisable / run四个生命周期中委托给pollingHelper。这种模式意味着无需在 Shippo 侧配置 Webhook 回调地址断连onDisable时框架会清理轮询状态时间戳去重保证流程不会因轮询重叠而重复消费同一订单/标签。七、典型场景串联从下单到打单的全自动流程结合以上积木可以搭建一条完整的物流自动化流程触发电商系统把新订单写入 Shippo或直接监听 Shippo 侧的新订单→ 使用New Order触发器处理通过Find Order按object_id拉取订单完整详情供后续分支判断如按国家/重量分派承运商衔接在 Shippo 中完成货件与标签创建后可在 Activepieces 中调用其他 Shippo/自定义 HTTP 积木用New Shipping Label触发器或Find Shipping Label拿到label_url与tracking_number通知把标签 PDF 链接、运单号发送到邮件、Slack 或 ERP 系统。由于 Piece 的 3 个 Action 均面向订单/标签 ID 的精确操作实践中常把Create Order的返回值含object_id直接传递给后续步骤避免手工复制 ID。八、注意事项与边界金额均为字符串total_price、shipping_cost等字段在 UI 层定义为ShortText传值时应使用如24.93的字符串格式国家代码地址中的country使用两位字母代码如US发货地与收货地均默认US幂等性差异create_order非幂等每次执行都新建订单两个查询 Action 幂等设计重试与并发时需区分对待标签查询走 TransactionsShippo 的标签即Transaction资源不要与Shipment货件混淆触发器默认排除测试标签若在沙箱环境联调记得勾选Include Test Labels版本约束该 Piece 需要 Activepieces0.36.1本地构建使用turbo run build --filteractivepieces/piece-shippo产物通过 package.json 的build脚本输出到dist/。九、延伸阅读体验多语言界面文案src/i18n/含 zh、ja、de、fr 等 8 种语言深入理解 Piece 开发框架packages/pieces/framework查看仓库内其他物流/电商类 Piece 以复用模式packages/pieces/communityPiece 开发规范与提交流程packages/pieces/CLAUDE.md。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表