1. Create an API key

Go to 管理员 → API 密钥, click Create API Key, and copy the secret. It is shown only once.

2. Authenticate

Pass the key as a Bearer token on every request:

Authorization: Bearer drfid_sk_live_...

Base URL: https://www.droprfid.com/api/v1

中间件示例使用 DROP_RFID_API_BASE_URL 和 DROP_RFID_API_KEY。请参阅 API-client 公共 API 指南.

复制粘贴中间件入门

公共 API client 仓库提供了一个无依赖的 Node 示例，包含列出和创建 SKU、创建订单、列出会话、获取单个会话，以及在启用时生成演示会话数据的命令。

export DROP_RFID_API_BASE_URL="https://www.droprfid.com/api/v1"
export DROP_RFID_API_KEY="drfid_sk_live_replace_me"
node examples/node-public-api.mjs list-skus

打开 examples/node-public-api.mjs 查看可运行版本。

3. List sessions

Returns every scan session for your organization with embedded device metadata.

GET /api/v1/public/sessions

curl -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/sessions

4. Get one session with RFIDs

Returns the session, its scanned RFID tags, and the device that produced them.

GET /api/v1/public/sessions/{session_id}

curl -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/sessions/<session_id>

{
  "id": "...",
  "org_id": "...",
  "device_id": "...",
  "status": "completed",
  "created_at": "2026-04-22T09:00:00Z",
  "completed_at": "2026-04-22T09:03:12Z",
  "device": {
    "id": "...",
    "name": "Warehouse-01",
    "serial_number": "SN-000123",
    "status": "active"
  },
  "rfids": [
    { "rfid_code": "E200470000...", "tid": "...", "rssi": -42, "read_count": 6, "scanned_at": "..." }
  ]
}

5. Orders

列出、创建、查询和更新订单。订单包含带预期数量的 SKU 行项目。

GET     /api/v1/public/orders          # optional ?status=pending
POST    /api/v1/public/orders          # create
GET     /api/v1/public/orders/{order_id}
PATCH   /api/v1/public/orders/{order_id}  # body: { "status": "completed" }

Create with SKU items

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_number": "PO-1042",
    "items": [
      { "sku_id": "sku-uuid-1", "expected_quantity": 24 },
      { "sku_id": "sku-uuid-2", "expected_quantity": 6 }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/orders

Update status

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  https://www.droprfid.com/api/v1/public/orders/<order_id>

Allowed status values: pending, in_progress, review_required, blocked, completed, cancelled.

6. 容器

容器是具有已记录内容和可选 RFID 或条形码标识符的命名集合——一个贴了标签的箱子，扫描它即可取回其内容。它们位于各自独立的路径上：容器绝不会出现在 /public/orders 中，订单也绝不会出现在 /public/containers 中。

GET     /api/v1/public/containers          # optional ?tag=holiday
POST    /api/v1/public/containers          # create
GET     /api/v1/public/containers/{container_id}
PATCH   /api/v1/public/containers/{container_id}

创建并记录内容

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Christmas decorations — Box 1",
    "items": [
      { "sku_id": "sku-uuid-1", "expected_quantity": 12 }
    ],
    "identifiers": [
      { "type": "rfid", "value": "E2004700ABCD" },
      { "type": "barcode", "value": "00123" }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/containers

已记录内容描述容器中存放的物品。它不能证明每件物品都被单独扫描过，也绝不会影响订单履行或库存计数。

重命名或更新内容

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"revision": 3, "display_name": "Christmas decorations — Attic"}' \
  https://www.droprfid.com/api/v1/public/containers/<container_id>

PATCH 请求必须提供 revision，且需与最后读取的值一致。过期的 revision 会返回 409，而不会静默覆盖并发的修改。提供 items 或 identifiers 会整体替换该集合。

7. SKU

Manage the SKU registry — products, variants, and the RFID codes bound to each. GET /skus/{sku_id} returns a SkuDetail with a rfids[] array.

GET     /api/v1/public/skus
POST    /api/v1/public/skus
GET     /api/v1/public/skus/{sku_id}
PATCH   /api/v1/public/skus/{sku_id}
DELETE  /api/v1/public/skus/{sku_id}

Create

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku_code":      "TSHIRT-RED-M",
    "product_title": "Classic Tee",
    "brand":         "Aqua",
    "color":         "Red",
    "size":          "M",
    "barcode":       "0123456789012",
    "rfids":         ["E200470000...", "E200470001..."],
    "rfid_ranges": [
      { "start": "1000", "end": "1050", "format": "numeric" },
      { "start": "00000000000000FE", "end": "0000000000000110", "format": "hex" }
    ]
  }' \
  https://www.droprfid.com/api/v1/public/skus

使用 rfid_ranges 可绑定一段连续的编码，而无需逐个列出。每个条目包含 start、end 和 format —— "numeric"（十进制整数，按最宽边界补零）或 "hex"（恰好 16 位十六进制数字）。区间在服务端展开，并与你提供的 rfids 合并；单个区间最多 10,000 个编码。

Partial update

All body fields are optional. Only fields you include are written. To clear a field, send an empty string. RFID bindings are managed separately.

curl -X PATCH -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"product_title": "Classic Tee — Updated", "color": "Crimson"}' \
  https://www.droprfid.com/api/v1/public/skus/<sku_id>

Delete

curl -X DELETE -H "Authorization: Bearer drfid_sk_live_..." \
  https://www.droprfid.com/api/v1/public/skus/<sku_id>

Returns 204 No Content on success. Deleting a SKU also removes its RFID bindings (the underlying RFID scan history is retained).

8. 例程

列出或创建引导式扫描工作流，或按例程代码幂等导入可复用的 YAML 和 JSON 清单。

GET   /api/v1/public/routines
POST  /api/v1/public/routines
POST  /api/v1/public/routines/import

创建引导式收货例程

curl -X POST -H "Authorization: Bearer drfid_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "inbound_receiving",
    "name": "Inbound Receiving",
    "description": "Capture a PO and location before scanning",
    "enabled": true,
    "config": {
      "start_fields": [
        {
          "key": "po_number",
          "label": "Purchase order",
          "type": "text",
          "required": true,
          "searchable": true,
          "display_in_sessions": true
        }
      ],
      "finish_fields": [],
      "completion_actions": []
    }
  }' \
  https://www.droprfid.com/api/v1/public/routines

使用完成动作发送签名 Webhook、创建报告，或按业务所需模式执行受支持的 Shopify 写回。

Rate limits

Every API key is capped at 60 requests/minute and 1,000 requests/hour. All responses include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1761096120

Over-limit requests return 429 Too Many Requests.

Versioning and stability