Desarrolladores

Conecta tus propios sistemas. Con una clave, una biblioteca y webhooks.

Cada tienda tiene una API para productos, pedidos, clientes, descuentos y stock. Dos bibliotecas listas, para JavaScript y Python, se ocupan de las claves, la paginación, los errores y las firmas de los webhooks, así que la primera llamada lleva minutos.

01Empezar

Tres pasos hasta la primera llamada.

  1. Crea una clave

    En el panel, abre Developers (Desarrolladores) y crea una clave de API solo con los permisos que necesita. Cópiala en ese momento: se muestra una sola vez. El acceso a la API forma parte del plan Business.

  2. Descarga una biblioteca

    JavaScript o Python, más abajo. Cada una es una sola descarga sin dependencias.

  3. Llama a la API

    Dale a la biblioteca la clave y el id de la tienda (ambos en la página Developers) y lee tus primeros productos. Guarda la clave en un servidor, nunca en una página que se abre en el navegador.

02Bibliotecas

Dos lenguajes, la misma API.

Las dos bibliotecas cubren lo mismo: productos, pedidos, clientes, descuentos y stock, cada lista página a página, errores con los que se puede actuar y la comprobación de firmas de webhooks. Lo que aún no cubren está a una llamada de distancia con request().

JavaScript y TypeScript

Para Node 18 o posterior, Deno, Bun y Cloudflare Workers. Un único módulo ES con sus definiciones de tipos.

Ejemplo
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

Para Python 3.9 o posterior, con tipos. Un wheel que se instala con pip; dentro solo usa la biblioteca estándar.

Instalación
pip install ./kreaza-1.0.0-py3-none-any.whl
Ejemplo
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)

Por ahora las bibliotecas se descargan de este sitio; no son paquetes de npm ni de PyPI.

03Listas

Página a página, o todo de una vez.

Una lista responde con una página y un next_cursor; la última página no lo trae. list() lee una página. all() sigue el cursor por ti y entrega los elementos de uno en uno, pidiendo la página siguiente solo cuando hace falta.

04Errores

Errores que dicen qué hacer.

Una petición rechazada lanza un error con el estado HTTP, un código estable para programas, los campos con problemas y un id de petición para dar a soporte. En JavaScript es KreazaError; en Python cada estado tiene su propia clase.

EstadoQué significaClase en Python
400, 422Los datos se rechazaron. fields indica cada campo y su problema.ValidationError
401La clave falta, es incorrecta, está revocada o es de otra tienda.AuthenticationError
403La clave funciona pero no tiene el permiso que esto necesita.PermissionDeniedError
404No existe en esta tienda.NotFoundError
409Choca con el estado actual, por ejemplo una dirección que ya está en uso.ConflictError
429Demasiadas peticiones. Espera y vuelve a intentarlo.RateLimitError
5xxLa API falló. Repetir una lectura es seguro; antes de repetir una escritura, comprueba qué pasó.ServerError
0Sin respuesta: falló la red (network) o tardó demasiado (timeout).APIConnectionError, APITimeoutError

05Webhooks

Entérate de un pedido en cuanto cambia.

Un webhook envía un mensaje JSON firmado a tu dirección https cuando pasa algo en la tienda: un pedido creado, pagado, enviado, cancelado o reembolsado, un cliente o producto nuevo o modificado, stock bajo, una reserva confirmada, una reseña, un mensaje o una solicitud de devolución. Una entrega que falla se repite con esperas cada vez más largas, hasta 8 veces, y cada intento queda en el registro de la página Developers.

Eventos

  • 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

Cada mensaje lleva X-Creatify-Signature: sha256= y el HMAC-SHA256 del cuerpo exacto con el secreto del webhook. Compruébalo sobre el cuerpo en bruto, antes de interpretarlo: un JSON escrito de nuevo no coincidirá.

JavaScript y 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)

06Permisos

Una clave hace solo lo que permites.

Eliges los permisos al crear la clave. La cuenta, los pagos, el equipo y las propias claves nunca están abiertos a una clave: quedan para quienes inician sesión en el panel.

Permisos que puede tener una clave

  • 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

Construye sobre tu tienda.

Abre una tienda, pasa a Business cuando estés listo y crea tu primera clave en la página Developers.