Merlion Fulfillment 开放平台

端点与鉴权

生产基址 https://api.merlion-fulfillment.com/v1。所有请求需携带 Authorization: Bearer <API_KEY>、Content-Type: application/json; charset=utf-8，并强烈建议 X-Request-Id（UUID v4）以便全链路排障。多主体账号可附加 X-MF-Account-Id 指定子商户/店铺维度。

常用路径（节选，HTTP 方法见手册）：GET /v1/orders、POST /v1/orders、GET /v1/orders/{id}、POST /v1/orders/{id}/cancel、GET /v1/inventory/skus、GET /v1/tracking、POST /v1/labels。列表接口统一支持 cursor 分页与 updated_since 增量游标，避免全量拉取压垮仓内库表。

Key 以环境隔离：生产 sk_live_…，联调请使用沙箱 sk_test_…。泄露后请在控制台立即轮换，旧 Key 有最多 15 分钟的重叠期。

数据对象与版本

核心实体包括 Order、LineItem、Shipment、InventoryItem、WebhookDelivery。订单与履约单在内部以不同 ID 解耦，对外通过 merchant_order_id 与 mf_fulfillment_id 互查。响应体带 api_version 与 schema_revision 字段，便于您侧做反序列化兼容。

若字段含义调整，会先在「beta」响应头 X-MF-Deprecation 中标注弃用与下线时间；在迁移窗内，新旧字段并行返回，新字段为权威。

限流与幂等

默认 每应用 1,200 次/分钟（以 2xx/4xx 为计数依据，429 与网络失败不计入），桶顶突发 100。超额返回 429，并带有 Retry-After（秒）。大促前可申请临时提额，需附峰值 QPS 与压测报告编号。

所有 写操作 建议携带 Idempotency-Key: <UUID>。同一 Key 在 24 小时 内仅落库一次业务结果，重复请求返回与首次相同的状态码与 body 快照，HTTP 409 仅用于「资源状态不允许当前操作」类冲突，与幂等无关。

错误与业务码

错误体为 JSON：{"error":{"code":"...","message":"...","request_id":"..."}}。request_id 与请求头 X-Request-Id 对齐，供工单与日志关联。

业务码示例：MF-1001 订单不存在，MF-2003 SKU 在仓冻结，MF-3007 截单窗口已关，MF-4002 面单渠道临时熔断。完整枚举见 PDF 附录 A。

Webhook 签名与投递

回调 URL 需在控制台登记并过 TLS；请求体为 JSON，头字段 X-MF-Signature: v1=<hex>，算法为 HMAC-SHA256，签名字符串为 timestamp + "." + raw_body，与控制台「签名密钥」一致。收到后请先验签再 200 应答；若您的端点 5s 内未返回 2xx，将按 1s → 4s → 16s → 64s 指数退避重试，最多 8 次，仍失败则进入死信列表供人工对账拉取。

常见 event：order.accepted、order.shipped、order.exception、inventory.threshold、label.generated。幂等以 event_id 为准，您的侧应去重后更新本地状态机。

沙箱与上线

沙箱基址 https://sandbox.api.merlion-fulfillment.com/v1。数据为合成库存与假轨迹，不会 触达真实承运商；Webhook 会投递到您登记的联调地址，与生产隔离。

上线前建议完成：Key 分环境保管、出口 IP 白名单、Webhook 验签、至少一轮订单全链路演练、对账文件 SFTP/推送字段对齐。商务可在工单中申请「只读预生产」用于灰度只读联调（名额有限）。

请求示例

以下为「查询物流轨迹」的演示代码。真实路径、Key 与响应体以《开放接口手册》PDF 为准。

Python

import requests

BASE = "https://api.merlion-fulfillment.com/v1"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "X-Request-Id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
}

def get_tracking(tracking_number: str) -> dict:
    r = requests.get(
        f"{BASE}/tracking",
        params={"tn": tracking_number},
        headers=HEADERS,
        timeout=8,
    )
    r.raise_for_status()
    return r.json()

if __name__ == "__main__":
    print(get_tracking("MF-SE-2026-00019827"))

Node.js (fetch)

import fetch from "node-fetch";

const BASE = "https://api.merlion-fulfillment.com/v1";
const headers = {
  Authorization: "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
  "X-Request-Id": crypto.randomUUID(),
};

export async function getTracking(trackingNumber) {
  const u = new URL(`${BASE}/tracking`);
  u.searchParams.set("tn", trackingNumber);
  const res = await fetch(u, { method: "GET", headers });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

getTracking("MF-SE-2026-00019827").then(console.log).catch(console.error);

cURL

curl -sS "https://api.merlion-fulfillment.com/v1/tracking?tn=MF-SE-2026-00019827" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 550e8400-e29b-41d4-a716-446655440000"

沙箱将基址替换为 https://sandbox.api.merlion-fulfillment.com/v1 与 sk_test_ 前缀 Key 即可。

开放接口手册（PDF）

离线版含签名算法、全部错误码、库存事件与字段字典、沙箱与上线检查清单。以下为站内静态文件，可直接下载或随站点一并部署；若与线上摘要不一致，以商户后台公告为准。