接口文档

全部 9 个接口的完整参考文档。基础地址： https://api.sp.airgoe.com

查询接入方信息

查询您的账户信息，验证 API Key 是否有效。

GET/api/v2/client/profile
响应示例json
{
  "success": true,
  "data": {
    "clientCode": "shansong",
    "clientName": "闪送",
    "status": "ACTIVE",
    "rateLimit": {
      "check": 60,
      "order": 30,
      "query": 120
    },
    "contact": {
      "name": "张三",
      "phone": "138****8001"
    }
  }
}

错误码

HTTP错误码说明
401MISSING_API_KEY缺少 X-API-Key 请求头
401INVALID_API_KEYAPI Key 无效或已停用

注册 Webhook

注册或更新 Webhook 回调地址。SP 会将订单状态变更事件推送到该地址。

POST/api/v2/webhooks

请求参数

字段类型是否必填说明
callbackUrlString必填回调地址（必须为 HTTPS）
eventsString[]必填要订阅的事件类型列表
secretString必填HMAC-SHA256 签名密钥（至少 16 个字符）
请求体json
{
  "callbackUrl": "https://api.example.com/webhooks/sp",
  "events": [
    "ORDER_CONFIRMED",
    "ORDER_PICKING",
    "ORDER_AIR_TRANSIT",
    "ORDER_DELIVERING",
    "ORDER_COMPLETED",
    "ORDER_CANCELLED",
    "ORDER_EXCEPTION",
    "ORDER_FALLBACK_GROUND"
  ],
  "secret": "whsec_your_secret_key_here"
}

可订阅事件

ORDER_CONFIRMED, ORDER_PICKING, ORDER_AIR_TRANSIT, ORDER_DELIVERING, ORDER_COMPLETED, ORDER_CANCELLED, ORDER_EXCEPTION, ORDER_FALLBACK_GROUND
响应示例json
{
  "success": true,
  "data": {
    "webhookId": "WH-20260310-001",
    "callbackUrl": "https://api.example.com/webhooks/sp",
    "events": ["ORDER_CONFIRMED", "ORDER_PICKING", "..."],
    "status": "ACTIVE",
    "createdAt": "2026-03-10T10:00:00.000Z"
  }
}

错误码

HTTP错误码说明
400VALIDATION_ERROR参数无效（非 HTTPS 地址、密钥太短等）

履约能力查询

7 层多维评估，判断是否支持无人机配送。返回最优航线的报价和预估时间。

POST/api/v2/fulfillment/check

请求参数

字段类型是否必填说明
senderObject必填寄件人信息（name、phone、address、lat、lng）
sender.nameString必填寄件人姓名
sender.phoneString必填寄件人手机号
sender.addressString必填寄件人地址
sender.latNumber必填纬度（-90 到 90）
sender.lngNumber必填经度（-180 到 180）
receiverObject必填收件人信息（结构同 sender）
receiver.nameString必填收件人姓名
receiver.phoneString必填收件人手机号
receiver.addressString必填收件人地址
receiver.latNumber必填纬度（-90 到 90）
receiver.lngNumber必填经度（-180 到 180）
cargoObject必填货物信息
cargo.nameString必填货物名称
cargo.weightNumber必填重量，单位 kg（精度 0.1）
cargo.lengthNumber必填长度，单位 cm
cargo.widthNumber必填宽度，单位 cm
cargo.heightNumber必填高度，单位 cm
cargo.categoryString可选DOCUMENT | FOOD | MEDICINE | ELECTRONICS | CLOTHING | OTHER
serviceLevelString可选EXCLUSIVE | EXPRESS | STANDARD（默认）| ECONOMY
请求体json
{
  "sender": {
    "name": "张三",
    "phone": "13800138001",
    "address": "朝阳区望京SOHO",
    "lat": 39.996,
    "lng": 116.481
  },
  "receiver": {
    "name": "李四",
    "phone": "13800138002",
    "address": "朝阳区大望路万达广场",
    "lat": 39.921,
    "lng": 116.486
  },
  "cargo": {
    "name": "文件",
    "weight": 2.5,
    "length": 30,
    "width": 20,
    "height": 10,
    "category": "DOCUMENT"
  },
  "serviceLevel": "STANDARD"
}

失败响应 (canFulfill: false)

失败响应json
{
  "success": true,
  "data": {
    "canFulfill": false,
    "failReasons": [
      {
        "layer": "L2",
        "code": "CARGO_OVERWEIGHT",
        "message": "货物重量 3.5kg 超出限制 2.7kg",
        "suggestion": "超重 0.8kg，建议走地面配送或拆分包裹"
      }
    ]
  }
}
响应示例json
{
  "success": true,
  "data": {
    "canFulfill": true,
    "quotationId": "QT20260310100001",
    "validUntil": "2026-03-10T10:35:00.000Z",
    "pricing": {
      "totalAmount": 45.0,
      "currency": "CNY",
      "breakdown": [
        { "type": "BASE_FEE", "amount": 20.0, "description": "基础费（3km 5kg 以内）" },
        { "type": "DISTANCE_FEE", "amount": 5.25, "description": "距离附加费" },
        { "type": "SEGMENT_A_FEE", "amount": 8.0, "description": "A段骑手费" },
        { "type": "FLIGHT_FEE", "amount": 25.0, "description": "B段空中运输费" },
        { "type": "SEGMENT_C_FEE", "amount": 8.0, "description": "C段骑手费" },
        { "type": "BAS_SERVICE_FEE", "amount": 6.0, "description": "BAS 站点服务费" },
        { "type": "PLATFORM_FEE", "amount": 3.0, "description": "低空服务费" },
        { "type": "INSURANCE_FEE", "amount": 1.0, "description": "货物保险费" }
      ]
    },
    "eta": {
      "totalMinutes": 35,
      "segments": { "A": 12, "B": 15, "C": 8, "basProcessing": 0 }
    },
    "selectedRoute": {
      "originBas": { "id": "bas-001", "name": "望京站" },
      "destBas": { "id": "bas-003", "name": "朝阳站" },
      "routeId": "RT-001-003",
      "distanceKm": 8.5
    }
  }
}

错误码

HTTP错误码说明
400VALIDATION_ERROR请求参数校验失败
400CARGO_OVERWEIGHT货物重量超出机队最大载荷（2.7kg）
400CARGO_OVERSIZE货物尺寸超出机队最大货舱（40x30x25cm）
422NO_FULFILLMENT_AVAILABLE全部 7 层评估均不通过，无可用航线
503SERVICE_UNAVAILABLE下游平台（OP/BAS/RP）不可用

附近站点

查询指定坐标附近的可用 BAS 站点。可用于引导用户选择更优的取件/配送位置。

GET/api/v2/stations/nearby

查询参数

字段类型是否必填说明
latNumber必填纬度（-90 到 90）
lngNumber必填经度（-180 到 180）
radiusKmNumber可选搜索半径，单位 km（默认 5，最大 20）
响应示例json
{
  "success": true,
  "data": [
    {
      "id": "bas-001",
      "stationCode": "WJ-001",
      "name": "望京 BAS 站",
      "address": "朝阳区望京SOHO T3",
      "lat": 39.9875,
      "lng": 116.4678,
      "distanceKm": 1.2,
      "status": "OPEN",
      "availableSlots": 15
    },
    {
      "id": "bas-002",
      "stationCode": "JXQ-001",
      "name": "酒仙桥 BAS 站",
      "address": "朝阳区酒仙桥路4号",
      "lat": 39.978,
      "lng": 116.492,
      "distanceKm": 2.8,
      "status": "OPEN",
      "availableSlots": 8
    }
  ]
}

错误码

HTTP错误码说明
400VALIDATION_ERROR坐标无效或 radiusKm 超过 20

创建订单

使用有效的 quotationId 创建配送订单。订单自动确认并立即开始编排。

POST/api/v2/orders

请求参数

字段类型是否必填说明
quotationIdString必填履约能力查询返回的报价单 ID
merchantOrderNoString可选您的订单参考号（最多 64 个字符）
notesString可选配送备注（最多 200 个字符）
callbackUrlString可选为该订单覆盖默认 Webhook 回调地址
请求体json
{
  "quotationId": "QT20260310100001",
  "merchantOrderNo": "YOUR-ORDER-001",
  "notes": "请轻拿轻放"
}

幂等性

通过 X-Idempotency-Key 请求头（UUID v4）防止重复创建订单。 24 小时内相同 Key 返回相同响应。
响应示例json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "orderNo": "SP20260310100001",
    "state": "CONFIRMED",
    "verificationCodes": {
      "pickupCode": "P-582716",
      "itemCode": "I-394821",
      "deliveryCode": "D-719463"
    },
    "estimatedDelivery": "2026-03-10T11:05:00.000Z",
    "pricing": {
      "totalAmount": 45.0,
      "currency": "CNY"
    },
    "route": {
      "originBas": { "id": "bas-001", "name": "望京站" },
      "destBas": { "id": "bas-003", "name": "朝阳站" }
    },
    "createdAt": "2026-03-10T10:30:00.000Z"
  }
}

错误码

HTTP错误码说明
400VALIDATION_ERROR请求参数校验失败
400QUOTATION_EXPIRED报价单已过期（超过 5 分钟）
400QUOTE_MISSING_SNAPSHOT报价单缺少请求快照，需重新查询
409QUOTATION_USED报价单已被使用
409IDEMPOTENCY_CONFLICT幂等键已存在但请求体不同

订单详情

查询订单完整信息，包括聚合状态、分段进度、验证码、预估时间和费用。

GET/api/v2/orders/:orderId

路径参数

字段类型是否必填说明
orderIdString必填SP 订单 ID（路径参数）
响应示例json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "orderNo": "SP20260310100001",
    "merchantOrderNo": "YOUR-ORDER-001",
    "aggregatedState": "AIR_TRANSIT",
    "stateDescription": "空中运输中",
    "sender": { "name": "张三", "phone": "138****8001", "address": "望京SOHO" },
    "receiver": { "name": "李四", "phone": "138****8002", "address": "万达广场" },
    "cargo": { "name": "文件", "weight": 2.5 },
    "pricing": { "totalAmount": 45.0, "currency": "CNY", "paid": true },
    "eta": { "estimatedDelivery": "2026-03-10T11:05:00.000Z", "remainingMinutes": 25 },
    "verificationCodes": {
      "pickupCode": { "code": "P-582716", "verified": true },
      "itemCode": { "code": "I-394821", "verified": false },
      "deliveryCode": { "code": "D-719463", "verified": false }
    },
    "segments": [
      { "type": "A", "label": "地面取件", "status": "COMPLETED",
        "from": "望京SOHO", "to": "望京 BAS" },
      { "type": "B", "label": "空中运输", "status": "IN_PROGRESS",
        "from": "望京 BAS", "to": "朝阳 BAS", "progress": 65 },
      { "type": "C", "label": "地面配送", "status": "PENDING",
        "from": "朝阳 BAS", "to": "万达广场" }
    ],
    "createdAt": "2026-03-10T10:30:00.000Z",
    "updatedAt": "2026-03-10T10:45:00.000Z"
  }
}

错误码

HTTP错误码说明
404ORDER_NOT_FOUND订单不存在

订单列表

分页查询订单列表，支持按状态、日期范围和关键词筛选。

GET/api/v2/orders

查询参数

字段类型是否必填说明
pageNumber可选页码，从 1 开始（默认：1）
pageSizeNumber可选每页条数，1-100（默认：20）
stateString可选按聚合状态筛选
startDateString可选起始日期（ISO 8601），包含
endDateString可选结束日期（ISO 8601），包含
searchString可选按 orderNo 或 merchantOrderNo 搜索
响应示例json
{
  "success": true,
  "data": [
    {
      "orderId": "SP20260310100001",
      "orderNo": "SP20260310100001",
      "aggregatedState": "AIR_TRANSIT",
      "stateDescription": "空中运输中",
      "sender": { "name": "张三", "address": "望京SOHO" },
      "receiver": { "name": "李四", "address": "万达广场" },
      "pricing": { "totalAmount": 45.0, "currency": "CNY" },
      "createdAt": "2026-03-10T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "pageSize": 20,
    "totalPages": 8
  }
}

错误码

HTTP错误码说明
400VALIDATION_ERROR查询参数无效（如 pageSize 超过 100）

取消订单

取消订单。仅在空中运输开始前（CONFIRMED 或 PICKING 状态）可取消。

POST/api/v2/orders/:orderId/cancel

请求参数

字段类型是否必填说明
reasonString必填USER_REQUEST | MERCHANT_REQUEST | PAYMENT_TIMEOUT | ADDRESS_ERROR | DUPLICATE_ORDER | OTHER
cancellationNoteString可选补充说明（最多 500 个字符）
请求体json
{
  "reason": "USER_REQUEST",
  "cancellationNote": "用户不再需要配送"
}

取消规则

当前状态可取消退款
CONFIRMED是全额退款
PICKING是全额退款
AIR_TRANSIT否-
DELIVERING否-
EXCEPTION视情况而定人工协商
响应示例json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "state": "CANCELLED",
    "cancellation": {
      "refundAmount": 45.0,
      "refundPercent": 100,
      "cancelledAt": "2026-03-10T10:35:00.000Z",
      "reason": "USER_REQUEST"
    }
  }
}

错误码

HTTP错误码说明
400VALIDATION_ERROR请求参数校验失败
400ORDER_CANNOT_CANCEL当前订单状态不允许取消
404ORDER_NOT_FOUND订单不存在

订单追踪

实时追踪信息，包括当前位置、预估到达时间和配送时间线。

GET/api/v2/orders/:orderId/tracking

路径参数

字段类型是否必填说明
orderIdString必填SP 订单 ID（路径参数）

各配送段位置数据来源

配送段数据源说明
A段（地面取件）RP 平台骑手 GPS 定位
B段（空中运输）OP 平台无人机位置 + 高度
C段（地面配送）RP 平台骑手 GPS 定位
响应示例json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "currentSegment": "B",
    "currentLocation": {
      "lat": 39.95,
      "lng": 116.483,
      "altitude": 120,
      "updatedAt": "2026-03-10T10:52:00.000Z"
    },
    "eta": {
      "remainingMinutes": 13,
      "estimatedArrival": "2026-03-10T11:05:00.000Z"
    },
    "timeline": [
      { "event": "ORDER_CREATED", "timestamp": "2026-03-10T10:30:00.000Z", "description": "订单已创建" },
      { "event": "RIDER_ACCEPTED", "timestamp": "2026-03-10T10:32:00.000Z", "description": "A段骑手已接单" },
      { "event": "RIDER_ARRIVED_PICKUP", "timestamp": "2026-03-10T10:35:00.000Z", "description": "骑手已到达取件地点" },
      { "event": "PICKUP_VERIFIED", "timestamp": "2026-03-10T10:38:00.000Z", "description": "取件已验证（P 码）" },
      { "event": "BAS_RECEIVED", "timestamp": "2026-03-10T10:42:00.000Z", "description": "起点站收到货物" },
      { "event": "CARGO_LOADED", "timestamp": "2026-03-10T10:44:00.000Z", "description": "货物已装载至无人机" },
      { "event": "FLIGHT_DEPARTED", "timestamp": "2026-03-10T10:45:00.000Z", "description": "无人机已起飞" }
    ]
  }
}

错误码

HTTP错误码说明
404ORDER_NOT_FOUND订单不存在