销售统计系统 Web API 文档
基于ASP.NET Web API构建的后端接口服务
版本: v1.0.0
响应格式: JSON
跨域支持: 已启用
文档信息
基本信息
| 项目 | 说明 |
|---|---|
| API名称 | 销售统计系统 Web API |
| 版本 | v1.0.0 |
| 基础URL | https://localhost:44337/api/ (开发环境) |
| 响应格式 | JSON |
| 字符编码 | UTF-8 |
| 跨域支持 | 已启用 (CORS) |
提示: 所有API都支持跨域请求,可以直接在前端项目中调用。
通用约定
响应格式
所有API响应都遵循以下标准格式:
{
"Success": true, // 操作是否成功
"Message": "操作成功", // 操作消息
"Data": { ... }, // 返回的数据
"Timestamp": "2024-01-15 10:30:00" // 响应时间戳
}
错误响应
{
"Success": false,
"Message": "错误描述信息",
"Timestamp": "2024-01-15 10:30:00"
}
日期格式: 所有日期参数请使用
yyyy-MM-dd 格式,例如:"2024-01-15"
系统状态检查
GET
检查API状态
/api/test/ping
功能: 检查Web API服务是否正常运行
请求参数
无
响应示例
{
"Success": true,
"Message": "Web API 运行正常",
"Timestamp": "2026-02-09 11:26:49",
"Version": "1.0.0"
}
GET
回显测试
/api/test/echo/{text}
功能: 测试接口回显功能
路径参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | ✓ | 需要回显的文本 |
响应示例
{
"Success": true,
"Message": "回显成功",
"Original": "HelloWorld",
"Echo": "你输入的是: HelloWorld",
"Timestamp": "2026-02-09 11:27:36"
}
仪表板数据
GET
获取仪表板统计数据
/api/dashboard/stats
功能: 获取首页仪表板的关键统计数据
请求参数
无
响应字段说明
| 字段名 | 类型 | 说明 |
|---|---|---|
| TotalSales | decimal | 今日销售额 |
| TotalInventory | decimal | 库存进价金额 |
| TotalProfit | decimal | 今日毛利 |
| TotalDebt | decimal | 总欠款金额 |
响应示例
{
"Success": true,
"TotalSales": 123456.78,
"TotalInventory": 45678.90,
"TotalProfit": 23456.78,
"TotalDebt": 56789.12,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
门店管理
GET
获取门店列表
/api/stores/list
功能: 获取所有有效门店列表
请求参数
无
响应数据结构
{
"Success": boolean,
"Data": [
{
"id": number, // 门店ID
"name": string // 门店名称
}
],
"Count": number,
"Message": string,
"Timestamp": string
}
响应示例
{
"Success": true,
"Data": [
{"id": 1, "name": "北京分店"},
{"id": 2, "name": "上海分店"},
{"id": 3, "name": "广州分店"}
],
"Count": 3,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
供应商管理
GET
获取供应商分组列表
/api/suppliers/groups
功能: 获取供应商分组信息
请求参数
无
响应示例
{
"Success": true,
"Data": ["全部", "华北区", "华东区", "华南区"],
"Count": 4,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
小组管理
POST
获取小组列表
/api/groups/list
功能: 根据门店ID获取对应的小组列表
请求头
Content-Type: application/json
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| StoreId | integer | ✓ | 门店ID |
请求示例
{
"StoreId": 1
}
响应示例
{
"Success": true,
"Data": [
{"id": 1, "name": "销售一组"},
{"id": 2, "name": "销售二组"},
{"id": 3, "name": "售后组"}
],
"Count": 3,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
库存管理
POST
获取库存数据
/api/inventory/data
功能: 根据门店和截止日期获取库存统计
请求头
Content-Type: application/json
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| StoreId | integer | ✓ | 门店ID |
| EndDate | string | ✓ | 截止日期 (yyyy-MM-dd) |
请求示例
{
"StoreId": 1,
"EndDate": "2024-01-31"
}
响应数据结构
{
"Success": boolean,
"Data": [
{
"Group": string, // 小组名称
"Quantity": integer, // 数量
"CostAmount": decimal, // 进价金额
"SaleAmount": decimal // 卖价金额
}
],
"Count": number,
"Message": string,
"Timestamp": string
}
响应示例
{
"Success": true,
"Data": [
{
"Group": "销售一组",
"Quantity": 150,
"CostAmount": 45000.00,
"SaleAmount": 67500.00
}
],
"Count": 1,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
销售管理
POST
获取销售统计数据
/api/sales/total
功能: 获取销售统计数据,包括小组销售和其他相关数据
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| StoreId | integer | ✓ | 门店ID |
| StartDate | string | ✓ | 开始日期 (yyyy-MM-dd) |
| EndDate | string | ✓ | 结束日期 (yyyy-MM-dd) |
请求示例
{
"StoreId": 1,
"StartDate": "2024-01-01",
"EndDate": "2024-01-31"
}
此接口返回复杂数据结构,包含三部分数据:小组销售数据、其他数据、汇总数据。
响应示例(简化版)
{
"Success": true,
"GroupSales": [
{
"group": "销售一组",
"quantity": 120,
"amount": 36000.00,
"profit": 10800.00,
"profitRate": "30%"
}
],
"OtherData": {
"memberRecharge": 5000.00,
"rechargeGift": 500.00,
"storedValueConsume": 3000.00,
"pointsOffset": 200.00,
"manualDiscount": 800.00,
"fullReduction": 300.00
},
"Summary": {
"TotalQuantity": 120,
"TotalAmount": 36000.00,
"TotalProfit": 10800.00
},
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
POST
获取销售明细数据
/api/sales/detail
功能: 获取详细的销售明细数据
请求参数
| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|---|---|---|---|---|
| StoreId | integer? | 可选 | 门店ID | 0 |
| GroupId | integer? | 可选 | 小组ID | 0 |
| StartDate | string | ✓ | 开始日期 (yyyy-MM-dd) | - |
| EndDate | string | ✓ | 结束日期 (yyyy-MM-dd) | - |
响应示例
{
"Success": true,
"Data": [
{
"供应商": "XX供应商",
"商品名称": "商品A",
"销售": 50.00,
"采购价": "100.00",
"零售价": "150.00",
"会员价": "130.00",
"销售均价": 145.00,
"销售额": 7250.00,
"首批日期": "2024-01-10",
"首批数量": "100.00",
"库存": 50.00,
"标签备注": "热销商品",
"分店备注": "需补货",
"类别": "电子产品"
}
],
"Count": 1,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
欠款管理
POST
获取欠款统计数据
/api/debt/summary
功能: 获取供应商欠款统计数据
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| SupplierGroup | string | ✓ | 供应商分组 |
| StartDate | string | ✓ | 开始日期 (yyyy-MM-dd) |
| EndDate | string | ✓ | 结束日期 (yyyy-MM-dd) |
请求示例
{
"SupplierGroup": "全部",
"StartDate": "2024-01-01",
"EndDate": "2024-01-31"
}
注意: 此接口返回动态列结构,月份列会根据查询时间范围动态生成。
响应示例
{
"Success": true,
"Data": [
{
"供应商": "供应商A",
"分店名称": "北京分店",
"期初欠款": "10000.00",
"2024-01": "5000.00",
"2024-02": "3000.00",
"期末欠款": "18000.00",
"合计": ""
}
],
"ColumnOrder": [
"供应商",
"分店名称",
"期初欠款",
"2024-01",
"2024-02",
"期末欠款",
"合计"
],
"DynamicColumns": ["2024-01", "2024-02"],
"Count": 1,
"Message": "获取成功",
"Timestamp": "2024-01-15 10:30:00"
}
前端调用示例
JavaScript Fetch API 示例
1. 获取仪表板数据 (GET)
// 异步函数方式
async function getDashboardStats() {
try {
const response = await fetch('https://localhost:44337/api/dashboard/stats');
const data = await response.json();
if (data.Success) {
console.log('销售额:', data.TotalSales);
console.log('库存金额:', data.TotalInventory);
// 处理数据...
return data;
} else {
console.error('获取失败:', data.Message);
return null;
}
} catch (error) {
console.error('网络错误:', error);
return null;
}
}
// 调用示例
getDashboardStats().then(data => {
if (data) {
// 更新UI
document.getElementById('sales').textContent = '¥' + data.TotalSales.toFixed(2);
document.getElementById('inventory').textContent = '¥' + data.TotalInventory.toFixed(2);
}
});
2. 获取销售统计 (POST)
async function getSalesTotal(storeId, startDate, endDate) {
const response = await fetch('https://localhost:44337/api/sales/total', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
StoreId: storeId,
StartDate: startDate,
EndDate: endDate
})
});
const data = await response.json();
return data;
}
// 调用示例
getSalesTotal(1, '2024-01-01', '2024-01-31')
.then(result => {
if (result.Success) {
// 处理小组销售数据
result.GroupSales.forEach(group => {
console.log(`${group.group}: ${group.quantity}件, ¥${group.amount}`);
});
// 处理汇总数据
console.log(`总计: ${result.Summary.TotalQuantity}件, ¥${result.Summary.TotalAmount}`);
}
});
jQuery AJAX 示例
使用jQuery调用
// 获取门店列表
$.ajax({
url: 'https://localhost:44337/api/stores/list',
type: 'GET',
success: function(data) {
if (data.Success) {
// 填充下拉菜单
var select = $('#storeSelect');
select.empty();
data.Data.forEach(store => {
select.append(`<option value="${store.id}">${store.name}</option>`);
});
}
},
error: function(error) {
console.error('获取门店列表失败:', error);
}
});
// POST请求示例 - 获取小组列表
$('#storeSelect').change(function() {
var storeId = $(this).val();
$.ajax({
url: 'https://localhost:44337/api/groups/list',
type: 'POST',
contentType: 'application/json',
data: JSON.stringify({ StoreId: storeId }),
success: function(data) {
if (data.Success) {
// 处理小组数据
console.log('获取到', data.Count, '个小组');
}
}
});
});
重要: 在生产环境中,请将基础URL替换为实际的生产环境地址。
错误代码说明
| 错误情况 | 处理建议 |
|---|---|
| 网络连接失败 | 检查网络连接和API地址是否正确 |
| 返回 Success: false | 查看Message字段获取错误详情,根据错误信息调整请求 |
| 跨域错误 (CORS) | 确保API已正确启用CORS配置,检查请求头设置 |
| 参数格式错误 | 检查JSON格式是否正确,参数类型是否符合要求 |
| 日期格式错误 | 确保使用 yyyy-MM-dd 格式,例如:"2024-01-15" |
| 返回空数据 | 检查查询条件是否匹配数据库中的数据 |
| 数据库连接失败 | 检查数据库连接字符串,确保数据库服务正常运行 |
调试建议: 使用浏览器开发者工具的"网络"标签查看请求和响应详情,有助于快速定位问题。
部署说明
开发环境配置
- URL:
https://localhost:44337/api/ - 端口: 44337(根据实际运行端口调整)
- 数据库: 使用开发环境数据库连接字符串
生产环境部署
1. 修改前端配置
// 前端JavaScript配置
const API_CONFIG = {
// 开发环境
development: {
baseUrl: 'https://localhost:44337/api/'
},
// 生产环境
production: {
baseUrl: 'https://api.your-domain.com/api/'
}
};
// 根据环境使用不同的配置
const currentEnv = process.env.NODE_ENV || 'development';
const API_BASE_URL = API_CONFIG[currentEnv].baseUrl;
2. 配置生产环境连接字符串
<!-- Web.config -->
<connectionStrings>
<add name="MyConnectionString"
connectionString="Data Source=生产服务器IP;Initial Catalog=SalesDB;User ID=sa;Password=生产密码;Integrated Security=False;Connect Timeout=30"
providerName="System.Data.SqlClient" />
</connectionStrings>
IIS部署步骤
- 在IIS中创建新的应用程序池(.NET Framework 4.x,集成模式)
- 创建新的网站或应用程序,指向发布目录
- 配置正确的身份验证和权限
- 配置SSL证书(如果需要HTTPS)
- 测试API接口是否正常响应
安全建议: 生产环境建议启用HTTPS,限制CORS源,并配置适当的防火墙规则。