Jobber

核心用法

本技能通过 Maton 网关代理接入 Jobber GraphQL API，实现现场服务业务的全面数字化管理。用户需先获取 Maton API Key 并完成 OAuth 授权，即可调用丰富的业务操作接口。

主要功能模块：

• 客户管理：创建、查询、更新客户档案，支持邮箱、电话、账单地址等完整信息
• 工单调度：管理服务工作工单，包含状态追踪、服务说明、关联客户与房产
• 财务流程：生成报价单、创建发票、追踪付款状态，形成完整业务闭环
• 资产管理：维护服务房产地址信息，支持多地址客户场景
• 团队协作：查询团队成员信息，辅助任务分配

技术特性：

• 纯 GraphQL 接口，支持精准字段查询与复杂嵌套
• 自动注入 API 版本头（2025-04-16），保障兼容性
• Relay 风格游标分页，高效处理大数据集
• Webhook 实时事件推送，支持业务自动化

显著优点

1. 托管 OAuth 简化集成：无需自建认证流程，Maton 网关自动处理令牌刷新与安全管理
2. 现场服务垂直优化：数据模型深度贴合保洁、维修、园艺等行业需求，如 property-job-invoice 关联设计
3. 弹性连接管理：支持多账户连接切换，通过 Maton-Connection 头灵活指定工作上下文
4. 成本可控的查询：GraphQL 精确字段选择避免过度获取，配合点数限速算法（10,000 点桶/500点/秒恢复）保障公平使用

潜在局限

1. GraphQL 学习门槛：相比 REST，需理解 Schema、Resolver、嵌套查询等概念
2. 速率限制严格：DDoS 防护 2500 请求/5分钟，复杂查询可能快速消耗点数配额
3. ID 编码特殊：采用 Base64 EncodedId，需字符串化处理，调试时不够直观
4. 网关依赖风险：所有流量经 Maton 网关代理，单点故障或政策变更可能影响服务

适合人群

• 现场服务企业的技术负责人或系统管理员
• 需要集成 Jobber 到内部 CRM/ERP 的开发团队
• 构建行业 SaaS 解决方案的 ISV（独立软件开发商）
• 自动化工作流编排的技术运营人员

常规风险

| 风险类型 | 说明 |

|---------|------|

| 数据权限 | OAuth 范围配置不当可能导致过度授权，需定期审计连接权限 |

| 密钥泄露 | MATON_API_KEY 泄露可导致账户数据暴露，建议使用密钥管理服务 |

| 计费失控 | 高频 Webhook 或轮询查询可能触发速率限制，影响业务连续性 |

| 版本漂移 | Jobber API 12-18 个月弃用旧版本，需关注版本升级通知 |

| 环境变量问题 | curl 管道到 jq 时环境变量可能无法展开，建议优先使用 Python/JS SDK 方式 |

核心用法

Jobber Skill 提供对知名现场服务管理软件 Jobber 的完整 API 集成能力，采用 GraphQL 单一端点架构。用户通过 Maton 托管网关访问，所有请求发送至 https://gateway.maton.ai/jobber/graphql，自动注入 OAuth Token 和 API 版本头。

关键操作流程：
1. 认证配置：设置 MATON_API_KEY 环境变量，在 Maton 控制面板创建 OAuth 连接
2. 连接管理：通过 ctrl.maton.ai 管理多账户连接，支持 Maton-Connection 头指定特定连接
3. 核心实体操作：客户（Clients）、工单（Jobs）、发票（Invoices）、报价单（Quotes）、房产（Properties）、团队（Users）
4. 分页机制：Relay 风格游标分页，通过 pageInfo.hasNextPage 和 endCursor 遍历数据
5. Webhook 支持：实时事件推送（客户创建、工单完成、报价批准等），含 HMAC-SHA256 签名验证

代码示例覆盖：bash/cURL、Python (urllib/requests)、JavaScript (fetch)，可直接复制使用。

显著优点

| 优势 | 说明 |

|------|------|

| **托管 OAuth** | 无需自行处理令牌刷新、授权流程，Maton 网关自动管理 |

| **GraphQL 精确查询** | 按需获取字段，避免 REST 过度获取；单次请求可跨实体关联（客户→工单→房产） |

| **企业级功能覆盖** | 从线索请求（Requests）到开票收款全链路支持，适合完整业务闭环 |

| **多租户支持** | `Maton-Connection` 头实现多 Jobber 账户无缝切换 |

| **版本兼容** | 网关自动注入 API 版本头（2025-04-16），旧版本支持 12-18 个月 |

| **速率限制透明** | 双层层级保护（DDoS 2500req/5min + GraphQL 成本点数制），文档清晰 |

潜在缺点与局限性

1. GraphQL 学习曲线：仅支持 GraphQL，无 REST 替代方案；需理解 Relay 分页、EncodedId 类型、嵌套查询成本计算
2. 强依赖 Maton 生态：API 流量必须通过 Maton 网关中转，无法直连 Jobber；若 Maton 服务中断则不可用
3. 环境变量安全风险：MATON_API_KEY 泄露即导致全部 Jobber 数据访问权限暴露（报告中风险项）
4. 无本地测试模式：所有操作需联网，无沙箱/模拟响应模式用于开发调试
5. 查询成本不透明：复杂嵌套查询可能快速耗尽 10,000 点成本上限，需手动优化

适合人群

• 现场服务业务 owner：保洁、维修、园林、家政等上门服务企业
• 运营管理员：需要批量管理客户档案、调度工单、追踪开票状态
• 系统集成开发者：将 Jobber 数据同步至内部 CRM/ERP/财务系统
• 多地点连锁业务：需要统一管理多个分支的客户和服务记录

常规风险

| 风险类型 | 等级 | 说明 |

|----------|------|------|

| **API 密钥泄露** | 中 | `MATON_API_KEY` 环境变量若被日志/版本控制暴露，可导致数据泄露 |

| **第三方数据中转** | 中 | 业务数据经 Maton 网关传输，需信任其数据处理政策 |

| **OAuth 会话失效** | 低 | 连接断开后需重新授权，可能导致自动化流程中断 |

| **Rate Limit 触发** | 低 | 批量操作时易触发 429 错误，需实现指数退避重试 |

| **Webhook 验证遗漏** | 低 | 若未验证 HMAC 签名，可能受到伪造事件推送攻击 |

缓解建议：密钥轮换周期 ≤90 天、使用密钥管理工具（1Password CLI/Bitwarden）、Webhook 端点强制 HMAC 校验、生产环境启用调用日志监控。