trade-assistant/docs/API_DESIGN.md

外贸小助手 (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 <access_token>

Token 刷新：access_token 有效期 24 小时，可使用 refresh_token 换新。

---

三、API 端点清单

1. 认证 API (/auth)

方法	路径	描述	认证
POST	/auth/register	用户注册	否
POST	/auth/login	用户登录	否
POST	/auth/refresh	刷新 Token	是
GET	/auth/me	获取当前用户信息	是

注册

POST /auth/register
Content-Type: application/json

{
  "username": "string",
  "phone": "string",
  "password": "string"
}

登录

POST /auth/login
Content-Type: application/json

{
  "username": "string",
  "password": "string"
}

响应：

{
  "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)

沉默客户

GET /customers/silent?days=3

响应：

{
  "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	反馈翻译质量	是

翻译

POST /translate
Authorization: Bearer <token>
Content-Type: application/json

{
  "text": "How much for 500pcs FOB Shanghai?",
  "source": "en",
  "target": "zh"
}

响应：

{
  "original": "How much for 500pcs FOB Shanghai?",
  "translated": "上海离岸价500件多少钱？",
  "provider": "deepl",
  "tokens_used": 45
}

回复建议

POST /translate/reply
Authorization: Bearer <token>
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"
}

响应：

{
  "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	竞品分析	是

生成文案

POST /marketing/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "product_name": "户外折叠椅",
  "description": "承重150kg，防水面料，带杯架和扶手",
  "category": "furniture",
  "price": "$25",
  "target": "US importers",
  "style": "professional",
  "language": "en",
  "count": 3
}

响应：

{
  "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	更新报价单状态	是

创建报价单

POST /quotations
Authorization: Bearer <token>
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"
}

响应：

{
  "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 验证

GET /whatsapp/webhook?hub.mode=subscribe&hub.challenge=STRING&hub.verify_token=TOKEN

发送消息

POST /whatsapp/send
Authorization: Bearer <token>
Content-Type: application/json

{
  "customer_id": "uuid",
  "message": "Thank you for your inquiry. Our price is $12.5/pc."
}

---

四、错误响应格式

{
  "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=<access_token>