Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Bônus e promo codes ​

Carregando a demo interativa…

A demo acima usa createIgaming(enginex) sobre um cliente com createMockFetch(withIgamingRoutes()): nenhuma chamada sai para a rede. Veja a vitrine pública, entre, participe da campanha de boas-vindas (optIn com o aceite dos termos) e resgate o prêmio (claim); no cenário de promo code, resolva e resgate BEMVINDO. O cenário Not eligible mostra BONUS_NOT_ELIGIBLE chegando com HTTP 500: identifique pelo código, nunca pelo status. No painel Under the hood, o promo code aparece mascarado e as idempotencyKey de optIn, claim e redeemPromoCode ficam visíveis.

O namespace bonus de @getenginex/sdk-igaming cobre as campanhas de bônus do operador: a vitrine pública, as ofertas do jogador, a entrada (opt-in), o resgate do prêmio (claim) e os promo codes. Só listPublicOffers é público; os demais métodos exigem login. Em testes, withIgamingRoutes já responde a todas estas rotas (veja Testes).

Ofertas ​

ts
// Showcase (no login): only describes the campaigns.
const showcase = await igaming.bonus.listPublicOffers()

// Logged in: the offers available to the player.
const { items, nextCursor } = await igaming.bonus.listOffers({ pageSize: 20 })
const offer = await igaming.bonus.getOffer({ campaignId: items[0].campaignId })

As listagens de bônus são paginadas por cursor (diferente do catálogo do cassino; veja Paginação): recebem CursorPageInput (cursor, pageSize) e devolvem CursorPage (items, nextCursor), tipos do core. Passe o nextCursor da página anterior como cursor; sem nextCursor, acabou.

ts
let cursor: string | undefined
do {
  const page = await igaming.bonus.listOffers({ cursor })
  render(page.items)
  cursor = page.nextCursor
} while (cursor)

Uma oferta (CampaignOffer) diz:

  • como entrar — offer.entryPolicy?.code: automatic (o jogador entra sozinho ao cumprir a qualificação), opt_in (botão "participar", com optIn), promo_code (com redeemPromoCode) ou manual;
  • como receber o prêmio — offer.rewardClaimPolicy?.code: automatic ou player_claim (botão "resgatar", com claim);
  • o que é preciso — offer.qualification (um de immediate, depositSettled, userEvent, activityAggregate);
  • o prêmio — offer.reward: rewardKind diz qual detalhe vem preenchido (balanceCredit, casinoFreeSpins, sportsBonusBet, sportsBetCoverage), mais rollover (wageringPolicy) e onde o saldo de bônus vale (usePolicy);
  • os textos — offer.content.localizedContent: nome, descrição e termos por idioma.
ts
import { formatMoney } from '@getenginex/sdk'
import type { CampaignOffer } from '@getenginex/sdk-igaming'

function texts(offer: CampaignOffer, locale: string) {
  const content = offer.content
  return (
    content?.localizedContent.find((c) => c.locale === locale) ??
    content?.localizedContent.find((c) => c.locale === content.defaultLocale)
  )
}

const credit = offer.reward?.balanceCredit?.fixedAmount?.amount // { amount: 5000, currency: 'BRL' }
if (credit) formatMoney(credit.amount, config.currency) // 'R$ 50,00'

Formato dos campos

O gateway escreve as campanhas no formato do protobuf. O SDK entrega em camelCase, com os enums sem o prefixo e em minúsculas (ENTRY_POLICY_CODE_OPT_IN → opt_in), o dinheiro em number (unidades menores), as durações em segundos e o valor zero no lugar do que o protobuf omite ('', 0, [], 'unspecified'). Objetos (janelas, políticas, prêmio, textos) podem vir ausentes: use ?.. Um enum novo passa adiante no mesmo formato — trate o caso padrão.

Estabilidade (0.x)

A árvore de detalhes do prêmio, da qualificação e das políticas (uso do saldo, rollover, acúmulo, odds, aposta máxima, recortes de cassino/esporte, perfis de execução e os campos version) espelha o protobuf do serviço de bônus e pode mudar em versões minor 0.x — esses tipos estão marcados como @beta na referência. A parte estável é: os campos de primeiro nível de CampaignOffer e CampaignParticipation, o status da participação, os códigos de entrada (entryPolicy.code) e de resgate (rewardClaimPolicy.code), content (textos), os inputs e os métodos.

Participar (opt-in) e resgatar (claim) ​

optIn e claim são idempotentes: o SDK manda uma Idempotency-Key por chamada e a mantém no retry interno após renovar a sessão. Para que um segundo clique ou uma nova tentativa depois de uma falha de rede não duplique a operação, gere a chave uma vez por intenção e reuse-a (como no depósito):

ts
import { isEnginexError } from '@getenginex/sdk'

const key = crypto.randomUUID() // one per click on "join"
const text = texts(offer, 'pt-BR')

try {
  const participation = await igaming.bonus.optIn(
    {
      campaignId: offer.campaignId,
      campaignVersionId: offer.campaignVersionId, // the version the player saw
      termsAcceptance: text && { locale: text.locale, termsRevision: text.termsRevision },
    },
    { idempotencyKey: key },
  )
  participation.status // 'enrolled' | 'qualifying' | 'qualified' | ...
} catch (e) {
  if (isEnginexError(e, 'BONUS_NOT_ELIGIBLE')) showNotEligible()
  else if (isEnginexError(e, 'BONUS_EXPIRED')) showExpired()
  else if (isEnginexError(e, 'KYC_REQUIRED')) goToKyc()
  else throw e
}

Quando a participação chega a qualified numa campanha player_claim, mostre o botão de resgate:

ts
const { items } = await igaming.bonus.listParticipations()
for (const p of items.filter((p) => p.status === 'qualified')) {
  const done = await igaming.bonus.claim({ participationId: p.id }, { idempotencyKey: claimKeys.get(p.id) })
  done.status // 'completed' (or 'reward_pending' while the reward is being granted)
}

A participação (CampaignParticipation) traz status, os timestamps do estado (qualifiedAt, completedAt, expiredAt) e, em snapshot, o prêmio, os textos e o aceite dos termos como estavam quando o jogador entrou.

As respostas de optIn, claim e redeemPromoCode são validadas sempre em modo estrito, mesmo com validation: 'warn' no cliente. Se vier VALIDATION_ERROR, a operação pode ter acontecido: consulte listParticipations/getParticipation antes de tentar de novo (ou repita com a mesma chave).

Promo codes ​

Primeiro mostre a oferta do código (nome, descrição e termos no idioma pedido); depois resgate:

ts
const { offer, localizedContent } = await igaming.bonus.resolvePromoCode({ code: input.value, locale: 'pt-BR' })
showOffer(localizedContent.displayName, localizedContent.terms)

const participation = await igaming.bonus.redeemPromoCode(
  { code: input.value, termsAcceptance: { locale: localizedContent.locale, termsRevision: localizedContent.termsRevision } },
  { idempotencyKey: key },
)
  • resolvePromoCode não entra na campanha; redeemPromoCode entra (e é idempotente: o gateway exige a chave).
  • O código é um segredo de baixa entropia: o SDK o manda só no corpo (nunca na URL nem nos hooks), e o gateway limita as tentativas por jogador (o mesmo limite vale para resolvePromoCode e redeemPromoCode) — RESOURCE_EXHAUSTED (429): espere e.retryAfter segundos antes de deixar o jogador tentar de novo. Não o registre em logs.
  • Se o limitador do gateway estiver fora do ar, as duas rotas fecham por segurança: UNAVAILABLE (503). Mostre "tente mais tarde", sem repetir em laço.

Erros ​

CódigoQuando
BONUS_NOT_FOUND (404)campanha, participação ou promo code inexistente (ou de outro jogador)
BONUS_ALREADY_CLAIMED (409)prêmio já resgatado; promo code já usado
ALREADY_EXISTS (409)o jogador já participa da campanha
BONUS_NOT_ELIGIBLEo jogador não pode entrar/resgatar (ex.: ainda não qualificou)
BONUS_EXPIREDfora da janela de entrada ou de resgate
KYC_REQUIRED, FAILED_PRECONDITION (422)pré-condição do serviço de bônus (KYC, termos, versão da campanha)
INVALID_ARGUMENT (400)id que não é UUID, pageSize inválido, código vazio
KEY_IN_USE (409), PAYLOAD_MISMATCH (422)mesma idempotencyKey em processamento, ou já usada com outro corpo
RESOURCE_EXHAUSTED (429)muitas tentativas de promo code (veja e.retryAfter)
UNAVAILABLE (503)promo code com o limitador de tentativas do gateway fora do ar
UNAUTHENTICATED (401)métodos que exigem login, sem sessão

Status HTTP de BONUS_NOT_ELIGIBLE e BONUS_EXPIRED

O gateway ainda não mapeia esses dois códigos para um status próprio: eles chegam com HTTP 500. O código vem certo — identifique sempre com isEnginexError(error, code), nunca pelo status.

Testes ​

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
  tenantHost: 'casino.test',
  fetch: createMockFetch(withIgamingRoutes()),
})
const igaming = createIgaming(enginex)
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })

const { items } = await igaming.bonus.listOffers() // welcome (opt-in) and free spins (automatic)
const welcome = items.find((o) => o.entryPolicy?.code === 'opt_in')!
const p = await igaming.bonus.optIn({ campaignId: welcome.campaignId, campaignVersionId: welcome.campaignVersionId })
await igaming.bonus.claim({ participationId: p.id }) // status: 'completed'
await igaming.bonus.redeemPromoCode({ code: 'BEMVINDO' }) // status: 'enrolled'

O mock guarda estado por instância, repete a primeira resposta para a mesma Idempotency-Key e devolve os mesmos erros do gateway (BONUS_ALREADY_CLAIMED no segundo resgate, ALREADY_EXISTS no segundo opt-in, BONUS_NOT_ELIGIBLE no opt-in de campanha automática, BONUS_NOT_FOUND para código desconhecido).