cccb7cfc
 tangwang
init
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
# OAuth2.0 认证步骤详解
## 🎯 完整认证流程
### 步骤1: 准备阶段
#### 1.1 获取Shoplazza应用凭证
```
1. 访问 https://partners.shoplazza.com/
2. 登录并创建新应用
3. 记录 CLIENT_ID 和 CLIENT_SECRET
```
#### 1.2 设置本地开发环境
```bash
# 安装依赖
pip install -r requirements.txt
# 安装ngrok (用于本地开发)
npm install -g ngrok
```
#### 1.3 启动ngrok隧道
```bash
# 在终端1中启动ngrok
ngrok http 3000
# 记录ngrok提供的HTTPS URL，例如：
# https://abc123.ngrok.io
```
### 步骤2: 配置应用
#### 2.1 创建环境配置文件
创建 `.env` 文件：
```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: 启动应用
```bash
# 在终端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 获取客户列表
```bash
curl https://abc123.ngrok.io/api/customers/your-shop.myshoplaza.com
```
#### 5.2 获取产品列表
```bash
curl https://abc123.ngrok.io/api/products/your-shop.myshoplaza.com
```
#### 5.3 获取订单列表
```bash
curl https://abc123.ngrok.io/api/orders/your-shop.myshoplaza.com
```
#### 5.4 获取商店信息
```bash
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配置正确
### 调试命令
```bash
# 检查应用状态
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. **令牌刷新**: 定期刷新访问令牌以保持有效性
|