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
// 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.
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", comoptIn),promo_code(comredeemPromoCode) oumanual; - como receber o prêmio —
offer.rewardClaimPolicy?.code:automaticouplayer_claim(botão "resgatar", comclaim); - o que é preciso —
offer.qualification(um deimmediate,depositSettled,userEvent,activityAggregate); - o prêmio —
offer.reward:rewardKinddiz 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.
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):
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:
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:
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 },
)resolvePromoCodenão entra na campanha;redeemPromoCodeentra (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
resolvePromoCodeeredeemPromoCode) —RESOURCE_EXHAUSTED(429): esperee.retryAftersegundos 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ódigo | Quando |
|---|---|
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_ELIGIBLE | o jogador não pode entrar/resgatar (ex.: ainda não qualificou) |
BONUS_EXPIRED | fora 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
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).