Разработчикам

Подключите свои системы. Ключ, библиотека и вебхуки.

У каждого магазина есть API для товаров, заказов, покупателей, скидок и остатков. Две готовые библиотеки, для JavaScript и Python, берут на себя ключи, постраничное чтение, ошибки и подписи вебхуков, так что первый запрос занимает минуты.

01Начало

Три шага до первого запроса.

  1. Создайте ключ

    В админке откройте «Разработчикам» и создайте ключ API только с нужными ему правами. Сразу скопируйте его: он показывается один раз. Доступ к API входит в тариф Business.

  2. Скачайте библиотеку

    JavaScript или Python, ниже. Каждая скачивается одним файлом без зависимостей.

  3. Вызовите API

    Передайте библиотеке ключ и id магазина (оба на странице «Разработчикам») и прочитайте первые товары. Держите ключ на сервере, никогда не в странице, которая открывается в браузере.

02Библиотеки

Два языка, один и тот же API.

Обе библиотеки умеют одно и то же: товары, заказы, покупатели, скидки и остатки, любой список страница за страницей, ошибки, по которым можно действовать, и проверка подписи вебхуков. То, чего в них пока нет, доступно одним вызовом 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-статусом, постоянным кодом для программ, полями с проблемой и id запроса для поддержки. В 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

05Вебхуки

Узнавайте о заказе в момент изменения.

Вебхук отправляет подписанное 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 точного тела с секретом вебхука. Проверяйте его на сыром теле, до разбора: заново записанный 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, когда будете готовы, и создайте первый ключ на странице «Разработчикам».