接入指南

完整的 6 步接入流程。按照以下步骤，从获取凭证到创建无人机配送订单。

1
获取凭证
2
注册回调
3
查询履约
4
创建订单
5
追踪订单
6
完成/取消

第一步：获取凭证

与 SP 签约后，您将获得以下凭证。

凭证说明
clientCode接入方唯一编码（如 shansong）
API Key接口调用凭证，通过 X-API-Key 请求头传递
Webhook Secret用于验证 Webhook 推送消息的 HMAC-SHA256 签名密钥

获取凭证后，调用以下接口验证连通性：

验证凭证bash
curl -X GET https://api.sp.airgoe.com/api/v2/client/profile \
  -H "X-API-Key: your_api_key_here"
响应示例json
{
  "success": true,
  "data": {
    "clientCode": "shansong",
    "clientName": "闪送",
    "status": "ACTIVE",
    "rateLimit": {
      "check": 60,
      "order": 30,
      "query": 120
    }
  }
}

第二步：注册回调

注册 Webhook 回调地址，后续 SP 会将订单状态变更推送到该地址。

注册 Webhookbash
curl -X POST https://api.sp.airgoe.com/api/v2/webhooks \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://api.example.com/webhooks/sp",
    "events": [
      "ORDER_CONFIRMED",
      "ORDER_PICKING",
      "ORDER_AIR_TRANSIT",
      "ORDER_DELIVERING",
      "ORDER_COMPLETED",
      "ORDER_CANCELLED",
      "ORDER_EXCEPTION"
    ],
    "secret": "whsec_your_webhook_secret_key"
  }'
响应示例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"
  }
}

Webhook 验证

注册成功后，SP 会发送一条验证请求确认回调地址可达。请确保您的接口返回 HTTP 200。

第三步：查询履约能力

创建订单前，先查询指定起终点是否支持无人机配送。

履约能力查询请求bash
curl -X POST https://api.sp.airgoe.com/api/v2/fulfillment/check \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {
      "name": "张三",
      "phone": "13800001111",
      "address": "杭州市西湖区XX路1号",
      "lat": 30.2741,
      "lng": 120.1551
    },
    "receiver": {
      "name": "李四",
      "phone": "13800002222",
      "address": "杭州市余杭区YY路2号",
      "lat": 30.2933,
      "lng": 120.0126
    },
    "cargo": {
      "name": "文件",
      "weight": 0.5,
      "length": 30,
      "width": 20,
      "height": 5,
      "category": "DOCUMENT"
    }
  }'
成功响应 (canFulfill: true)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": "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段骑手费" }
      ]
    },
    "eta": {
      "totalMinutes": 35,
      "segments": { "A": 12, "B": 15, "C": 8 }
    },
    "selectedRoute": {
      "originBas": { "id": "bas-001", "name": "西湖站" },
      "destBas": { "id": "bas-003", "name": "余杭站" },
      "distanceKm": 8.5
    }
  }
}

报价单有效期

quotationId 有效期为 5 分钟。过期后需重新查询履约能力才能创建订单。

您还可以查询附近的 BAS 站点，引导用户选择更优的取件/配送位置：

附近站点查询bash
curl -X GET "https://api.sp.airgoe.com/api/v2/stations/nearby?lat=30.2741&lng=120.1551&radiusKm=5" \
  -H "X-API-Key: your_api_key_here"

第四步：创建订单

拿到有效的 quotationId 后创建订单。订单自动确认并开始编排。

创建订单请求bash
curl -X POST https://api.sp.airgoe.com/api/v2/orders \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "quotationId": "QT20260310100001",
    "merchantOrderNo": "YOUR-ORDER-001",
    "notes": "请轻拿轻放"
  }'
响应示例 (HTTP 201)json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "orderNo": "SP20260310100001",
    "state": "CONFIRMED",
    "verificationCodes": {
      "pickupCode": "P-582716",
      "itemCode": "I-394821",
      "deliveryCode": "D-719463"
    },
    "estimatedDelivery": "2026-03-10T11:15:00.000Z",
    "pricing": {
      "totalAmount": 45.0,
      "currency": "CNY"
    },
    "createdAt": "2026-03-10T10:30:00.000Z"
  }
}

验证码说明

每个订单生成三组验证码：

  • P 码（取件码）：交给寄件人，A段骑手取件时验证
  • I 码（物品码）：贴在包裹上，全程跟随
  • D 码（配送码）：交给收件人，C段骑手配送时验证

第五步：追踪订单

两种方式追踪订单进度：主动查询和被动接收 Webhook 推送。

方式一：主动查询

实时追踪bash
curl -X GET https://api.sp.airgoe.com/api/v2/orders/SP20260310100001/tracking \
  -H "X-API-Key: your_api_key_here"
追踪响应json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "currentSegment": "B",
    "currentLocation": {
      "lat": 30.28,
      "lng": 120.08,
      "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": "BAS_RECEIVED", "timestamp": "2026-03-10T10:42:00.000Z", "description": "起点站收到货物" },
      { "event": "FLIGHT_DEPARTED", "timestamp": "2026-03-10T10:45:00.000Z", "description": "无人机已起飞" }
    ]
  }
}

方式二：Webhook 推送

SP 在订单状态变更时，向已注册的回调地址推送通知：

Webhook 推送示例json
{
  "eventType": "ORDER_AIR_TRANSIT",
  "orderId": "SP20260310100001",
  "orderNo": "SP20260310100001",
  "data": {
    "aggregatedState": "AIR_TRANSIT",
    "previousState": "PICKING",
    "flightId": "FL-20260310-001",
    "droneId": "D-001"
  },
  "timestamp": "2026-03-10T10:45:00.000Z",
  "signature": "sha256=abcdef1234567890..."
}

最佳实践

建议以 Webhook 作为主要通知渠道，主动查询作为补充（例如在地图上展示无人机实时位置）。

第六步：完成或取消

订单在收件人验证后自动完成。空中运输开始前可取消订单。

当C段骑手送达包裹且收件人通过 D 码验证后，订单状态变为 COMPLETED。

取消订单

取消订单请求bash
curl -X POST https://api.sp.airgoe.com/api/v2/orders/SP20260310100001/cancel \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "USER_REQUEST",
    "cancellationNote": "用户不再需要配送"
  }'
取消响应json
{
  "success": true,
  "data": {
    "orderId": "SP20260310100001",
    "state": "CANCELLED",
    "cancellation": {
      "refundAmount": 45.0,
      "refundPercent": 100,
      "cancelledAt": "2026-03-10T10:35:00.000Z",
      "reason": "USER_REQUEST"
    }
  }
}

取消规则

  • CONFIRMED / PICKING：可取消，全额退款
  • AIR_TRANSIT / DELIVERING：不可取消
  • EXCEPTION：视情况而定，需人工介入