Referência da API

API REST

Crie uma chave de API em Loja → Chaves de API. Ela é mostrada uma vez só. Autentique com um token bearer:

curl https://sua-loja.example/api/v1/products \
  -H "Authorization: Bearer shuz_live_…"

As chaves têm escopo (products:read, orders:write, e assim por diante) e limite de uso por chave. As respostas trazem X-RateLimit-Limit e X-RateLimit-Remaining; uma requisição recusada traz Retry-After. O esquema completo está publicado em /api/v1/openapi.json.

Criar um pedido devolve o endereço de pagamento para você mostrar ao comprador:

POST /api/v1/orders
{
  "email": "comprador@exemplo.com",
  "asset": "BTC",
  "items": [{ "productId": "…", "quantity": 1 }]
}

201
{
  "order":   { "number": "4KQ7-M2XN-9F3T", "status": "PENDING" },
  "invoice": { "address": "bc1q…", "expected": "0.00031312", "expiresAt": "…" }
}

O corpo aceita items, que é o mesmo nome que o pedido devolve — então dá para ler um pedido, mudar uma quantidade e mandar de volta. lines continua funcionando, para quem integrou antes; mande um ou outro, nunca os dois. Exemplo que roda:

curl -X POST https://sua-loja.example/api/v1/orders \
  -H "Authorization: Bearer shuz_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "comprador@exemplo.com",
    "asset": "BTC",
    "items": [{ "productId": "prod_…", "quantity": 1 }]
  }'

Webhooks

Adicione um endpoint em Loja → Webhooks e assine os eventos que te interessam. Cada entrega carrega:

X-Shuz-Event:     order.completed
X-Shuz-Delivery:  <id da entrega>
X-Shuz-Timestamp: 1774000000
X-Shuz-Signature: <hex>

A assinatura é HMAC-SHA256(timestamp + "." + corpoBruto) usando o segredo do seu endpoint. Verifique antes de confiar no corpo, e recuse um timestamp de mais de alguns minutos, para que uma requisição capturada não possa ser reenviada:

import { createHmac, timingSafeEqual } from 'node:crypto'

const expected = createHmac('sha256', secret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex')

const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(signature))

Entregas que falham são repetidas com espera crescente. Um endpoint que falha dez vezes seguidas é desativado sozinho, e você é avisado.

Validação de licença

Ative o licenciamento num produto e cada unidade vendida emite uma chave. Seu próprio software confere a chave contra um endpoint público, sem chave de API, porque ele roda na máquina do seu cliente:

POST /api/v1/license/validate
{ "key": "A1B2C-D3E4F-G5H6J-K7L8M", "hardwareId": "…" }

{ "valid": true, "status": "ACTIVE",
  "expiresAt": null, "activationsRemaining": 2 }

As ativações são vinculadas ao id de hardware que você informa, contadas contra o limite do produto, e revogáveis pelo painel. Uma verificação que falha nunca diz a que loja ou a que produto a chave pertence.