Conecte seus próprios sistemas. Com uma chave, uma biblioteca e webhooks.
Toda loja tem uma API para produtos, pedidos, clientes, descontos e estoque. Duas bibliotecas prontas, para JavaScript e Python, cuidam das chaves, da paginação, dos erros e das assinaturas dos webhooks, então a primeira chamada leva minutos.
No painel, abra Developers (Desenvolvedores) e crie uma chave de API só com as permissões de que ela precisa. Copie na hora: ela aparece uma única vez. O acesso à API faz parte do plano Business.
2
Baixe uma biblioteca
JavaScript ou Python, logo abaixo. Cada uma é um único download, sem dependências.
3
Chame a API
Passe para a biblioteca a chave e o id da loja (os dois estão na página Developers) e leia seus primeiros produtos. Mantenha a chave num servidor, nunca numa página aberta no navegador.
02Bibliotecas
Duas linguagens, a mesma API.
As duas bibliotecas cobrem o mesmo: produtos, pedidos, clientes, descontos e estoque, cada lista página por página, erros com que dá para agir e a verificação de assinatura dos webhooks. O que elas ainda não cobrem está a uma chamada de distância com request().
JavaScript e TypeScript
Para Node 18 ou mais recente, Deno, Bun e Cloudflare Workers. Um único módulo ES com suas definições 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 enquanto as bibliotecas são downloads deste site, não pacotes do npm ou do PyPI.
03Listas
Página por página, ou tudo de uma vez.
Uma lista responde com uma página e um next_cursor; a última página não tem. list() lê uma página. all() segue o cursor para você e entrega os itens um por um, buscando a próxima página só quando precisa.
04Erros
Erros que dizem o que fazer.
Uma requisição recusada lança um erro com o status HTTP, um código estável para programas, os campos com problema e um id de requisição para informar ao suporte. Em JavaScript é KreazaError; em Python cada status tem sua própria classe.
Status
O que significa
Classe em Python
400, 422
Os dados foram recusados. fields aponta cada campo e o problema dele.
ValidationError
401
A chave está faltando, errada, revogada ou é de outra loja.
AuthenticationError
403
A chave funciona, mas não tem a permissão necessária para isso.
PermissionDeniedError
404
Isso não existe nesta loja.
NotFoundError
409
Conflita com o estado atual, por exemplo um endereço já em uso.
ConflictError
429
Requisições demais. Espere e tente de novo.
RateLimitError
5xx
A API falhou. Repetir uma leitura é seguro; antes de repetir uma escrita, confira o que aconteceu.
ServerError
0
Sem resposta: a rede falhou (network) ou demorou demais (timeout).
APIConnectionError, APITimeoutError
05Webhooks
Saiba de um pedido assim que ele muda.
Um webhook envia uma mensagem JSON assinada para o seu endereço https quando algo acontece na loja: um pedido criado, pago, enviado, cancelado ou reembolsado, um cliente ou produto novo ou alterado, estoque baixo, uma reserva confirmada, uma avaliação, uma mensagem ou um pedido de devolução. Uma entrega que falha é repetida com intervalos cada vez maiores, até 8 vezes, e cada tentativa fica no registro da 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 mensagem traz X-Creatify-Signature: sha256= e o HMAC-SHA256 do corpo exato com o segredo do webhook. Confira no corpo bruto, antes de interpretar: um JSON escrito de novo não vai bater.
JavaScript e 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)
06Permissões
Uma chave faz só o que você permite.
Você escolhe as permissões ao criar a chave. A conta, os pagamentos, a equipe e as próprias chaves nunca ficam abertos a uma chave: ficam com quem entra no painel.
Permissões que uma chave pode ter
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
Construa sobre a sua loja.
Abra uma loja, passe para o Business quando estiver pronto e crie sua primeira chave na página Developers.