REST API Launch & Developer Tools

CalcuMake REST API v1

使用全面的、生产就绪的 REST API 构建强大的 3D 打印工作流程集成。

每个资源超过 50 个现有端点

此 API 提供对 CalcuMake 所有功能的完整、程序化访问。

打印定价（8 个端点）

• 列出、创建、显示、更新和删除定价计算
• 复制现有计算
• 增加或减少打印计数器
• 完全支持具有嵌套关系的多板

打印机（5 个端点）

• 管理打印机库存
• 获取规格和功耗数据
• 跟踪打印机成本和盈利能力计算

材料（12 个端点）

• 线材：除了复制之外的完整 CRUD 操作
• 树脂：树脂打印材料的完整管理
• 统一材料库：通过一个请求浏览所有材料

客户（5 个端点）

• 管理和跟踪客户
• 将客户链接到定价计算和发票

用户管理（3 个端点）

• 获取和更新用户配置文件
• 导出用户数据（GDPR 合规）
• 使用情况统计和分析

API 令牌（3 个端点）

• 列出活动令牌
• 创建具有到期日期的新令牌
• 安全地撤销令牌

具有 JSON 响应的 RESTful 设计

API 遵循最佳 REST 实践：

• 标准 HTTP 方法：GET、POST、PATCH、DELETE
• JSON 请求/响应格式：干净、可预测的结构
• 适当的状态代码：200、201、400、401、404、422、500
• Bearer 令牌身份验证：安全、行业标准的方法
• 分页支持：高效处理大型数据集

完整的 API 文档

我们在 /api-documentation 上创建了一个全面的参考指南。

入门指南

• 基本 URL 和端点结构
• 测试 API 的简单示例
• 设置身份验证的教程

三种语言的代码示例

• cURL：简单的命令行测试
• JavaScript (Node.js)：现代 async/await 示例
• Ruby：基本的 Rails 兼容示例

完整的端点参考

• 超过 50 个端点的详细描述
• 请求参数表
• 响应格式示例
• 错误处理文档

身份验证指南

• 如何创建 API 令牌
• Bearer 令牌格式和用法
• 安全最佳实践

语法高亮和交互式选项卡

文档功能：

• 所有代码示例的 Prism.js 语法高亮
• 语言之间的基于选项卡的切换
• 复制到剪贴板功能（计划在第 2 阶段实施）
• 适用于移动设备和桌面的响应式设计

可通过导航栏访问

轻松找到 API 文档：

1. 单击导航栏中的帮助
2. 导航到开发者部分

• 选择API 文档

API 令牌管理中的改进

我们彻底改造了 API 令牌的创建和管理体验。

一次性令牌显示

安全至上的设计：

• API 令牌仅在创建后显示一次
• 令牌在使用 SHA-256 存储之前进行哈希处理
• 纯文本令牌在初始显示后永远不会显示
• 显示复制令牌的明确警告

改进的用户体验：

• 令牌显示在专用警告卡中
• 自动复制到剪贴板按钮
• 这是一次性显示的视觉指示器
• 有关存储令牌的明确说明

基于会话的令牌存储：

• 令牌存储在会话中（而不是闪存中），以避免显示 Toast 通知
• 成功消息仅显示为 Toast 通知
• 干净、低噪音的 UI

API 使用示例

以下是一些简单的入门示例：

列出所有打印定价

curl https://calcumake.com/api/v1/print_pricings \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch("https://calcumake.com/api/v1/print_pricings", {
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
  },
});
const data = await response.json();

创建一个新的打印机

curl https://calcumake.com/api/v1/printers \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "printer": {
      "name": "Bambu Lab X1 Carbon",
      "power_consumption": 350,
      "material_technology": "fdm"
    }
  }'

获取使用情况统计信息

curl https://calcumake.com/api/v1/me/usage \
  -H "Authorization: Bearer YOUR_API_TOKEN"

立即尝试

API 和所有改进对所有 CalcuMake 用户立即可用。

开始使用 API

1. 创建 API 令牌 - 创建您的第一个令牌
2. 阅读文档 - 完整的参考指南
3. 测试健康端点 - 无需身份验证！

探索功能

• 查看 API 令牌 - 管理活动令牌
• 检查 API 状态 - 获取基本 URL
• 查看代码示例 - 查看实施模式

下一步是什么？

我们已经在为 API 开发第 2 阶段的改进。

交互式文档功能：

• 复制所有代码示例到剪贴板
• 无缝导航
• 侧边栏中的活动部分突出显示
• 页面加载之间的选项卡持久性

其他端点：

• 发票管理 API
• 板级操作
• 提高效率的批量操作
• 用于实时通知的 Webhook 支持

开发者工具：

• API 客户端库（Ruby、JavaScript、Python）
• Postman 集合
• OpenAPI/Swagger 规范
• 速率限制和使用情况分析

需要帮助？

如果您对 API 有疑问，或者需要帮助将 CalcuMake 集成到您的工作流程中：

• 阅读文档 - 完整的参考
• 联系支持 - 发送电子邮件至 [email protected]
• 报告问题 - GitHub 问题

我们很高兴看到您使用 CalcuMake API 构建的内容！

技术细节

对于对实施感兴趣的开发者：

架构：

• 版本化的 Rails 8.1.1 API 控制器 (/api/v1/)
• JSON:API 兼容的响应格式
• 通过 ApiToken 模型进行 Bearer 令牌身份验证
• 用于安全的 SHA-256 令牌哈希
• 全面的测试覆盖率（1503+ 个测试）

技术：

• 用于语法高亮的 Prism.js (CDN)
• 用于代码示例的 Bootstrap 5 选项卡
• 用于交互的 Stimulus 控制器
• 用于 SPA 式导航的 Turbo
• 具有自动翻译的 I18n

性能：

• 固定的侧面导航栏 (CSS position: sticky)
• 具有移动优化的响应式设计
• CDN 加载的语法高亮
• 小的 JavaScript 占用空间