Import

达人列表同步

企业自有 CRM、DMP、达人库可以通过 OpenAPI 把达人名单写入紫薯通告。写入后的达人进入企业达人库，后续由采集任务补齐昵称、头像、粉丝量、互动率、报价等公开或授权字段。

导入流程

企业系统生成达人列表，至少提供 platform 和 url。
调用 POST /open-api/bloggers/batch，建议带稳定 Idempotency-Key。
后端按平台 URL 解析规则提取 platformBloggerId。
按 organizationId + platform + platformBloggerId 幂等 upsert。
写入 OpenApiBloggerImportRun，返回新增、更新、失败和行级错误。
导入成功的达人进入企业达人库，后续采集任务会补齐缺失的公开或授权数据。

导入只表示名单写入成功，不代表采集完成。客户侧只需要关注导入批次结果和后续达人变更时间。

鉴权

达人列表导入使用企业级 ZSK_API_KEY。用于写入的 API Key 必须包含blogger:write 权限。

X-API-Key: zsk_xxx
Idempotency-Key: crm-import-20260518-001
Content-Type: application/json

企业为 LOCAL 模式时，所有 /open-api/* 写入和读取接口都会返回 403。

接口

Method	Path	说明
`POST`	`/open-api/bloggers`	单条导入或更新达人
`POST`	`/open-api/bloggers/batch`	批量导入或更新达人，单批最多 500 条
`POST`	`/open-api/bloggers/deactivate`	停用/归档达人，不物理删除历史数据
`GET`	`/open-api/import-runs`	导入批次列表
`GET`	`/open-api/import-runs/:id`	导入批次详情

Payload

V1 最小请求只要求 platform + url。其他字段均可选，且 priceJson / rawData 必须保持结构化对象。

POST /open-api/bloggers/batch
X-API-Key: zsk_xxx
Idempotency-Key: crm-import-20260518-001
Content-Type: application/json

{
  "sourceSystem": "brand-crm",
  "items": [
    {
      "platform": "PGY",
      "url": "https://www.xiaohongshu.com/user/profile/5fa1...",
      "externalId": "crm_123",
      "tags": ["美妆", "护肤"],
      "priceJson": {
        "imageText": 5000,
        "video": 12000
      }
    }
  ]
}

URL 解析

如果传入 platformBloggerId，优先按该值 upsert。
如果未传 platformBloggerId，后端按 platform + url 解析达人 ID。
PGY 支持蒲公英链接、小红书主页链接和 xhslink.com 短链。
短链会先展开再解析；展开失败且未传 ID 时返回行级错误。
URL host 与声明的 platform 不匹配时返回 PLATFORM_URL_MISMATCH。

响应

{
  "runId": "oir_xxx",
  "total": 100,
  "created": 20,
  "updated": 75,
  "failed": 5,
  "discardedFieldsByPlatform": {
    "PGY": ["unsupportedField"]
  },
  "errors": [
    {
      "index": 3,
      "platform": "PGY",
      "code": "SHORT_URL_EXPAND_FAILED",
      "message": "短链展开失败，请提供 platformBloggerId 或改传达人主页长链接"
    }
  ]
}

批次记录

每次导入会生成一条 OpenApiBloggerImportRun。客户可通过GET /open-api/import-runs 和GET /open-api/import-runs/:id 查看历史导入结果。

相同 Idempotency-Key 且请求体一致时，后端返回同一批次结果；如果 key 相同但请求体不同，会返回 409。