Desenvolvedores

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.

01Começar

Três passos até a primeira chamada.

  1. Crie uma chave

    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.

Exemplo
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 ou mais recente, com tipos. Um wheel que você instala com pip; por dentro, só a biblioteca padrão.

Instalação
pip install ./kreaza-1.0.0-py3-none-any.whl
Exemplo
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.

StatusO que significaClasse em Python
400, 422Os dados foram recusados. fields aponta cada campo e o problema dele.ValidationError
401A chave está faltando, errada, revogada ou é de outra loja.AuthenticationError
403A chave funciona, mas não tem a permissão necessária para isso.PermissionDeniedError
404Isso não existe nesta loja.NotFoundError
409Conflita com o estado atual, por exemplo um endereço já em uso.ConflictError
429Requisições demais. Espere e tente de novo.RateLimitError
5xxA API falhou. Repetir uma leitura é seguro; antes de repetir uma escrita, confira o que aconteceu.ServerError
0Sem 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.