品應用 API 文件

快速開始

品應用 API 基於 RESTful 架构，所有请求使用 HTTPS 协议，数据格式为 JSON。基础 URL 为：

https://api.pwmapp.com/v1

第一步：获取 API Key

登入 品應用 管理後台，進入「設定 - 開發者 - API 密钥」，點擊「創建密钥」。系统會生成一对 API Key 和 API Secret，请妥善儲存。

第二步：發起第一個请求

使用 curl 測試获取客戶列表：

curl -X GET "https://api.pwmapp.com/v1/customers?page=1&page_size=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

成功回應示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 156,
    "page": 1,
    "page_size": 10,
    "items": [
      {
        "id": "cus_abc123",
        "name": "華东建材集團",
        "industry": "building_materials",
        "level": "A",
        "contact": "張經理",
        "phone": "138****8888",
        "created_at": "2026-01-15T10:30:00Z"
      }
    ]
  }
}

认证方式

品應用 API 支援两種认证方式：

1. API Key（推薦）

在请求頭中携带 API Key：

Authorization: Bearer YOUR_API_KEY

2. OAuth 2.0

適用於第三方应用集成。流程：

1. 在開發者後台創建 OAuth 应用，获取 client_id 和 client_secret
2. 引导使用者访问授权頁：https://app.pwmapp.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code
3. 使用者授权後，获取 code，换取 access_token
4. 使用 access_token 调用 API

错误碼

错误回應格式：

{
  "code": 10002,
  "message": "Invalid API Key",
  "request_id": "req_xyz789"
}

頻率限制

超出限制时返回 429 状态碼，回應頭中包含 X-RateLimit-Reset 表示重置時間（Unix 時間戳）。

SDK 下載

我們提供多種语言的官方 SDK，简化集成过程：

• Python SDK：pip install pwmapp
• Node.js SDK：npm install @pwmapp/sdk
• Java SDK：Maven 依赖，详见 GitHub
• Go SDK：go get github.com/pwmapp/go-sdk
• PHP SDK：Composer 安裝

SDK 源碼和示例：https://github.com/pwmapp

接口參考

客戶管理

創建客戶请求示例：

POST /v1/customers
{
  "name": "恒瑞醫药連锁",
  "industry": "pharmaceutical",
  "level": "A",
  "contact": "李主任",
  "phone": "13900001111",
  "email": "li@hengrui.com",
  "address": "上海市浦东新區張江路100號",
  "tags": ["重點客戶", "醫药"],
  "custom_fields": {
    "hospital_level": "三甲",
    "annual_budget": "5000000"
  }
}

商机管理

外勤拜访

跟進记录

数据报表

AI 能力

AI 对话请求示例：

POST /v1/ai/chat
{
  "query": "本月華东區的銷售漏斗健康度如何？",
  "context": {
    "user_id": "usr_001",
    "page": "dashboard"
  },
  "stream": false
}

Webhook

Webhook 允许您在特定事件發生时接收即時通知。在「設定 - 開發者 - Webhook」中配置回调 URL 和订閱事件。

支援的事件類型：

• customer.created / customer.updated / customer.deleted
• opportunity.created / opportunity.stage_changed / opportunity.won / opportunity.lost
• visit.checkin / visit.checkout / visit.report_generated
• activity.created
• ai.alert.triggered（AI 异常預警）

Webhook 推送示例：

POST /your-webhook-endpoint
X-pwmapp-Signature: sha256=abc123...
{
  "event": "opportunity.won",
  "timestamp": "2026-08-29T10:30:00Z",
  "data": {
    "id": "opp_001",
    "name": "華东建材年度采购",
    "amount": 500000,
    "customer_id": "cus_001",
    "owner_id": "usr_001"
  }
}