# 外贸小助手 (TradeMate) — API 设计文档 > 版本: v1.0 > 创建日期: 2026-05-08 --- ## 一、Base URL ``` Production: https://api.trademate.example.com/api/v1 Development: http://localhost:8000/api/v1 ``` --- ## 二、认证方式 采用 JWT Bearer Token 认证，请求 Header 中需携带： ``` Authorization: Bearer ``` Token 刷新：access_token 有效期 24 小时，可使用 refresh_token 换新。 --- ## 三、API 端点清单 ### 1. 认证 API (`/auth`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | POST | `/auth/register` | 用户注册 | 否 | | POST | `/auth/login` | 用户登录 | 否 | | POST | `/auth/refresh` | 刷新 Token | 是 | | GET | `/auth/me` | 获取当前用户信息 | 是 | #### 注册 ```http POST /auth/register Content-Type: application/json { "username": "string", "phone": "string", "password": "string" } ``` #### 登录 ```http POST /auth/login Content-Type: application/json { "username": "string", "password": "string" } ``` 响应： ```json { "access_token": "string", "refresh_token": "string", "token_type": "bearer", "user": { "id": "uuid", "username": "string", "tier": "free" } } ``` --- ### 2. 客户管理 API (`/customers`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | GET | `/customers` | 获取客户列表 | 是 | | GET | `/customers/silent` | 获取沉默客户列表 | 是 | | GET | `/customers/{id}` | 获取单个客户详情 | 是 | | POST | `/customers` | 创建新客户 | 是 | | PATCH | `/customers/{id}` | 更新客户信息 | 是 | | DELETE | `/customers/{id}` | 删除客户 | 是 | | GET | `/customers/{id}/conversation` | 获取客户对话记录 | 是 | #### 列表查询参数 - `status`: 筛选状态 (lead/negotiating/customer/lost) - `page`: 页码 (默认 1) - `size`: 每页数量 (默认 20) #### 沉默客户 ```http GET /customers/silent?days=3 ``` 响应： ```json { "customers": [ { "id": "uuid", "name": "Carlos", "country": "Mexico", "last_contact_at": "2026-05-01T10:00:00Z", "silence_days": 5 } ], "count": 10, "silence_days": 3 } ``` --- ### 3. 翻译与回复 API (`/translate`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | POST | `/translate` | 翻译文本 | 是 | | POST | `/translate/reply` | 生成回复建议 | 是 | | POST | `/translate/extract` | 提取关键信息 | 是 | | POST | `/translate/feedback` | 反馈翻译质量 | 是 | #### 翻译 ```http POST /translate Authorization: Bearer Content-Type: application/json { "text": "How much for 500pcs FOB Shanghai?", "source": "en", "target": "zh" } ``` 响应： ```json { "original": "How much for 500pcs FOB Shanghai?", "translated": "上海离岸价500件多少钱？", "provider": "deepl", "tokens_used": 45 } ``` #### 回复建议 ```http POST /translate/reply Authorization: Bearer Content-Type: application/json { "customer_message": "Hi, I'm interested in your outdoor chairs. Can you give me a quote for 500pcs?", "product_context": "户外折叠椅，承重150kg", "tone": "professional" } ``` 响应： ```json { "suggestions": [ { "text": "Thank you for your inquiry. Our FOB Shanghai price for 500pcs is $12.5/pc. Lead time is 25 days. Payment terms: T/T 30% deposit.", "tone": "professional", "reasoning": "Based on询价 context, direct quote with terms" }, { "text": "Hi! Thanks for reaching out. I'd be happy to help you with our outdoor folding chairs. $12.5/pc for 500pcs, FOB Shanghai. Want more details?", "tone": "friendly", "reasoning": "More casual approach for initial contact" } ] } ``` --- ### 4. 营销素材 API (`/marketing`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | POST | `/marketing/generate` | 生成营销文案 | 是 | | POST | `/marketing/keywords` | 生成关键词建议 | 是 | | POST | `/marketing/competitor-analysis` | 竞品分析 | 是 | #### 生成文案 ```http POST /marketing/generate Authorization: Bearer Content-Type: application/json { "product_name": "户外折叠椅", "description": "承重150kg，防水面料，带杯架和扶手", "category": "furniture", "price": "$25", "target": "US importers", "style": "professional", "language": "en", "count": 3 } ``` 响应： ```json { "results": [ "Premium Outdoor Folding Chair - 150kg Load Capacity, Waterproof Fabric, Cup Holder & Armrests. Perfect for patios, camping, and events. FDA certified manufacturer.", "Heavy-Duty Folding Chair: 150kg capacity, waterproof, portable. Ideal for restaurants, events, outdoor venues. MOQ: 100pcs. FOB Shanghai.", "Upgrade your outdoor seating! Our folding chairs feature reinforced steel frame, waterproof fabric, and convenient cup holder. Bulk orders welcome." ], "product": "户外折叠椅", "target": "US importers", "count": 3 } ``` --- ### 5. 报价单 API (`/quotations`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | POST | `/quotations` | 创建报价单 | 是 | | GET | `/quotations` | 获取报价单列表 | 是 | | GET | `/quotations/{id}` | 获取报价单详情 | 是 | | PATCH | `/quotations/{id}/status` | 更新报价单状态 | 是 | #### 创建报价单 ```http POST /quotations Authorization: Bearer Content-Type: application/json { "customer_id": "uuid", "title": "Quote for Outdoor Chairs", "currency": "USD", "payment_terms": "T/T 30% deposit", "delivery_terms": "FOB Shanghai", "lead_time": "25 days", "valid_until": "2026-06-08", "items": [ { "product_name": "Outdoor Folding Chair", "description": "150kg capacity, waterproof", "quantity": 500, "unit_price": 12.5, "unit": "pcs" } ], "discount": 0, "shipping": 0, "notes": "Sample quote" } ``` 响应： ```json { "id": "uuid", "customer_id": "uuid", "title": "Quote for Outdoor Chairs", "status": "draft", "currency": "USD", "subtotal": 6250, "total": 6250, "items": [...], "text": "QUOTATION\n\nDate: 2026-05-08...", "created_at": "2026-05-08T10:00:00Z" } ``` --- ### 6. WhatsApp API (`/whatsapp`) | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | GET | `/whatsapp/webhook` | Webhook 验证 | 否 | | POST | `/whatsapp/webhook` | Webhook 接收消息 | 否 | | POST | `/whatsapp/send` | 发送消息 | 是 | | GET | `/whatsapp/qr` | 获取二维码 | 是 | #### Webhook 验证 ```http GET /whatsapp/webhook?hub.mode=subscribe&hub.challenge=STRING&hub.verify_token=TOKEN ``` #### 发送消息 ```http POST /whatsapp/send Authorization: Bearer Content-Type: application/json { "customer_id": "uuid", "message": "Thank you for your inquiry. Our price is $12.5/pc." } ``` --- ## 四、错误响应格式 ```json { "error": "error_code", "detail": "具体错误描述", "timestamp": "2026-05-08T10:00:00Z" } ``` 常见错误码： - `UNAUTHORIZED`: 未认证 - `FORBIDDEN`: 无权限 - `NOT_FOUND`: 资源不存在 - `QUOTA_EXCEEDED`: 配额超限 - `TIER_LIMITED`: 订阅等级限制 - `VALIDATION_ERROR`: 参数校验失败 --- ## 五、速率限制 | 级别 | 请求限制 | |------|---------| | 免费版 | 100 请求/分钟 | | Pro版 | 500 请求/分钟 | | 企业版 | 2000 请求/分钟 | --- ## 六、WebSocket (可选) 实时翻译进度和消息推送： ``` wss://api.trademate.example.com/ws/translate ``` 连接需携带 Token 参数： ``` wss://api.trademate.example.com/ws/translate?token= ```