Loja e moedas

Moedas e loja são a camada de gamificação com valor real. O usuário acumula moedas participando da comunidade e as troca por itens numa loja. O diferencial da Cativa é que o pedido tem um ciclo de vida que você conecta ao seu próprio fulfillment (enviar um brinde físico, liberar um cupom, disparar uma integração).

Os dois lados

MOEDAS (Wallets)                          LOJA (Store)
carteira do usuário       ──troca por──>  itens da loja
saldo + extrato                           pedido (order)

Ganho de moedas:                          Ciclo do pedido:
- engajamento na comunidade               criado ──> approve / reject
- crédito via admin/integração                    ──> fulfill / refund

Moedas são a economia interna. O usuário ganha moedas por engajamento e você também pode creditar saldo via admin ou integração (ex: bônus por compra externa). A loja troca esse saldo por itens. Cada resgate vira um pedido, e o pedido passa por um ciclo que é o gancho de integração para o fulfillment. Pense nas moedas como os tíquetes de um parque de diversões: o visitante ganha tíquetes brincando e os troca por um brinde no balcão de prêmios. O pedido é o comprovante do balcão; aprovar, entregar o brinde e (se faltou no estoque) devolver os tíquetes são as etapas que você controla.

Base URL e autenticação

Todas as rotas ficam na API da Cativa:

https://apis.cativalab.digital/tenant/api/v2

Autentique com sua API Key no header:

Authorization: Bearer cativa_live_...

Nunca exponha sua API Key no frontend nem a comite no repositório. Use YOUR_API_KEY como placeholder e injete o valor real por variável de ambiente.

Moedas (Wallets)

O saldo e o extrato vivem na carteira do usuário.

Rota	O que faz
`GET /monetization/wallet/coins`	Saldo de moedas do usuário
`GET /monetization/wallet/history`	Extrato (histórico de ganhos e gastos)

Do lado admin, você credita saldo e consulta a carteira de qualquer usuário (por id ou por email). Veja os endpoints e os campos exatos na API Reference, tag Wallets.

Consultar o saldo do usuário

curl https://apis.cativalab.digital/tenant/api/v2/monetization/wallet/coins \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://apis.cativalab.digital/tenant/api/v2/monetization/wallet/coins",
  {
    headers: { Authorization: `Bearer ${process.env.YOUR_API_KEY}` },
  }
);

const wallet = await res.json();

Resposta ilustrativa (o schema autoritativo fica na API Reference, tag Wallets). balance é o saldo de moedas do usuário, em unidades inteiras:

{
  "balance": 1250
}

A estrutura exata da resposta (nomes dos campos de saldo, moeda, extrato) está na API Reference. Consulte as tags Wallets e Store em vez de assumir o shape aqui.

Loja (Store)

O usuário navega pelas lojas, vê os itens e resgata com moedas.

Rota	O que faz
`GET /monetization/stores`	Lista as lojas
`GET /monetization/stores/{storeId}/items`	Itens de uma loja
`GET /monetization/stores/items/{itemId}`	Detalhe de um item
`POST /monetization/stores/items/{itemId}/purchase`	Resgata o item com moedas
`GET /monetization/stores/my-orders`	Pedidos do usuário

Os IDs (storeId, itemId, orderId) são ULID. Do lado admin, você gerencia lojas e itens e opera os pedidos:

POST /admin/monetization/stores · PUT / DELETE /admin/monetization/stores/{storeId}
POST /admin/monetization/stores/{storeId}/items · PUT / DELETE /admin/monetization/stores/items/{itemId}
GET /admin/monetization/stores/orders · GET /admin/monetization/stores/orders/{orderId}

O ciclo do pedido

Quando o usuário resgata um item, nasce um pedido. Esse pedido percorre um ciclo, e cada transição é uma ação admin:

criado ──> approve  ──> fulfill
       └─> reject       └─> refund

approve / reject: você valida o resgate (estoque, elegibilidade, antifraude) e aprova ou recusa.
fulfill: você marca o pedido como entregue. Esse é o ponto onde o fulfillment externo acontece: enviar o brinde físico, gerar o cupom, chamar sua integração de logística.
refund: devolve as moedas ao usuário quando o item não pode ser entregue.

As ações admin de pedido ficam em:

POST /admin/monetization/stores/orders/{orderId}/approve
POST /admin/monetization/stores/orders/{orderId}/reject
POST /admin/monetization/stores/orders/{orderId}/fulfill
POST /admin/monetization/stores/orders/{orderId}/refund

O fluxo típico de um resgate, do clique do usuário ao fechamento:

Usuário resgata

POST /monetization/stores/items/{itemId}/purchase debita as moedas e cria o pedido em estado inicial.

Você valida e aprova

POST /admin/monetization/stores/orders/{orderId}/approve (ou reject) depois de checar estoque, elegibilidade e antifraude.

Você entrega e conclui

Rode seu fulfillment externo (enviar o brinde, gerar o cupom) e feche com POST .../fulfill.

Se algo falhar, devolva

POST .../refund estorna as moedas ao usuário quando o item não pode ser entregue.

Trate fulfill como o webhook da sua operação. Ao aprovar um pedido, dispare seu processo de entrega; ao concluir a entrega externa, chame fulfill para fechar o ciclo. Se a entrega falhar, use refund para devolver as moedas.

Aprovar e concluir um pedido

# 1. aprova o resgate
curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/monetization/stores/orders/01J8Z9K3M4N5P6Q7R8S9T0V1W2/approve \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. após entregar o item externamente, marca como concluído
curl -X POST \
  https://apis.cativalab.digital/tenant/api/v2/admin/monetization/stores/orders/01J8Z9K3M4N5P6Q7R8S9T0V1W2/fulfill \
  -H "Authorization: Bearer YOUR_API_KEY"

const base =
  "https://apis.cativalab.digital/tenant/api/v2/admin/monetization/stores/orders";
const orderId = "01J8Z9K3M4N5P6Q7R8S9T0V1W2";
const headers = { Authorization: `Bearer ${process.env.YOUR_API_KEY}` };

// 1. aprova o resgate
await fetch(`${base}/${orderId}/approve`, { method: "POST", headers });

// 2. após entregar o item externamente, marca como concluído
await fetch(`${base}/${orderId}/fulfill`, { method: "POST", headers });

Resposta ilustrativa de um pedido após approve (o schema autoritativo fica na API Reference, tag Store). O status reflete a etapa do ciclo:

{
  "orderId": "01J8Z9K3M4N5P6Q7R8S9T0V1W2",
  "status": "approved",
  "itemId": "01J8ITEM4567890ABCDEFGHJKM",
  "userId": "01HQ0USER1234567890ABCDEF",
  "coinsSpent": 500,
  "createdAt": "2026-07-10T14:00:00Z"
}

Os campos de resposta de cada rota (status do pedido, valores, timestamps) estão na API Reference, tags Store e Wallets. Não assuma o shape a partir dos exemplos acima.

Erros comuns e dúvidas

O resgate falhou por saldo insuficiente

purchase só cria o pedido se o usuário tem moedas suficientes para o item. Sem saldo, a chamada é recusada e nenhum pedido nasce. Consulte GET /monetization/wallet/coins antes, ou credite saldo pelo endpoint admin (tag Wallets) se a regra do seu programa permitir.

O pedido travou em aprovado e nunca foi entregue

approve só valida o resgate; ele não entrega nada sozinho. A entrega é o seu fulfillment externo, e é você quem chama fulfill ao concluir. Um pedido aprovado e nunca fulfill-ado fica em aberto de propósito, esperando sua operação fechar o ciclo.

As moedas foram debitadas mas o item não pôde ser entregue

Use refund. Ele estorna as moedas do pedido de volta à carteira do usuário. É a saída correta quando o estoque acabou ou a integração de logística falhou depois do débito.

Chamei approve duas vezes, dobrou alguma coisa?

As transições de pedido são idempotentes por estado: reaplicar approve num pedido já aprovado não cria um segundo pedido nem debita de novo. Isso torna seguro dar retry nas ações admin em jobs.

Quero liberar acesso a um grupo, não entregar um item físico

A loja entrega itens; ela não é o mecanismo de acesso. Para liberar grupo, curso ou espaço, use badge como permissão (veja badges como permissão). Moedas e acesso são camadas separadas.

Como isso se conecta

Para creditar moedas por uma ação externa (compra, indicação, brinde), use os endpoints admin de crédito por id ou email (tag Wallets).
Para liberar acesso em vez de entregar item físico, o mecanismo é outro: veja badges como permissão.
Para entender quem é o usuário dono da carteira e do pedido, veja identidade e usuários.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Os dois lados

Base URL e autenticação

Moedas (Wallets)

Consultar o saldo do usuário

Loja (Store)

O ciclo do pedido

Aprovar e concluir um pedido

Erros comuns e dúvidas

Como isso se conecta

​Os dois lados

​Base URL e autenticação

​Moedas (Wallets)

​Consultar o saldo do usuário

​Loja (Store)

​O ciclo do pedido

​Aprovar e concluir um pedido

​Erros comuns e dúvidas

​Como isso se conecta

Os dois lados

Base URL e autenticação

Moedas (Wallets)

Consultar o saldo do usuário

Loja (Store)

O ciclo do pedido

Aprovar e concluir um pedido

Erros comuns e dúvidas

Como isso se conecta