API Cards Realm ERP v1

API REST para integrar sua loja com sistemas externos: estoque, pedidos e busca de cartas.

Autenticação

Gere uma chave de API na página de configurações da sua loja (Configurações → API) e envie em todas as requisições no cabeçalho:

Authorization: Bearer crk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Guarde sua chave com segurança. Ela dá acesso total ao estoque e pedidos da sua loja e só é exibida uma vez, no momento em que é gerada.

Limites de uso

120 requisições/minuto para leitura, 60/minuto para escrita, 10/minuto para atualização de preços em massa, por chave de API.

Loja

GET /api/v1/store

Retorna os dados básicos da sua loja.

Estoque

GET /api/v1/products?page=1&q=ilha
POST /api/v1/products
PATCH /api/v1/products/<selling_id>
DELETE /api/v1/products/<selling_id>
POST /api/v1/products/bulk-price

Exemplo: adicionar uma carta ao estoque (use /api/v1/cards/search e /api/v1/cards/<card_id>/editions para descobrir os IDs):

curl -X POST https://SEU-DOMINIO/api/v1/products \
  -H "Authorization: Bearer crk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": 15377,
    "print_id": 222,
    "set_number": "273",
    "quality_id": 1,
    "language_id": 1,
    "quantity": 4,
    "price": "12.50",
    "foil": false
  }'

Atualização de preços em massa:

curl -X POST https://SEU-DOMINIO/api/v1/products/bulk-price \
  -H "Authorization: Bearer crk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rule": "percent", "value": 10}'

rule: "percent" (percentual +/-), "fixed_add" (soma/subtrai valor fixo), "set_fixed" (define preço fixo). Filtros opcionais: print_id, price_min, price_max.

Pedidos

GET /api/v1/orders
GET /api/v1/orders/<order_id>

O mesmo formato é usado nos webhooks de pedido:

{
  "order_id": 123,
  "status": "paid",
  "buyer_name": "...", "buyer_email": "...",
  "currency": "BRL",
  "subtotal_cents": 30000,
  "discount_cents": 6000,
  "coupon_code": "PROMO20",
  "commission_cents": 2400,
  "store_payout_cents": 21600,
  "shipping_cents": 1500, "shipping_carrier": "jadlog", "shipping_service": "Package",
  "insurance_cents": 0,
  "fulfillment_method": "shipping",
  "pickup_scheduled_at": null,
  "created_at": "...", "paid_at": "...",
  "items": [
    {
      "card_name": "...", "edition": "...", "quality": "NM", "language": "English",
      "quantity": 2, "unit_price_cents": 10000,
      "is_custom_product": false,
      "is_preorder": false, "full_price_cents": null,
      "bundle_name": null
    }
  ]
}

Atenção ao conferir valores: subtotal_cents é o valor ANTES do desconto. O que o cliente pagou pelos produtos é subtotal_cents - discount_cents, e é sobre esse valor que commission_cents é calculada. Em um item de pré-venda, unit_price_cents é apenas o depósito cobrado agora - full_price_cents traz o preço cheio.

Busca de cartas

GET /api/v1/cards/search?q=ilha
GET /api/v1/cards/<card_id>/editions

Webhooks

Configure uma URL em Configurações → Webhooks para receber uma notificação HTTP quando algo acontecer, em vez de precisar consultar GET /api/v1/orders repetidamente.

Eventos disponíveis: order.created, order.paid, order.refunded, além de ping (evento de teste).

Cada requisição é assinada em HMAC-SHA256 (chave mostrada na página de Webhooks) e enviada com os cabeçalhos:

X-CardsRealm-Event: order.paid
X-CardsRealm-Signature: <hmac_sha256(secret, corpo_da_requisicao)>

Verifique a assinatura antes de confiar no conteúdo - calcule o HMAC-SHA256 do corpo bruto da requisição com sua chave e compare com o cabeçalho recebido.

Erros

Respostas de erro sempre têm o formato {"error": "mensagem"} com o código HTTP apropriado (400, 401, 404, 429).

← Voltar ao painel