# PingCAP Account API 文档

## 说明

> 所有的 API 调用都有频率限制，未认证用户 30 次/分钟, 认证用户 100 次/分钟，超出调用频率会返回 HTTP-Status-Code 429  
> i18n支持(zh-hans/en-us), 在请求 Header 中声明： Accept-Language: zh-hans  
> 当 cookie 中有 csrftoken 时, put|post|delete|patch 等请求需在 header 中声明: X-CSRFTOKEN  
> 以下 API 文档中均未提及 5xx 错误, 但你在使用 API 的时候应考虑到相关错误(包括网络延时)

### 关于跨域

以下接口同时部署在了 `https://accounts.pingcap.cn/api/`、`https://tidb.io/api/` 和 `https://asktug.com/_/sso/api/` 目录下，在这三个域名下你只需要设置不同的 URL Prefix 即可调用对应接口, 所以不会涉及到进行跨域的问题。

### PRD https://pingcap.feishu.cn/docs/doccn9IRDeuKKBhFJtixjaLvlib#jNzLNg

- [TiDB 版本列表](#TiDB-版本列表)
- [用户资格预检查](#用户资格预检查)
- [提交紧急事故处理](#提交紧急事故处理)
- [提交社区生态合作](#提交社区生态合作)
- [提交技术专家交流](#提交技术专家交流)
- [官网联系我们 发送验证码](#官网联系我们-发送验证码)
- [官网联系我们](#官网联系我们)
- [官网联合解决方案互认证申请](#官网联合解决方案互认证申请)
- [社区联系我们](#社区联系我们)

### TiDB 版本列表

#### Request

- Method: **GET**
- URL: `/api/tidb-releases`
- Content-Type: application/json
- Permission: AllowAny

#### Response Example

- Success

  - HTTP/1.1 200

    ```json
    {
      "detail": "success",
      "data": [
        {
          "major_number": 5,
          "prefix": "v5",
          "children": [
            "v5.1.0",
            "v5.0.3",
            "v5.0.1"
          ]
        },
        {
          "major_number": 4,
          "prefix": "v4",
          "children": [
            "v4.1.0",
            "v4.0.1",
            "v4.0.0"
          ]
        }
      ]
    }
    ```


### 用户资格预检查

#### Request

- Method: **GET**
- URL: `/api/contact-us/validate-qualification`
- Content-Type: application/json
- Permission: Authenticated User

#### Response Example

- Success

  - HTTP/1.1 200

    ```json
    {
      "detail": "success",
      "data": {
        "company_info_is_completed": true,  // 公司信息是否完善
        "phone_email_is_completed": true, // 手机号和邮箱是否完善
      }
    }
    ```

- Failed

  - HTTP/1.1 401

    ```json
    {
      "detail": "Authentication credentials were not provided"
    }
    ```


### 提交紧急事故处理

#### Request

- Method: **POST**
- URL: `/api/contact-us/emergencies`
- Body:

  ```json
  {
    "emergency_type": "online",  // 事故类型, choices: online(在线业务)/offline(离线业务), 必填
    "priority": "p0",            // 事故等级, choices: p0/p1/p2_and_below, 必填
    "tidb_version": "v1",        // TiDB 版本, 必填
    "summary": "",               // 场景 + 问题概述, 500 字限制, 必填
    "background": "",            // 背景(做过哪些操作), 500 字限制, 必填
    "appearance": "",            // 业务和数据库现象, 500 字限制, 必填
    "problem": "",               // 当前遇到的问题, 500 字限制, 必填
    "affect": "",                // 业务影响, 500 字限制, 必填
  }
  ```
- Content-Type: application/json
- Permission: Authenticated User

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "emergency_type": [ "`onoffline` is not a valid choice" ],
        "affect": [ "this field is required" ]
      }
    }
    ```

  - HTTP/1.1 401

    ```json
    {
      "detail": "Authentication credentials were not provided"
    }
    ```

  - HTTP/1.1 428  用户需要先补全信息后才能继续提交

    ```json
    {
      "detail": "precondition required",
      "data": {
        "company_info_is_completed": false,  // 公司信息是否完善
        "phone_email_is_completed": true, // 手机号和邮箱是否完善
      }
    }
    ```


### 提交社区生态合作

#### Request

- Method: **POST**
- URL: `/api/contact-us/cooperation`
- Body:

  ```json
  {
    "cooperation_type": "technology",  // 合作类型, choices: technology(技术合作)/community(社区活动)/other(其他), 必填
    "detail": "",            // 详细内容, 限制 300 字, 必填
  }
  ```
- Content-Type: application/json
- Permission: Authenticated User

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "cooperation_type": [ "this field is required" ],
        "detail": [ "this field is required" ]
      }
    }
    ```

  - HTTP/1.1 401

    ```json
    {
      "detail": "Authentication credentials were not provided"
    }
    ```

  - HTTP/1.1 428  用户需要先补全信息后才能继续提交

    ```json
    {
      "detail": "precondition required",
      "data": {
        "company_info_is_completed": true,  // 公司信息是否完善
        "phone_email_is_completed": false, // 手机号和邮箱是否完善
      }
    }
    ```


### 提交技术专家交流

#### Request

- Method: **POST**
- URL: `/api/contact-us/communication`
- Body:

  ```json
  {
    "tidb_node_num": 1,          // TiDB 节点数, 最小为 0, 必填
    "tikv_node_num": 1,          // TiKV 节点数, 最小为 0, 必填
    "tiflash_node_num": 1,       // TiFlash 节点数, 最小为 0, 必填
    "occupation_rate_of_tidb": 0.5,  // TiDB 在贵司 RDBMS 中的占有率, float, 取值在 0 和 1 之间, 必填
    "tidb_version": ["v1.x", "v2.x"],  // TiDB 版本, 多选, 必填
    "key_scene": "",            // 重点高优先级场景, 100 字限制, 非必填
    "current_scenarios_and_architecture": "",    // 当前业务场景和技术架构, 100 字限制, 必填
    "pain_points": "",                // 业务痛点, 100 字限制, 必填
    "technical_debt": "",             // 技术场景面临的挑战, 100 字限制, 必填
    "expect_benefits_from_tidb": "",  // 希望 TiDB 带来哪些收益, 100 字限制, 必填
    "launch_or_poc_date": "2021-07-09",  // 业务计划上线或者 POC 时间, 日期格式(2021-07-09), 非必填
    "person_resource": 1,            // 该业务人力安排(人/天), int, 非必填
    "tidb_usage": ["htap", "olap"],  // 希望 TiDB 支撑的数据模型, choices: htap/olap/olap_scale/rawkv, 必填
  }
  ```
- Content-Type: application/json
- Permission: Authenticated User

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "tidb_node_num": [ "this field is required" ],
        "pain_points": [ "this feild is required" ]
      }
    }
    ```

  - HTTP/1.1 401

    ```json
    {
      "detail": "Authentication credentials were not provided"
    }
    ```

  - HTTP/1.1 428  用户需要先补全信息后才能继续提交

    ```json
    {
      "detail": "precondition required",
      "data": {
        "company_info_is_completed": false,  // 公司信息是否完善
        "phone_email_is_completed": true, // 手机号和邮箱是否完善
      }
    }
    ```

### 官网联系我们 发送验证码

#### Request

- Method: **POST**
- URL: `/api/official/contact-us/sms-code`
- Content-Type: application/json
- Permission: Anyone
- Body

  ```json
  {
    "phone" : "136xxxxxxxx",  // 手机号, 必填
    "captcha_key": "5abf340505f84e5b9af959481d73c915",  // 验证码 key, 选填
    "captcha_response": "abcd",  // 验证码答案, 选填
  }
  ```

#### Response Example

- Success

  - HTTP 200 发送成功

    ```json
    {
      "detail": "success"
    }
    ```

- Failed

  - HTTP 400 参数错误

    ```json
    {
      "detail": "params error",
      "errors": {
          "phone": ["this field is required"],  // 键是传入的名参数; 值是一个数组, 其中包含了具体的错误信息
          "captcha_response": ["invalid captcha response"], // 验证码答案错误
      }
    }
    ```

  - HTTP 428 需要填入验证码

    ```json
    {
      "detail": "captcha required",
      "data": {
        "key": "5abf340505f84e5b9af959481d73c915",
        "image_url": "https://accounts.pingcap.cn/captcha/image/5abf340505f84e5b9af959481d73c915"
      }
    }
    ```

  - HTTP 429 频率限制, 同一手机号, 1 分钟内只能发送一次验证码

    ```json
    {
      "detail": "rate limit"
    }
    ```

### 官网联系我们

#### Request

- Method: **POST**
- URL: `/api/official/contact-us`
- Body:

  ```json
  {
    "name": "张三",              // 姓名, 最多 32 字, 必填
    "phone": "136xxx1111",      // 中国手机号, 11 位, 必填
    "phone_code": "123456",     // 手机验证码, 6 位, 必填
    "company": "PingCAP",       // 公司名称, 最多 128 字, 必填
    "job_title": "xxx_003",     // 职位代码, 选填,  来源: https://gist.github.com/wd0517/c5d407f165b6a0485cbc66d6acaa47ae
    "consult_category": "xxx_01", // 咨询类别, 选填, 来源: https://gist.github.com/wd0517/c5d407f165b6a0485cbc66d6acaa47ae
    "consult_detail": "",     // 咨询事宜, 最多 1000 字, 选填
    "utm_source": "",       // 最长 64 字, 选填
    "utm_medium": "",       // 最长 64 字, 选填
    "utm_campaign": "",     // 最长 64字, 选填
    "utm_term": "",         // 最长 64 字, 选填
    "referer": "",          // 留资页面 URL, 最长 2000 字, 选填
    "referer2": "",          // 留资前一页面 URL, 最长 2000 字, 选填
  }
  ```

- Content-Type: application/json
- Permission: Anyone

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "name": [ "this field is required" ],  // 键是传入的名参数; 值是一个数组, 其中包含了具体的错误信息
        "phone": [ "this field is required" ],
        "phone_code": [ "this field is required" ],
      }
    }
    ```

### 官网联合解决方案互认证申请

#### Request

- Method: **POST**
- URL: `/api/official/joint-solution-mutual-certification`
- Content-Type: multipart/form-data
- Permission: Anyone
- Body:

  | 字段    | 类型 | 必填 | 说明 |
  | -------- | -------- | -------- | -------- |
  | company  | string   | 必填     | 公司名称，最多 100 字 |
  | company_address  | string   | 必填     | [公司地址](https://gist.github.com/wd0517/c5d407f165b6a0485cbc66d6acaa47ae#file-pingcap_crm_options-txt-L61)   |
  | application_type | string   | 必填     | [申请类型](https://gist.github.com/wd0517/c5d407f165b6a0485cbc66d6acaa47ae#file-pingcap_crm_options-txt-L84) |
  | contact_name | string   | 必填     | 联系人姓名，最多 100 字 |
  | contact_job_title | string   | 必填     | 联系人职位，最多 32 字 |
  | contact_phone | string   | 必填     | 联系人手机号，11 位 |
  | phone_code | string   | 必填     | 联系人手机号验证码，6 位 |
  | contact_address | string   | 必填     | 联系人邮寄地址，最多 100 字 |
  | joint_solution_name | string   | 必填     | 联合解决方案名称，最多 100 字 |
  | joint_solution_description | string   | 必填     | 联合解决方案介绍 |
  | joint_solution_industry | string   | 必填     | [产品重点推广行业](https://gist.github.com/wd0517/c5d407f165b6a0485cbc66d6acaa47ae#file-pingcap_crm_options-txt-L91) |
  | joint_solution_contact_name | string   | 必填     | 合作伙伴证书负责人姓名 |
  | joint_solution_contact_job_title | string   | 必填     | 合作伙伴证书负责人职务 |
  | attachment_docx | 文件   | 必填     | 必须为 doc、docx 文件，限制 50M 大小 |
  | attachment_xlsx | 文件   | 必填     | 必须为 xlsx 文件，限制 50M 大小 |

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "company_address": [ "this field is required" ],  // 键是传入的名参数; 值是一个数组, 其中包含了具体的错误信息
        "phone_code": [ "this field is required" ],
      }
    }
    ```


### 社区联系我们

#### Request

- Method: **POST**
- URL: `/api/community-contact-us`
- Body:

  ```json
  {
    "name": "张三",              // 姓名, 最多 32 字, 必填
    "phone": "136xxx1111",      // 中国手机号, 11 位, 未登录时必填
    "phone_code": "123456",     // 手机验证码, 6 位, 未登录时必填, 使用 /api/official/contact-us/sms-code 发送验证码
    "company": "PingCAP",       // 公司名称, 最多 128 字, 必填
    "consult_detail": "",       // 咨询事宜, 最多 1000 字, 选填
  }
  ```

- Content-Type: application/json
- Permission: Anyone

#### Response Example

- Success
  - HTTP/1.1 200

    ```json
    {
        "detail": "success"
    }
    ```

- Failed

  - HTTP/1.1 400

    ```json
    {
      "detail": "params error",
      "errors": {
        "name": [ "this field is required" ],  // 键是传入的名参数; 值是一个数组, 其中包含了具体的错误信息
        "phone": [ "this field is required" ],
        "phone_code": [ "this field is required" ],
      }
    }
    ```