Shipping Partner API · v1

Pigee Shipping Partner API

通过单一REST API，将实时多承运人全球配送、自动化报关、实时追踪和款项收取功能集成到您的系统中。适用于货运代理、3PL、电商平台和自定义履行集成。

REST
JSON
190+ 国家
200+ 承运人
135+ 货币
获取API密钥 → 打开Postman沙箱 预约演示
⚡

实时多承运商费率

DHL、FedEx、UPS、Aramex、Parcelforce及200多家本地快递，一次POST请求搞定。返回排序后的运费，包含运输时间和完税价格。

🤖

AI报关自动化

从产品目录自动分类HS编码。商业发票、报关单和关税按目的地计算。

💳

Pigee Pay收款

分享付款链接或嵌入结账界面。以135多种货币从终端客户处收款，并以本地货币结算至您的银行账户。

📡

实时Webhook

接收 shipment.created, payment.received, parcel.delivered 及更多事件实时推送到您的端点。

🏷️

标签与发票

订单创建时自动生成PDF标签和商业发票。无需访问承运商门户。

💰

自定义服务费

在Pigee基础运费基础上，按承运商、按路线或全局添加您自己的百分比或固定费用。

快速入门

从创建账户到您的首个实时发货，仅需一小时以内。按以下五个步骤操作：

  1. 在 account.pigeepost.com 创建免费的Pigee账户，并选择 配送合作伙伴 作为您的账户类型。
  2. 转到 控制面板 → 开发者 → API密钥 并生成一个正式密钥和一个测试密钥。
  3. 选择您的付款方式： Pigee Pay 或 Pigee账户余额.
  4. 在 控制面板 → 费用.
  5. 配置您的服务费。导入 Postman集合 进行预发布开发。
💡
提示： Postman沙箱镜像生产环境，包含合成承运商、关税事件和付款。不会产生实际费用。

身份验证

每个请求都必须在 Authorization 标头中包含您的API密钥，以 Bearer 令牌。密钥映射到您的合作伙伴账户，包含您的费率配置和付款方式。

HTTP 请求头
Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

密钥类型

前缀环境说明
pgk_live_…LIVE实际货物和实际费用。
pgk_test_…TEST仅限沙箱环境。无任何费用，模拟运力商响应，适用于 CI/CD。
⚠️
安全性： 切勿在客户端或公开仓库中公开您的 API 密钥。如密钥泄露，请立即从仪表板重新生成。

环境和基础 URL

生产环境https://api.pigeepost.comLIVE
沙箱环境https://sandbox.api.pigeepost.comTEST

沙箱是生产环境的完整 1:1 镜像。通过切换密钥前缀切换环境，或使用显式沙箱 URL 以保持清晰。

ℹ️
API 版本： 所有端点目前在 v1上。版本是路径的一部分： /api/v1/….

SDK 和库

官方 SDK 使用类型化模型、自动重试和沙箱助手来包装 REST API。

🟨 JavaScript / Node.js
🐍 Python
🐘 PHP
📱 iOS Swift
🤖 Android Kotlin
🛒 WooCommerce 插件
🛍️ Shopify 应用
📮 Postman集合

验证 API 密钥

在上线前调用此端点来确认您的 API 密钥处于活跃状态且配置正确。

POST/api/v1/store/valid200 OK
验证您的 API 密钥并返回合作伙伴账户详情。
请求
POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}
响应 200
{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

获取运费

获取货物的实时承运人运费。返回所有可用服务，按价格排序，包括预计送达时间、保价支持和最终成本。

POST/api/v1/store/order/getcarriercost200 OK
返回可用承运人选项的数组，包括定价、送达时间估计和一个 carrier_request_id 用于创建订单。
请求正文
{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}
响应 200
{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

请求参数

字段类型必需说明
shop_url字符串必需您的店铺或平台网址。
currency字符串必需ISO 4217 货币代码。
parcel.type字符串必需Box | Bag | Tube | Pallet
parcel.boxsize整数必需尺寸等级 1 至 6。
weight.value数字必需包裹的实际重量。
weight.units字符串必需kg | lbs
尺寸对象可选长度、宽度、高度和单位。
address.pickup对象必需寄件人地址。
address.destination对象必需收件人地址。

创建订单

使用以下方式创建 Pigee 订单 carrier_request_id 来自运费端点。Pigee 生成标签、商业发票，如果使用 Pigee Pay，则生成托管支付链接。

ℹ️
付款方式 在您的仪表板中设置，而不是在此请求中设置。
POST/api/v1/store/order/create200 OK
创建一个发货并返回 Pigee 订单 ID、标签 URL 和所需的托管支付链接。
请求正文
{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}
响应 200
{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

履行订单

支付确认后发送最终履行详情。Pigee 生成运输标签、预订承运商并返回跟踪号。

POST/api/v1/store/order/fulfill200 OK
触发标签生成和承运商预订。
请求正文
{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}
响应 200
{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

追踪

检索通过 API 创建的任何发货的实时跟踪事件。

GET/api/v1/tracking/{pigee_order_id}200 OK
返回发货的标准化跟踪历史记录。
响应 200
{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

支付方式

Pigee 支持两种付款方式。活跃模式在您的合作伙伴仪表板中设置，适用于所有订单。

模式工作原理最适合
Pigee PayPigee 托管一个结账页面。订单创建返回一个 payment_url.电商和市场集成。
账户余额运费将从您的Pigee预存余额中扣除。货运代理、3PL和高量级合作伙伴。

服务费

作为运输合作伙伴，您可以在Pigee基础承运人费率之上添加自己的费用。费用在您的仪表板中配置，并在返回费率前自动应用。

  • 百分比费用： 按基础承运人成本的百分比计算。
  • 固定费用： 每票货物增加的固定金额。
  • 航线特定覆盖： 为特定的始发地/目的地对覆盖全局费用。

结算与外汇

Pigee Pay可从最终客户收取 135+种货币 并以您当地货币结算到您的银行账户。

  • 结算周期通常为货物交付确认后的T+2个工作日。
  • 通过仪表板从您的Pigee余额提现。
  • 详细交易日志可查看 财务 → 结算.
  • 已结算交易的发票自动生成，可用PDF格式获取。

Webhook

Pigee将实时事件作为JSON推送至您的HTTPS端点 POST 请求。在以下位置配置您的webhook URL 仪表板 → 开发者 → Webhooks.

示例webhook有效载荷
{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Webhook事件参考

shipment.created订单已确认，承运人已预订，标签已生成。shipment
payment.received客户完成了Pigee Pay。payment
payment.failedPigee Pay结账已过期或被拒绝。payment
parcel.collected快递公司已从寄件人处取件。tracking
parcel.in_transit包裹已在转运中心扫描。tracking
parcel.customs_hold包裹被海关扣留。customs
parcel.customs_cleared海关清关完成。customs
parcel.out_for_delivery包裹已装上最后一英里配送车辆。tracking
parcel.delivered已确认送达。tracking
parcel.delivery_failed配送尝试失败。tracking
parcel.returned包裹已退回寄件人。tracking
settlement.completed资金已结算至您的银行账户。payment

Webhook 签名

每个 webhook 请求都包含一个 X-Pigee-Signature 标头，是原始请求体的 HMAC-SHA256 摘要。处理前务必验证此签名。

Node.js 验证示例
// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}
⚠️
使用 时间安全比较 以防止时序攻击。拒绝任何签名不匹配的 webhook。

错误

所有错误都返回 JSON，包含一个 error 对象，包含机器可读的 code 和人类可读的 message.

错误响应
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}
HTTP错误代码含义及解决方案
400INVALID_REQUEST字段缺失或格式错误。
401INVALID_API_KEY密钥缺失、格式错误或已撤销。
402INSUFFICIENT_BALANCE账户余额不足。
403FORBIDDEN账户类型无权访问此端点。
404ORDER_NOT_FOUND找不到指定ID的订单。
409ORDER_ALREADY_FULFILLED订单已履行。
422INVALID_ADDRESS地址无法验证。
422CARRIER_UNAVAILABLE此路线无可用的运输商服务。
422RATE_EXPIREDcarrier_request_id 已过期。请重新获取运费。
429RATE_LIMITED请求过于频繁。请稍候后重试。
500INTERNAL_ERRORPigee端错误。请使用指数退避法重试。
503CARRIER_TIMEOUT下游运输商API超时。

速率限制

速率限制按API密钥应用，并根据您的账户等级调整。

账户等级请求/分钟请求/天
免费测试601,000
配送合作伙伴上线30050,000
企业版自定义自定义

触发速率限制时，API 返回 HTTP 429 和 Retry-After 标头

数据类型与约定

  • 日期和时间 - ISO 8601 UTC，例如 2026-05-06T14:22:07Z
  • 货币 - ISO 4217 三字母代码，例如 GBP, USD, NGN
  • 货币金额 - number 精确到两位小数，始终与 currency 字段配对
  • 国家名称 - 英文全名，例如 "United Kingdom", "United States"
  • 电话号码 - 建议采用 E.164 格式，例如 +447700900123
  • 重量 - kg 或 lbs 按请求指定
  • ID - Pigee 生成的 ID 使用前缀格式，例如 po_78910, cr_abc123

运营商 ID 参考

使用 pigee_carrier_id 创建订单时来自费率响应的值

carrier_id示例 pigee_carrier_id地区
dhlDHL_EXPRESS_WORLDWIDE, DHL_EXPRESS_12全球
fedexFEDEX_INTERNATIONAL_PRIORITY, FEDEX_INTERNATIONAL_ECONOMY全球
upsUPS_WORLDWIDE_EXPRESS, UPS_WORLDWIDE_EXPEDITED全球
aramexARAMEX_EXPRESS, ARAMEX_ECONOMY中东、非洲、亚洲
parcelforcePARCELFORCE_EXPRESS24, PARCELFORCE_GLOBAL_EXPRESS英国及国际
teleportTELEPORT_STANDARD东南亚
local_*local_5b3, local_8ac区域性、动态返回

更新日志

v1.3 - 2026年5月

  • 已添加 insurance_available 和 customs_included 标志至费率响应。
  • Webhook签名验证现在使用HMAC-SHA256。
  • 新错误代码 RATE_EXPIRED.
  • 已添加追踪端点： GET /api/v1/tracking/{pigee_order_id}.

v1.2 - 2026年2月

  • 已在仪表盘中添加单条路线服务费覆盖。
  • Pigee Pay支付链接现已包含 expires_at 字段。
  • 已为海关和结算添加新webhook事件。

v1.1 - 2025年10月

  • 已发布初始Postman集合。
  • 沙箱环境已推出。
  • 账户余额支付模式已发布。

v1.0 - 2025年6月

  • 初始公开发布：验证、获取费率、创建订单、履行订单。
🚀 SEO 优化 Pigee