API接口文档

完整的REST API接口文档，支持开发者快速集成活牛采购系统

RESTful API
JWT认证
JSON格式
API信息

基础URL:
https://api.niumall.com/v1

版本: v1.0

认证: Bearer Token

接口分类
概述 认证授权 用户管理 订单管理 供应商管理 运输管理 财务管理 错误处理

API概述

活牛采购智能数字化系统提供完整的REST API接口，支持开发者快速集成和自定义开发。

快速开始

所有API请求都需要使用HTTPS协议，并在请求头中包含有效的JWT Token。

curl -X GET "https://api.niumall.com/v1/orders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
响应格式

所有API响应都使用JSON格式，并遵循统一的响应结构：

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": "2024-01-20T12:00:00Z"
}

认证授权

POST /auth/login 用户登录
请求参数
参数名 类型 必填 说明
username string 是 用户名或手机号
password string 是 密码
请求示例
{
  "username": "admin@example.com",
  "password": "password123"
}
响应示例
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin"
    }
  },
  "message": "登录成功"
}

订单管理

GET /orders 获取订单列表
查询参数
参数名 类型 必填 说明
page integer 否 页码，默认1
limit integer 否 每页数量，默认20
status string 否 订单状态筛选
响应示例
{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 1,
        "order_no": "ORD20240120001",
        "supplier_id": 101,
        "supplier_name": "山东畜牧合作社",
        "cattle_count": 50,
        "total_weight": 25000,
        "unit_price": 28.5,
        "total_amount": 712500,
        "status": "shipping",
        "created_at": "2024-01-20T10:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 100
    }
  },
  "message": "获取成功"
}
POST /orders 创建新订单
请求参数
参数名 类型 必填 说明
supplier_id integer 是 供应商ID
cattle_breed string 是 牛种类型
cattle_count integer 是 牛只数量
expected_weight decimal 是 预期重量(kg)
unit_price decimal 是 单价(元/kg)
请求示例
{
  "supplier_id": 101,
  "cattle_breed": "西门塔尔",
  "cattle_count": 30,
  "expected_weight": 15000,
  "unit_price": 28.5,
  "delivery_address": "北京市朝阳区xx养殖场",
  "expected_delivery_date": "2024-01-25"
}

错误处理

API使用标准HTTP状态码来表示请求的成功或失败状态。

HTTP状态码
状态码 说明
200 请求成功
201 创建成功
400 请求参数错误
401 未授权，需要登录
403 禁止访问，权限不足
404 资源不存在
500 服务器内部错误
错误响应格式
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求参数验证失败",
    "details": [
      {
        "field": "cattle_count",
        "message": "牛只数量必须大于0"
      }
    ]
  },
  "timestamp": "2024-01-20T12:00:00Z"
}