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.
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.
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.
Estado
Qué significa
Clase en Python
400, 422
Los datos se rechazaron. fields indica cada campo y su problema.
ValidationError
401
La clave falta, es incorrecta, está revocada o es de otra tienda.
AuthenticationError
403
La clave funciona pero no tiene el permiso que esto necesita.
PermissionDeniedError
404
No existe en esta tienda.
NotFoundError
409
Choca con el estado actual, por ejemplo una dirección que ya está en uso.
ConflictError
429
Demasiadas peticiones. Espera y vuelve a intentarlo.
RateLimitError
5xx
La API falló. Repetir una lectura es seguro; antes de repetir una escritura, comprueba qué pasó.
ServerError
0
Sin 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.