快速开始

Palm API 提供对组织订单数据的编程访问能力，可用于构建集成、同步外部系统或驱动自定义报表。

Base URL

所有 API 请求发送至：

https://lite-dev.palmnet.co/v1

API 通过 URL 路径进行版本控制，当前版本为 v1。

第一个请求

获取 API 密钥 后，尝试获取最近的订单：

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lite-dev.palmnet.co/v1/orgs/{orgId}/orders?page_size=5"

成功响应示例：

{
  "orders": [
    {
      "id": "cfa605d4-1ec6-4e32-87c5-4db875801639",
      "storeId": "00000000-0000-0000-0000-000000000001",
      "paymentStatus": "paid",
      "totalCents": 1375,
      "createdAt": "2024-06-15T14:30:00Z"
    }
  ],
  "hasMore": true
}

接口

订单列表

GET /v1/orgs/{orgId}/orders

返回组织下所有门店的订单，按时间倒序。需要 orders:read 权限。

查询参数

参数	类型	默认值	说明
store_id	string	—	按门店筛选
view	string	all	active、all、history
payment_status	string	—	逗号分隔：paid, unpaid, partial, refunded
fulfillment_status	string	—	逗号分隔：pending, accepted, preparing, ready, completed, cancelled
source	string	—	逗号分隔：pos, kiosk, online
from	string	—	起始时间（RFC 3339 或 YYYY-MM-DD）
to	string	—	截止时间（仅日期时视为当天结束）
amount_min	integer	—	最小 totalCents，含边界
amount_max	integer	—	最大 totalCents，含边界
page_size	integer	200	1–200。expand 包含 items 时上限为 50
before	string	—	分页游标 — 传入上一页最后一条订单的 createdAt
expand	string	—	内联子资源：items, payments, refunds, tax_breakdown

展开子资源

列表接口默认只返回订单头信息。通过 expand 参数可以内联关联数据，免去逐条请求详情。

curl -H "X-Api-Key: $KEY" \
  "https://lite-dev.palmnet.co/v1/orgs/$ORG_ID/orders?expand=items,payments"

值	效果
items	包含商品明细。page_size 上限降为 50
payments	包含支付记录
refunds	包含退款（含退款商品和退款支付明细）
tax_breakdown	包含按税率拆分的税费明细

提示

批量同步订单数据时，建议使用 expand=items,payments 在一次分页循环中获取全部数据，而非逐条调用详情接口。

分页

API 使用基于游标的分页。

1. 首次请求不传 before。
2. 如果 hasMore 为 true，将最后一条订单的 createdAt 作为 before 传入下次请求。
3. 重复直到 hasMore 为 false。

订单详情

GET /v1/orgs/{orgId}/orders/{orderId}

返回单个订单的完整数据 — 商品明细、支付记录、退款、税费明细和促销信息。需要 orders:read 权限。

完整响应结构请参考 API Reference。

---

约定

金额

所有金额均为最小货币单位的整数（分）。totalCents: 1250 即门店币种下的 12.50。

时间戳

所有时间戳为 RFC 3339 格式，UTC 时区。示例：2024-06-15T14:30:00Z。

多语言字符串

部分字段（如 productName、paymentMethodName）为多语言字符串对象，每个 key 为语言代码，_base 为兜底值。

{
  "_base": "Latte",
  "en": "Latte",
  "zh": "拿铁"
}

显示时优先匹配用户语言，无匹配则回退到 _base。

---

下一步

• 认证 — 创建和管理 API 密钥
• API Reference — 交互式接口文档
• OpenAPI Spec — 下载用于 Postman、Insomnia 或代码生成