מפתחים

מחברים את המערכות שלכם. עם מפתח, ספרייה ו־Webhooks.

לכל חנות יש API למוצרים, הזמנות, לקוחות, הנחות ומלאי. שתי ספריות מוכנות, ל־JavaScript ול־Python, מטפלות במפתחות, בדפדוף, בשגיאות ובחתימות של Webhooks, כך שהקריאה הראשונה לוקחת דקות.

01מתחילים

שלושה צעדים עד הקריאה הראשונה.

  1. יוצרים מפתח

    בניהול החנות פותחים את ״מפתחים״ ויוצרים מפתח API רק עם ההרשאות שהוא צריך. מעתיקים אותו מיד: הוא מוצג פעם אחת. גישה ל־API כלולה במסלול Business.

  2. מורידים ספרייה

    JavaScript או Python, למטה. כל אחת היא הורדה אחת בלי תלויות.

  3. קוראים ל־API

    נותנים לספרייה את המפתח ואת מזהה החנות (שניהם בדף ״מפתחים״) וקוראים את המוצרים הראשונים. המפתח נשאר בשרת, אף פעם לא בדף שנפתח בדפדפן.

02ספריות

שתי שפות, אותו API.

שתי הספריות עושות אותו דבר: מוצרים, הזמנות, לקוחות, הנחות ומלאי, כל רשימה עמוד אחרי עמוד, שגיאות שאפשר לפעול לפיהן ובדיקת חתימה של 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ה־API נכשל. קריאה בטוח לנסות שוב; לפני שחוזרים על כתיבה בודקים מה קרה.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 כשמוכנים, ויוצרים את המפתח הראשון בדף ״מפתחים״.