← 返回子舟链

⛓️ 子舟链 API 文档

RESTful API 接口文档 · v1.1.2 · 2026-05-11

🔐 统一认证 (auth)

所有平台共享的统一认证接口，前缀 /api/auth

POST /api/auth/sms/send
发送手机验证码（60秒冷却，5分钟有效）
POST /api/auth/sms/login
手机号+验证码登录/注册（自动注册，platform: art/trace/points/clan）
POST /api/auth/email/login
邮箱+密码登录（platform参数必须）
POST /api/auth/email/register
邮箱+密码+用户名注册
POST /api/auth/email/send-code
发送邮箱验证码（绑定邮箱时使用）
POST /api/auth/forgot-password/sms
通过手机号重置密码（发送验证码）
POST /api/auth/reset-password
重置密码（手机号+验证码+新密码）
GET /api/auth/profile
获取用户资料（需Bearer Token）
POST /api/auth/bind-phone
绑定手机号（需验证码）
POST /api/auth/bind-email
绑定邮箱（需验证码）
POST /api/auth/unbind-phone
解绑手机号（需至少保留一种联系方式）
POST /api/auth/unbind-email
解绑邮箱
POST /api/auth/kyc/submit
提交KYC实名认证（姓名+身份证号，腾讯云人脸核身）
GET /api/auth/kyc/status
查询KYC认证状态
GET /api/auth/health
认证服务健康检查

🎨 数字藏品 (art)

数字藏品存证平台接口，前缀 /api

GET /api/health
平台健康检查
GET /api/chain/stats
链统计（区块高度、验证者数、存证数等）
POST /api/register
邮箱+密码注册（旧版，推荐用auth/email/register）
POST /api/login
邮箱+密码登录（旧版，推荐用auth/email/login）
GET /api/gallery
公开藏品馆（is_public=true & on_chain）
POST /api/submit
提交存证（需登录）
GET /api/verify/:hash
链上验证（V2优先，自动fallback legacy）
POST /api/file/hash
文件哈希计算（SHA-256 + SM3双哈希）
GET /api/certificate/:proof_id
生成PDF存证证书（WeasyPrint）
GET /api/admin/proofs
管理员存证列表（需admin Token）
POST /api/admin/proofs/batch-review
批量审核存证（approve/reject）
POST /api/admin/proofs/batch-on-chain
批量上链（最多50条）
GET /api/monitor/status
监控状态

🔍 链上溯源 (trace)

产品溯源平台接口，前缀 /api

GET /api/health
溯源服务健康检查
POST /api/auth/login
用户名+密码登录
POST /api/auth/register
用户注册
POST /api/enterprise/register
企业入驻（公司/个人）
GET /api/enterprise/me
我的企业信息
GET /api/enterprise/templates
行业模板列表（16个行业）
GET /api/verify/:batch_code
溯源验证（批次码）
GET /api/v1/qrcode/:batch_code
生成溯源二维码PNG

💎 链上积分 (points)

区块链积分联盟接口，前缀 /api/points

GET /api/points/health
积分服务健康检查
POST /api/points/sms/send
发送手机验证码
POST /api/points/user/login
手机号登录
POST /api/points/user/register
手机号注册
GET /api/points/shop/items
商城商品列表
GET /api/points/admin/stats
管理员统计（需admin Token）

📜 数字族谱 (genealogy)

数字族谱平台接口，前缀 /api

GET /api/health
族谱服务健康检查
GET /api/clans/public
公开族谱列表（无需登录）
GET /api/clans/
我的族谱列表（需登录）
POST /api/clans/
创建族谱
GET /api/gedcom/export/:clan_id
导出GEDCOM文件

📊 公共接口

GET /api/chain/stats
全局链统计（Portal专属，聚合所有平台数据）

🤖 AI 生成 (ai)

AI图像生成服务，前缀 /api/ai

POST /api/ai/generate
AI图像生成（支持中文prompt自动翻译）

参数：

响应： {"success": true, "image_url": "https://...", "translated_prompt": "..."}

🔗 溯源上链 (trace chain)

溯源记录提交到区块链，前缀 /api/v1

POST /api/v1/records/:id/submit-chain
将溯源记录提交到区块链存证
{"success": true, "tx_hash": "0x..."}

📜 族谱公开接口 (clan public)

无需登录的公开族谱查询，前缀 /api/clans

GET /api/clans/public
获取所有公开族谱列表（无需登录）
{"success": true, "clans": [...], "total": 4}

🔑 API Key 管理 (developer)

开发者API密钥管理，前缀 /api/auth/keys，需要JWT认证

GET /api/auth/keys
获取当前用户的API Key列表
{"success": true, "keys": [{"id": 1, "name": "...", "key_prefix": "zz_live_xxxx", "tier": "developer"}]}
POST /api/auth/keys
创建新的API Key

参数：

{"success": true, "key": "zz_live_xxxx...", "key_prefix": "zz_live_xxxx"}
GET /api/auth/keys/health
API Key服务健康检查（无需认证）
{"success": true, "service": "api-keys"}