开发者

数据 API 文档

三个只读 / 写入接口，覆盖榜单查询、条目详情与竞价下单。所有金额字段单位为美分（integer），避免浮点误差。

版本 v1 · 最近更新：2026-09-10 · 基础地址 https://api.pubutang.cn/v1

Developers

Data API documentation

Three read / write endpoints covering leaderboard queries, item detail, and bid creation. All monetary fields are integers in minor units (cents) to avoid floating-point error.

Version v1 · Updated 2026-09-10 · Base URL https://api.example.com/v1

当前状态：规范草案。本站为演示版本，尚未开放真实 API 服务。以下接口定义可直接用于对接评估，正式上线前不会发生重大变更。

一、快速开始

所有请求使用 HTTPS，响应格式为 JSON，字符集 UTF-8。时间戳均为 Unix 秒级整数，金额均为分（integer）。

bash

curl https://api.pubutang.cn/v1/leaderboard?category=seo&limit=10 \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxx"

二、鉴权

在商家中心创建 API Key，通过 Authorization 头传递。Key 分为 pt_live_（生产）与 pt_test_（沙箱）两种前缀，沙箱环境不产生真实扣款。

权限范围	说明	适用接口
`read`	只读榜单与条目	接口 1、2
`write`	创建竞价订单	接口 3
`stats`	读取自有条目曝光数据	接口 2 扩展字段

API Key 等同于付款凭证，请仅存放于服务端，切勿写入前端代码、小程序包或 Git 仓库。

三、接口 1 · 榜单查询

GET /v1/leaderboard — 分页返回指定榜单的条目列表。

参数	类型	必填	说明
`category`	string	否	分类 key，默认 `all`
`period`	string	否	`all` / `today`，默认 `all`
`limit`	integer	否	1–100，默认 50
`cursor`	string	否	游标分页，取上一页 `next_cursor`

json

{
  "code": 0,
  "data": {
    "total": 2705,
    "next_cursor": "eyJvIjoxMDB9",
    "items": [
      {
        "id": "itm_8fJ2kQ",
        "rank": 1,
        "name": "Outrank · AI 自动化 SEO 流量",
        "desc": "用 AI 自动优化你的 SEO",
        "category": "seo",
        "amount_cents": 1300500,
        "url": "https://example.com",
        "ad_label": "广告",
        "created_at": 1757000000
      }
    ]
  }
}

四、接口 2 · 条目详情

GET /v1/items/{id} — 返回单个条目的完整信息。带 stats 权限时额外返回自有条目的曝光与点击数据。

json

{
  "code": 0,
  "data": {
    "id": "itm_8fJ2kQ",
    "rank": 1,
    "amount_cents": 1300500,
    "next_bid_cents": 1313505,  // 超越本名次所需最低金额
    "category": "seo",
    "status": "active",     // active | reviewing | removed
    "impressions": 12840,
    "clicks": 847
  }
}

五、接口 3 · 创建竞价

POST /v1/claims — 对目标名次下单，返回支付二维码地址。订单 15 分钟内未支付自动关闭。

bash

curl -X POST https://api.pubutang.cn/v1/claims \
  -H "Authorization: Bearer pt_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","target_rank":3,"category":"seo","period_days":30}'

字段	类型	必填	说明
`url`	string	是	目标网址，会被归一化处理
`target_rank`	integer	是	目标名次，1–1000
`category`	string	是	分类 key
`period_days`	integer	否	展示周期，默认 30

成功响应返回 order_id、amount_cents、pay_url（MoR 收单商结账页）与 expires_at。支付结果通过 webhook 回调通知，回调签名算法为 HMAC-SHA256，签名放在 X-PT-Signature 头。

六、错误码

HTTP	code	含义	处理建议
400	1001	参数缺失或格式错误	检查字段类型
401	2001	API Key 无效或已吊销	重新签发 Key
403	2003	权限范围不足	申请对应 scope
403	3005	内容未通过机检（违禁词 / 黑名单）	修改描述后重试
403	3006	类目需前置资质	上传资质
409	4001	名次已被抢占	重新查询后按新金额下单
429	5001	触发限流	按 `Retry-After` 退避
500	9001	服务内部错误	携带 `request_id` 提交工单

七、限流与配额

接口类型	默认配额	突发上限
只读接口	60 次 / 分钟	120
写入接口	10 次 / 分钟	20
Webhook 重试	失败后按 1 / 5 / 30 / 120 分钟退避，共 4 次

响应头 X-RateLimit-Remaining 与 X-RateLimit-Reset 实时反映配额状态。需要更高配额请通过工单申请。

Current status: draft specification. This is a demonstration build and no live API is open yet. The definitions below are stable enough for integration scoping; no breaking changes are planned before launch.

1. Quick start

All requests use HTTPS. Responses are JSON, charset UTF-8. Timestamps are Unix seconds (integer); all amounts are integers in minor units (cents, 1/100 USD).

bash

curl https://api.example.com/v1/leaderboard?category=seo&limit=10 \
   -H "Authorization: Bearer pt_live_xxxxxxxxxxxx"

2. Authentication

Create an API key in the Merchant Center and pass it in the Authorization header. Keys come in two prefixes: pt_live_ (production) and pt_test_ (sandbox). The sandbox never charges real money.

Scope	What it allows	Applies to
`read`	Read-only leaderboard and items	Endpoints 1, 2
`write`	Create bid orders	Endpoint 3
`stats`	Read impression data for your own items	Endpoint 2 extended fields

An API key is equivalent to payment credentials. Keep it server-side only — never in front-end code, a client bundle, or a Git repository.

3. Endpoint 1 · List leaderboard

GET /v1/leaderboard — returns a paginated list of entries for the given board.

Parameter	Type	Required	Notes
`category`	string	No	Category key; defaults to `all`
`period`	string	No	`all` / `today`; defaults to `all`
`limit`	integer	No	1–100; defaults to 50
`cursor`	string	No	Cursor pagination; pass the previous page's `next_cursor`

json

{
  "code": 0,
  "data": {
    "total": 2705,
    "next_cursor": "eyJvIjoxMDB9",
    "items": [
      {
        "id": "itm_8fJ2kQ",
        "rank": 1,
        "name": "Outrank · AI-driven SEO traffic",
        "desc": "Automate your SEO with AI",
        "category": "seo",
        "amount_cents": 1300500,
        "url": "https://example.com",
        "ad_label": "Ad",
        "created_at": 1757000000
      }
    ]
  }
}

4. Endpoint 2 · Item detail

GET /v1/items/{id} — returns full information for a single item. With the stats scope it additionally returns impressions and clicks for your own items.

json

{
  "code": 0,
  "data": {
    "id": "itm_8fJ2kQ",
    "rank": 1,
    "amount_cents": 1300500,
    "next_bid_cents": 1313505,  // minimum amount to take this rank
    "category": "seo",
    "status": "active",     // active | reviewing | removed
    "impressions": 12840,
    "clicks": 847
  }
}

5. Endpoint 3 · Create a bid

POST /v1/claims — places an order for a target rank and returns a checkout URL. Unpaid orders close automatically after 15 minutes.

bash

curl -X POST https://api.example.com/v1/claims \
   -H "Authorization: Bearer pt_live_xxxxxxxxxxxx" \
   -H "Content-Type: application/json" \
   -d '{"url":"https://example.com","target_rank":3,"category":"seo","period_days":30}'

Field	Type	Required	Notes
`url`	string	Yes	Target URL; normalised server-side
`target_rank`	integer	Yes	Target rank, 1–1000
`category`	string	Yes	Category key
`period_days`	integer	No	Display period; defaults to 30

A successful response returns order_id, amount_cents, pay_url (the merchant-of-record checkout URL), and expires_at. Payment outcome is delivered by webhook, signed with HMAC-SHA256 in the X-PT-Signature header.

6. Error codes

HTTP	code	Meaning	Suggested handling
400	1001	Missing or malformed parameter	Check field types
401	2001	API key invalid or revoked	Issue a new key
403	2003	Insufficient scope	Request the matching scope
403	3005	Content failed automated screening (prohibited words / blacklist)	Revise the description and retry
403	3006	Category needs a prior licence	Upload the licence
409	4001	Rank already taken	Re-query, then order at the new amount
429	5001	Rate limited	Back off per `Retry-After`
500	9001	Internal server error	Open a ticket with the `request_id`

7. Rate limits & quotas

Endpoint type	Default quota	Burst ceiling
Read endpoints	60 / minute	120
Write endpoints	10 / minute	20
Webhook retries	On failure, retry after 1 / 5 / 30 / 120 minutes — 4 attempts in total

The X-RateLimit-Remaining and X-RateLimit-Reset response headers reflect quota status in real time. For a higher quota, open a ticket.