Citeway发布渠道 API v1

接口参考

本页由契约生成。v1 在契约之上的执行限制见 v1 限制

接口

get/public/price-list

公开价目(不需要 API Key)

对所有人公开,不需要鉴权;按来源限流(超出返回 429)。 只给五个字段:媒体条目编号、内容类型、档位、零售价(分)、当前能否下单。名称、覆盖面等明细请用带 Key 的 /media。 与报价同一价源:同一时刻,这里的零售价就是 POST /quotes 会给的价;要锁价仍须报价。 缓存:响应带 Cache-Control 与 ETag;带 If-None-Match 且未变化时返回 304。

参数位置类型必填说明
content_typequeryContentType否
tierquerystring否

档位代码

pagequeryinteger否
page_sizequeryinteger否
If-None-Matchheaderstring否
响应说明响应体
200

一页公开价目

object
304

未变化(If-None-Match 命中)

422

请求格式或内容不合格:VALIDATION_FAILED / CONTENT_MISMATCH / CONTENT_REJECTED。不冻结。

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/media

列出可下单的媒体条目

参数位置类型必填说明
content_typequeryContentType否
platformquerystring否

平台代码,取值见 /media/facets

regionquerystring否

地区代码,取值见 /media/facets

industryquerystring否

行业代码,取值见 /media/facets

tierquerystring否

档位代码,取值见 /media/facets

audience_bandquerystring否

受众规模档,取值见 /media/facets

editablequeryboolean否

是否接受改稿

max_turnaround_hoursqueryinteger否
price_minqueryinteger否

零售价下限,单位:分

price_maxqueryinteger否

零售价上限,单位:分

qquerystring否

按媒体名称搜索

sortquerystring否
pagequeryinteger否
page_sizequeryinteger否
响应说明响应体
200

一页媒体条目

object
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
403

Key 有效,但本组织无权执行该操作(FORBIDDEN / CONTENT_TYPE_NOT_ENABLED / ACCOUNT_SUSPENDED)

Error
422

请求格式或内容不合格:VALIDATION_FAILED / CONTENT_MISMATCH / CONTENT_REJECTED。不冻结。

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/media/facets

目录筛选项的可选值(平台 / 地区 / 行业 / 档位 / 受众规模档)

响应说明响应体
200

各筛选维度的取值

Facets
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/media/{offer_id}

单个媒体条目

参数位置类型必填说明
offer_idpathOfferId是
响应说明响应体
200

媒体条目

MediaOffer
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

post/quotes

为一组媒体条目报价

报价即快照:返回的每条价格与合计在 expires_at 前有效,下单只认 quote_id。 一个报价只能开一个订单。条目下架或不可下单时整单拒绝(409 OFFER_UNAVAILABLE),不做部分报价。 同一报价内的条目必须是同一种内容类型(一个订单只带一份内容),混合类型返回 422 CONTENT_MISMATCH。

参数位置类型必填说明
Idempotency-Keyheaderstring是

调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。

请求体:object

响应说明响应体
201

已出报价

Quote
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
403

Key 有效,但本组织无权执行该操作(FORBIDDEN / CONTENT_TYPE_NOT_ENABLED / ACCOUNT_SUSPENDED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
409

与当前状态冲突:QUOTE_EXPIRED / QUOTE_ALREADY_USED / QUOTE_STALE / OFFER_UNAVAILABLE / IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_IN_PROGRESS / NOT_CANCELLABLE

Error
422

请求格式或内容不合格:VALIDATION_FAILED / CONTENT_MISMATCH / CONTENT_REJECTED。不冻结。

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/quotes/{quote_id}

查报价(含是否仍可下单)

参数位置类型必填说明
quote_idpathQuoteId是
响应说明响应体
200

报价

Quote
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/orders

本组织的订单(新到旧)

参数位置类型必填说明
statusqueryOrderStatus否
created_afterquerystring (date-time)否
created_beforequerystring (date-time)否
pagequeryinteger否
page_sizequeryinteger否
响应说明响应体
200

一页订单

object
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
422

请求格式或内容不合格:VALIDATION_FAILED / CONTENT_MISMATCH / CONTENT_REJECTED。不冻结。

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

post/orders

按报价下单

校验顺序:报价有效 → 内容与每个条目的内容类型匹配 → 内容合规检查 → 余额 → 冻结合计 → 受理。 内容合规检查不通过返回 422 CONTENT_REJECTED,不冻结;余额不足返回 402,不冻结、不欠费。 受理后每个条目以 pending 开始。

参数位置类型必填说明
Idempotency-Keyheaderstring是

调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。

请求体:object

响应说明响应体
201

已受理

Order
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
402

可用余额不足以冻结本单合计(INSUFFICIENT_BALANCE)。未冻结、未受理。

Error
403

Key 有效,但本组织无权执行该操作(FORBIDDEN / CONTENT_TYPE_NOT_ENABLED / ACCOUNT_SUSPENDED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
409

与当前状态冲突:QUOTE_EXPIRED / QUOTE_ALREADY_USED / QUOTE_STALE / OFFER_UNAVAILABLE / IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_IN_PROGRESS / NOT_CANCELLABLE

Error
422

请求格式或内容不合格:VALIDATION_FAILED / CONTENT_MISMATCH / CONTENT_REJECTED。不冻结。

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

get/orders/{order_id}

查订单与每个条目的状态、回执、结算

参数位置类型必填说明
order_idpathOrderId是
响应说明响应体
200

订单

Order
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

post/orders/{order_id}/cancel

取消仍在排队的条目

只取消 status = pending 的条目,其占用金额原额退回(charge.state = released)。 已进入 submitted 及之后状态的条目不受影响。没有任何 pending 条目时返回 409 NOT_CANCELLABLE。

参数位置类型必填说明
order_idpathOrderId是
Idempotency-Keyheaderstring是

调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。

响应说明响应体
200

取消后的订单

Order
401

缺少 / 无效 / 已吊销的 API Key(UNAUTHENTICATED)

Error
404

资源不存在或不属于本组织(两者不区分)(NOT_FOUND)

Error
409

与当前状态冲突:QUOTE_EXPIRED / QUOTE_ALREADY_USED / QUOTE_STALE / OFFER_UNAVAILABLE / IDEMPOTENCY_KEY_REUSED / IDEMPOTENCY_IN_PROGRESS / NOT_CANCELLABLE

Error
429

超过速率或单日上限(RATE_LIMITED / DAILY_QUOTA_EXCEEDED)。按 Retry-After 等待后, 带同一个 Idempotency-Key 重试是安全的:不会重复冻结、不会重复下单。

Error
500

本渠道内部错误(INTERNAL_ERROR)。带同一个 Idempotency-Key 重试是安全的: 若首次请求其实已受理,重试返回首次的结果,不会重复冻结、不会重复下单。

Error

事件

postitem.status_changed

占位 · 本版本未启用

占位,v1 不投递。 预留事件名与信封版本号,启用时间与签名方式在后续版本公布; 在此之前请以 GET /orders/{order_id} 轮询。

数据结构

OfferId string

QuoteId string

OrderId string

ItemId string

ContentType string

article 媒体文章 · imagenote 自媒体图文 · svideo 短视频。每个媒体条目只接受一种内容类型。

取值:articleimagenotesvideo

Amount object

人民币金额。value 单位为分(整数,不用小数)。

字段类型必填说明
valueinteger是

金额,单位:分

currencystring = "CNY"是

PublicPriceEntry object

公开价目的一行。只有这五个字段(闭集白名单)。

字段类型必填说明
offer_idOfferId是
content_typeContentType是
tierstring是

档位代码

priceAmount是
orderableboolean是

当前能否下单

MediaOffer object

字段类型必填说明
offer_idOfferId是
namestring是

媒体名称

content_typeContentType是
platformstring是

平台代码

tierstring是

档位代码

regionsarray<string>否
industriesarray<string>否
audience_bandstring | null否
editableboolean | null否

是否接受改稿

includes_linkboolean | null否

是否允许正文带链接

turnaround_hoursinteger | null否

常规出稿时长(小时),仅供参考

priceAmount是
requirementsContentRequirements否
availableboolean是

当前是否可报价

ContentRequirements object

结构化内容要求;字段缺省 = 本条目未设该项限制。

字段类型必填说明
min_charsinteger否
max_charsinteger否
max_imagesinteger否
max_video_secondsinteger否
disallowed_categoriesarray<string>否

Facets object

字段类型必填说明
platformsarray<FacetValue>是
regionsarray<FacetValue>是
industriesarray<FacetValue>是
tiersarray<FacetValue>是
audience_bandsarray<FacetValue>是

FacetValue object

字段类型必填说明
codestring是
labelstring是

Terms object

本报价适用的渠道规则。下单即接受此版本;之后规则更新不影响已下的单。

字段类型必填说明
versionstring是

规则版本号

price_basisstring = "quote_snapshot"是

成交价取自本报价快照,回执与退款都不按当时目录价重算

refund_before_publicationstring = "full_release"是

拒稿 / 提交失败 / 排队中取消 ⇒ 该条目占用金额原额退回余额

refund_after_publicationstring = "none"是

取得回执后账号被封、内容被删除或不可见 ⇒ 不退

receipt_scopestring = "submission_and_receipt_only"是

只承诺已提交 / 已回执(附链接)/ 失败(附原因码);不承诺可见、收录、排名

textstring是

以上规则的完整文字版

Quote object

字段类型必填说明
quote_idQuoteId是
statestring是

open 可下单 · used 已开过一单 · expired 过期或失效

created_atstring (date-time)是
expires_atstring (date-time)是
itemsarray<object>是
totalAmount是
termsTerms是
order_idOrderId | null否

state = used 时为开出的订单

OrderContent ArticleContent | ImageNoteContent | ShortVideoContent

订单内容。报价里的每个条目都会收到同一份内容;内容类型必须与条目一致,否则 422 CONTENT_MISMATCH。

ArticleContent object

字段类型必填说明
typestring = "article"是
titlestring是
bodystring是

正文(Markdown)

image_urlsarray<string (uri)>否

ImageNoteContent object

字段类型必填说明
typestring = "imagenote"是
titlestring是
bodystring是
image_urlsarray<string (uri)>是
tagsarray<string>否

ShortVideoContent object

字段类型必填说明
typestring = "svideo"是
titlestring是
video_urlstring (uri)是
cover_urlstring (uri)否
captionstring否
tagsarray<string>否

OrderStatus string

由条目状态归并:任一条目在途 ⇒ processing;全部取得回执 ⇒ completed; 全部取消 ⇒ cancelled;有回执也有失败 / 拒稿 / 取消 ⇒ partial;其余 ⇒ failed。

取值:processingcompletedpartialfailedcancelled

ItemStatus string

值 含义 终态 费用
pending 已受理,排队未提交;可取消 否 冻结
submitted 已提交渠道,等待回执 否 冻结
receipted 已回执且本渠道已核实链接。保留值:本渠道核实能力上线前不下发 是 结算,不退
receipted_unverified 已回执(附链接),本渠道尚未核实 是* 结算,不退
rejected 渠道拒稿(发出前) 是 原额释放
failed 提交失败 / 未能发出 是 原额释放
cancelled 排队中被取消 是 原额释放

* receipted_unverified 之后只可能变成 receipted,不会回到在途或失败。 客户端遇到未知的新值时按「在途」处理。

取值:pendingsubmittedreceiptedreceipted_unverifiedrejectedfailedcancelled

ChargeState string

frozen 已冻结未结算 · charged 已结算 · released 已原额释放 · under_review 结算待人工复核。

under_review:条目已到终态,但自动结算没有完成(例如结算记账失败)时进入;金额始终是成交价,不变。 复核后离开,只可能变成 charged(条目已取得回执)或 released(条目发出前失败 / 被拒 / 被取消), 与条目状态一致,不产生第三种结果。

取值:frozenchargedreleasedunder_review

FailureCode string

本渠道自己的原因码。message 为本渠道撰写的说明,不转述第三方原文。

取值:CONTENT_NOT_ACCEPTEDCONTENT_REQUIREMENTS_NOT_METMEDIA_UNAVAILABLESUBMISSION_FAILEDTIMED_OUTCANCELLED_BY_CLIENTCANCELLED_BY_CHANNEL

OrderItem object

字段类型必填说明
item_idItemId是
offer_idOfferId是

下单时的媒体条目编号;订单生命周期内不变

namestring是
content_typeContentType是
statusItemStatus是
priceAmount是

成交价(来自报价快照)

chargeobject是
receiptnull | object否
failurenull | object否
updated_atstring (date-time)是

Order object

字段类型必填说明
order_idOrderId是
quote_idQuoteId是
client_referencestring | null否
statusOrderStatus是
created_atstring (date-time)是
itemsarray<OrderItem>是
totalAmount是

本单合计(来自报价快照)

terms_versionstring是

下单时接受的渠道规则版本

ErrorCode string

码 HTTP
UNAUTHENTICATED 401
INSUFFICIENT_BALANCE 402
FORBIDDEN · CONTENT_TYPE_NOT_ENABLED · ACCOUNT_SUSPENDED 403
NOT_FOUND 404
QUOTE_EXPIRED · QUOTE_ALREADY_USED · QUOTE_STALE · OFFER_UNAVAILABLE · IDEMPOTENCY_KEY_REUSED · IDEMPOTENCY_IN_PROGRESS · NOT_CANCELLABLE 409
VALIDATION_FAILED · CONTENT_MISMATCH · CONTENT_REJECTED 422
RATE_LIMITED · DAILY_QUOTA_EXCEEDED 429
INTERNAL_ERROR 500

QUOTE_STALE:报价后目录发生变化,该报价不再能下单,请重新报价(不会按新价悄悄成交)。

取值:UNAUTHENTICATEDINSUFFICIENT_BALANCEFORBIDDENCONTENT_TYPE_NOT_ENABLEDACCOUNT_SUSPENDEDNOT_FOUNDQUOTE_EXPIREDQUOTE_ALREADY_USEDQUOTE_STALEOFFER_UNAVAILABLEIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_IN_PROGRESSNOT_CANCELLABLEVALIDATION_FAILEDCONTENT_MISMATCHCONTENT_REJECTEDRATE_LIMITEDDAILY_QUOTA_EXCEEDEDINTERNAL_ERROR

Error object

字段类型必填说明
errorobject是

错误码

码 HTTP
UNAUTHENTICATED 401
INSUFFICIENT_BALANCE 402
FORBIDDEN · CONTENT_TYPE_NOT_ENABLED · ACCOUNT_SUSPENDED 403
NOT_FOUND 404
QUOTE_EXPIRED · QUOTE_ALREADY_USED · QUOTE_STALE · OFFER_UNAVAILABLE · IDEMPOTENCY_KEY_REUSED · IDEMPOTENCY_IN_PROGRESS · NOT_CANCELLABLE 409
VALIDATION_FAILED · CONTENT_MISMATCH · CONTENT_REJECTED 422
RATE_LIMITED · DAILY_QUOTA_EXCEEDED 429
INTERNAL_ERROR 500

QUOTE_STALE:报价后目录发生变化,该报价不再能下单,请重新报价(不会按新价悄悄成交)。

  • UNAUTHENTICATED
  • INSUFFICIENT_BALANCE
  • FORBIDDEN
  • CONTENT_TYPE_NOT_ENABLED
  • ACCOUNT_SUSPENDED
  • NOT_FOUND
  • QUOTE_EXPIRED
  • QUOTE_ALREADY_USED
  • QUOTE_STALE
  • OFFER_UNAVAILABLE
  • IDEMPOTENCY_KEY_REUSED
  • IDEMPOTENCY_IN_PROGRESS
  • NOT_CANCELLABLE
  • VALIDATION_FAILED
  • CONTENT_MISMATCH
  • CONTENT_REJECTED
  • RATE_LIMITED
  • DAILY_QUOTA_EXCEEDED
  • INTERNAL_ERROR

失败原因码

本渠道自己的原因码。message 为本渠道撰写的说明,不转述第三方原文。

  • CONTENT_NOT_ACCEPTED
  • CONTENT_REQUIREMENTS_NOT_MET
  • MEDIA_UNAVAILABLE
  • SUBMISSION_FAILED
  • TIMED_OUT
  • CANCELLED_BY_CLIENT
  • CANCELLED_BY_CHANNEL