指南 · store:write · orders:write

经营 Bloop 店铺

将您的仓库、电商系统或电子表格连接到 Linework 上的 Bloop 店铺：商品、库存、订单和发货。

权限范围：store:read、store:write、orders:read、orders:write。

支付由 Linework 在应用内处理。API 从不涉及资金流转：您负责管理商品目录和订单履行，买家照常在 Linework 中付款。

端点	用途
GET `/store`	您的店铺。
POST `/store`	如果您还没有店铺，则创建店铺。
PATCH `/store`	更新名称、描述和其他店铺信息。
GET `/store/products`	列出您的商品（分页）。
POST `/store/products`	创建商品。
PATCH `/store/products/{id}`	更新商品。
DELETE `/store/products/{id}`	移除商品。
PATCH `/store/products/{id}/stock`	设置可用数量。
GET `/store/orders`	收到的订单（分页）。
GET `/store/orders/{id}`	单个订单，包含商品明细和收货地址。
POST `/store/orders/{id}/ship`	将订单标记为已发货，并附带物流信息。

1. 检查您的店铺#

curl https://api.linework.app/open/v1/store \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

如果您还没有店铺，GET /store 会返回 404 NOT_FOUND：请使用 POST /store 创建店铺（字段请参阅 API 参考）。

2. 创建商品#

先使用 POST /media 上传照片（请参阅发布带媒体的帖子），然后使用这些照片的 mediaId 创建商品。

curl https://api.linework.app/open/v1/store/products \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Linen shirt",
    "description": "100% Italian linen, made in Biella.",
    "price": 59.00,
    "currency": "EUR",
    "stock": 25,
    "sku": "SHIRT-LIN-M",
    "mediaIds": ["m_8f2c1a"]
  }'

const res = await fetch("https://api.linework.app/open/v1/store/products", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Linen shirt",
    description: "100% Italian linen, made in Biella.",
    price: 59.0,
    currency: "EUR",
    stock: 25,
    sku: "SHIRT-LIN-M",
    mediaIds: [mediaId],
  }),
});
const product = await res.json();

import os, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

product = s.post(API + "/store/products", json={
    "title": "Linen shirt",
    "description": "100% Italian linen, made in Biella.",
    "price": 59.00,
    "currency": "EUR",
    "stock": 25,
    "sku": "SHIRT-LIN-M",
    "mediaIds": [media_id],
}, timeout=30).json()

3. 保持库存同步#

请使用专门的库存端点：它很轻量，并且不会改动商品的其他信息。

curl -X PATCH https://api.linework.app/open/v1/store/products/7781/stock \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stock": 12 }'

典型的同步任务会从您的系统读取数量，并只更新发生变化的商品：

const API = "https://api.linework.app/open/v1";
const headers = { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}`, "Content-Type": "application/json" };

const warehouse = { "SHIRT-LIN-M": 12, "SHIRT-LIN-L": 0 }; // from your system

let cursor = null;
do {
  const url = `${API}/store/products?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
  const page = await fetch(url, { headers }).then((r) => r.json());
  for (const p of page.data) {
    const qty = warehouse[p.sku];
    if (qty !== undefined && qty !== p.stock) {
      await fetch(`${API}/store/products/${p.id}/stock`, {
        method: "PATCH", headers, body: JSON.stringify({ stock: qty }),
      });
    }
  }
  cursor = page.next_cursor;
} while (cursor);

warehouse = {"SHIRT-LIN-M": 12, "SHIRT-LIN-L": 0}  # from your system

cursor = None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    page = s.get(API + "/store/products", params=params, timeout=30).json()
    for p in page["data"]:
        qty = warehouse.get(p.get("sku"))
        if qty is not None and qty != p["stock"]:
            s.patch(f"{API}/store/products/{p['id']}/stock", json={"stock": qty}, timeout=30)
    cursor = page.get("next_cursor")
    if not cursor:
        break

库存为 0 时，商品仍保留在目录中并显示为售罄。如需移除，请使用 DELETE /store/products/{id}。

4. 读取新订单#

curl "https://api.linework.app/open/v1/store/orders?limit=50" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

订单按从新到旧的顺序返回。每个订单都有 ID、状态、商品明细和总额；通过 GET /store/orders/{id} 还可获取收货地址。请每隔几分钟获取一次列表，并处理已付款但尚未发货的订单。完整的订单结构和状态值请参阅 API 参考。

订单包含买家的个人数据（姓名、地址）。请仅将其用于履行订单，妥善保管，切勿共享。请参阅 API 条款。

5. 标记为已发货#

curl https://api.linework.app/open/v1/store/orders/50213/ship \
  -H "Authorization: Bearer $LINEWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "carrier": "BRT", "trackingNumber": "084512345678" }'

买家会在应用中收到包含物流信息的通知。对同一订单发货两次，或对无法发货的订单（例如已取消）发货，会返回 409 CONFLICT。