Bonos y promo codes
Cargando la demo interactiva…
La demo de arriba usa createIgaming(enginex) sobre un cliente con createMockFetch(withIgamingRoutes()): ninguna llamada sale a la red. Mira la vitrina pública, inicia sesión, participa en la campaña de bienvenida (optIn con la aceptación de los términos) y canjea el premio (claim); en el escenario de promo code, resuelve y canjea BEMVINDO. El escenario Not eligible muestra BONUS_NOT_ELIGIBLE llegando con HTTP 500: identifícalo por el código, nunca por el estado. En el panel Under the hood, el promo code aparece enmascarado y las idempotencyKey de optIn, claim y redeemPromoCode quedan visibles.
El namespace bonus de @getenginex/sdk-igaming cubre las campañas de bonos del operador: la vitrina pública, las ofertas del jugador, la entrada (opt-in), el canje del premio (claim) y los promo codes. Solo listPublicOffers es público; los demás métodos exigen inicio de sesión. En pruebas, withIgamingRoutes ya responde todas estas rutas (consulta Pruebas).
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 })Los listados de bonos se paginan por cursor (a diferencia del catálogo del casino; consulta Paginación): reciben CursorPageInput (cursor, pageSize) y devuelven CursorPage (items, nextCursor), tipos del core. Pasa el nextCursor de la página anterior como cursor; sin nextCursor, se acabó.
let cursor: string | undefined
do {
const page = await igaming.bonus.listOffers({ cursor })
render(page.items)
cursor = page.nextCursor
} while (cursor)Una oferta (CampaignOffer) indica:
- cómo entrar —
offer.entryPolicy?.code:automatic(el jugador entra solo al cumplir la calificación),opt_in(botón "participar", conoptIn),promo_code(conredeemPromoCode) omanual; - cómo recibir el premio —
offer.rewardClaimPolicy?.code:automaticoplayer_claim(botón "canjear", conclaim); - qué se necesita —
offer.qualification(uno deimmediate,depositSettled,userEvent,activityAggregate); - el premio —
offer.reward:rewardKindindica qué detalle viene completo (balanceCredit,casinoFreeSpins,sportsBonusBet,sportsBetCoverage), además del rollover (wageringPolicy) y dónde vale el saldo de bono (usePolicy); - los textos —
offer.content.localizedContent: nombre, descripción y términos 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 de los campos
El gateway escribe las campañas en formato protobuf. El SDK las entrega en camelCase, con los enums sin el prefijo y en minúsculas (ENTRY_POLICY_CODE_OPT_IN → opt_in), el dinero como number (unidades menores), las duraciones en segundos y el valor cero en lugar de lo que protobuf omite ('', 0, [], 'unspecified'). Los objetos (ventanas, políticas, premio, textos) pueden faltar: usa ?.. Un enum nuevo pasa tal cual en el mismo formato: maneja el caso por defecto.
Estabilidad (0.x)
El árbol de detalles del premio, de la calificación y de las políticas (uso del saldo, rollover, acumulación, cuotas, apuesta máxima, recortes de casino/deportes, perfiles de ejecución y los campos version) refleja el protobuf del servicio de bonos y puede cambiar en versiones minor 0.x: esos tipos están marcados como @beta en la referencia. La parte estable es: los campos de primer nivel de CampaignOffer y CampaignParticipation, el status de la participación, los códigos de entrada (entryPolicy.code) y de canje (rewardClaimPolicy.code), content (textos), los inputs y los métodos.
Participar (opt-in) y canjear (claim)
optIn y claim son idempotentes: el SDK envía una Idempotency-Key por llamada y la mantiene en el reintento interno tras renovar la sesión. Para que un segundo clic, o un nuevo intento después de una falla de red, no duplique la operación, genera la clave una vez por intención y reutilízala (como en el 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
}Cuando la participación llega a qualified en una campaña player_claim, muestra el botón de canje:
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)
}La participación (CampaignParticipation) trae status, las marcas de tiempo del estado (qualifiedAt, completedAt, expiredAt) y, en snapshot, el premio, los textos y la aceptación de los términos tal como estaban cuando el jugador entró.
Las respuestas de optIn, claim y redeemPromoCode se validan siempre en modo estricto, incluso con validation: 'warn' en el cliente. Si llega VALIDATION_ERROR, la operación pudo haberse realizado: consulta listParticipations/getParticipation antes de intentar de nuevo (o repite con la misma clave).
Promo codes
Primero muestra la oferta del código (nombre, descripción y términos en el idioma pedido); luego canjea:
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 },
)resolvePromoCodeno entra a la campaña;redeemPromoCodesí (y es idempotente: el gateway exige la clave).- El código es un secreto de baja entropía: el SDK lo envía solo en el cuerpo (nunca en la URL ni en los hooks), y el gateway limita los intentos por jugador (el mismo límite vale para
resolvePromoCodeyredeemPromoCode) —RESOURCE_EXHAUSTED(429): esperae.retryAftersegundos antes de dejar que el jugador intente de nuevo. No lo registres en logs. - Si el limitador del gateway está caído, las dos rutas se cierran por seguridad:
UNAVAILABLE(503). Muestra "inténtalo más tarde", sin repetir en bucle.
Errores
| Código | Cuándo |
|---|---|
BONUS_NOT_FOUND (404) | campaña, participación o promo code inexistente (o de otro jugador) |
BONUS_ALREADY_CLAIMED (409) | premio ya canjeado; promo code ya usado |
ALREADY_EXISTS (409) | el jugador ya participa en la campaña |
BONUS_NOT_ELIGIBLE | el jugador no puede entrar/canjear (p. ej., aún no calificó) |
BONUS_EXPIRED | fuera de la ventana de entrada o de canje |
KYC_REQUIRED, FAILED_PRECONDITION (422) | precondición del servicio de bonos (KYC, términos, versión de la campaña) |
INVALID_ARGUMENT (400) | id que no es UUID, pageSize inválido, código vacío |
KEY_IN_USE (409), PAYLOAD_MISMATCH (422) | misma idempotencyKey en proceso, o ya usada con otro cuerpo |
RESOURCE_EXHAUSTED (429) | demasiados intentos de promo code (consulta e.retryAfter) |
UNAVAILABLE (503) | promo code con el limitador de intentos del gateway caído |
UNAUTHENTICATED (401) | métodos que exigen inicio de sesión, sin sesión |
Estado HTTP de BONUS_NOT_ELIGIBLE y BONUS_EXPIRED
El gateway aún no asigna a estos dos códigos un estado propio: llegan con HTTP 500. El código viene correcto — identifícalos siempre con isEnginexError(error, code), nunca por status.
Pruebas
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'El mock guarda estado por instancia, repite la primera respuesta para la misma Idempotency-Key y devuelve los mismos errores del gateway (BONUS_ALREADY_CLAIMED en el segundo canje, ALREADY_EXISTS en el segundo opt-in, BONUS_NOT_ELIGIBLE en el opt-in de una campaña automática, BONUS_NOT_FOUND para un código desconocido).