دليل · store:write · orders:write
إدارة متجر Bloop
اربط مستودعك أو متجرك الإلكتروني أو جدول البيانات الخاص بك بمتجرك في Bloop على Linework: المنتجات، والمخزون، والطلبات، والشحن.
نطاقات الصلاحية: 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"
تُرجَع الطلبات من الأحدث إلى الأقدم. لكل طلب معرّف وحالة وعناصره ومجاميعه، ومع 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.
هل تشحن من التطبيق بدلًا من ذلك؟ طباعة الملصق واختيار شركة الشحن مشروحان في شحن طلب.