# 今日水印相机api技术文档

# 1 简介

## 1.1 什么是今日水印相机api

开放平台支持今日水印相机用户自有系统接入，照片资源与水印信息等数据可同步至自有系统，获得对数据的二次开发的能力，从而满足各类定制化需求。

## 1.2 今日水印相机api能做什么

初步开放以下功能，更多功能正在逐步开发中。 - 获取照片数据 - 获取水印数据 - 团队组织架构

## 1.3 今日水印相机api的安全保障说明

开放平台 api 数据传输全程加密（密钥按月更新，可以支持更高安全标准的密钥动态下发），用户通过开放平台 api 传输的数据全程不存储、不落库，保证用户数据隐私和安全，系统全流程符合国家三级等保标准，系统无被入侵风险，数据无泄漏风险。

# 2 接入准备

目前支持两种接入方式:主动拉取数据，webhook推送数据

## 2.1 主动拉取数据

![png2](https://net-cloud.xhey.top/data/9333f089-c128-4b21-8560-11d6e020f786.png)

## 2.2 webhook推送数据

通过提供webhook的domain，与开放平台建立绑定关系。一旦有新数据更新时，会自动将增量数据推送至自建系统。

![](https://net-cloud.xhey.top/data/364f87da-4724-44af-b401-7d825e8f7186.png)

## 2.3 加签流程

对接沟通后，我们会给提供跟团队绑定的唯一key和secret。

以v2/department/sublist接口为例:

1. 接口请求参数为：

```javascript
{
  "departmentID": 1
}
```

2. 将该请求参数序列化并进行一次签名，目前仅支持HmacSha256算法，签名函数如下：

```golang
// data是加密的内容
func sign(data string, groupSecret string) (ret string) {
    hmacObj := hmac.New(sha256.New, []byte(groupSecret))
    hmacObj.Write([]byte(data))
    ret = base64.StdEncoding.EncodeToString(hmacObj.Sum(nil))
    return ret
}
```

3. 把groupKey、参数签名（第二步的结果）、timestamp拼接为一个字符串

```golang
timestamp := time.Now().Unix()
groupKey := "groupKey"
str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
    groupKey,
    sign,
    strconv.FormatInt(timestamp, 10),
)
```

4. 把第三步拼接后的字符串再进行一次签名，并得到最终签名。

```golang
signature := sign(str, "groupSecret")
```

5. 把对应的信息设置至header头中。

```golang
req, _ := http.NewRequest(http.MethodGet, "url", nil)
req.Header.Set("GroupKey", groupKey)
req.Header.Set("Timestamp", strconv.FormatInt(timestamp, 10))
req.Header.Set("Signature", signature)
```

完整Http客户端代码如下：

```golang
func main() {
    data := map[string]interface{}{
        "departmentID": 1,
    }
    buf, _ := json.Marshal(data)

    groupKey := "groupKey"       // 需申请
    groupSecret := "groupSecret" // 需申请
    dataSign := sign(string(buf), groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    // sign为加签流程中定义的函数
    signature := sign(str, groupSecret)

    url := "https://openapi.xhey.top/v2/department/sublist"

    client := &http.Client{}
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(buf))
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    _, _ = client.Do(req)
}

func sign(source string, groupSecret string) string {
    hmacObj := hmac.New(sha256.New, []byte(groupSecret))
    hmacObj.Write([]byte(source))
    return base64.StdEncoding.EncodeToString(hmacObj.Sum(nil))
}

```

Python版本

```python
# -*- coding: utf-8 -*-
import json
import requests
import hashlib
import time
import base64
import hmac


# 计算签名
def generate_signature(data, secret_key):
    hmac_obj = hmac.new(secret_key.encode('utf-8'), data.encode('utf-8'), hashlib.sha256)
    return base64.b64encode(hmac_obj.digest()).decode('utf-8')


# 请求数据
data = {
    "departmentID": 1,
}

json_data = json.dumps(data)

group_secret = "groupSecret"
group_key, timestamp = "groupKey", str(int(time.time()))
data_sign = generate_signature(json_data, group_secret)

str_to_sign = "groupKey={0}&sign={1}&timestamp={2}".format(group_key, data_sign, timestamp)

signature = generate_signature(str_to_sign, group_secret)

url = "https://openapi.xhey.top/v2/department/sublist"

# 构建请求头
headers = {
    "GroupKey": group_key,
    "Timestamp": timestamp,
    "Signature": signature
}

# 发送HTTP POST请求
response = requests.post(url, data=json_data, headers=headers)

```

## 2.4 Webhook 推送加签

前提：配置了webhook地址的团队也必须申请groupKey以及groupSecret，否则无法进行签名验证。

1. 获取header头中的Timestamp、GroupKey、Signature。
2. 校验Timestamp、GroupKey是否合法。（Timestamp校验规则由接入方自行定义）
3. 获取当前请求参数，并通过GroupKey对应的GroupSecret生成DataSign。
4. GroupKey、DataSign、Timestamp拼接成一个字符串并通过GroupSecret生成最终的Signature
5. 校验第四步生成的Signature是否与header中的Signature一致

参考代码：

```golang
body, _ := ioutil.ReadAll(c.Request.Body)
timestamp := c.GetHeader("Timestamp")
// 校验时间戳
groupKey := c.GetHeader("GroupKey")
// 通过groupKey获取groupSecret
dataSign := sign(string(body), "groupSecret")

str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
    groupKey,
    dataSign,
    timestamp,
)
signature := sign(str, "groupSecret")

return signature == c.GetHeader("Signature")
```

# 3 API 接口总览

下表为**普通 API** 全部接口,按功能模块归类;详细请求 / 返回见后续章节。

| 类目         | 接口                       | 请求方式 | 请求路径                          |
| ------------ | -------------------------- | -------- | --------------------------------- |
| **组织架构** | 获取团队成员 id 列表       | POST     | `/v2/group/user/idList`           |
| **组织架构** | 获取团队下一级部门列表     | POST     | `/v2/group/sublist`               |
| **组织架构** | 获取某部门的子部门列表     | POST     | `/v2/department/sublist`          |
| **组织架构** | 查询部门信息               | POST     | `/v2/department/info`             |
| **组织架构** | 获取部门成员列表           | POST     | `/v2/department/userList`         |
| **组织架构** | 团队成员信息查询           | POST     | `/v2/user/info`                   |
| **组织架构** | 批量查询团队成员信息       | POST     | `/v2/user/infos`                  |
| **照片**     | 获取团队照片               | POST     | `/v2/group/photo`                 |
| **照片**     | 多维度查询团队照片         | POST     | `/v2/group/photo/search`          |
| **照片**     | 根据照片 id 获取下载地址   | POST     | `/v2/group/photo/downloadUrl`     |
| **照片**     | 根据照片 id 获取水印数据   | POST     | `/v2/group/watermark/byPhotoId`   |
| **照片**     | 根据时间范围获取水印数据   | POST     | `/v2/group/watermark/byTime`      |
| **Webhook**  | 主动推送(平台回调)       | —        | 见第 7 章                         |

# 4 组织架构接口

## 4.1 获取团队成员id列表

获取团队成员id列表

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/user/idList`

### 返回参数

| 名称      | 类型     | 示例值                                        | 描述                 |
| --------- | -------- | --------------------------------------------- | -------------------- |
| code      | Integer  | 200                                           | 状态码               |
| msg       | String   | success                                       | 状态码对应的提示内容 |
| data      | []String | ["open_6e13763f_68d4_49d1_9178_06998191a5c8"] | 返回数据             |
| timestamp | Integer  | 1629092630                                    | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/user/idList
```

**请求示例（Golang API）**

```golang
    url := "https://openapi.xhey.top/v2/group/user/idList"

    groupSecret := "groupSecret"// 需申请
    groupKey := "groupKey"// 需申请
    dataSign := sign("", groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, nil)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```JavaScript
{
    "code": 200,
    "msg": "success",
    "data": ["open-06ns8591-02pr-941q-n81r-snn8340598r5","open-3q3p3182-p7s6-90nr-4044-s5nq3ro9n6n5"],
    "timestamp": 1629099324
}
```

## 4.2 获取团队下一级部门列表

调用本接口获取团队下的所有直属子部门列表。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/sublist`

### 返回参数

| 名称           | 类型     | 示例值     | 描述                 |
| -------------- | -------- | ---------- | -------------------- |
| code           | String   | 200        | 状态码               |
| msg            | String   | success    | 状态码对应的提示内容 |
| data           | []Object |            | 返回内容             |
| |—id      | Integer  | 17         | 部门id               |
| |—groupID | Integer  | 42180013   | 团队id               |
| |—name    | String   | 后勤处     | 部门名称             |
| timestamp      | Integer  | 1629092630 | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/sublist
```

**请求示例（Golang API）**

```golang
    url := "https://openapi.xhey.top/v2/group/sublist"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign("", groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, nil)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```JavaScript
{
    "code": 200,
    "msg": "success",
    "data": [{
        "id": 1,
        "groupID": 42180013,
        "name": "后勤处"
    }, {
        "id": 4,
        "groupID": 42180013,
        "name": "测试部门"
    }],
    "timestamp": 1629101164
}
```

## 4.3 获取某部门的子部门列表

通过部门id调用本接口，获取该部门下的所有直属子部门列表。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/department/sublist`

### Body参数

| 名称         | 类型    | 是否必填 | 示例值 | 描述     |
| ------------ | ------- | -------- | ------ | -------- |
| departmentID | Integer | 是       | 241    | 父部门id |

### 返回参数

| 名称            | 类型     | 示例值     | 描述                 |
| --------------- | -------- | ---------- | -------------------- |
| code            | String   | 200        | 状态码               |
| msg             | String   | success    | 状态码对应的提示内容 |
| data            | []Object |            | 返回内容             |
| |—id       | Integer  | 981090726  | 部门id               |
| |—parentID | Integer  | 241        | 父部门id             |
| |—name     | String   | 后勤处     | 部门名称             |
| timestamp       | Integer  | 1629092630 | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/department/sublist
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "departmentID": 46
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/department/sublist"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": [{
        "id": 18,
        "parentID": 17,
        "name": "保安部门"
    },{
        "id": 73,
        "parentID": 17,
        "name": "测试部门2"
    }],
    "timestamp": 1629101550
}
```

## 4.4 查询部门信息

通过部门id调用本接口，获取该部门的详情信息。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/department/info`

### Body参数

| 名称         | 类型    | 是否必填 | 示例值 | 描述     |
| ------------ | ------- | -------- | ------ | -------- |
| departmentID | Integer | 是       | 241    | 父部门id |

### 返回参数

| 名称                  | 类型    | 示例值                                                                      | 描述                 |
| --------------------- | ------- | --------------------------------------------------------------------------- | -------------------- |
| code                  | String  | 200                                                                         | 状态码               |
| msg                   | String  | success                                                                     | 状态码对应的提示内容 |
| data                  | Object  |                                                                             | 返回内容             |
| |—id             | Integer | 981090726                                                                   | 部门id               |
| |—parentID       | Integer | 241                                                                         | 父部门id             |
| |—avatar         | String  | https://net-cloud.xhey.top/group/photo/a3bc63de58978dcb328ed84115d122c9.jpg | 部门头像             |
| |—name           | String  | 后勤处                                                                      | 部门名称             |
| |—containSubDept | Boolean | false                                                                       | 是否包含下级部门     |
| |—memberNum      | Integer | 166                                                                         | 部门成员数           |
| timestamp             | Integer | 1629092630                                                                  | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/department/info
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "departmentID": 46
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/department/info"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 17,
        "parentID": 3,
        "avatar": "https://net-cloud.oss-cn-beijing.aliyuncs.com/icon/department-av.jpg",
        "name": "后勤处",
        "containSubDept": false,
        "memberNum": 166
    },
    "timestamp": 1629101848
}
```

## 4.5 获取部门成员列表

通过部门id调用本接口，获取该部门的详情信息。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/department/userList`

### Body参数

| 名称         | 类型    | 是否必填 | 示例值 | 描述                                             |
| ------------ | ------- | -------- | ------ | ------------------------------------------------ |
| departmentID | Integer | 是       | 17     | 部门id                                           |
| pageSize     | Integer | 否       | 100    | 支持分页查询，每页条目数，如果不传，默认值为1000 |
| pageNo       | Integer | 否       | 1      | 支持分页查询，分页页码，如果不传，默认值为1      |

### 返回参数

| 名称               | 类型     | 示例值                                                                                              | 描述                 |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------- | -------------------- |
| code               | String   | 200                                                                                                 | 状态码               |
| msg                | String   | success                                                                                             | 状态码对应的提示内容 |
| data               | []Object |                                                                                                     | 返回内容             |
| |—hasMore     | Boolean  | true                                                                                                | 是否还有下一页数据   |
| |—nextPageNo  | Integer  | 2                                                                                                   | 下一页的页码         |
| |—users       | []Object |                                                                                                     | 成员信息列表         |
| |——userID     | Integer  | open_6e13763f_68d4_49d1_9178_06998191a5c8                                                           | 用户id               |
| |——nickname   | String   | zackhuang                                                                                           | 昵称                 |
| |——headImgUrl | String   | https://net-cloud.xhey.top/group/headimg/avatar_default_1_d0b9ef45-a1de-42f8-82f6-8f4d674a8b07.jpeg | 头像地址             |
| |——mobile     | String   | 18604xxxxxx                                                                                         | 手机号码             |
| timestamp          | Integer  | 1629092630                                                                                          | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/department/userList
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "departmentID": 46,
        "pageSize": 100,
        "pageNo": 1
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/department/userList"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": {
        "hasMore": false,
        "nextPageNo": 0,
        "users": [{
            "userID": "open-81415183-2024-961s-n43s-4s98o566pr34",
            "nickname": "zackhuang",
            "headImgUrl": "https://net-cloud.xhey.top/group/headimg/avatar_default_1_44c84097-f99c-4603-aaf5-49ff10b1b8a0.jpeg",
            "mobile": "18801611111"
        }]
    },
    "timestamp": 1629102955
}
```

## 4.6 团队成员信息查询

通过用户id调用本接口，获取用户的详情信息。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/user/info`

### Body参数

| 名称   | 类型   | 是否必填 | 示例值                                    | 描述   |
| ------ | ------ | -------- | ----------------------------------------- | ------ |
| userID | String | 是       | open_6e13763f_68d4_49d1_9178_06998191a5c8 | 用户id |

### 返回参数

| 名称              | 类型    | 示例值                                                                                              | 描述                 |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------- | -------------------- |
| code              | String  | 200                                                                                                 | 状态码               |
| msg               | String  | success                                                                                             | 状态码对应的提示内容 |
| data              | Object  |                                                                                                     | 返回内容             |
| |—userID     | String  | open_6e13763f_68d4_49d1_9178_06998191a5c8                                                           | 用户id               |
| |—nickname   | String  | zackhuang                                                                                           | 昵称                 |
| |—headImgUrl | String  | https://net-cloud.xhey.top/group/headimg/avatar_default_1_d0b9ef45-a1de-42f8-82f6-8f4d674a8b07.jpeg | 头像地址             |
| |——mobile    | String  | 18604xxxxxx                                                                                         | 手机号码             |
| timestamp         | Integer | 1629092630                                                                                          | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/user/info
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "userID": "open-991733sq-3pqr-988q-o816-5n98r988sqrn"
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/user/info"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": {
        "userID": "open-991733sq-3pqr-988q-o816-5n98r988sqrn",
        "nickname": "zackhuang",
        "headImgUrl": "https://net-cloud.xhey.top/group/headimg/avatar_default_1.jpeg",
        "mobile": "18602222221"
    },
    "timestamp": 1629102431
}
```

## 4.7 批量查询团队成员信息

批量传入用户id，获取用户详细信息
最大支持一次查询1000条员工信息

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/user/infos`

### Body参数

| 名称    | 类型     | 是否必填 | 示例值                                                                                    | 描述   |
| ------- | -------- | -------- | ----------------------------------------------------------------------------------------- | ------ |
| userIDs | []String | 是       | ["open_6e13763f_68d4_49d1_9178_06998191a5c8","open_6e13763f_68d4_49d1_9178_06998191a5c8"] | 用户id |

### 返回参数

| 名称                | 类型     | 示例值                                                                                              | 描述                 |
| ------------------- | -------- | --------------------------------------------------------------------------------------------------- | -------------------- |
| code                | String   | 200                                                                                                 | 状态码               |
| msg                 | String   | success                                                                                             | 状态码对应的提示内容 |
| data                | Object   |                                                                                                     | 返回内容             |
| |—userInfos    | []Object |                                                                                                     | 成员信息集合         |
| |———userID     | String   | open_6e13763f_68d4_49d1_9178_06998191a5c8                                                           | 用户id               |
| |———nickname   | String   | zackhuang                                                                                           | 昵称                 |
| |———headImgUrl | String   | https://net-cloud.xhey.top/group/headimg/avatar_default_1_d0b9ef45-a1de-42f8-82f6-8f4d674a8b07.jpeg | 头像地址             |
| |————mobile    | String   | 18604xxxxxx                                                                                         | 手机号码             |
| timestamp           | Integer  | 1629092630                                                                                          | 请求时间，Unix时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/user/infos
```

**请求示例（Golang API）**

```golang
	reqStr := `{
	    "userIDs": ["open-991733sq-3pqr-988q-o816-5n98r988sqrn"]
	}`
	reader := bytes.NewReader(([]byte)(reqStr))

	url := "https://openapi.xhey.top/v2/user/infos"

	groupSecret := "groupSecret" // 需申请
	groupKey := "groupKey"       // 需申请
	dataSign := sign(reqStr, groupSecret)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
		groupKey,
		dataSign,
		timestamp,
	)
	signature := sign(str, groupSecret)
	req, _ := http.NewRequest("POST", url, reader)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Set("GroupKey", groupKey)
	req.Header.Set("Timestamp", timestamp)
	req.Header.Set("Signature", signature)

	client := &http.Client{}
	defer client.CloseIdleConnections()
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	var buf bytes.Buffer
	_, err = buf.ReadFrom(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": {
        "userInfos":[{
            "userID": "open-991733sq-3pqr-988q-o816-5n98r988sqrn",
            "nickname": "zackhuang",
            "headImgUrl": "https://net-cloud.xhey.top/group/headimg/avatar_default_1.jpeg",
            "mobile": "18602222221"
        }]
    },
    "timestamp": 1629102431
}
```

# 5 照片接口

## 5.1 获取团队照片

通过筛选条件获取团队下的照片。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/photo`

### Body参数

| 名称      | 类型     | 是否必填 | 示例值                                                                                    | 描述                                                          |
| --------- | -------- | -------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| startTime | Integer  | 否       | 1623826153                                                                                | Unix时间戳，筛选条件的开始时间点                              |
| endTime   | Integer  | 否       | 1629096554                                                                                | Unix时间戳，筛选条件的结束时间点                              |
| userID    | []String | 否       | ["open-06ns8591-02pr-941q-n81r-snn8340598r5","open-3q3p3182-p7s6-90nr-4044-s5nq3ro9n6n5"] | 用户id列表                                                    |
| mediaType | Integer  | 否       | 0                                                                                         | 资源类型，0-照片 1-视频，如果不传该值，将会查询满足0或1的资源 |
| pageSize  | Integer  | 否       | 100                                                                                       | 支持分页查询，每页条目数，如果不传，默认值为1000              |
| pageNo    | Integer  | 否       | 1                                                                                         | 支持分页查询，分页页码，如果不传，默认值为1                   |

### 返回参数

| 名称                   | 类型     | 示例值                                                                                                                                | 描述                                                          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| code                   | String   | 200                                                                                                                                   | 状态码                                                        |
| msg                    | String   | success                                                                                                                               | 状态码对应的提示内容                                          |
| data                   | Object   |                                                                                                                                       | 返回内容                                                      |
| |—hasMore         | Boolean  | true                                                                                                                                  | 是否还有下一页数据                                            |
| |—nextPageNo      | Integer  | 2                                                                                                                                     | 下一页的页码                                                  |
| |—photos          | []Object |                                                                                                                                       | 水印数据数组                                                  |
| |——id             | Integer  | 981090726                                                                                                                             | 照片id                                                        |
| |——mediaUrl       | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg                                                       | 资源地址(用户上传的原图)                                      |
| |——mediaSimpleUrl | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto,w_300 | 简版资源地址 照片类型时为缩略图，视频类型时为首祯图片         |
| |——mediaType      | Integer  | 0                                                                                                                                     | 资源类型，0-照片 1-视频，如果不传该值，将会查询满足0或1的资源 |
| |——time           | Integer  | 1627612                                                                                                                               | 拍照时间，Unix时间戳                                          |
| |——userID         | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77                                                                                             | 拍照人id                                                      |
| timestamp              | Integer  | 1629092630                                                                                                                            | 请求时间，Unix时间戳                                          |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/photo
```

**请求正文**

```javascript
{
	"startTime": 1625483483,
	"endTime": 1628161884,
	"userID": ["open_6e13763f_68d4_49d1_9178_06998191a5c8","open_6e13763f_68d4_49d1_9178_06998191a5c8"],
	"mediaType": 0,
	"pageSize":100,
	"pageNo":1
}
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "startTime": 1625483483,
        "endTime": 1628161884,
        "userID": ["open_6e13763f_68d4_49d1_9178_06998191a5c8","open_6e13763f_68d4_49d1_9178_06998191a5c8"],
        "mediaType": 0,
        "pageSize":10,
        "pageNo":1
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/group/photo"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
	"code": 200,
	"msg": "success",
	"data": {
		"hasMore": true,
		"nextPageNo": 2,
		"photos": [{
			"id": 981090726,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1627612397,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}, {
			"id": 981090725,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/7b4b1def-da53-470e-baec-7b5ed4945aed.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1626056664,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}, {
			"id": 981090724,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/d08a25b5-576c-49eb-8e6d-d34e3b537068.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1626056654,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}]
	},
	"timestamp": 1629100265
}
```

## 5.2 多维度查询团队照片

通过筛选条件获取团队下的照片。
目前最大支持查询1000条数据，超出时只显示1000条

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/photo/search`

### Body参数

| 名称             | 类型     | 是否必填 | 示例值                                                                                    | 描述                                                                                                      |
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| startTime        | Integer  | 否       | 1623826153                                                                                | Unix时间戳，筛选条件的开始时间点 开始时间与结束时间最长支持180天，不传值的情况下默认为当前时间的180天之前 |
| endTime          | Integer  | 否       | 1629096554                                                                                | Unix时间戳，筛选条件的结束时间点 开始时间与结束时间最长支持180天，不传值的情况下默认为当前时间            |
| userIds          | []String | 否       | ["open-06ns8591-02pr-941q-n81r-snn8340598r5","open-3q3p3182-p7s6-90nr-4044-s5nq3ro9n6n5"] | 用户id列表                                                                                                |
| mediaType        | Integer  | 否       | 0                                                                                         | 资源类型，0-照片 1-视频，如果不传该值，将会查询满足0或1的资源                                             |
| watermarkContent | []string | 否       | ["水印内容"]｜水印中携带的关键词信息，最多支持三个关键词，每个关键词最长支持15个字符      |

### 返回参数

| 名称                   | 类型     | 示例值                                                                                                                                | 描述                                                          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| code                   | String   | 200                                                                                                                                   | 状态码                                                        |
| msg                    | String   | success                                                                                                                               | 状态码对应的提示内容                                          |
| data                   | Object   |                                                                                                                                       | 返回内容                                                      |
| |—photos          | []Object |                                                                                                                                       | 水印数据数组                                                  |
| |——id             | Integer  | 981090726                                                                                                                             | 照片id                                                        |
| |——mediaUrl       | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg                                                       | 资源地址                                                      |
| |——mediaSimpleUrl | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto,w_300 | 简版资源地址 照片类型时为缩略图，视频类型时为首祯图片         |
| |——mediaType      | Integer  | 0                                                                                                                                     | 资源类型，0-照片 1-视频，如果不传该值，将会查询满足0或1的资源 |
| |——time           | Integer  | 1627612                                                                                                                               | 拍照时间，Unix时间戳                                          |
| |——userID         | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77                                                                                             | 拍照人id                                                      |
| timestamp              | Integer  | 1629092630                                                                                                                            | 请求时间，Unix时间戳                                          |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/photo/search
```

**请求正文**

```javascript
{
	"startTime": 1625483483,
	"endTime": 1628161884,
	"UserIds":["open_6e13763f_68d4_49d1_9178_06998191a5c8","open_6e13763f_68d4_49d1_9178_06998191a5c8"],
	"mediaType": 0,
	"watermarkContent":["水印关键词"]
}
```

**请求示例（Golang API）**

```golang
    reqStr := `{
        "startTime": 1625483483,
        "endTime": 1628161884,
        "userIds":["open_6e13763f_68d4_49d1_9178_06998191a5c8","open_6e13763f_68d4_49d1_9178_06998191a5c8"],
        "mediaType": 0,
        "watermarkContent":["水印关键词"]
    }`
    reader := bytes.NewReader(([]byte)(reqStr))

    url := "https://openapi.xhey.top/v2/group/photo/search"

    groupSecret := "groupSecret" // 需申请
    groupKey := "groupKey"       // 需申请
    dataSign := sign(reqStr, groupSecret)
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
        groupKey,
        dataSign,
        timestamp,
    )
    signature := sign(str, groupSecret)
    req, _ := http.NewRequest("POST", url, reader)
    req.Header.Add("Content-Type", "application/json")
    req.Header.Set("GroupKey", groupKey)
    req.Header.Set("Timestamp", timestamp)
    req.Header.Set("Signature", signature)

    client := &http.Client{}
    defer client.CloseIdleConnections()
    resp, err := client.Do(req)

    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()

    var buf bytes.Buffer
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println(buf.String())
```

**返回示例**

```javascript
{
	"code": 200,
	"msg": "success",
	"data": {
		"photos": [{
			"id": 981090726,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1627612397,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}, {
			"id": 981090725,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/7b4b1def-da53-470e-baec-7b5ed4945aed.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1626056664,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}, {
			"id": 981090724,
			"mediaUrl": "https://net-cloud.xhey.top/group/photo/d08a25b5-576c-49eb-8e6d-d34e3b537068.jpg",
			"mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto",
			"mediaType": 0,
			"time": 1626056654,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77"
		}]
	},
	"timestamp": 1629100265
}
```

## 5.3 根据照片id获取团队照片水印数据

通过照片ID列表，获取对应的水印数据。经纬度坐标系为gcj02。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/watermark/byPhotoId`

### Body参数

| 名称     | 类型      | 是否必填 | 示例值                          | 描述                                             |
| -------- | --------- | -------- | ------------------------------- | ------------------------------------------------ |
| photoID  | []Integer | 是       | [981090726,981090735,981090728] | 照片id列表                                       |
| pageSize | Integer   | 否       | 100                             | 支持分页查询，每页条目数，如果不传，默认值为1000 |
| pageNo   | Integer   | 否       | 1                               | 支持分页查询，分页页码，如果不传，默认值为1      |

### 返回参数

| 名称                  | 类型     | 示例值                                    | 描述                           |
| --------------------- | -------- | ----------------------------------------- | ------------------------------ |
| code                  | String   | 200                                       | 状态码                         |
| msg                   | String   | success                                   | 状态码对应的提示内容           |
| data                  | Object   |                                           | 返回内容                       |
| |—hasMore        | Boolean  | true                                      | 是否还有下一页数据             |
| |—nextPageNo     | Integer  | 2                                         | 下一页的页码                   |
| |—watermarks     | []Object |                                           | 水印数据数组                   |
| |——watermarkID   | Integer  | 1444928478914561                          | 水印id，用于多维度查询照片数据 |
| |——photoID       | Integer  | 981090726                                 | 照片id                         |
| |——userID        | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77 | 拍照人id                       |
| |——watermarkName | String   | 时间地点天气                              | 水印名称                       |
| |——time          | Integer  | 1627612                                   | 拍照时间，Unix时间戳           |
| |——addr          | String   | 成都市·天荟                               | 拍照地点                       |
| |——weather       | String   | 晴 11° 北风≤3级                           | 天气                           |
| |——lng           | String   | 104.065727                                | 经度                           |
| |——lat           | String   | 30.554810                                 | 纬度                           |
| |——altitude      | String   | 50.7                                      | 海拔高度，单位 ‘米’            |
| |——extends       | []Object | 981090726                                 | 照片id                         |
| |———title        | String   | 工程名称                                  | 水印中的自定义条目标题         |
| |———content      | String   | 工程记录                                  | 水印中的自定义条目内容         |
| timestamp             | Integer  | 1629092630                                | 请求时间，Unix时间戳           |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/watermark/byPhotoId
```

**请求正文**

```javascript
{
    "photoID": [981090726,981090735,981090728,981090718,981090716],
    "pageSize": 100,
    "pageNo": 1
}
```

**请求示例（Golang API）**

```golang
	reqStr := `{
	    "photoID": [981090726,981090735,981090728,981090718,981090716],
	    "pageSize": 100,
	    "pageNo": 1
	}`
	reader := bytes.NewReader(([]byte)(reqStr))

	url := "https://openapi.xhey.top/v2/group/watermark/byPhotoId"

	groupSecret := "groupSecret" // 需申请
	groupKey := "groupKey"       // 需申请
	dataSign := sign(reqStr, groupSecret)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
		groupKey,
		dataSign,
		timestamp,
	)
	signature := sign(str, groupSecret)
	req, _ := http.NewRequest("POST", url, reader)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Set("GroupKey", groupKey)
	req.Header.Set("Timestamp", timestamp)
	req.Header.Set("Signature", signature)

	client := &http.Client{}
	defer client.CloseIdleConnections()
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	var buf bytes.Buffer
	_, err = buf.ReadFrom(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(buf.String())
```

**返回示例**

```javascript
{
	"code": 200,
	"msg": "success",
	"data": {
		"hasMore": false,
		"nextPageNo": 0,
		"watermarks": [{
			"watermarkID": 1444928478913901,
			"photoID": 981090716,
			"userID": "open-6oq698q3-04ps-99s8-o21o-43058r291507",
			"watermarkName": "时间地点天气",
			"time": 1625732,
			"addr": "成都市·天荟",
			"weather": "晴 17° 西南风≤3级",
			"lng": "104.065598",
			"lat": "30.554556",
			"altitude": "51.0",
			"extends": []
		}, {
			"watermarkID": 1444928478914289,
			"photoID": 981090718,
			"userID": "open-06ns8591-02pr-941q-n81r-snn8340598r5",
			"watermarkName": "时间地点天气",
			"time": 1625732,
			"addr": "成都市·天荟",
			"weather": "晴 17° 西南风≤3级",
			"lng": "104.065552",
			"lat": "30.554632",
			"altitude": "50.5",
			"extends": [{
				"title": "工程名称",
				"content": "工程记录"
			}]
		}, {
			"watermarkID": 1444928478914561,
			"photoID": 981090726,
			"userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77",
			"watermarkName": "时间地点天气",
			"time": 1627612,
			"addr": "成都市·天荟",
			"weather": "晴 11° 北风≤3级",
			"lng": "104.065727",
			"lat": "30.554810",
			"altitude": "50.7",
			"extends": []
		}]
	},
	"timestamp": 1629093972
}
```

## 5.4 根据时间范围获取团队照片水印数据

通过开始和结束时间的范围，获取对应的水印数据。经纬度坐标系为gcj02。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/watermark/byTime`

### Body参数

| 名称      | 类型    | 是否必填 | 示例值     | 描述                                             |
| --------- | ------- | -------- | ---------- | ------------------------------------------------ |
| startTime | Integer | 是       | 1623826153 | Unix时间戳，筛选条件的开始时间点                 |
| endTime   | Integer | 是       | 1629096554 | Unix时间戳，筛选条件的结束时间点                 |
| pageSize  | Integer | 否       | 100        | 支持分页查询，每页条目数，如果不传，默认值为1000 |
| pageNo    | Integer | 否       | 1          | 支持分页查询，分页页码，如果不传，默认值为1      |

### 返回参数

| 名称                  | 类型     | 示例值                                    | 描述                           |
| --------------------- | -------- | ----------------------------------------- | ------------------------------ |
| code                  | String   | 200                                       | 状态码                         |
| msg                   | String   | success                                   | 状态码对应的提示内容           |
| data                  | Object   |                                           | 返回内容                       |
| |—hasMore        | Boolean  | true                                      | 是否还有下一页数据             |
| |—nextPageNo     | Integer  | 2                                         | 下一页的页码                   |
| |—watermarks     | []Object |                                           | 水印数据数组                   |
| |——watermarkID   | Integer  | 1444928478914561                          | 水印id，用于多维度查询照片数据 |
| |——photoID       | Integer  | 981090726                                 | 照片id                         |
| |——userID        | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77 | 拍照人id                       |
| |——watermarkName | String   | 时间地点天气                              | 水印名称                       |
| |——time          | Integer  | 1627612                                   | 拍照时间，Unix时间戳           |
| |——addr          | String   | 成都市·天荟                               | 拍照地点                       |
| |——weather       | String   | 晴 11° 北风≤3级                           | 天气                           |
| |——lng           | String   | 104.065727                                | 经度                           |
| |——lat           | String   | 30.554810                                 | 纬度                           |
| |——altitude      | String   | 50.7                                      | 海拔高度，单位 ‘米’            |
| |——extends       | []Object | 981090726                                 | 照片id                         |
| |———title        | String   | 工程名称                                  | 水印中的自定义条目标题         |
| |———content      | String   | 工程记录                                  | 水印中的自定义条目内容         |
| timestamp             | Integer  | 1629092630                                | 请求时间，Unix时间戳           |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/watermark/byTime
```

**请求正文**

```javascript
{
	"startTime": 1623826153,
	"endTime": 1629096554,
	"pageSize": 100,
	"pageNo": 1
}
```

**请求示例（Golang API）**

```golang
	reqStr := `{
	    "startTime": 1623826153,
	    "endTime": 1629096554,
	    "pageSize": 100,
	    "pageNo": 1
	}`
	reader := bytes.NewReader(([]byte)(reqStr))

	url := "https://openapi.xhey.top/v2/group/watermark/byTime"

	groupSecret := "groupSecret" // 需申请
	groupKey := "groupKey"       // 需申请
	dataSign := sign(reqStr, groupSecret)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
		groupKey,
		dataSign,
		timestamp,
	)
	signature := sign(str, groupSecret)
	req, _ := http.NewRequest("POST", url, reader)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Set("GroupKey", groupKey)
	req.Header.Set("Timestamp", timestamp)
	req.Header.Set("Signature", signature)

	client := &http.Client{}
	defer client.CloseIdleConnections()
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	var buf bytes.Buffer
	_, err = buf.ReadFrom(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(buf.String())
```

**返回示例**

```javascript
{
    "code": 200,
    "msg": "success",
    "data": {
        "hasMore": false,
        "nextPageNo": 0,
        "watermarks": [{
            "watermarkID": 1444928478914521,
            "photoID": 981090716,
            "userID": "open-6oq698q3-04ps-99s8-o21o-43058r291507",
            "watermarkName": "时间地点天气",
            "time": 1625732,
            "addr": "成都市·天荟",
            "weather": "晴 17° 西南风≤3级",
            "lng": "104.065598",
            "lat": "30.554556",
            "altitude": "51.0",
            "extends": []
        }, {
            "watermarkID": 1444928478915527,
            "photoID": 981090718,
            "userID": "open-06ns8591-02pr-941q-n81r-snn8340598r5",
            "watermarkName": "时间地点天气",
            "time": 1625732,
            "addr": "成都市·天荟",
            "weather": "晴 17° 西南风≤3级",
            "lng": "104.065552",
            "lat": "30.554632",
            "altitude": "50.5",
            "extends": [{
                "title": "工程名称",
                "content": "工程记录"
            }]
        }, {
            "watermarkID": 1444928478915527,
            "photoID": 981090726,
            "userID": "open-0q325626-s606-93qr-33q9-n535snnoqn77",
            "watermarkName": "时间地点天气",
            "time": 1627612,
            "addr": "成都市·天荟",
            "weather": "晴 11° 北风≤3级",
            "lng": "104.065727",
            "lat": "30.554810",
            "altitude": "50.7",
            "extends": []
        }]
    },
    "timestamp": 1629093972
}
```

# 6 照片下载接口

## 6.1 照片下载接口

根据照片 ID 批量获取照片下载地址，单次请求最多支持 1000 个照片 ID。

### 基本信息

请求方式：POST

请求地址：`https://openapi.xhey.top/v2/group/photo/downloadUrl`

### Body参数

| 名称     | 类型      | 是否必填 | 示例值                          | 描述                                                       |
| -------- | --------- | -------- | ------------------------------- | ---------------------------------------------------------- |
| photoIDs | []Integer | 是       | [981090726,981090725,981090724] | 照片 ID 列表，至少 1 个、最多 1000 个，不允许重复或小于等于 0 |

### 返回参数

| 名称                   | 类型     | 示例值                                                                                      | 描述                     |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- | ------------------------ |
| code                   | String   | 200                                                                                         | 状态码                   |
| msg                    | String   | success                                                                                     | 状态码对应的提示内容     |
| data                   | Object   |                                                                                             | 返回内容                 |
| |—photos          | []Object |                                                                                             | 照片下载信息数组         |
| |——id             | Integer  | 981090726                                                                                   | 照片 ID                  |
| |——downloadUrl    | String   | https://net-private.xhey.top/group/photo/example.jpg?auth_key=...                            | 携带鉴权信息的下载地址   |
| timestamp              | Integer  | 1629092630                                                                                  | 响应时间，Unix 秒级时间戳 |

### 示例

**请求示例（HTTP）**

```
POST https://openapi.xhey.top/v2/group/photo/downloadUrl
```

**请求正文**

```javascript
{
	"photoIDs": [981090726, 981090725, 981090724]
}
```

**请求示例（Golang API）**

```golang
	reqStr := `{
	    "photoIDs": [981090726, 981090725, 981090724]
	}`
	reader := bytes.NewReader(([]byte)(reqStr))

	url := "https://openapi.xhey.top/v2/group/photo/downloadUrl"

	groupSecret := "groupSecret" // 需申请
	groupKey := "groupKey"       // 需申请
	dataSign := sign(reqStr, groupSecret)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	str := fmt.Sprintf("groupKey=%s&sign=%s&timestamp=%s",
		groupKey,
		dataSign,
		timestamp,
	)
	signature := sign(str, groupSecret)
	req, _ := http.NewRequest("POST", url, reader)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Set("GroupKey", groupKey)
	req.Header.Set("Timestamp", timestamp)
	req.Header.Set("Signature", signature)

	client := &http.Client{}
	defer client.CloseIdleConnections()
	resp, err := client.Do(req)

	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	var buf bytes.Buffer
	_, err = buf.ReadFrom(resp.Body)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println(buf.String())
```

**返回示例**

```javascript
{
  "code": 200,
  "msg": "success",
  "data": {
    "photos": [
      {
        "id": 981090726,
        "downloadUrl": "https://net-private.xhey.top/group/photo/example-1.jpg?auth_key=..."
      },
      {
        "id": 981090725,
        "downloadUrl": "https://net-private-tx.xhey.top/group/photo/tencent-example-2.jpg?auth_key=..."
      },
      {
        "id": 981090724,
        "downloadUrl": "https://net-private.xhey.top/group/photo/example-3.jpg?auth_key=..."
      }
    ]
  },
  "timestamp": 1629092630
}
```

# 7 Webhook 接口

webhook 请求 header 携带鉴权信息

### 接收参数

| 名称                           | 类型     | 示例值                                                                                                                                | 描述                                                          |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| groupID                        | String   | 11971798                                                                                                                              | 团队号                                                        |
| photo                          | Object   |                                                                                                                                       | 资源信息                                                      |
| |—id                      | Integer  | 981090726                                                                                                                             | 资源id                                                        |
| |—mediaUrl                | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg                                                       | 资源地址                                                      |
| |—mediaSimpleUrl          | String   | https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto,w_300 | 简版资源地址 照片类型时为缩略图，视频类型时为首祯图片         |
| |—mediaType               | Integer  | 0                                                                                                                                     | 资源类型，0-照片 1-视频，如果不传该值，将会查询满足0或1的资源 |
| |—time                    | Integer  | 1627612                                                                                                                               | 拍照时间，Unix时间戳                                          |
| |—userID                  | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77                                                                                             | 拍照人id                                                      |
| |—userName                | String   | 拍摄人                                                                                                                                | 拍照人昵称                                                    |
| watermark                      | Object   |                                                                                                                                       | 水印信息                                                      |
| |—watermarkID             | Integer  | 1444928478914561                                                                                                                      | 水印id，用于多维度查询照片数据                                |
| |-watermarkIdentification | String   | 182ba62d-257e-11ec-5660-3f95007345e9                                                                                                  | 水印标识                                                      |
| |—photoID                 | Integer  | 981090726                                                                                                                             | 照片id                                                        |
| |—userID                  | String   | open-0q325626-s606-93qr-33q9-n535snnoqn77                                                                                             | 拍照人id                                                      |
| |—watermarkName           | String   | 时间地点天气                                                                                                                          | 水印名称                                                      |
| |—time                    | Integer  |                                                                                                                                       | 拍摄时间，Unix时间戳                                          |
| |—addr                    | String   | 成都市·天荟                                                                                                                           | 拍摄地址                                                      |
| |—weather                 | String   | 晴 11° 北风≤3级                                                                                                                       | 天气                                                          |
| |—lng                     | String   | 104.065727                                                                                                                            | 经度                                                          |
| |—lat                     | String   | 30.554810                                                                                                                             | 纬度                                                          |
| |—altitude                | String   | 50.7                                                                                                                                  | 海拔高度，单位 ‘米’                                           |
| |—extends                 | []Object |                                                                                                                                       | 水印自定义内容                                                |
| |———title                 | String   | 工程名称                                                                                                                              | 水印中的自定义条目标题                                        |
| |———content               | String   | 工程记录                                                                                                                              | 水印中的自定义条目内容                                        |

### 返回参数

| 名称    | 类型    | 示例值 | 描述                                          |
| ------- | ------- | ------ | --------------------------------------------- |
| status  | Integer | 200    | 接收到消息返回200认为发送成功，否则会一直重试 |
| message | String  |        | 失败时返回的特殊消息                          |

**请求正文**

```javascript
{
  "groupID":11971798,
  "photo": {
    "id": 29043766,
    "mediaUrl": "https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg",
    "mediaSimpleUrl":"https://net-cloud.xhey.top/group/photo/87485164-6394-4b9d-966e-05ac786b5160.jpg?x-oss-process=video/snapshot,t_0,m_fast,ar_auto,w_300",
    "mediaType": 0,
    "time": 1631761794,
    "userID": "open-4814n211-8789-95p3-o84o-972159218n8s",
    "userName":"拍摄人"
  },
  "watermark": {
	"watermarkID":1444928478914561,
    "watermarkIdentification":"182ba62d-257e-11ec-5660-3f95007345e9",
    "photoID": 29043766,
    "userID": "open-4814n211-8789-95p3-o84o-972159218n8s",
    "watermarkName": "工程记录",
    "time": 1631761794,
    "addr": "北京市·上地佳园",
    "weather": "晴 28° 西北风2级",
    "lng": "113.133652",
    "lat": "29.376331",
    "altitude": "46.8",
    "extends": []
  }
}
```

**返回示例**

```javascript
{
	"code": 200,
	"msg": ""
}
```

# 8 状态码列表

当code值不等于200时，返回数据的data为null

| code值 | 类型    | 错误内容                                                                              |
| ------ | ------- | ------------------------------------------------------------------------------------- |
| 200    | Integer | success                                                                               |
| 2001   | Integer | you can query a maximum of 1000 records, please be precise with your query conditions |
| 400    | Integer | param error                                                                           |
| 401    | Integer | verify error                                                                          |
| 403    | Integer | forbidden                                                                             |
| 404    | Integer | not found                                                                             |
| 500    | Integer | service error                                                                         |
| 4007   | Integer | group key or secret not right                                                         |
| 4008   | Integer | you can query a maximum of 1000 personnel information at a time                       |
| 4009   | Integer | time param error                                                                      |
| 4010   | Integer | you can query longest of 180 days data                                                |
| 4011   | Integer | you can use a maximum of three keywords to search                                     |
| 4012   | Integer | one keyword contain a maximum of 15 characters                                        |
| 4013   | Integer | not support watermark ids query                                                       |
| 4014   | Integer | trial expired（试用已过期）                                                            |
| 4015   | Integer | trial quota exhausted（试用调用次数已用尽）                                            |
| 4016   | Integer | service closed（该服务已停用）                                                         |
| 4017   | Integer | rate limited（超过 QPS 限额，已触发限流）                                              |
| 4018   | Integer | entitlement missing（缺少照片模块或对应服务权益）                                      |
| 4019   | Integer | quota exhausted（正式账户的验真 API 或验真报告 API 调用次数已用尽）                    |