Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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 ​

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 })

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ó.

ts
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", con optIn), promo_code (con redeemPromoCode) o manual;
  • cómo recibir el premio — offer.rewardClaimPolicy?.code: automatic o player_claim (botón "canjear", con claim);
  • qué se necesita — offer.qualification (uno de immediate, depositSettled, userEvent, activityAggregate);
  • el premio — offer.reward: rewardKind indica 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.
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 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):

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
}

Cuando la participación llega a qualified en una campaña player_claim, muestra el botón de canje:

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)
}

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:

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 no entra a la campaña; redeemPromoCode sí (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 resolvePromoCode y redeemPromoCode) — RESOURCE_EXHAUSTED (429): espera e.retryAfter segundos 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ódigoCuá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_ELIGIBLEel jugador no puede entrar/canjear (p. ej., aún no calificó)
BONUS_EXPIREDfuera 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 ​

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'

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).