开发者报表获取

一、功能概述

Carty 开发者平台提供 开发者报表获取 接口，供开发者通过服务端接口拉取报表数据。
接口支持按日期维度统计并分页返回，便于开发者进行数据分析、收益核对与运营监控。

---

二、接口信息

• 接口名称：开发者报表获取
• 接口地址：/api/report/out-search
• 请求方式：POST
• 字符编码：UTF-8
• Content-Type：application/json

2.1 域名

• 生产环境：
  https://developer.gocarty.net/

• 完整请求地址示例：

  https://developer.gocarty.net/api/report/out-search

---

三、认证方式（Authorization）

该接口采用 API Key 鉴权方式。

• 请求 Header：Authorization
• 示例值：rk_0jmtmwkz8grugecy1bp7syh4e6wgg4oa
• 获取方式：在系统后台 apikeys 模块中获取

⚠️ 请妥善保管 API Key，避免泄露或提交至公共代码仓库。

---

四、请求参数

4.1 Header 参数

参数名	必填	类型	说明
Authorization	是	String	API Key
Content-Type	是	String	固定为 application/json

---

4.2 Body 参数（JSON）

参数名	必填	类型	说明
start_date	是	String	开始日期，格式：YYYY-MM-DD
end_date	是	String	结束日期，格式：YYYY-MM-DD（需 ≥ start_date）
page	否	Int	页码，默认 1
page_size	否	Int	每页条数，默认 10

请求示例

{
  "start_date": "2026-01-14",
  "end_date": "2026-01-14",
  "page": 1,
  "page_size": 10
}

---

五、返回参数

5.1 返回结构说明

字段	类型	说明
code	Int	状态码：0 表示成功，非 0 表示失败
message	String	返回信息
data	Object	数据对象

---

5.2 data.list 字段说明

字段	类型	说明
date	String	日期（YYYY-MM-DD）
bid_type	Int	竞价类型
request	Int	请求量
fill	Int	填充量
impression	Int	展示量
click	Int	点击量
revenue	Number	开发者收入
click_rate	Number	点击率（%）
ecpm	Number	eCPM
ecpc	Number	eCPC
fill_rate	Number	填充率（%）
impression_rate	Number	展示率（%）

---

5.3 data.page 字段说明

字段	类型	说明
current	Int	当前页
page_size	Int	每页条数
total	Int	总条数

---

六、返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "date": "2026-01-14",
        "bid_type": 2,
        "request": 473541,
        "fill": 288414,
        "impression": 164519,
        "click": 30095,
        "revenue": 470.74,
        "click_rate": 18.29,
        "ecpm": 2.86,
        "ecpc": 0.02,
        "fill_rate": 60.91,
        "impression_rate": 57.04
      }
    ],
    "page": {
      "current": 1,
      "page_size": 10,
      "total": 1
    }
  }
}

---

七、请求示例（curl）

curl --location --request POST 'https://developer.gocarty.net/api/report/out-search' \
--header 'Authorization: rk_0jmtmwkz8grugecy1bp7syh4e6wgg4os' \
--header 'Content-Type: application/json' \
--data-raw '{
  "start_date": "2026-01-14",
  "end_date": "2026-01-14",
  "page": 1,
  "page_size": 10
}'

---

八、错误码说明（示例）

code	含义
0	success
非 0	参数错误 / 鉴权失败 / 系统异常

常见错误原因

• Authorization 缺失或 API Key 无效
• 日期格式错误或时间范围不合法
• page / page_size 参数非法

---