合作对接 / API 文档

对接概览

我们会将曲目与元数据推送到合作站点。合作方需要提供接收接口并校验密钥即可完成对接。

• 鉴权 请求头 Authorization: Bearer <push_api_key>
• 格式 Content-Type: application/json
• 幂等 建议以 track_id 做唯一键，重复推送时更新/忽略
• 重试 5xx / 网络超时 会进入队列重试（请保证接口幂等）

合作流程：提交申请 → 审核 → 发放推送密钥与推送地址 → 联调 → 上线。

鉴权方式

合作站点需校验：

Authorization: Bearer <push_api_key>

• 密钥由平台发放，可轮换。
• 建议你们侧支持“双密钥过渡”（新旧密钥在一段时间内同时有效），便于平滑轮换。
• 如需更强安全（HMAC、时间戳、防重放），可在合作阶段协商升级。

接收曲目 API

合作站需要提供的端点（官方站会调用合作站接口推送曲目）：

POST https://your-site.com/api/receive-track
Content-Type: application/json
Authorization: Bearer <push_api_key>

请求体示例（降敏，字段可能按合作扩展）：

{
  "track_id": "7617",
  "title": "Track Title",
  "artist": "Artist Name",
  "album": "",
  "genre": "House",
  "duration": 249,
  "bpm": 128,
  "key": "G",
  "price": 0,
  "is_free": true,
  "artwork_url": "https://official.example.com/storage/covers/xxx.jpg",
  "audio_file_url": "https://official.example.com/api/stream/7617/compressed",
  "preview_file_url": "https://official.example.com/api/stream/7617/preview",
  "metadata": { "source": "official_site", "sync_time": "2026-03-17T13:40:00+08:00" }
}

成功响应（建议）：返回 200，并在 body 里给出你们侧的曲目 ID，便于日志追踪。

{
  "code": 0,
  "message": "ok",
  "data": { "track_id": "remote_abc123" }
}

失败响应（建议）：

// 401：鉴权失败（不重试）
{ "code": 401, "message": "Unauthorized" }

// 400/422：参数错误（一般不重试）
{ "code": 1002, "message": "missing required fields: track_id,title,audio_file_url" }

// 500：服务异常（会重试，需幂等）
{ "code": 2001, "message": "temporary error" }

curl 调试示例（合作站本地模拟接收端时可用）：

curl -X POST "https://your-site.com/api/receive-track" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <push_api_key>" ^
  -d "{\"track_id\":\"7617\",\"title\":\"Track Title\",\"audio_file_url\":\"https://official.example.com/api/stream/7617/compressed\"}"

字段说明（核心）

以下为常用字段（具体可按合作需求增减）。

请求体示例：

{
  "track_id": "official_123",
  "title": "曲目名称",
  "artist": "艺人名",
  "genre": "Electronic",
  "bpm": 128,
  "price": 2.99,
  "is_free": false,
  "artwork_url": "https://official.com/artwork.jpg",
  "audio_file_url": "https://official.com/audio.mp3",
  "preview_file_url": "https://official.com/preview.mp3",
  "metadata": { "source": "official_site", "sync_time": "2026-03-16T10:00:00Z" }
}

渠道跳转链接（可选）

用途：合作站展示曲目时，可提供一个按钮跳转到官方站对应页面，并附带渠道参数用于链路追踪/统计。

GET https://official.example.com/track/7617?from=partner&partner_site_id=12&click_id=xxxxxx

• partner_site_id：合作站点 ID（双方约定）
• click_id：可选，用于点击链路追踪

交易/行为事件回传（可选）

用途：合作站内发生关键事件后（例如：展示、点击、收藏、下载、交易成功等），按约定回传给官方站，用于统计/风控/链路追踪。

合作站调用（官方站提供）：

POST https://official.example.com/api/partner/report/event
Content-Type: application/json
Authorization: Bearer <api_key>

字段说明（建议）：

请求示例（降敏）：

{
  "partner_site_id": 12,
  "event_id": "evt_20260317_xxx",
  "event_type": "click",
  "track_id": 7617,
  "event_at": "2026-03-17 13:55:10",
  "context": { "click_id": "xxxxxx" },
  "sign": "HMAC_SHA256_SIGNATURE"
}

交易事件示例（trade_paid，可选字段更完整）：

{
  "partner_site_id": 12,
  "event_id": "evt_20260317_trade_xxx",
  "event_type": "trade_paid",
  "track_id": 7617,
  "event_at": "2026-03-17 14:02:30",
  "order_id": "P-20260317-00001",
  "amount_minor": 199,
  "currency": "CNY",
  "context": { "client": "web" },
  "sign": "HMAC_SHA256_SIGNATURE"
}

响应示例：

{ "code": 0, "message": "ok", "data": { "accepted": true } }

说明：event_id 建议幂等；5xx 可重试；签名推荐。金额仅用于技术对接字段示例，实际含义与使用范围以合作约定为准。

curl 调试示例：

curl -X POST "https://official.example.com/api/partner/report/event" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <api_key>" ^
  -d "{\"partner_site_id\":12,\"event_id\":\"evt_xxx\",\"event_type\":\"click\",\"track_id\":7617,\"event_at\":\"2026-03-17 13:55:10\"}"

下载授权 / 发货（可选）

用途：合作站在站内完成某些操作后（例如交易完成/权限校验通过），向官方站申请一次性下载链接/凭证，由官方站统一发货下载（便于控制有效期/次数与追踪）。

POST https://official.example.com/api/partner/fulfillment/download-token
Content-Type: application/json
Authorization: Bearer <api_key>

请求示例：

{
  "partner_site_id": 12,
  "request_id": "req_20260317_xxx",
  "track_id": 7617,
  "qty": 1,
  "sign": "HMAC_SHA256_SIGNATURE"
}

响应示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "download_url": "https://official.example.com/api/partner/fulfillment/download?token=xxxx",
    "expire_at": "2026-03-17 14:10:00"
  }
}

失败响应示例：

// 401：鉴权失败
{ "code": 401, "message": "Unauthorized" }

// 422：参数错误/不允许发货
{ "code": 1002, "message": "invalid request_id/track_id" }

// 500：临时错误（可重试）
{ "code": 2001, "message": "temporary error" }

curl 调试示例：

curl -X POST "https://official.example.com/api/partner/fulfillment/download-token" ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer <api_key>" ^
  -d "{\"partner_site_id\":12,\"request_id\":\"req_xxx\",\"track_id\":7617,\"qty\":1}"

签名与验签（可选，推荐）

用途：用于事件回传/下载授权等接口，防止参数被篡改。签名算法与字段拼接规则以合作阶段约定为准。

S1. 待签名字符串（示例）

partner_site_id=12&track_id=7617&request_id=req_20260317_xxx&event_id=evt_20260317_xxx

S2. 生成签名（Node.js 示例）

import crypto from "crypto";

function sign(payload, secret) {
  return crypto.createHmac("sha256", secret).update(payload, "utf8").digest("hex");
}

S3. 校验签名（PHP 示例）

<?php
function verifySign(string $payload, string $secret, string $sign): bool {
    $calc = hash_hmac('sha256', $payload, $secret);
    return hash_equals($calc, $sign);
}

建议：签名密钥与 push_api_key 分离，并支持轮换。

错误码与重试

重试策略与最大次数可在合作阶段确认。建议你们对同一 track_id 重复请求不产生副作用。

常见问题

Q：为什么会重复推送？
网络抖动/5xx 重试可能导致重复请求。请用 track_id 幂等处理。

Q：如何更新密钥？
支持轮换。建议实现“双密钥过渡期”，避免瞬时切换导致 401。

Q：你们是否支持回调？
可选能力：你们完成入库/上架后回调我们（需在合作阶段约定）。