欢迎使用花生壳开放 API！本手册将帮助您快速了解如何通过接口来管理您的花生壳映射（包括创建、查询、修改和删除等操作）。

一、 准备工作：身份认证（API Key）

在开始调用任何接口之前，您需要获取一个身份凭证（API Key），这就相当于您的“通行证”。
1.获取途径：登录 花生壳管理平台 ，进入 API keys 页面，创建一个新的 API Key 并获取密钥内容。
2.注意事项：由于密钥（Secret Key）只会在创建时显示一次，请务必将其妥善保管！
3.如何使用：在后续的所有接口请求中，您都需要在请求头（Header）中带上这个通行证。

基础调用信息：
●请求地址 (Base URL)： https://hsk-api.oray.com
●认证方式：在 Header 中添加字段Authorization: apikey 您的秘钥

二、 核心功能：映射管理

这里包含了您日常使用最频繁的映射操作接口。

1. 获取映射列表

作用：查看您当前账号下所有的映射配置。
●接口地址： GET /openapi/v2/mapping/list

请求示例:

响应示例：

2. 获取域名列表

作用：查看您账号下所有可用来做映射的域名列表。
●接口地址： GET /openapi/api/domain/list

请求示例:

响应示例：

3. 创建映射

作用：新建一条内网穿透映射。
●接口地址： POST /openapi/v2/mapping/create
核心请求参数说明：

参数名	含义	示例/说明
memo	映射备注	给这条映射起个名字，如：“我的办公电脑”
domain	域名	需使用您账号下已有的域名
fwtype	映射类型	1=TCP, 2=HTTP, 3=HTTPS, 4=UDP
port	外网端口	期望的外网访问端口（可先查询可用端口，见第三章节）
servicehost	内网IP	您本地服务器的 IP，如 127.0.0.1
serviceport	内网端口	您本地服务器的端口，如 3000
bandwidth	带宽	分配给该映射的带宽数值

**请求示例 (JSON 格式)**：

4. 更新映射

作用：修改已有映射的配置（如修改备注、内网IP或端口）。
使用说明：设置接口地址里的参数找到映射，更新为请求体里的数据。
●接口地址： PUT /openapi/v2/mappings/{domain}/{port}/{fwtype}

请求示例 (修改备注和内网端口)：

必填参数说明:
●memo (string, required): 映射备注/名称
●fwtype (integer, required): 映射类型 (1=TCP, 2=HTTP, 3=HTTPS, 4=UDP)

5. 停用 / 启用映射

作用：临时关闭或重新开启某条映射，而不删除它。
●接口地址： POST /openapi/api/mapping/{userid}/forbid/{switch}
●参数说明：
○{userid}: 您的用户 ID（可以从映射详情或服务信息接口中获取）
○{switch}: 填写 on 代表停用，填写 off 代表启用

请求示例：

响应：操作成功后无特定返回内容（204 No Content）。

6. 删除映射

作用：永久删除不需要的映射。
●标准接口： DELETE /openapi/v2/mappings/{domain}/{port}/{fwtype}
路径参数:
●domain: 域名
●port: 端口
●fwtype: 映射类型

请求示例:

三、 前置准备接口

在创建映射时，您可能不知道自己有哪些域名可用，或者想随机分配一个端口。您可以先调用以下接口获取必要的信息。

1. 查询账户服务信息

作用：查看您的内网穿透服务详情（包括剩余可用带宽、流量、映射数量限制、服务有效期等）。
●接口地址： GET /openapi/api/forward/service

请求示例:

响应示例（提取核心信息）：

2. 获取域名列表

作用：查看您账号下所有可用来做映射的域名列表。
●接口地址： GET /openapi/api/domain/list

请求示例:

响应示例（提取核心信息）：

3. 查询可用端口

作用：在创建映射前，检查某个外网端口是否可用（是否被占用或需要购买）。
●接口地址：GET /openapi/api/port/search?port={端口号}
● 实用技巧：如果指定的端口不可用或需要额外购买，您可以在创建映射时将 port 参数设置为 0，系统会自动为您随机分配一个可用端口。

CURL 示例:

**响应示例 (当端口不可用时)**：

四、 附录：常用代码与字段说明

1. 映射类型 (fwtype) 对照表

数值	代表的映射类型
1	TCP映射
2	HTTP映射
3	HTTPS映射
4	UDP映射

2. 常见状态/字段解释

●isforbid：映射是否被禁用（true 表示已停用，false 表示正常运行）
●servicehost / serviceport：内网服务主机 IP / 端口

3.响应字段说明

●memo: 映射备注/名称
●domain: 域名
●port: 外部端口
●servicehost: 内网服务主机
●serviceport: 内网服务端口
●basebandwidth: 基础带宽
●extrabandwidth: 额外带宽
●fwtype: 映射类型
●isforbid: 是否禁用
●speedtryrecord: 速度测试记录

4. 常见错误代码 (HTTP 状态码)

状态码	含义	解决建议
200	请求成功	操作已顺利完成
400	参数错误	请检查请求参数是否填写正确（如是否遗漏了必填项）
401	认证失败	请检查 API Key 是否正确或已过期
404	资源不存在	请求的域名、端口或接口地址可能有误
500	服务器内部错误	花生壳服务器出现异常，请稍后重试