Citeway发布渠道 API v1
版本 1.0.1 · OpenAPI 3.1.0

Citeway Publishing Channel API引路 · 发布渠道 API

目录 · 报价 · 下单 · 查询。一个报价开一个订单;价格以报价为准。

把内容发往各类媒体,按人民币预存、按单结算。

接口参考 公开价目
公开价目(不需要 API Key)
请求
GET /v1/public/price-list?page=1&page_size=20
Accept: application/json
响应
{
  "data": [
    {
      "offer_id": "off_EXAMPLE0001",
      "content_type": "article",
      "tier": "T1",
      "price": { "value": 100, "currency": "CNY" },
      "orderable": true
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1,
  "updated_at": "…"
}
金额单位:分示例值,实际以公开价目为准

一张单怎么走

  1. 目录 get /media
  2. 报价 post /quotes
  3. 下单 post /orders
  4. 查询 get /orders/{order_id}
已提交已回执失败

本渠道只承诺「已提交」「已回执(附链接)」「失败(附原因码)」,不承诺发布可见、收录或排名。

三条规则

  1. 价格以报价为准。

    下单只认报价编号;订单成交价取自报价快照,之后目录调价、回执到达、退款,都不按当时的目录价重算。

  2. 发出前没成功的,占用金额原额退回余额。

    被渠道拒稿、提交失败、在排队中取消 ——该条目下单时占用的金额原额退回。

  3. 发出后不退。

    条目一旦取得回执(receipted 或 receipted_unverified),该条目费用即结算;之后账号被封、内容被平台删除或不可见,不退。

每个报价的 terms 字段里也带着,下单即视为接受该版本

鉴权与幂等

  • 组织级 API Key,放在 Authorization: Bearer <api_key>。Key 只能看到本组织的数据。
  • 所有 POST 都必须带 Idempotency-Key 头。同键 + 同请求体 ⇒ 返回首次的结果, 响应头 Idempotent-Replayed: true,不重复冻结。同键 + 不同请求体 ⇒ 409 IDEMPOTENCY_KEY_REUSED。 幂等键在组织内唯一,至少保留 24 小时。

apiKey · http · bearer

组织级 API Key(可在控制台创建、吊销)。吊销后立即失效(401)。

编号

全部是本渠道的不透明字符串编号(off_ 媒体条目 · qt_ 报价 · ord_ 订单 · itm_ 订单条目)。 编号在其生命周期内不变;不要解析编号的内容。

金额

金额一律以人民币计,Amount = {value, currency}:value 是非负整数,单位是分(不用小数); currency 恒为 CNY。本 API 不做现金收付;余额充值在控制台完成。 文档与示例中的金额(如 100 分)都是示例值,不代表任何实际价格;实际价格以公开价目与报价为准。

公开价目

GET /public/price-list 不需要 API Key,限流,带缓存头;只给媒体条目编号、内容类型、档位、零售价与当前能否下单。 公开价目与报价取自同一价源:同一时刻,价目里的零售价就是报价会给的价。

媒体条目的公开零售价见 公开价目(打开时实时读取,不需要 API Key)。

跨域

本 API 不开 CORS(任何响应都不带 Access-Control-Allow-* 头)。开发者门户页面与 API 同源,用相对路径取数。

服务地址

  • https://cngeo.top/v1

v1 限制

以下是 v1 服务端当前的执行限制。契约(OpenAPI)本身不变,这些限制在契约允许的范围内另外生效;后续版本放开时会在这里更新。

1. 文章类内容暂不支持配图与正文内嵌图片

ArticleContent 在契约里允许 image_urls,但 v1 会拒绝带配图的文章: 请求里带了 image_urls 时返回 422 CONTENT_REJECTED, error.details 里对应项的 field 为 content.image_urls。 请去掉 image_urls 后重新提交;该请求不冻结任何金额。

文章正文 body 里暂不支持内嵌图片:Markdown 图片 ![说明](https://…)、引用式图片 ![说明][ref](配 [ref]: https://…)、 HTML <img …> 都会在下单时被拒,同样返回 422 CONTENT_REJECTED,error.details 里对应项的 field 为 content.body。 普通链接 [文字](https://…) 与正文里直接写的网址不受影响,照常发出。

2. 标题长度上限

按内容类型区分。「契约上限」是 schema 里 title.maxLength 的值;「v1 实际上限」可能更严,以本表为准。

内容类型schema契约上限(字符)v1 实际上限(字符)
article ArticleContent 120 45
imagenote ImageNoteContent 60 45
svideo ShortVideoContent 60 45

3. 派发超时

下单后 24 小时内仍未能派发的条目,按失败处理并全额退回:条目的 status 为 failed, failure.code 为 TIMED_OUT, charge.state 为 released(冻结金额原额释放)。

4. 内容触发发布端复核提示

提交的内容触发发布端的复核提示时,该条目按失败处理并全额退回: status 为 failed, failure.code 为 CONTENT_NOT_ACCEPTED, charge.state 为 released(冻结金额原额释放)。

接口目录