欢迎来到 Quote3D 文档！⏳
Quote3D LogoQuote3D文档

在您的网站上嵌入 3D 打印报价小组件

将 Quote3D 强大的 3D 报价引擎直接嵌入到您自己的网站或电子商务平台中。

概览

Quote3D 嵌入式部件是一个低代码解决方案，让您可以在任何网站上为客户提供即时 3D 打印报价。无论您使用自定义网站、WordPress 还是 Shopify，都可以无缝连接 3D 模型查看和订单放置。

主要特性

  • 3D 模型查看器：交互式预览上传的 STL、OBJ、3MF 和 STEP 文件。
  • 即时定价：基于您自己的材料和打印机配置自动计算成本。
  • 多技术支持：支持 FDM、SLA、SLS、SLM 和 MJF，每种技术都有各自的计算逻辑。
  • 自定义主题：使用毛玻璃效果和自定义调色板来匹配您的品牌美学。
  • 零配置客户体验：您的客户无需了解技术切片详情；一切均由 Quote3D 处理。
  • 平台插件：为 WooCommerce、PrestaShop、OpenCart、Magento 和 Wix 提供可安装的插件包，并为 Shopify、Webflow 和 Framer 提供现成代码。
  • 基础和高级表单：可以只询问打印质量和强度来代替切片设置，也可以显示全部打印设置，或让每位客户在两者之间切换。在小组件自定义界面或通过 SDK 的 mode 选项进行设置。

您可以做什么

  • 实时电商同步：使用“添加到购物车”事件将报价直接链接到您商店的购物车。
  • 自动化潜在客户生成：自动捕获客户需求和模型数据。
  • 缩略图生成：自动捕获并存储模型截图，用于制造跟踪。
  • 灵活跳转：计算成功后将客户引导至指定落地页。跳转目标必须是 http 或 https 的 URL。

入门指南

准备好开始集成了吗？您可以在仪表板中自定义组件的主题、语言、颜色、重定向行为和会话持久性，然后生成所需的嵌入代码或平台代码片段。

前往组件设置

价格说明

WooCommerce、PrestaShop、OpenCart、Magento 和 Wix：插件包会在您的服务器上从 Quote3D API 重新读取每个报价，并按该价格加入购物车，顾客无法修改。没有 Plus 的 Shopify 只能按商品定价，因此报价会变成单价商品的数量；请在每个订单中核对报价 ID。Webflow、Framer 和 Squarespace 没有小组件可以访问的购物车。无论哪种情况，Quote3D 定价货币都必须与店铺货币一致。Quote3D 支持以下币种计价：TRY, USD, EUR, GBP, JPY, CNY, RUB, CAD, AUD, CHF, SEK, NOK, DKK, SGD, HKD, NZD, MXN, BRL, INR。

平台集成：WooCommerce、Shopify、PrestaShop、OpenCart、Magento 等

小组件可在任何网站上运行。我们为以下平台提供可安装的插件包或现成代码；购物车中会发生什么因平台而异：

WooCommerce 3D 打印报价插件

安装 PHP 插件，粘贴您的小组件令牌，并选择报价加入购物车时所用的 WooCommerce 商品（设置了常规价格的简单商品，价格可以为 0）。客户点击“加入购物车”时，插件会通过 Quote3D API 校验价格和数量，并将报价连同文件、材料和预览作为行项目元数据加入 WooCommerce 购物车——无需手动覆盖价格。配合服务器令牌（保存在您的服务器上，绝不写入页面），它还会在 WordPress 中添加 Quote3D 菜单：套餐与剩余额度、所有报价、由报价转成的订单，以及按日到按年的报告。购物车和订单保存在店铺自己的数据库中；Quote3D 只提供套餐、额度和报价数量。

Shopify 3D 打印报价区块

在有单价的“3D 打印”商品模板中添加包含我们代码的 Custom Liquid 区块。Shopify 从商品读取价格，只有 Shopify Plus 能覆盖它，因此报价会以该商品的数量形式加入（商品价格为 1.00 时，45.99 的报价会变成 46 × 1.00）。订单中包含报价 ID 和报价金额，方便您在打印前核对。可选地修改主题的购物车模板，即可在该行显示模型缩略图；结账页面仍显示商品图片。

其他平台与自定义技术栈

  • Wix：一个 Velo 插件包，在您网站的后端校验报价价格并加入 Wix Stores 购物车（需 Premium 套餐；使用 Wix 目前处于测试阶段的 eCommerce Catalog service plugin）。购物车行显示的是载体商品的图片，而不是模型缩略图：Wix 只接受其 Media Manager 中的图片。
  • Squarespace：通过 Code Block 嵌入小组件。Squarespace 没有购物车 API，因此订单需通过报价请求、发票或付款链接处理。
  • PrestaShop 8：可安装模块，在您的服务器上验证报价价格并加入购物车，Quote3D 后台位于 Sell 菜单下：报价、生产队列、颜色库存、报表、模型下载和设置。
  • OpenCart 3.0、4.0.2.2+ 和 4.1：可安装扩展，在您的服务器上验证报价价格并加入购物车，后台带有 Quote3D 菜单：报价、生产队列、颜色库存、报表、模型下载和设置。
  • Magento Open Source / Adobe Commerce 2.4：在您的服务器上验证报价价格并加入购物车的模块，后台带有 Quote3D 菜单：报价、生产队列、颜色库存、报表、模型下载和设置。
  • Webflow：通过 Code Embed 元素嵌入小组件。报价无法加入 Webflow Ecommerce 购物车。
  • Framer：用于小组件的 React 代码组件。Framer 没有内置购物车。
  • 自定义软件：可以使用 JS SDK 集成到任何 React、Vue 或 Vanilla JS 项目中。

技术工作原理

Quote3D Widget 以高性能 Iframe 或现代 JS SDK 的形式运行。其工作原理如下：

  • 隔离运行：该 Widget 在其自身的保护区域（Iframe）中运行，因此不会破坏您网站的样式。
  • 实时通信：小组件通过 'postMessage' API 将计算结果传送到您的页面。使用 SDK 时，事件只会投递给嵌入小组件的来源，而不会广播给任意监听者。
  • 自动调整大小：在使用 SDK 时，该 Widget 会根据内容自动调整其高度。

在使用小组件的同时调用 API

小组件在内部处理自己的 API 流量——这些路由无需您自行调用。若想用自己的代码读取或处理同一批数据，请使用核心概念中介绍的公开 v2 端点，指向 https://api.quote3d.com/v2，并使用真实的 API Bearer 令牌而非令牌 ID。若要在买家把配置好的零件加入购物车时做出响应，请订阅 widget.added_to_cart Webhook，而不要直接调用任何接口。

从您自己的代码调用 API

v2 API 仅对已配置的 Quote3D 来源响应跨域请求。请从您的服务器调用，而不要从店铺前端 JavaScript 调用；小组件本身运行在 iframe 内的 Quote3D 来源上，因此其自身请求不受影响。

安全与验证

小组件从浏览器调用 Quote3D，因此任何查看页面源代码的人都能看到它的令牌。请创建专用的小组件令牌，限制为小组件作用域，并绑定到您的店铺来源。轮换会保留这两项限制，因此轮换后的小组件令牌绝不会变成完全访问令牌。

已上传的文件及预览

通过小部件上传的文件采用加密存储，且无法通过公开途径访问。“加入购物车”负载会提供 thumbnailUrl，这是一个从您自己的店面渲染的绝对链接：请务必按接收到的原样进行存储。重写该链接、剥离其查询参数或将其重新托管到您的域名下都会导致图片无法显示。

店铺可以信赖的价格

  • 小组件作用域的令牌无法设定价格。使用该令牌请求的报价只保留顾客在表单中选择的选项；材料、设备和费用价格始终来自您自己的配置文件。
  • widget.added_to_cart webhook 报告的是随报价保存的价格、币种、数量和材料，而不是浏览器发送的内容，并且每个报价只发送一次。
  • 您的页面收到的 QUOTE3D_ADD_TO_CART 消息来自顾客的浏览器，可能在那里被篡改。收费前，请通过 webhook 或 GET https://api.quote3d.com/v2/quotes/{quote_id} 核对价格。

小组件令牌作用域

以小组件作用域创建的令牌只能访问嵌入式体验真正需要的端点。API 上的其他一切都会被拒绝，因此从您页面源代码中窃取的令牌无法被用来危害您的账户。

小组件作用域允许：

  • 读取您的打印机与材料配置，以便报价表单能呈现您的选项。
  • 请求上传 ID 并上传模型文件。
  • 读取并删除它自己上传的文件。
  • 为该文件发起异步报价，并轮询由此产生的任务。
  • 按 ID 读取报价、保存其缩略图，并发送加入购物车事件。

小组件作用域拒绝：

  • Webhook 管理，以免被窃取的令牌把您的事件流转发到其他服务器。
  • 账户信息、上传历史、报价列表、分析、用量与额度。
  • 许可证激活，以及上面未列出的其他所有端点。

来源绑定

列出允许使用该令牌的店铺，例如 https://shop.example.com。小组件令牌至少需要一个：iframe 加载时，Quote3D 会检查嵌入小组件的页面，并拒绝在不在列表中的任何网站上显示。

来源绑定对您页面的要求

  • 该检查读取浏览器加载小组件 iframe 时发送的引荐来源。这是默认行为，因此普通页面无需任何额外设置。
  • 如果您的页面设置了 referrer-policy: no-referrer，来源无法验证，小组件将不会加载。在嵌入小组件的页面上请使用浏览器默认值（strict-origin-when-cross-origin）或 origin。
  • 直接的 API 调用会单独检查：从名单之外站点的浏览器发出的请求会被拒绝，而不发送 Origin 标头的服务器间调用则不受影响。

小组件令牌读不到什么

配置端点只返回报价表单需要呈现的内容——打印机名称、成型尺寸、材料、颜色和层数限制。您的成本基础（每公斤材料价格、机器小时成本、支撑成本系数、功耗）绝不会发送到浏览器；定价在服务器端完成计算。

访客会话

小组件令牌是公开的，因此按令牌计算的限额会由您店铺的所有顾客共享，一个脚本就可能将其耗尽，把其他人全部挡在门外。因此，小组件会在顾客首次上传文件时开启一个短时访客会话，产生成本的步骤按会话计数。

  • 嵌入的小组件会自动完成这一步，标准嵌入代码无需任何修改。
  • 上传文件、发起报价、保存缩略图和加入购物车事件需要会话；读取您的配置、轮询任务和获取报价则不需要，因此耗时较长的计算不会让顾客半途受阻。
  • 会话有效期为 30 分钟。每个会话中，顾客每小时最多可进行 30 次上传、15 次报价、30 次缩略图保存和 20 次加入购物车事件。同一 IP 地址每小时最多可为同一令牌开启 20 个会话。
  • 这些规则仅适用于小组件作用域的令牌。未设置作用域的令牌被视为服务器集成，不享有任何这些保护，因此您店铺中的令牌应始终使用小组件作用域。
  • 如果您使用小组件作用域的令牌自行调用这些端点，请先开启会话：通过 GET https://api.quote3d.com/v2/widget/challenge 获取挑战，找出 0 到 maxnumber 之间的一个数，使盐值后接该数的 SHA-256 与挑战相等，然后将其发送到 POST https://api.quote3d.com/v2/widget/session。在 X-Widget-Session 请求头中发送返回的值。缺少会话或会话已过期时，服务器会返回 401 及错误码 AUTH_005；请开启新会话后重试该请求。
  • 小组件流量拥有独立于服务器集成的每小时配额，因此繁忙的店铺与您自己的后端不会相互拖累。您还可以在控制台为小组件设置每日报价上限；达到上限后，系统会提示顾客次日再试，并向您发送电子邮件。

未设置作用域创建的令牌保持完全访问权限，因此现有集成可继续正常运行。为令牌添加作用域即是让它进入受限模式的方式。