通过 Maton 代理安全接入 Jobber GraphQL API，实现客户、工单、发票、报价等字段服务业务的自动化管理。
说明：
## 核心用法
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 变更公告，预留迁移窗口 |
会员专属
