المطورون

اربط أنظمتك. بمفتاح ومكتبة وWebhooks.

لكل متجر واجهة API للمنتجات والطلبات والعملاء والخصومات والمخزون. مكتبتان جاهزتان، لـJavaScript وPython، تتوليان المفاتيح والتنقل بين الصفحات والأخطاء وتواقيع Webhooks، فيستغرق الطلب الأول دقائق.

01البداية

ثلاث خطوات حتى الطلب الأول.

  1. أنشئ مفتاحًا

    في لوحة الإدارة افتح «المطورون» وأنشئ مفتاح API بالصلاحيات التي يحتاجها فقط. انسخه فورًا: يظهر مرة واحدة. الوصول إلى API جزء من باقة Business.

  2. نزّل مكتبة

    JavaScript أو Python، في الأسفل. كل منهما تنزيل واحد بلا اعتماديات.

  3. استدعِ API

    أعطِ المكتبة المفتاح ومعرّف المتجر (كلاهما في صفحة «المطورون») واقرأ منتجاتك الأولى. أبقِ المفتاح على الخادم، ولا تضعه أبدًا في صفحة تُفتح في المتصفح.

02المكتبات

لغتان، والواجهة نفسها.

تغطي المكتبتان الشيء نفسه: المنتجات والطلبات والعملاء والخصومات والمخزون، وكل قائمة صفحة بعد صفحة، وأخطاء يمكن التصرف بناءً عليها، والتحقق من توقيع Webhooks. وما لا تغطيانه بعد متاح بطلب واحد عبر request().

JavaScript وTypeScript

لـNode 18 وما بعده وDeno وBun وCloudflare Workers. وحدة ES واحدة مع تعريفات أنواعها.

مثال
import { Kreaza, KreazaError } from "./kreaza.js";

const kreaza = new Kreaza({
  apiKey: process.env.KREAZA_API_KEY,
  storeId: process.env.KREAZA_STORE_ID,
});

// One page of active products
const { products, next_cursor } = await kreaza.products.list({ status: "active" });

// Every paid order, page after page
for await (const order of kreaza.orders.all({ payment_status: "paid" })) {
  console.log(order.number, order.total);
}

try {
  await kreaza.products.create({ title: "", variants: [{ price: 12900 }] });
} catch (e) {
  if (e instanceof KreazaError) console.log(e.status, e.code, e.fields);
}

Python

لـPython 3.9 وما بعده، مع الأنواع. ملف wheel تثبّته باستخدام pip؛ وبداخله المكتبة القياسية فقط.

التثبيت
pip install ./kreaza-1.0.0-py3-none-any.whl
مثال
import os
from kreaza import Kreaza, ValidationError

kreaza = Kreaza(api_key=os.environ["KREAZA_API_KEY"],
                store_id=os.environ["KREAZA_STORE_ID"])

# One page of active products
page = kreaza.products.list(status="active")
print(len(page), page.next_cursor)

# Every paid order, page after page
for order in kreaza.orders.all(payment_status="paid"):
    print(order["number"], order["total"])

try:
    kreaza.products.create({"title": "", "variants": [{"price": 12900}]})
except ValidationError as e:
    print(e.status, e.code, e.fields)

المكتبات حاليًا تنزيلات من هذا الموقع، وليست حزمًا على npm أو PyPI.

03القوائم

صفحة بعد صفحة، أو كلها دفعة واحدة.

تجيب القائمة بصفحة واحدة وبقيمة next_cursor؛ والصفحة الأخيرة بلا قيمة. تقرأ list() صفحة واحدة. وتتبع all() المؤشر نيابةً عنك وتسلّمك العناصر واحدًا بعد آخر، ولا تجلب الصفحة التالية إلا عند الحاجة.

04الأخطاء

أخطاء تقول ماذا تفعل.

الطلب المرفوض يرفع خطأً فيه حالة HTTP، ورمز ثابت للبرامج، والحقول المسببة، ومعرّف طلب تذكره للدعم. في JavaScript هو KreazaError؛ وفي Python لكل حالة صنفها الخاص.

الحالةمعناهاالصنف في Python
400, 422رُفض الإدخال. يذكر fields كل حقل ومشكلته.ValidationError
401المفتاح مفقود أو خاطئ أو ملغى أو يخص متجرًا آخر.AuthenticationError
403المفتاح يعمل لكنه لا يملك الصلاحية المطلوبة لهذا.PermissionDeniedError
404لا يوجد شيء كهذا في هذا المتجر.NotFoundError
409يتعارض مع الحالة الحالية، مثل عنوان مستخدم بالفعل.ConflictError
429طلبات كثيرة جدًا. انتظر ثم حاول مجددًا.RateLimitError
5xxفشلت الواجهة. إعادة القراءة آمنة؛ تحقّق قبل تكرار عملية كتابة.ServerError
0لا رد: فشلت الشبكة (network) أو استغرق الأمر وقتًا طويلًا (timeout).APIConnectionError, APITimeoutError

05Webhooks

اعرف بالطلب لحظة تغيّره.

يرسل Webhook رسالة JSON موقّعة إلى عنوان https الخاص بك عندما يحدث شيء في المتجر: طلب يُنشأ أو يُدفع أو يُشحن أو يُلغى أو يُسترد، زبون أو منتج جديد أو تغيّر، مخزون منخفض، حجز مؤكد، مراجعة، رسالة أو طلب إرجاع. التسليم الذي يفشل يُعاد بفواصل متزايدة حتى 8 مرات، وكل محاولة تظهر في السجل في صفحة «المطورون».

الأحداث

  • order.created
  • order.paid
  • order.fulfilled
  • order.cancelled
  • order.refunded
  • customer.created
  • customer.updated
  • product.created
  • product.updated
  • product.deleted
  • inventory.low
  • booking.confirmed
  • review.created
  • form.submitted
  • return.requested

تحمل كل رسالة X-Creatify-Signature: sha256= متبوعًا بـHMAC-SHA256 للنص الحرفي بسرّ الـWebhook. تحقّق منه على النص الخام قبل تحليله: JSON المعاد كتابته لن يطابق.

JavaScript وTypeScript
import { verifyWebhook } from "./kreaza.js";

// Read the body as text, before parsing it
const raw = await request.text();
const ok = await verifyWebhook(process.env.KREAZA_WEBHOOK_SECRET, raw,
  request.headers.get("x-creatify-signature"));
if (!ok) return new Response("bad signature", { status: 401 });
const event = JSON.parse(raw);
Python
from kreaza import verify_webhook

# The raw bytes, before parsing them
raw = request.get_data()
if not verify_webhook(os.environ["KREAZA_WEBHOOK_SECRET"], raw,
                      request.headers.get("X-Creatify-Signature")):
    abort(401)
event = json.loads(raw)

06الصلاحيات

المفتاح يفعل ما تسمح به فقط.

تختار الصلاحيات عند إنشاء المفتاح. الحساب والمدفوعات والفريق والمفاتيح نفسها ليست متاحة لأي مفتاح أبدًا: تبقى لمن سجّل الدخول إلى لوحة الإدارة.

الصلاحيات التي يمكن أن يحملها المفتاح

  • products.read
  • products.write
  • inventory.read
  • inventory.write
  • orders.read
  • orders.manage
  • customers.read
  • customers.write
  • discounts.read
  • discounts.write
  • analytics.read
  • hosting.read
  • hosting.manage
  • hosting.settings
  • themes.read
  • themes.write

ابنِ على متجرك.

افتح متجرًا، وانتقل إلى Business حين تكون جاهزًا، وأنشئ مفتاحك الأول في صفحة «المطورون».