接口概览

百万田园开放平台提供RESTful API接口，所有接口均通过HTTPS协议访问，返回JSON格式数据。

基础信息

项目	说明
接口协议	HTTPS
数据格式	JSON
字符编码	UTF-8
请求方式	GET/POST
Base URL	`https://api.baiwantianyuan.com/v1`

响应格式

所有API接口返回统一格式的JSON数据：

{
  "code": 200,           // 状态码
  "message": "success",  // 状态描述
  "data": {              // 业务数据
    // ...
  },
  "timestamp": 1708224000  // 时间戳
}

认证方式

所有API请求需要在Header中携带Access Token进行身份认证。

获取Access Token

POST /auth/token

请求参数

参数名	类型	必填	说明
app_key	string	是	应用Key
app_secret	string	是	应用密钥

请求示例

POST /auth/token
Content-Type: application/json

{
  "app_key": "your_app_key",
  "app_secret": "your_app_secret"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 7200,
    "token_type": "Bearer"
  }
}

使用Access Token

获取Token后，在后续API请求的Header中添加：

Authorization: Bearer {access_token}

获取水果列表

获取当季水果商品列表，支持分页和筛选。

GET /fruit/list

请求参数

参数名	类型	必填	说明
page	int	否	页码，默认1
limit	int	否	每页数量，默认20
category_id	int	否	分类ID
region_id	int	否	产区ID
is_monthly	int	否	是否本月推荐：0-否，1-是

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "阿克苏冰糖心苹果",
        "subtitle": "天山雪水灌溉 霜降后采摘",
        "cover": "https://...",
        "price": 68.00,
        "market_price": 98.00,
        "unit": "箱",
        "origin": "新疆阿克苏",
        "is_monthly": 1
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

获取水果详情

获取指定水果的详细信息，包括规格、口感、营养价值等。

GET /fruit/detail

请求参数

参数名	类型	必填	说明
id	int	是	水果ID

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "阿克苏冰糖心苹果",
    "subtitle": "天山雪水灌溉 霜降后采摘",
    "description": "...",
    "cover": "https://...",
    "images": ["...", "..."],
    "price": 68.00,
    "market_price": 98.00,
    "unit": "箱",
    "spec": "10斤装（约12-15个）",
    "origin": "新疆阿克苏",
    "season": "10月-次年2月",
    "taste": "脆甜多汁，糖度高",
    "nutrition": "富含维生素C、膳食纤维",
    "storage_method": "0-4℃冷藏保存",
    "shelf_life": "冷藏30天",
    "category": {
      "id": 4,
      "name": "仁果类"
    },
    "orchard": {
      "id": 1,
      "name": "阿克苏红旗坡苹果园"
    }
  }
}

创建订单

创建水果购买订单。

POST /order/create

请求参数

参数名	类型	必填	说明
items	array	是	商品列表 [{fruit_id, num}]
consignee	string	是	收货人姓名
mobile	string	是	联系电话
address	string	是	详细地址
remark	string	否	订单备注

请求示例

POST /order/create
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "items": [
    {"fruit_id": 1, "num": 2},
    {"fruit_id": 3, "num": 1}
  ],
  "consignee": "张三",
  "mobile": "13800138000",
  "address": "北京市朝阳区xxx街道xxx号",
  "remark": "请尽快发货"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "BW202402180001",
    "total_amount": 196.00,
    "pay_amount": 196.00,
    "create_time": "2024-02-18 10:00:00"
  }
}

查询物流

查询订单物流信息。

GET /logistics/query

请求参数

参数名	类型	必填	说明
order_sn	string	是	订单编号

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "BW202402180001",
    "company": "顺丰速运",
    "tracking_no": "SF1234567890",
    "status": 2,
    "status_text": "运输中",
    "trace_list": [
      {
        "time": "2024-02-18 16:00",
        "desc": "已发货，顺丰速运"
      },
      {
        "time": "2024-02-18 14:00",
        "desc": "已完成包装"
      },
      {
        "time": "2024-02-18 12:00",
        "desc": "水果已采摘"
      }
    ]
  }
}

错误码说明

错误码	说明	处理建议
200	请求成功	-
400	请求参数错误	检查请求参数是否符合要求
401	未授权	检查Access Token是否有效
403	禁止访问	检查API权限是否已申请
404	资源不存在	检查请求的资源ID是否正确
429	请求过于频繁	降低请求频率或申请更高配额
500	服务器内部错误	联系技术支持