核心用法
Jobber 技能通过 Maton 托管的 OAuth 代理，为用户提供对 Jobber 现场服务管理平台的完整 GraphQL API 访问能力。用户需先在 Maton 平台获取 API Key 并建立 OAuth 连接，随后即可通过 https://api.maton.ai/jobber/graphql 端点执行各类操作。
该技能采用纯 GraphQL 架构，所有请求均为 POST 方法，支持查询（Query）和变更（Mutation）两类操作。核心功能覆盖六大业务实体：
- 客户管理：创建、更新、查询客户档案，支持邮箱、电话、账单地址等多字段操作
- 工单调度：完整的工单生命周期管理，包括创建、状态追踪、分配说明等
- 财务票据：发票与报价的生成、查询及行项目管理，支持自定义定价
- 资产管理：物业地址、自定义字段的维护与关联
- 团队协作：团队成员信息查询与权限管理
- 实时通知：通过 Webhook 订阅客户创建、工单完成、报价审批等事件
分页采用 Relay 风格的游标机制，pageInfo 返回 hasNextPage 和 endCursor。ID 采用 Base64 编码的 EncodedId 类型传递。
显著优点
1. 托管式 OAuth 安全：Maton 集中管理令牌刷新与版本头注入，开发者无需处理 OAuth 流程复杂性，降低凭据泄露风险
2. GraphQL 灵活性：单一端点支持精确字段选择，避免 REST 的过度获取问题，特别适合字段服务场景下的多实体关联查询
3. 企业级功能完整：原生支持报价-工单-发票业务闭环，契合 HVAC、保洁、园艺等现场服务行业的标准 workflow
4. 多连接管理：支持同一 Maton 账户绑定多个 Jobber 组织，通过 Maton-Connection 头实现租户级路由
5. 版本兼容保障：API 版本 2025-04-16 享有 12-18 个月的支持周期，变更可控
潜在局限
- GraphQL 学习成本：相比 REST，查询构造、片段复用、嵌套深度优化需要额外掌握
- 速率限制严格：采用积分制漏桶算法（10,000 分上限，500 分/秒恢复），复杂嵌套查询易触发限流
- 写入操作需人工确认：文档明确要求所有 create/update/delete 操作执行前须向用户确认目标资源及预期效果，增加交互步骤
- 代理层依赖：功能可用性绑定 Maton 服务状态，非 Jobber 官方直连
- 环境变量敏感：
MATON_API_KEY需妥善保管，多租户场景下配置管理复杂度上升
适合人群
- 现场服务企业的技术负责人，需将 Jobber 数据同步至内部 BI 或 ERP 系统
- 开发者为中小承包商构建定制客户门户或移动调度应用
- 财务自动化场景，需批量生成发票或对账
- 多地点运营的管理者，需跨组织聚合报表数据
常规风险
| 风险类别 | 描述 | 缓解建议 |
|---------|------|---------|
| 授权范围过大 | OAuth 默认覆盖客户、工单、发票等全量读写 | 定期审计 Maton 连接权限，及时删除闲置连接 |
| 误操作数据 | GraphQL 变更无二次确认机制 | 严格执行文档要求，变更前弹窗确认目标资源 |
| 速率超限 | 积分制限流导致业务中断 | 实现指数退避重试，避免深度嵌套查询 |
| 密钥泄露 | `MATON_API_KEY` 硬编码或日志暴露 | 使用密钥管理服务，禁止终端输出原始密钥 |
| 版本漂移 | Jobber 原生 API 更新与 Maton 代理版本不同步 | 关注 Maton 变更公告，预留迁移窗口 |