把商品侵权初筛接入ERP与批量流程

先读公开接口规范

SafeSell AI提供REST API介绍、OpenAPI规范和交互文档。接口可用范围由账号、密钥scope与当前服务决定；业务查询可能产生S算力消耗。

从无需密钥的健康检查开始

curl https://safesellai.com/api/v1/health

健康检查只验证服务状态，不验证某个业务端点、账号额度或检测结果。不要将密钥写进网页代码或公开仓库。

品牌与批量请求示例

POST /api/v1/check/brand
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"brand":"待核对品牌","category":"shoes","position":"brand_field"}

POST /api/v1/check/batch
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{"items":[{"word":"待核对品牌","position":"brand_field"}]}

示例仅说明请求形状，没有伪造成功响应或风险结论。批量接口使用 words 或 items，商品链接初筛使用独立的 /api/v1/check/link。返回字段、上限和费用请核对当前OpenAPI与操作规则。

侵权初筛API的输入、输出与认证

规范观察：2026-10-24 · OpenAPI 3.0.3 / 接口文档版本 1.1.0

下表转述当时可公开读取的规范，方便ERP开发者逐项核对。它是文档约定，不是带Key业务调用的验收报告；当前规范若有变化，以线上OpenAPI和账号实际权限为准。

各端点处理不同输入，不能相互代替
POST端点	规范输入	规范输出与缺口
`/api/v1/check/brand`	示例包含`brand`、`category`。	描述为风险结果；公开规范未给出完整逐字段成功响应schema，不在这里补造响应。
`/api/v1/check/batch`	`words`字符串数组，或`items`中的`word`与`position`；规范约定每次最多100项。position为`brand_field`、`title_first`、`title_other`或`user_query`。	描述为逐词风险；这是文字列表接口，不是Excel文件导入或批量图片接口。实际字段、对应关系和失败项须用获准的小批次保存返回核对。
`/api/v1/check/link`	`url`商品链接。	描述为商品及风险结果；该端点另列502抓取失败。链接可打开不代表抓取或筛查已完成。
`/api/v1/check/image`	`image_b64`或`image_url`；规范还列`own_brands`。URL有图床白名单条件，不能据此承诺接受任意链接。	规范描述`has_brand_element`、`suggestion`及texts、brand_hits等结果项。它们是品牌元素线索，不是图片版权授权或无侵权证明；本页没有该链路的成功实测。
`/api/v1/check/tro`	`brand`。	描述为相关历史记录命中；503 / `tro_data_unavailable`表示资料暂不可用，不是未发现记录。存在关联记录也不直接证明该商品受某份命令约束。

Bearer密钥与scope

这五个端点的公开规范均列write:check scope，使用Authorization: Bearer YOUR_API_KEY。密钥有效、scope足够和账号套餐符合要求分别核对；文档中的企业版说明不能代替当前账号授权。不要把真实密钥放在查询参数、浏览器前端代码、截图或公开示例中。

响应信封

规范概述成功信封为success: true并含data、meta；错误信封为success: false，含error.code、error.message，标准错误示例的meta.request_id用于关联请求。先保存HTTP状态，再按实际信封核对错误和业务结果；成功传输与业务风险结论分开处理。

计费与限流怎么核对

公开规范描述与网页账号共用S算力池，并对不同端点列出不同消耗及例外。批量词、商品链接、单图和案件查询不采用同一计费口径；规范中的某项0消耗也不表示全部接口、套餐或后续重试免费。操作前核对当前文档、账号、输入数量和可用余额，保存返回与实际扣费证据。本页没有执行收费业务或验证实际账单。

遇到429时读取实际Retry-After并限制重试次数；不要把公开默认限流写成账号固定额度。对可能已完成或扣费但响应丢失的请求，先核对状态与记录，避免盲目重复提交。

ERP应分别处理哪些接口错误

以下状态和错误名称来自所读公开规范；这不是本轮实际制造全部错误的测试结果。

HTTP / code	含义与处理
400 / `invalid_request`	核对输入、字段和类型，修正后再提交；不转换为低风险。
401 / `invalid_api_key`	缺少或无效密钥。停止无依据重试，核对密钥状态；本页下方已有无Key实际返回节选。
402 / `scoin_insufficient`	S算力不足；核对当前余额及使用记录，不能由集成脚本自行购买或充值。
403 / `insufficient_scope`、`plan_not_eligible`	权限或套餐条件不符，确认授权范围；反复换参数不解决权限问题。
429 / `rate_limit`	按实际Retry-After及服务限制进行有上限的退避，保留失败项。
502抓取失败；503 / `tro_data_unavailable`	前者在商品链接端点列出，后者在案件端点列出。保留资料缺失/未完成状态，不能记成未命中。
其它规范错误：`not_found`、`internal_error`、`upstream_error`	按实际HTTP状态、message与request_id定位；公开全局枚举与端点列表不是所有运行时错误的穷尽集合。

本页补充的是可检索的接口说明。健康200、规范可读、缺密钥401、品牌文字样例、图片成功、完整Excel导入导出和认证API成功是不同证据；没有执行的链路继续标为未验证。

ERP接入要处理的结果

保留请求中的店铺、SKU映射、返回状态和检查时间，避免错行和重复处理。
认证失败、权限不足、额度不足、限流、输入错误和超时分别处理；不能把失败当作低风险。
重试前确认前次是否完成或产生扣费；批量请求先从小批次验证。
风险结果先进入复核流程。发布、改价、库存或下架属于后续业务动作，分别授权。

团队复核流程 · 网页批量模式 · MCP与REST的区别

已取得哪些接入证据

观察日期：2026-10-24 · 使用生产公开入口，无API Key

请求	实际状态	能证明的范围
GET /api/v1/health	200	当时服务健康；不能证明某个业务查询成功或账号具有scope。
GET /api/v1/openapi.json	200	可以读取接口规范；不能代替执行验证。
GET /api/v1/balance（未发送密钥）	401 / invalid_api_key	该已知端点拒绝缺失密钥的请求；没有读取任何账户余额，也没有产生业务查询成功响应。

健康响应节选

{
  "success": true,
  "data": {
    "status": "ok",
    "version": "v1",
    "service": "safesellai-api",
    "time": "2026-10-24T08:24:49.889Z"
  }
}

缺少密钥的错误响应节选

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "API Key 缺失或格式无效（应为 Authorization: Bearer sk_live_xxx）"
  }
}

节选省略请求追踪ID。这里没有执行带Key的品牌、图片、批量、店铺检查或MCP业务调用，因此不宣称已验证其成功返回、scope或计费。本次两条品牌/标题输入的真实输出来自网页匿名链路，不能作为 /api/v1/check/batch 的响应样例。

正式接入先使用有权限的密钥核对scope、额度、成本和错误处理，在获准的小批次中保存实际请求与返回。不要把401、429、500或超时转换成“没有风险”，重试前确认前次是否已完成或扣费。