api-integrator

name	api-integrator
description	API 集成连接器 - 指导电商 API 集成，包括 Shopify API、ERP/CRM 集成和 Webhook 配置
version	1.0.0
author	Shopilot
argument-hint	<integration-type> [target-system]
disable-model-invocation	false
user-invocable	true

API Integrator 🔗

连接你的电商生态系统

API 集成连接器帮助电商商家实现系统间的无缝连接，从 Shopify API 集成到第三方 ERP/CRM 连接，提供完整的 API 集成指南和最佳实践。

---

🎯 常用集成场景

ERP 系统集成

目标系统:
  SAP:
    - 复杂度: 高
    - 适合: 大型企业
    - 成本: $[50,000-200,000]

  Oracle NetSuite:
    - 复杂度: 高
    - 适合: 中大型企业
    - 成本: $[25,000-100,000]

  Microsoft Dynamics:
    - 复杂度: 中高
    - 适合: 中型企业
    - 成本: $[20,000-80,000]

  Odoo:
    - 复杂度: 中
    - 适合: 中小企业
    - 成本: $[5,000-30,000]

集成功能:
  - 订单同步
  - 库存管理
  - 产品信息
  - 财务数据
  - 客户信息

CRM 系统集成

目标系统:
  Salesforce:
    - 复杂度: 中高
    - 适合: 中大型企业
    - 成本: $[10,000-50,000]

  HubSpot:
    - 复杂度: 中
    - 适合: 中小企业
    - 成本: $[5,000-20,000]

  Microsoft Dynamics 365:
    - 复杂度: 中高
    - 适合: 中大型企业
    - 成本: $[15,000-60,000]

集成功能:
  - 客户数据同步
  - 订单历史
  - 营销自动化
  - 客户服务
  - 销售管道

会计软件集成

目标系统:
  QuickBooks:
    - 复杂度: 低
    - 适合: 小型企业
    - 成本: $[2,000-10,000]

  Xero:
    - 复杂度: 低
    - 适合: 小型企业
    - 成本: $[2,000-10,000]

  Sage:
    - 复杂度: 中
    - 适合: 中小型企业
    - 成本: $[5,000-20,000]

集成功能:
  - 订单同步
  - 发票生成
  - 库存价值
  - 财务报表
  - 税务计算

---

🔌 Shopify API

API 基础

认证方式:
  API 密钥:
    - Admin API
    - 用于服务端集成
    - 需要 API 密钥和密码

  Access Token:
    - Admin API
    - 用于特定应用
    - 更安全的方式

  OAuth 2.0:
    - 用于公共应用
    - 用户授权流程

API 版本:
  - REST Admin API
  - GraphQL Admin API
  - Storefront API
  - Liquid (模板)

速率限制:
  - 漏桶算法
  - 40 请求/秒 (标准)
  - 80 请求/秒 (Plus)

常用 API 端点

REST API:
  产品:
    GET /admin/api/[version]/products.json
    POST /admin/api/[version]/products.json
    PUT /admin/api/[version]/products/[id].json
    DELETE /admin/api/[version]/products/[id].json

  订单:
    GET /admin/api/[version]/orders.json
    GET /admin/api/[version]/orders/[id].json
    POST /admin/api/[version]/orders.json

  客户:
    GET /admin/api/[version]/customers.json
    POST /admin/api/[version]/customers.json

  库存:
    GET /admin/api/[version]/inventory_levels.json
    POST /admin/api/[version]/inventory_levels/adjust.json

GraphQL API:
  - 更高效的数据查询
  - 单次请求多个资源
  - 类型安全
  - 更好的性能

最佳实践

性能优化:
  - 批量操作
  - 使用 GraphQL
  - 缓存数据
  - 异步处理

错误处理:
  - 重试机制
  - 指数退避
  - 错误日志
  - 监控告警

安全措施:
  - 使用 HTTPS
  - 验证输入
  - 限制权限
  - 定期轮换密钥

---

🔔 Webhook 配置

Webhook 设置

Webhook 事件:
  订单事件:
    - orders/create
    - orders/updated
    - orders/paid
    - orders/cancelled
    - orders/fulfilled

  产品事件:
    - products/create
    - products/update
    - products/delete

  客户事件:
    - customers/create
    - customers/update
    - customers/delete

  库存事件:
    - inventory_levels/update
    - inventory_levels/connect
    - inventory_levels/disconnect

配置步骤:
  1. 创建 Webhook 端点
  2. 验证 Webhook 请求
  3. 处理 Webhook 数据
  4. 返回响应
  5. 错误处理和重试

Webhook 处理

验证签名:
  - HMAC-SHA256
  - 验证数据完整性
  - 防止伪造请求

处理流程:
  1. 接收 Webhook
  2. 验证签名
  3. 解析数据
  4. 业务逻辑处理
  5. 返回 200 OK
  6. 错误时返回非 200

重试机制:
  - Shopify 自动重试
  - 最多 19 次
  - 指数退避
  - 最终失败通知

---

🛠️ 集成开发

开发流程

Phase 1: 需求分析
  明确需求:
    - 集成目标
    - 数据流向
    - 触发条件
    - 业务规则

  技术评估:
    - API 可用性
    - 数据结构
    - 限制条件
    - 安全要求

Phase 2: 设计
  架构设计:
    - 系统架构
    - 数据流程
    - 错误处理
    - 监控日志

  接口设计:
    - API 映射
    - 数据转换
    - 同步策略
    - 事务处理

Phase 3: 开发
  开发任务:
    - API 客户端开发
    - 数据映射
    - 业务逻辑
    - 错误处理

  测试:
    - 单元测试
    - 集成测试
    - 
     

 
  
     
      
     
     

数据同步策略

实时同步:
  - Webhook 触发
  - 低延迟
  - 高资源消耗
  - 适合关键数据

定时同步:
  - 批量处理
  - 低资源消耗
  - 有延迟
  - 适合非实时数据

增量同步:
  - 只同步变化
  - 高效
  - 需要时间戳
  - 推荐方式

全量同步:
  - 同步全部数据
  - 确保一致性
  - 高资源消耗
  - 初始化使用

---

📊 集成监控

监控指标

性能指标:
  - API 调用次数
  - 响应时间
  - 错误率
  - 速率限制使用

业务指标:
  - 同步成功率
  - 数据延迟
  - 数据量
  - 异常数量

系统指标:
  - CPU 使用率
  - 内存使用
  - 网络流量
  - 磁盘 I/O

告警配置

告警规则:
  API 错误:
    - 条件: 错误率 > 5%
    - 级别: 高
    - 通知: 即时

  同步延迟:
    - 条件: 延迟 > 5分钟
    - 级别: 中
    - 通知: 15分钟

  数据不一致:
    - 条件: 数据校验失败
    - 级别: 高
    - 通知: 即时

通知方式:
  - 邮件
  - 短信
  - Slack/钉钉
  - PagerDuty

---

🔗 相关 Skills

• /multi-store-manager - 多店铺 API 集成
• /order-automation - 订单自动化集成
• /inventory-optimizer - 库存系统集成
• /workflow-automation - 工作流集成
• /customer-profile-builder - CRM 集成

---

📊 成功指标

技术指标

• API 成功率 > 99.5%
• 平均响应时间 < 500ms
• 数据延迟 < 30秒

业务指标

• 数据准确率 > 99.9%
• 同步覆盖率 = 100%
• 异常恢复时间 < 1小时

---

⚠️ 注意事项

常见错误

• 忽视速率限制
• 错误处理不足
• 数据验证缺失
• 监控告警缺失

最佳实践

• 幂等性设计
• 完整的错误处理
• 充分的日志记录
• 定期的数据校验

---

Connect everything, automate anything! 🔗

版本: 1.0.0 更新: 2026-04-12 作者: Shopilot Team