ccriador.studio
Integração · API

API de cupom e comissão de criadores pro seu checkout

Com checkout próprio, o seu servidor faz três chamadas: confere se o cupom vale no checkout, registra a venda quando o pagamento é confirmado e desfaz a venda no reembolso. A comissão, a carência, as metas e as campanhas o criador.studio calcula sozinho.

Atualizado em

Três chamadas e pronto

1. No checkout: o cupom vale?
POST https://criador.studio/api/v1/coupons/check
Authorization: Bearer cs_live_…

{ "code": "CAROL15", "product": "primodock",
  "buyer_email": "cliente@exemplo.com" }      opcional

→ { "valid": true, "discount": 15 }
→ { "valid": true, "discount": 30, "campaign": "Black Friday" }
→ { "valid": false, "error": "own_coupon" }      o criador comprando com o próprio cupom
→ { "valid": false, "error": "limit_reached",
    "message": "O cupom CAROL15 esgotou: …",   mostre pro cliente
    "attribution": true }   sem desconto, mas mande o cupom na venda: ela é do criador
   outros: unknown_code, paused, unknown_product, inactive_product,
   campaign_off (cupom de campanha fora da campanha)
2. Pagou: registra a venda
POST https://criador.studio/api/v1/sales
Authorization: Bearer cs_live_…

{ "order": "9f2c…", "product": "primodock", "code": "CAROL15",
  "amount": 11900, "currency": "BRL", "method": "Pix",
  "buyer_email": "cliente@exemplo.com",      opcional: pega compra própria
  "subscription": "sub_81f…", "charge": 2 } opcional: renovações de assinatura

→ { "commission": 2380, "commission_pct": 20, "flags": [], "notes": [] }
   flags: own_purchase, over_limit, not_recurring
3. Devolveu: desfaz
POST https://criador.studio/api/v1/sales/9f2c…/refund
Authorization: Bearer cs_live_…

→ { "status": "reversed" }   comissão zerada, sai do próximo Pix
→ { "status": "reversed_after_payout", "debt": 2380 }
   já paga: R$ 23,80 descontados do próximo Pix
4. Trial ou cadastro: registra a conversão
POST https://criador.studio/api/v1/conversions
Authorization: Bearer cs_live_…

{ "event": "trial", "id": "acc_81f…", "product": "primodock",
  "code": "CAROL15", "buyer_email": "cliente@exemplo.com" }
   event: trial ou signup

→ { "rewarded": true, "bonus": 500, "status": "held" }
→ { "rewarded": false, "reason": "no_campaign" }   nenhuma campanha paga por isso
   outros: paused, own_coupon, repeat_customer, cap_reached
   falso? POST /v1/sales/trial:acc_81f…/refund
Mandar a mesma venda duas vezes não duplica nada. O valor vai em centavos, já com o desconto. As chamadas saem do seu servidor, nunca do app. Os campos opcionais: buyer_email pega o criador comprando com o próprio cupom (a gente nunca mostra o e-mail pra ele); subscription é o id da assinatura, igual em toda cobrança, e charge o número da cobrança (sem ele, a gente conta). Assim as renovações seguem a sua regra de assinaturas, em Regras do programa.

O básico

  • Autenticação: Authorization: Bearer cs_live_…, com a chave criada no painel, em Integração.
  • Valores em centavos, já com o desconto do cupom. Venda em dólar entra convertida pela PTAX do Banco Central no dia.
  • Assinatura: mande o mesmo subscription em toda cobrança, e a regra da marca decide a comissão de cada renovação.
  • Trial ou cadastro: POST /v1/conversions, que só paga enquanto uma campanha pagar por isso.

A referência completa, com cada campo e cada erro, está em /llms.txt, num formato que também serve pra colar no seu assistente de código.

Perguntas

Posso chamar a API do app ou do navegador?
Não. A chave dá acesso ao programa da marca, então as chamadas saem do seu servidor. No app, o servidor registra a venda quando confirmar a compra.
Mandar a mesma venda duas vezes duplica?
Não. A venda é única pelo número do pedido: a segunda chamada devolve a mesma venda, com 200 em vez de 201.
Tem como testar sem bagunçar o mês?
Tem. As chaves cs_test_ registram vendas de teste, que aparecem só no registro da Integração e nunca contam como comissão.
Existe um conector de IA?
Existe um servidor MCP em criador.studio/mcp, com a mesma chave, pra perguntar ao Claude quanto vendeu ou quem precisa receber Pix.
Pegue as chaves de teste e ligue hoje.14 dias grátis, sem cartão. O dinheiro continua indo direto pra você.Testar 14 dias grátis