商业API接入说明

本文档用于说明商业 API 的接口认证方式、访问地址、调用示例、MCP 服务接入方式以及认证失败时的返回结构。

1. 接口认证说明

所有对外接口均需要进行认证。调用接口时，调用方需要在 HTTP 请求头中传入访问令牌。

请求头格式如下：

Authorization: <token>

其中：

<token> 表示调用方获得的有效访问令牌。

实际请求时不要携带尖括号 <>。

访问令牌需要放在 Authorization 请求头中。

正确示例：

Authorization: your_access_token

错误示例：

Authorization: <your_access_token>

2. 接口访问地址

API 路由前缀如下：

https://api.menglar.com/gateway/ozon-service/api/

调用具体接口时，需要在该路由前缀后拼接对应的接口路径。

例如，一级类目查询接口地址为：

https://api.menglar.com/gateway/ozon-service/api/v1/categories/level1/query

3. 调用示例

以下示例演示如何通过 curl 调用一级类目查询接口。

请将示例中的 your_access_token 替换为实际获得的访问令牌。

注意：请求令牌中不要携带 <> 符号。

4. MCP 服务地址

MCP 服务访问地址如下：

https://api.menglar.com/gateway/ai/mcp/ozon-mcp-service/mcp

MCP 请求连接协议为 streamable HTTP。

MCP 服务请求同样需要携带认证凭证，认证格式与 API 接口一致，推荐使用 Authorization 请求头传递访问令牌。

请求头格式如下：

Authorization: <token>

实际请求时请将 <token> 替换为有效访问令牌，并且不要携带尖括号 <>。

示例：

Authorization: your_access_token

对于不支持自定义请求头的 MCP 客户端，也支持通过 URL 查询参数传递访问令牌。

格式如下：

https://api.menglar.com/gateway/ai/mcp/ozon-mcp-service/mcp?key=token

示例：

https://api.menglar.com/gateway/ai/mcp/ozon-mcp-service/mcp?key=ACMA:XXXXXXXXXX

说明：

推荐优先使用 Authorization 请求头传递访问令牌。

当 MCP 客户端不支持设置请求头时，可以使用 ?key=your_access_token 的方式传递认证凭证。

key 参数的值仅填写访问令牌本身，不要添加尖括号 <>。

5. 认证失败说明

当出现以下情况时，接口会返回认证失败错误：

请求未携带访问令牌。

访问令牌无效。

访问令牌已过期。

调用方没有对应接口的访问权限。

认证失败时，接口会返回标准错误结构，示例如下：

{
  "success": false,
  "errorCode": "UNAUTHORIZED",
  "errorMessage": "Missing or invalid authentication credentials"
}

说明：

success：请求是否成功。

errorCode：错误码。

errorMessage：错误描述。

实际返回的 errorCode 和 errorMessage 以接口响应为准。

6. 接入注意事项

所有接口请求都必须携带有效的 Authorization 请求头。

Authorization 的值仅填写访问令牌本身，不要添加尖括号 <>。

MCP 服务推荐使用 Authorization 请求头认证；如果客户端不支持设置请求头，可以使用 ?key=your_access_token。

建议调用方妥善保存访问令牌，避免泄露。

如果接口返回认证失败，请优先检查令牌是否缺失、填写错误、过期或是否未启用凭证。

1. 接口认证说明#

2. 接口访问地址#

3. 调用示例#

4. MCP 服务地址#