tangwang / shoplazza_oauth_backend

step_by_step_oauth.md 4.21 KB

OAuth2.0 认证步骤详解

🎯 完整认证流程

步骤1: 准备阶段

1.1 获取Shoplazza应用凭证

1. 访问 https://partners.shoplazza.com/
2. 登录并创建新应用
3. 记录 CLIENT_ID 和 CLIENT_SECRET

1.2 设置本地开发环境

# 安装依赖
pip install -r requirements.txt

# 安装ngrok (用于本地开发)
npm install -g ngrok

1.3 启动ngrok隧道

# 在终端1中启动ngrok
ngrok http 3000

# 记录ngrok提供的HTTPS URL，例如：
# https://abc123.ngrok.io

步骤2: 配置应用

2.1 创建环境配置文件

创建 .env 文件：

CLIENT_ID=your_actual_client_id_from_shoplazza
CLIENT_SECRET=your_actual_client_secret_from_shoplazza
BASE_URL=https://abc123.ngrok.io
REDIRECT_URI=/auth/shoplazza/callback
SECRET_KEY=your-random-secret-key
FLASK_ENV=development
FLASK_DEBUG=True
PORT=3000

2.2 在Shoplazza开发者中心配置URL

应用URL: https://abc123.ngrok.io/auth/install
回调URL: https://abc123.ngrok.io/auth/shoplazza/callback
Webhook URL: https://abc123.ngrok.io/webhook/shoplazza

步骤3: 启动应用

# 在终端2中启动应用
python run.py

您应该看到类似输出：

🚀 启动 Shoplazza OAuth2.0 后端服务...
📡 服务地址: http://localhost:3000
🔗 认证端点: https://abc123.ngrok.io/auth/install?shop=your-shop.myshoplaza.com
📋 API文档: https://abc123.ngrok.io/

步骤4: 执行OAuth认证

4.1 开始认证流程

在浏览器中访问：

https://abc123.ngrok.io/auth/install?shop=your-shop.myshoplaza.com

注意: 将 your-shop.myshoplaza.com 替换为实际的商店域名

4.2 授权确认

  1. 系统会重定向到Shoplazza授权页面
  2. 商家点击"安装应用"或"授权"
  3. 系统自动处理回调

4.3 验证认证结果

访问以下URL查看认证状态：

https://abc123.ngrok.io/auth/tokens

步骤5: 测试API调用

5.1 获取客户列表

curl https://abc123.ngrok.io/api/customers/your-shop.myshoplaza.com

5.2 获取产品列表

curl https://abc123.ngrok.io/api/products/your-shop.myshoplaza.com

5.3 获取订单列表

curl https://abc123.ngrok.io/api/orders/your-shop.myshoplaza.com

5.4 获取商店信息

curl https://abc123.ngrok.io/api/shop_info/your-shop.myshoplaza.com

🔍 认证流程详解

OAuth2.0 流程图

商家 → 应用安装 → 授权页面 → 确认授权 → 回调处理 → 获取令牌 → API调用

详细步骤说明

  1. 应用安装请求

    • 商家从应用商店安装应用
    • Shoplazza发送请求到 /auth/install
    • 应用重定向到Shoplazza授权页面

  2. 用户授权

    • 商家在Shoplazza页面确认授权
    • 选择需要的权限范围
    • 点击"安装应用"

  3. 授权回调

    • Shoplazza重定向到 /auth/shoplazza/callback
    • 携带授权码和HMAC签名
    • 应用验证HMAC签名

  4. 令牌交换

    • 应用使用授权码请求访问令牌
    • Shoplazza返回访问令牌和刷新令牌
    • 应用存储令牌用于后续API调用

  5. API调用

    • 使用访问令牌调用Shoplazza API
    • 获取客户、产品、订单等数据

🛠️ 故障排除

常见错误及解决方案

  1. "Missing HMAC parameter"

    • 检查请求是否来自Shoplazza
    • 确认URL参数完整

  2. "HMAC validation failed"

    • 检查CLIENT_SECRET配置
    • 确认请求参数顺序正确

  3. "Shop not authorized"

    • 确认已完成OAuth认证
    • 检查访问令牌是否有效

  4. "Failed to obtain access token"

    • 检查CLIENT_ID和CLIENT_SECRET
    • 确认回调URL配置正确

调试命令

# 检查应用状态
curl https://abc123.ngrok.io/health

# 查看已授权的商店
curl https://abc123.ngrok.io/auth/tokens

# 刷新访问令牌
curl https://abc123.ngrok.io/auth/refresh_token/your-shop.myshoplaza.com

📝 注意事项

  1. HTTPS要求: 生产环境必须使用HTTPS
  2. 令牌安全: 生产环境应使用数据库存储令牌
  3. 错误处理: 实现适当的错误处理和日志记录
  4. 权限范围: 只请求应用实际需要的权限
  5. 令牌刷新: 定期刷新访问令牌以保持有效性