接口
get/public/price-list
公开价目(不需要 API Key)
对所有人公开,不需要鉴权;按来源限流(超出返回 429)。
只给五个字段:媒体条目编号、内容类型、档位、零售价(分)、当前能否下单。名称、覆盖面等明细请用带 Key 的 /media。
与报价同一价源:同一时刻,这里的零售价就是 POST /quotes 会给的价;要锁价仍须报价。
缓存:响应带 Cache-Control 与 ETag;带 If-None-Match 且未变化时返回 304。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
content_type | query | ContentType | 否 | |
tier | query | string | 否 | 档位代码 |
page | query | integer | 否 | |
page_size | query | integer | 否 | |
If-None-Match | header | string | 否 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 一页公开价目 | object |
304 | 未变化( | |
422 | 请求格式或内容不合格: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
get/media
列出可下单的媒体条目
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
content_type | query | ContentType | 否 | |
platform | query | string | 否 | 平台代码,取值见 /media/facets |
region | query | string | 否 | 地区代码,取值见 /media/facets |
industry | query | string | 否 | 行业代码,取值见 /media/facets |
tier | query | string | 否 | 档位代码,取值见 /media/facets |
audience_band | query | string | 否 | 受众规模档,取值见 /media/facets |
editable | query | boolean | 否 | 是否接受改稿 |
max_turnaround_hours | query | integer | 否 | |
price_min | query | integer | 否 | 零售价下限,单位:分 |
price_max | query | integer | 否 | 零售价上限,单位:分 |
q | query | string | 否 | 按媒体名称搜索 |
sort | query | string | 否 | |
page | query | integer | 否 | |
page_size | query | integer | 否 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 一页媒体条目 | object |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
403 | Key 有效,但本组织无权执行该操作( | Error |
422 | 请求格式或内容不合格: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
get/media/facets
目录筛选项的可选值(平台 / 地区 / 行业 / 档位 / 受众规模档)
get/media/{offer_id}
单个媒体条目
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
offer_id | path | OfferId | 是 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 媒体条目 | MediaOffer |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
post/quotes
为一组媒体条目报价
报价即快照:返回的每条价格与合计在 expires_at 前有效,下单只认 quote_id。
一个报价只能开一个订单。条目下架或不可下单时整单拒绝(409 OFFER_UNAVAILABLE),不做部分报价。
同一报价内的条目必须是同一种内容类型(一个订单只带一份内容),混合类型返回 422 CONTENT_MISMATCH。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。 |
请求体:object
| 响应 | 说明 | 响应体 |
|---|---|---|
201 | 已出报价 | Quote |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
403 | Key 有效,但本组织无权执行该操作( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
409 | 与当前状态冲突: | Error |
422 | 请求格式或内容不合格: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
get/quotes/{quote_id}
查报价(含是否仍可下单)
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
quote_id | path | QuoteId | 是 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 报价 | Quote |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
get/orders
本组织的订单(新到旧)
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
status | query | OrderStatus | 否 | |
created_after | query | string (date-time) | 否 | |
created_before | query | string (date-time) | 否 | |
page | query | integer | 否 | |
page_size | query | integer | 否 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 一页订单 | object |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
422 | 请求格式或内容不合格: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
post/orders
按报价下单
校验顺序:报价有效 → 内容与每个条目的内容类型匹配 → 内容合规检查 → 余额 → 冻结合计 → 受理。
内容合规检查不通过返回 422 CONTENT_REJECTED,不冻结;余额不足返回 402,不冻结、不欠费。
受理后每个条目以 pending 开始。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。 |
请求体:object
| 响应 | 说明 | 响应体 |
|---|---|---|
201 | 已受理 | Order |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
402 | 可用余额不足以冻结本单合计( | Error |
403 | Key 有效,但本组织无权执行该操作( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
409 | 与当前状态冲突: | Error |
422 | 请求格式或内容不合格: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
get/orders/{order_id}
查订单与每个条目的状态、回执、结算
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
order_id | path | OrderId | 是 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 订单 | Order |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | Error |
post/orders/{order_id}/cancel
取消仍在排队的条目
只取消 status = pending 的条目,其占用金额原额退回(charge.state = released)。
已进入 submitted 及之后状态的条目不受影响。没有任何 pending 条目时返回 409 NOT_CANCELLABLE。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
order_id | path | OrderId | 是 | |
Idempotency-Key | header | string | 是 | 调用方生成的唯一键(建议 UUID)。同键同体重放返回首次结果;同键异体 409。 |
| 响应 | 说明 | 响应体 |
|---|---|---|
200 | 取消后的订单 | Order |
401 | 缺少 / 无效 / 已吊销的 API Key( | Error |
404 | 资源不存在或不属于本组织(两者不区分)( | Error |
409 | 与当前状态冲突: | Error |
429 | 超过速率或单日上限( | Error |
500 | 本渠道内部错误( | 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 单位为分(整数,不用小数)。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
value | integer | 是 | 金额,单位:分 |
currency | string = "CNY" | 是 |
PublicPriceEntry object
公开价目的一行。只有这五个字段(闭集白名单)。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
offer_id | OfferId | 是 | |
content_type | ContentType | 是 | |
tier | string | 是 | 档位代码 |
price | Amount | 是 | |
orderable | boolean | 是 | 当前能否下单 |
MediaOffer object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
offer_id | OfferId | 是 | |
name | string | 是 | 媒体名称 |
content_type | ContentType | 是 | |
platform | string | 是 | 平台代码 |
tier | string | 是 | 档位代码 |
regions | array<string> | 否 | |
industries | array<string> | 否 | |
audience_band | string | null | 否 | |
editable | boolean | null | 否 | 是否接受改稿 |
includes_link | boolean | null | 否 | 是否允许正文带链接 |
turnaround_hours | integer | null | 否 | 常规出稿时长(小时),仅供参考 |
price | Amount | 是 | |
requirements | ContentRequirements | 否 | |
available | boolean | 是 | 当前是否可报价 |
ContentRequirements object
结构化内容要求;字段缺省 = 本条目未设该项限制。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
min_chars | integer | 否 | |
max_chars | integer | 否 | |
max_images | integer | 否 | |
max_video_seconds | integer | 否 | |
disallowed_categories | array<string> | 否 |
Facets object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
platforms | array<FacetValue> | 是 | |
regions | array<FacetValue> | 是 | |
industries | array<FacetValue> | 是 | |
tiers | array<FacetValue> | 是 | |
audience_bands | array<FacetValue> | 是 |
FacetValue object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | 是 | |
label | string | 是 |
Terms object
本报价适用的渠道规则。下单即接受此版本;之后规则更新不影响已下的单。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
version | string | 是 | 规则版本号 |
price_basis | string = "quote_snapshot" | 是 | 成交价取自本报价快照,回执与退款都不按当时目录价重算 |
refund_before_publication | string = "full_release" | 是 | 拒稿 / 提交失败 / 排队中取消 ⇒ 该条目占用金额原额退回余额 |
refund_after_publication | string = "none" | 是 | 取得回执后账号被封、内容被删除或不可见 ⇒ 不退 |
receipt_scope | string = "submission_and_receipt_only" | 是 | 只承诺已提交 / 已回执(附链接)/ 失败(附原因码);不承诺可见、收录、排名 |
text | string | 是 | 以上规则的完整文字版 |
Quote object
OrderContent ArticleContent | ImageNoteContent | ShortVideoContent
订单内容。报价里的每个条目都会收到同一份内容;内容类型必须与条目一致,否则 422 CONTENT_MISMATCH。
ArticleContent object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string = "article" | 是 | |
title | string | 是 | |
body | string | 是 | 正文(Markdown) |
image_urls | array<string (uri)> | 否 |
ImageNoteContent object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string = "imagenote" | 是 | |
title | string | 是 | |
body | string | 是 | |
image_urls | array<string (uri)> | 是 | |
tags | array<string> | 否 |
ShortVideoContent object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string = "svideo" | 是 | |
title | string | 是 | |
video_url | string (uri) | 是 | |
cover_url | string (uri) | 否 | |
caption | string | 否 | |
tags | array<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_id | ItemId | 是 | |
offer_id | OfferId | 是 | 下单时的媒体条目编号;订单生命周期内不变 |
name | string | 是 | |
content_type | ContentType | 是 | |
status | ItemStatus | 是 | |
price | Amount | 是 | 成交价(来自报价快照) |
charge | object | 是 | |
receipt | null | object | 否 | |
failure | null | object | 否 | |
updated_at | string (date-time) | 是 |
Order object
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
order_id | OrderId | 是 | |
quote_id | QuoteId | 是 | |
client_reference | string | null | 否 | |
status | OrderStatus | 是 | |
created_at | string (date-time) | 是 | |
items | array<OrderItem> | 是 | |
total | Amount | 是 | 本单合计(来自报价快照) |
terms_version | string | 是 | 下单时接受的渠道规则版本 |
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
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
error | object | 是 |
错误码
| 码 | 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
失败原因码
本渠道自己的原因码。message 为本渠道撰写的说明,不转述第三方原文。
CONTENT_NOT_ACCEPTEDCONTENT_REQUIREMENTS_NOT_METMEDIA_UNAVAILABLESUBMISSION_FAILEDTIMED_OUTCANCELLED_BY_CLIENTCANCELLED_BY_CHANNEL