Linework Developers
AR
احصل على الوصول

دليل · 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.

هل تشحن من التطبيق بدلًا من ذلك؟ طباعة الملصق واختيار شركة الشحن مشروحان في شحن طلب.