API Cards Realm Gestão de Lojas 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
Estes endpoints operam sobre CARTAS do catálogo. Produtos que não são carta (board game, sleeve, playmat, hora de estúdio) vivem em outra tabela e têm endpoints próprios - ver abaixo.
Produtos que não são carta
GET /api/v1/custom-products
POST /api/v1/custom-products
PATCH /api/v1/custom-products/<id>
DELETE /api/v1/custom-products/<id>
Só name e price_cents são
obrigatórios na criação; o restante (slug, descrição, categoria, código de barras, localização,
atributos livres) é opcional. O PATCH é parcial: o que você não mandar
fica como está.
Dois booleanos opcionais: requires_shipping (padrão true) e
unlimited_stock (padrão false - produto digital / sem controle de estoque: a venda
não desconta a quantidade, o estorno não devolve, e o produto nunca pede frete).
O limite de produtos do seu plano conta cartas e produtos customizados JUNTOS - contar só um lado transformaria a API na porta dos fundos do limite.
Produto de assinatura: subscription_cycle (padrão null) com um dos
ciclos WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY,
QUARTERLY, SEMIANNUALLY ou YEARLY. Com ciclo, o
produto é sempre digital e só se vende por POST /api/v1/subscriptions - o
checkout avulso, o carrinho e a vitrine o recusam.
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.
Carrinho pronto para enviar ao cliente
POST /api/v1/carts
{"items": [{"selling_id": 123, "quantity": 4},
{"custom_product_id": 9, "quantity": 1},
{"bundle_id": 3, "quantity": 1}]}
Monta um carrinho e devolve um link para você mandar ao cliente por WhatsApp, e-mail ou o que preferir. Quem abrir vê a lista com preço e estoque do momento e leva tudo para o próprio carrinho com um clique. Serve para recuperação de venda, orçamento e reserva.
{"token": "kR3...", "url": "https://sualoja.com.br/lista/kR3...",
"lines": 3, "unavailable": [{"selling_id": 123, "requested": 4, "available": 1}]}
Cada item traz exatamente um entre selling_id,
custom_product_id e bundle_id, mais um
quantity opcional (padrão 1). Este endpoint aceita só JSON - lista de
objetos não cabe em formulário. Até 100 linhas por chamada.
Um item que não é da sua loja recusa a chamada inteira (400), dizendo
qual linha e por quê - gerar um link com parte da lista faria você achar que deu certo e o
cliente receber menos do que foi prometido. Já estoque que acabou não é erro: o link sai
assim mesmo e o que falta vem em unavailable, para a sua automação
decidir se avisa, troca o item ou não envia.
O link não guarda preço, de propósito: preço e disponibilidade são
lidos ao vivo quando o cliente abre, então um link de semanas atrás nunca vende pelo valor de
antes. Se você precisa do valor para escrever a mensagem, leia
GET /api/v1/products no mesmo fluxo.
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": "...", "buyer_userid": null,
"external_reference": null,
"currency": "BRL",
"subtotal_cents": 30000,
"discount_cents": 6000,
"coupon_code": "PROMO20",
"commission_cents": 2020,
"commission_rate": 0.08,
"commission_fixed_cents": 100,
"store_payout_cents": 21980,
"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, "custom_product_id": null,
"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. A comissão tem duas partes: commission_fixed_cents somado a commission_rate vezes esse valor - as duas ficam congeladas no pedido, então uma mudança de preço da plataforma nunca reescreve uma venda já feita. Em um item de pré-venda, unit_price_cents é apenas o depósito cobrado agora - full_price_cents traz o preço cheio.
Criar um pedido e o link de pagamento
POST /api/v1/orders/checkout
{"items": [{"custom_product_id": 12, "quantity": 1}],
"buyer": {"userid": 123, "email": "a@b.com", "name": "Fulano", "document": null},
"return_url": "https://cardsrealm.com/pt-br/download/ebook-x",
"external_reference": "download:7"}
201 {"order_id": 456, "payment_url": "https://...", "status": "pending"}
Para vender fora da vitrine (um site seu, um bot) produtos personalizados ATIVOS e sem
frete. O preço vem do cadastro, nunca do corpo; a comissão é a mesma da vitrine, e a cobrança sai
pelo gateway da loja. Depois de pagar (ou desistir), o comprador volta para
return_url com ?erp_order=<id>. O pagamento
chega pelo webhook order.paid, com external_reference
e buyer_userid no pedido; o estorno, por order.refunded.
return_url precisa ser https num domínio da rede Cards Realm (ou http://localhost para teste). Um item que não resolve, ou que precisa de frete, recusa a chamada inteira com 400.
Assinatura recorrente no cartão
POST /api/v1/subscriptions
{"custom_product_id": 12,
"buyer": {"userid": 123, "email": "a@b.com", "name": "Fulano", "document": null},
"return_url": "https://cardsrealm.com/pt-br/premium",
"external_reference": "premium:123"}
201 {"subscription_id": 7, "payment_url": "https://...", "status": "pending"}
GET /api/v1/subscriptions?buyer_userid=123&status=active
GET /api/v1/subscriptions/<id>
POST /api/v1/subscriptions/<id>/cancel
Para vender um plano: o produto precisa ter subscription_cycle, estar
ativo e ser desta loja, e a loja precisa receber pelo Asaas. A cobrança é SEMPRE no cartão de
crédito, recorrente: o assinante digita o cartão na página do Asaas e ele cobra sozinho a cada
ciclo. Valor e ciclo vêm do cadastro, nunca do corpo. Comprador, return_url
e external_reference seguem as mesmas regras do pedido acima; a volta
leva ?erp_subscription=<id>. Gateway que recusa responde 502 com o subscription_id.
Status: pending (link criado, ainda não pago),
active, past_due (a renovação falhou no cartão),
canceled (não cobra mais; o acesso vale até current_period_end) e expired (acabou de vez). Cancelar é idempotente e para a cobrança no
Asaas na hora. Cada cobrança confirmada vira também um pedido pago, com
external_reference = subscription:<id>, que chega como
order.paid.
{"subscription_id": 7, "status": "active", "custom_product_id": 12,
"product_name": "Premium mensal", "cycle": "MONTHLY", "value_cents": 990,
"currency": "BRL", "buyer_userid": 123, "buyer_email": "a@b.com",
"external_reference": "premium:123",
"current_period_end": "2026-12-10T23:59:59", "last_payment_at": "2026-11-10T14:03:11",
"canceled_at": null, "expired_at": null, "created_at": "2026-11-10T14:01:52"}
Uma assinatura com o cartão recusado é encerrada (cancelada no Asaas e
expired) 3 dias depois do fim do período pago, se nenhuma nova tentativa passar.
Um link que ninguém concluiu em 2 dias vira canceled sem webhook.
Busca de cartas
GET /api/v1/cards/search?q=ilha
GET /api/v1/cards/<card_id>/editions
Marcar um pedido como enviado
POST /api/v1/orders/<order_id>/ship
{"tracking_code": "AA123456789BR", "tracking_carrier": "correios"}
Guarda o rastreio, avisa o comprador por e-mail com o link da transportadora e dispara
o evento order.shipped. Os dois campos são opcionais - dá para despachar
sem código (entrega em mãos, motoboy), e o que muda a vida do comprador é saber que saiu. Só um
pedido pago pode ser despachado.
Agendamento
Para um bot (n8n, WhatsApp) marcar horário e cobrar a caução sozinho. Estes endpoints obedecem exatamente as mesmas regras da página pública de agendamento - janela de atendimento, antecedência mínima, intervalo entre atendimentos e bloqueios -, então o bot nunca oferece um horário que a loja não abre.
GET /api/v1/booking-services
GET /api/v1/booking-services/<id>/slots?from=2026-09-01&days=30
POST /api/v1/bookings
GET /api/v1/bookings (filtro opcional ?status=confirmed)
GET /api/v1/bookings/<id>
POST /api/v1/bookings/<id>/cancel
PATCH /api/v1/bookings/<id> {"starts_at": "2026-11-27T10:30"}
POST /api/v1/bookings/<id>/payment-link
POST /api/v1/bookings/<id>/deposit {"deposit_status": "paid"}
GET /api/v1/blocks
POST /api/v1/blocks
DELETE /api/v1/blocks/<id>
GET /api/v1/clients?phone=5521999998888
GET /api/v1/clients?email=...&document=...
POST /api/v1/clients
PATCH /api/v1/clients/<id>
POST /api/v1/clients/<id>/merge
Remarcar ou corrigir o contato de um agendamento (só JSON): os campos starts_at,
customer_name, customer_email, customer_phone e
notes são opcionais, e o que não vier não muda. O horário novo mantém a duração e o
sinal já pago, e passa pela mesma checagem de sala da criação (409 se não houver sala livre). Mudou o
horário, o cliente recebe o e-mail de remarcação e sai o webhook booking.rescheduled.
Completar a ficha de um cliente (só JSON):
PATCH /api/v1/clients/42
{"document": "12.345.678/0001-90", "legal_name": "Empresa X LTDA",
"note": "pediu nota fiscal no CNPJ"}
Grava só os campos que estão VAZIOS na ficha (e-mail, telefone, CPF/CNPJ, razão social,
endereço, Instagram, nome da marca) e nunca troca um dado que já existe: um valor diferente volta em
conflicts, para uma pessoa conferir. Um e-mail, telefone ou documento que já é de
outro cliente também volta como conflito. O campo note é acrescentado às
observações da ficha, nunca as substitui. A resposta traz filled,
conflicts e o cliente atualizado.
Para CORRIGIR um dado errado, nomeie o campo em replace: ele é trocado
mesmo preenchido, e o valor antigo vai para as observações (a resposta traz replaced).
Um contato que já é de outro cliente continua sendo conflito: aí são duas fichas da mesma pessoa.
PATCH /api/v1/clients/42
{"phone": "+55 21 97181-6744", "replace": ["phone"]}
Fundir duas fichas da mesma pessoa: vendas, agendamentos e saldos do absorb_id
vão para a ficha da URL, que fica; os campos vazios dela são preenchidos, e a outra ficha some.
POST /api/v1/clients/42/merge
{"absorb_id": 57}
Criar um agendamento (só JSON):
POST /api/v1/bookings
{"service_id": 3, "starts_at": "2026-09-01T14:00",
"customer_name": "Maria Silva", "customer_email": "maria@exemplo.com",
"customer_phone": "21999998888", "notes": "primeira vez",
"discount_percent": 10}
O campo discount_percent é opcional: um número inteiro de 0 a
20, aplicado ao valor do atendimento e ao sinal deste agendamento -
o tipo de atendimento continua com o preço de tabela. Fora dessa faixa a resposta é 400 e nada é
marcado. O link de pagamento e o restante cobrado no dia já saem com o desconto.
O campo price_cents é o preço DESTA venda, para o cliente com
preço combinado: em centavos, maior que zero e no máximo o preço do atendimento. Vira desconto sobre a
tabela, que fica em list_price_cents para o cliente ver o desconto especial;
o sinal desce na mesma proporção. Não se manda junto com discount_percent. Com "waive_deposit": true esta venda não cobra sinal.
O campo deposit_method diz como o sinal será pago:
"link" (o padrão) devolve o payment_url; com
"pix" o cliente paga o sinal por Pix direto na chave da loja, nenhuma cobrança é
criada e o horário fica segurado por 72 h (prazo que cair no sábado ou domingo vai para segunda às 13h)
(hold_expires_at). Quando o comprovante chegar, marque a caução como paga no
painel e o agendamento é confirmado; sem isso, o horário volta a ficar livre no fim do prazo. Com Pix
o e-mail do cliente não é obrigatório.
O link da caução EXPIRA em 24h - `payment-link` gera outro reusando o mesmo pedido, em vez de criar uma cobrança nova a cada reenvio. É o que permite um bot marcar hoje e reenviar amanhã sem desmarcar.
A busca de cliente responde 200 com found: false
quando o contato não é cliente - não é um erro, é a resposta à pergunta. O telefone é
normalizado, e o código do país que o WhatsApp manda (55) é tratado. A resposta traz o saldo de
horas do kit e se o cliente dispensa caução.
A resposta traz o agendamento e, quando o atendimento tem caução,
payment_url - o link da Stripe para mandar na conversa. Enquanto ele não é
pago o horário fica RESERVADO até hold_expires_at e depois volta a ficar
livre sozinho. Atendimento gratuito nasce confirmed na hora e sem link.
Fechar um horário da agenda (manutenção, feriado, evento), o mesmo bloqueio de Configurar agenda:
POST /api/v1/blocks
{"starts_at": "2026-11-16T10:00", "ends_at": "2026-11-16T11:00",
"reason": "Limpeza do ar-condicionado", "resource_id": null}
Sem resource_id vale para todas as salas. O horário sai da vitrine e
dos slots na hora e vai para o Google Agenda. Bloquear NÃO desmarca ninguém: quem já estava marcado
no intervalo volta em overlapping_bookings para você decidir. Um bloqueio
importado de calendário (.ics) não se apaga por aqui (409); remova-o na origem.
Desmarcar libera o horário e NÃO estorna a caução: quanto volta depende da política da loja, e isso continua sendo feito na tela de vendas.
Kits (pacotes)
GET /api/v1/kits
POST /api/v1/kits
PATCH /api/v1/kits/<id>
POST /api/v1/kits
{"name": "32 horas de gravação", "slug": "32-horas-de-gravacao", "discount_percent": 20,
"items": [{"custom_product_id": 953, "quantity": 32}]}
Cada item é um produto próprio (custom_product_id) ou uma carta do
estoque (selling_id) da PRÓPRIA loja; um item de outra loja é recusado. O
PATCH muda só os campos enviados (nome, descrição, desconto, ativo) e não mexe nos
itens. A resposta traz o preço cheio e o preço com desconto, calculados com os preços atuais dos
componentes.
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.shipped, order.refunded, return.requested,
return.resolved, booking.created, booking.canceled,
booking.rescheduled,
booking.reminder, subscription.activated,
subscription.renewed, subscription.past_due,
subscription.canceled, subscription.expired, além de
ping (evento de teste).
Os eventos de assinatura carregam o mesmo objeto que
GET /api/v1/subscriptions/<id>. subscription.activated é a
primeira cobrança confirmada; subscription.renewed, cada uma das seguintes
(com current_period_end um ciclo à frente). Cada cobrança também chega como order.paid.
Os eventos de agendamento carregam o mesmo objeto que
GET /api/v1/bookings/<id>. booking.reminder sai uma vez por
agendamento, cerca de 24h antes da hora marcada - é o gancho para mandar a lembrança no WhatsApp
pelo n8n. NÃO existe um evento separado de "sinal pago": quando a caução cai, chega o
order.paid de sempre, e a linha dele traz o booking_id
do agendamento que acabou de ser confirmado.
Os eventos de devolução carregam return_id,
order_id, resolution e refund_cents.
Uma devolução parcial NÃO muda o status do pedido, que continua paid -
o valor devolvido aparece em refunded_cents no pedido.
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.
Conectando com o n8n
O n8n fala HTTP puro, então não precisa de nada especial dos dois lados: um nó HTTP Request chama esta API, e um nó Webhook recebe os nossos eventos.
Nó pronto: montar o carrinho e pegar o link
Copie o bloco abaixo e cole direto na tela do n8n (Ctrl+V no canvas cria o nó).
Troque a chave e o domínio, e ligue a saída dele no seu nó de WhatsApp ou e-mail - o link
fica em url.
{
"nodes": [
{
"parameters": {
"method": "POST",
"url": "https://SEU-DOMINIO/api/v1/carts",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{ "name": "Authorization", "value": "Bearer crk_live_SUA_CHAVE" }
]
},
"sendBody": true,
"specifyBody": "json",
"jsonBody": "={{ JSON.stringify({ items: [ { selling_id: 123, quantity: 4 } ] }) }}",
"options": {}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [0, 0],
"name": "Criar carrinho"
}
],
"connections": {}
}
Para montar a lista a partir do que veio antes no fluxo, troque o
conteúdo de items por uma expressão que devolva a mesma forma - por
exemplo mapeando as linhas de uma planilha para
{ selling_id, quantity }.
Nó pronto: marcar horário e pegar o link da caução
Mesma ideia, para a agenda. A resposta traz payment_url quando o
atendimento tem caução - é esse link que vai na conversa. Um atendimento gratuito devolve
null ali e já nasce confirmado, então ramifique nesse campo em vez de assumir
que sempre há cobrança.
{
"nodes": [
{
"parameters": {
"method": "POST",
"url": "https://SEU-DOMINIO/api/v1/bookings",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{ "name": "Authorization", "value": "Bearer crk_live_SUA_CHAVE" }
]
},
"sendBody": true,
"specifyBody": "json",
"jsonBody": "={{ JSON.stringify({ service_id: 3, starts_at: '2026-09-01T14:00', customer_name: $json.nome, customer_phone: $json.telefone, customer_email: $json.email }) }}",
"options": {}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [0, 0],
"name": "Marcar horario"
}
],
"connections": {}
}
Antes deste nó, chame
GET /api/v1/booking-services/<id>/slots para oferecer à pessoa só os
horários que existem de verdade - a API recusa qualquer outro com 409, e é melhor não oferecer do
que oferecer e voltar atrás.
Recebendo nossos eventos no n8n
Crie um nó Webhook (método POST), copie a URL de produção dele e cole em
Configurações → Webhooks. Confira a assinatura antes de
confiar no conteúdo, num nó Code logo depois:
const crypto = require('crypto');
const segredo = 'SEU_SEGREDO_DE_WEBHOOK';
const corpo = JSON.stringify($input.first().json.body);
const esperado = crypto.createHmac('sha256', segredo).update(corpo).digest('hex');
const recebido = $input.first().json.headers['x-cardsrealm-signature'];
if (esperado !== recebido) { throw new Error('assinatura invalida'); }
return $input.all();
Ative "Raw body" no nó Webhook se a sua versão do n8n reordenar as chaves do JSON: a assinatura é calculada sobre os bytes exatos que enviamos, então qualquer reserialização pelo caminho muda o resultado.
Erros
Respostas de erro sempre têm o formato {"error": "mensagem"} com o código HTTP apropriado (400, 401, 404, 429).