BBT打车 API 文档

简介

BBT打车API提供完整的打车服务接口，包括价格预估、订单管理、司机位置查询、司乘沟通等功能。

主要特点

• 简单认证：使用 X-API-Key Header 认证
• 统一接口：所有API采用统一的请求/响应格式
• 完整功能：覆盖从价格预估到订单完成的全流程

认证方式

API Key 认证

所有API请求需要在HTTP Header中携带 X-API-Key：

X-API-Key: your_api_key

请求格式

• 请求方法：POST
• Content-Type：application/json
• 字符编码：UTF-8

示例请求

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"bookingType": "1", "countryName": "香港", ...}' \
  https://your-api-host/api/estimatePrice

注意：如果服务端未配置 MIDDLEWARE_API_KEY 环境变量，则API Key认证将被跳过（适用于开发环境）。

响应格式

成功响应

{
  "success": true,
  "response": {
    "code": 200,
    "msg": "成功",
    "data": { ... }
  }
}

错误响应

{
  "error": "错误描述",
  "type": "ErrorType"
}

API 接口列表

一、商品类接口

1.1 价格预估 - estimatePrice

叫车预估费用，预估价格仅供参考，最终支付费用以实际产生费用为准。

请求路径：POST /api/estimatePrice

请求参数：

地址对象（departAddress/arriveAddress）结构：

请求示例：

{
  "bookingType": "1",
  "countryName": "香港",
  "countryId": "279",
  "departAddress": {
    "address": "香港-雅高工業大樓",
    "addressDetail": "香港-雅高工業大樓",
    "cityName": "香港",
    "latitude": "22.313832",
    "longitude": "114.196877",
    "cityId": "279"
  },
  "arriveAddress": {
    "address": "香港-天天洗衣",
    "addressDetail": "香港-天天洗衣",
    "cityName": "香港",
    "latitude": "22.318384",
    "longitude": "114.198753",
    "cityId": "279"
  }
}

响应示例：

{
  "success": true,
  "response": {
    "code": 200,
    "msg": "成功",
    "data": {
      "estimateId": "xxx",
      "priceList": [
        {
          "priceMark": "646b4a1857a3a349a3636a81",
          "carTypeName": "经济型",
          "estimatePrice": "50.00",
          "currency": "HKD"
        }
      ]
    }
  }
}

二、订单类接口

2.1 创建订单 - createOrder

用户根据需要发起叫车请求。

请求路径：POST /api/createOrder

请求参数：

请求示例：

{
  "priceMarks": ["646b4a1857a3a349a3636a81"],
  "passengerName": "张三",
  "passengerPhone": "13800138000",
  "passengerPhoneAreaCode": "+86",
  "contactName": "张三",
  "contactPhone": "13800138000"
}

响应示例：

{
  "success": true,
  "response": {
    "code": 200,
    "msg": "成功",
    "data": {
      "orderId": 100000030
    }
  }
}

2.2 订单详情 - queryOrderDetail

查询订单详细信息。

请求路径：POST /api/queryOrderDetail

请求参数：

请求示例：

{
  "orderId": 100000030
}

响应示例：

{
  "success": true,
  "response": {
    "code": 200,
    "msg": "成功",
    "data": {
      "orderId": 100000030,
      "orderStatus": 1,
      "passengerName": "张三",
      "passengerPhone": "13800138000",
      "departAddress": { ... },
      "arriveAddress": { ... },
      "driverInfo": { ... }
    }
  }
}

2.3 取消订单 - cancelOrder

取消订单。派单中可无偿取消，已派单可能收取取消费。

请求路径：POST /api/cancelOrder

请求参数：

请求示例：

{
  "orderId": 100000030,
  "force": true
}

2.4 订单取消原因 - cancelReason

提交订单取消原因。

请求路径：POST /api/cancelReason

请求参数：

请求示例：

{
  "orderId": 100000030,
  "reason": "不需要用车了"
}

三、司机类接口

3.1 司机实时位置 - queryDriverLocation

查询司机实时位置，适用于已派单和行进中状态定时查询。

请求路径：POST /api/queryDriverLocation

请求参数：

请求示例：

{
  "orderId": 100000030
}

响应示例：

{
  "success": true,
  "response": {
    "code": 200,
    "msg": "成功",
    "data": {
      "latitude": "22.313832",
      "longitude": "114.196877",
      "heading": 90,
      "speed": 30
    }
  }
}

3.2 司机评分 - orderScore

对司机服务进行评分，仅在订单结束后可进行评价。

请求路径：POST /api/orderScore

请求参数：

请求示例：

{
  "orderId": 100000030,
  "level": 5,
  "comment": "服务很好"
}

四、司乘沟通类接口

4.1 获取司乘沟通记录 - listMessages

获取订单的沟通消息记录。

请求路径：POST /api/listMessages

请求参数：

请求示例：

{
  "orderId": 100000030,
  "language": "zh"
}

4.2 发送消息 - postMessagest

发送消息给司机。

请求路径：POST /api/postMessagest

请求参数：

请求示例：

{
  "orderId": 100000030,
  "language": "zh",
  "text": "你好，请在大门口等我"
}

4.3 获取消息模板 - getTemplateChat

获取消息类型和模板列表。

请求路径：POST /api/getTemplateChat

请求参数：

请求示例：

{
  "orderId": 100000030,
  "language": "zh"
}

五、投诉类接口

5.1 投诉原因 - reason

查询投诉原因列表，会根据指定订单的不同场景返回不同的投诉选项。

请求路径：POST /api/reason

请求参数：

请求示例：

{
  "orderId": 100000030
}

5.2 乘客投诉 - complain

乘客发起投诉，一个订单只能投诉一次，不可重复投诉。

请求路径：POST /api/complain

请求参数：

请求示例：

{
  "orderId": 100000030,
  "type": 1,
  "mobileAreaCode": "+86",
  "mobile": "13800138000",
  "content": "司机态度不好"
}

六、Webhook 回调

6.1 支付通知回调 - paymentNotify

接收支付完成通知的Webhook端点。当订单支付状态发生变化时，系统会主动调用此接口。

请求路径：POST /api/webhook/paymentNotify

请求参数：

处理流程：

1. 验证请求有效性
2. 验证channelKey匹配
3. 如配置了 PAYMENT_NOTIFY_WEBHOOK_URL，将通知转发到该地址
4. 返回处理结果

响应格式：

成功：

{
  "code": 200,
  "msg": "成功",
  "data": null
}

验证失败：

{
  "code": 600,
  "msg": "验证失败",
  "data": null
}

6.2 订单状态变更推送 - UpdateOrderStatus

当订单状态发生变化时，平台会向您配置的回调地址发送请求。推送仅包含状态信息，完整订单信息请通过「订单详情」接口查询；新建订单首次回调状态为派单中（dispatching）。中间件支持 GET、POST、PUT、DELETE 方法接收并转发。

请求路径：POST /api/callback/UpdateOrderStatus

请求参数：

请求示例：

{
  "sign": "test",
  "orderId": "10000068",
  "orderStatus": "dispatched",
  "timestamp": "1000023586423",
  "channelKey": "123456789",
  "event": "booking.status.updated"
}

orderStatus 取值说明（附录B 状态定义）

回调中的 orderStatus 为字符串，可能取值如下（马上叫车状态）：

处理流程：

1. 接收平台回调请求
2. 若配置了 ORDER_STATUS_WEBHOOK_URL，则按相同 method 与 body 转发到该地址
3. 返回处理结果

响应格式：

成功：

{
  "code": 200,
  "msg": "成功",
  "data": null
}

事件说明（event）：

错误码说明

环境配置

服务通过环境变量进行配置：

附录

订单状态说明

预订类型说明

常用地区ID

更新日志

• v1.0.1 - 新增 6.2 订单状态变更推送（UpdateOrderStatus）Webhook 文档及 Postman 示例
• v1.0.0 - 初始版本，支持完整的打车API功能