📘 NewAPI 开发者文档
欢迎使用 NewAPI — 一个现代化、高性能的 RESTful API 平台。 无论您是构建电商应用、SaaS 工具还是移动端服务，NewAPI 都能为您提供稳定可靠的后端支持。
我们的 API 遵循 RESTful 设计规范，使用 JSON 进行数据交换， 并通过 Bearer Token 进行身份认证。基础 URL 如下：
🔐 认证方式
NewAPI 使用 API Key 进行认证。您可以在控制台面板中生成和管理您的 API 密钥。 所有请求都需要在 Header 中携带您的密钥。
请求头格式
测试环境请使用以 napi_sk_test_ 开头的测试密钥，
生产环境使用 napi_sk_live_ 开头的正式密钥。
👤 用户管理
用户资源相关的 API 端点，用于创建、查询、更新和删除用户。
返回所有用户的列表，支持分页和筛选。
查询参数
| 参数 | 类型 | 说明 |
|---|---|---|
page | integer | 页码，默认 1 |
limit | integer | 每页数量，默认 20，最大 100 |
status | string | 筛选状态：active / inactive |
响应示例
{
"id": "usr_8f7d3a2b",
"name": "张三",
"email": "zhangsan@example.com",
"status": "active",
"created_at": "2026-07-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 156,
"total_pages": 8
}
创建一个新的用户账户。
请求体参数
| 参数 | 类型 | 说明 |
|---|---|---|
name 必需 | string | 用户姓名，2-50 个字符 |
email 必需 | string | 邮箱地址，需唯一 |
phone | string | 手机号码（可选） |
role | string | 角色：member / admin，默认 member |
请求示例
{
"name": "李四",
"email": "lisi@example.com",
"role": "member"
}
响应 201 Created
"name": "李四",
"email": "lisi@example.com",
"role": "member",
"status": "active",
"created_at": "2026-07-17T08:15:22Z"
根据用户 ID 获取用户的详细信息。
路径参数
| 参数 | 类型 | 说明 |
|---|---|---|
id 必需 | string | 用户唯一标识，如 usr_8f7d3a2b |
响应示例
"name": "张三",
"email": "zhangsan@example.com",
"phone": "+86 138****1234",
"role": "admin",
"status": "active",
"created_at": "2026-07-15T10:30:00Z",
"updated_at": "2026-07-16T14:22:00Z"
📦 产品管理
产品资源相关的 API 端点，用于管理商品目录和库存。
返回所有产品，支持分类筛选、价格排序和关键词搜索。
| 参数 | 类型 | 说明 |
|---|---|---|
category | string | 按分类筛选 |
sort | string | 排序方式：price_asc / price_desc / newest |
search | string | 关键词搜索（产品名称和描述） |
page | integer | 页码 |
limit | integer | 每页数量 |
向目录中添加新产品。
| 参数 | 类型 | 说明 |
|---|---|---|
name 必需 | string | 产品名称 |
price 必需 | number | 价格（分），如 2999 表示 ¥29.99 |
stock | integer | 库存数量 |
description | string | 产品描述 |
🛒 订单管理
订单资源相关的 API 端点，用于处理购买流程和订单追踪。
返回订单列表，可按状态筛选。
| 参数 | 类型 | 说明 |
|---|---|---|
status | string | 订单状态：pending / paid / shipped / cancelled |
user_id | string | 按用户 ID 筛选 |
创建一个新订单。
| 参数 | 类型 | 说明 |
|---|---|---|
user_id 必需 | string | 下单用户 ID |
items 必需 | array | 订单商品列表，每项包含 product_id 和 quantity |
total_amount 必需 | number | 订单总金额（分） |
🔔 Webhooks
NewAPI 支持 Webhooks 机制，当特定事件发生时（如订单支付成功、用户注册等）， 我们会向您配置的 URL 发送 POST 请求通知。
事件类型
| 事件 | 说明 |
|---|---|
order.paid | 订单支付成功 |
order.shipped | 订单已发货 |
user.created | 新用户注册 |
user.updated | 用户信息更新 |
验证签名
每个 Webhook 请求都会在 Header 中包含 X-Signature 字段，
您应使用 Webhook Secret 验证该签名以确保请求来自 NewAPI。
📊 数据分析
获取业务数据的统计与分析报告。
返回关键业务指标，包括总收入、订单数、用户增长等。
"total_orders": 3421,
"total_users": 8920,
"growth_rate": 12.5
⚠️ 错误码说明
NewAPI 使用标准的 HTTP 状态码来表示请求结果。错误响应体包含详细的错误信息。
| 状态码 | 说明 |
|---|---|
200 | 请求成功 |
201 | 资源创建成功 |
400 | 请求参数错误 |
401 | 未认证或 API Key 无效 |
403 | 权限不足 |
404 | 资源未找到 |
429 | 请求频率超限 |
500 | 服务器内部错误 |
错误响应格式
"code": 400,
"message": "邮箱地址格式无效",
"field": "email"
}
⏱️ 速率限制
为保障服务稳定，NewAPI 对 API 请求实施速率限制。默认限制如下：
| 套餐 | 限制 |
|---|---|
| 免费版 | 每分钟 60 次请求 |
| 专业版 | 每分钟 600 次请求 |
| 企业版 | 每分钟 3000 次请求 |
当超出限制时，API 将返回 429 Too Many Requests。
响应头中包含 X-RateLimit-Remaining 表示剩余可用次数。
📝 更新日志
v2.1.0 — 2026-07-10
- ✨ 新增数据分析仪表盘端点
- 🔧 优化订单查询性能，响应速度提升 40%
- 🐛 修复用户邮箱更新时的验证问题
v2.0.0 — 2026-06-01
- 🚀 全新 v2 版本发布，API 路径迁移至
/v2 - 🔐 引入新的 API Key 格式
napi_sk_* - 📦 新增产品管理和订单管理模块