Referidos
El historial de referidos, con el correo enmascarado, aparece en la demo de Fidelización (escenario Referrals).
El namespace referrals de @getenginex/sdk-igaming muestra el código y el enlace de referido del jugador, el historial de referidos y registra el código de otro jugador. Los tres métodos exigen inicio de sesión. En pruebas, withIgamingRoutes ya responde las tres rutas (consulta Pruebas).
Código y enlace
const referral = await igaming.referrals.get()
console.log(referral.code, referral.link)
console.log(referral.totalReferrals, referral.completedReferrals, referral.pendingReferrals)
console.log(referral.totalEarned, referral.bonusPerReferral, referral.minDeposit)ReferralInfo trae:
| Campo | Qué es |
|---|---|
code, link | código y enlace de referido del jugador; null cuando el gateway envía vacío |
totalReferrals, completedReferrals, pendingReferrals | contadores (enteros) |
totalEarned | total ganado con referidos, en unidades menores |
bonusPerReferral | bono por referido, en unidades menores |
minDeposit | depósito mínimo del referido, en unidades menores |
El contrato (bonus.proto) no dice cuándo un referido cuenta como completed (por ejemplo, si exige un depósito mínimo) ni si totalEarned incluye bonos aún pendientes. La descripción del campo minDeposit como "depósito mínimo del referido" es una suposición, no confirmada por el contrato. Confirma la regla con el operador antes de prometerla en pantalla.
Valores en unidades menores
El gateway escribe el dinero de los referidos como float en la unidad mayor (centavos divididos entre 100, p. ej.: 19.99). El SDK lo convierte todo de vuelta a unidades menores enteras, como el resto del SDK (consulta Dinero): Math.round(valor * 100), con las mitades redondeadas alejándose del cero.
| El gateway envía | El SDK devuelve |
|---|---|
19.99 | 1999 |
0.1 + 0.2 (0.30000000000000004) | 30 |
1e-7 | 0 |
-19.99 | -1999 (el signo se conserva) |
-0.005 | -1 (simétrico a 0.005 → 1; nunca -0) |
La conversión vale para totalEarned, bonusPerReferral y minDeposit de get, referrerBonus y refereeBonus de cada referido, totalEarned del historial y refereeBonus del registro. Un valor que no es un número finito, o que no cabe en un entero seguro después de ×100, se rechaza con VALIDATION_ERROR en validation: 'strict' (en 'warn' el campo llega crudo y se avisa a onValidationIssue, sin el valor). Excepción en el historial: en 'warn', un referido cuyo referrerBonus o refereeBonus no se convierte a unidades menores se descarta de items (y se reporta), para nunca mostrar la unidad mayor en un campo de unidades menores. La moneda no viene incluida: usa la del operador.
Historial
const history = await igaming.referrals.listHistory({ page: 1, perPage: 20 })
for (const r of history.items) {
console.log(r.refereeName, r.refereeEmailMasked, r.status, r.referrerBonus, r.createdAt)
}
console.log(history.totalItems, history.totalPages, history.completedCount, history.totalEarned)listHistory devuelve Page<Referral> (items, page, perPage, totalItems, totalPages; consulta Paginación) más completedCount y totalEarned, que valen para todas las páginas. page es un entero ≥ 1 y perPage un entero de 1 a 100; fuera de eso se rechaza con CONFIGURATION_ERROR, sin request.
A diferencia de las misiones, el gateway envía la paginación dentro de data (pagination.page, page_size, total_items, total_pages), no en el meta del envelope. El SDK arma el Page a partir de ella y la refuerza: page_size pasa a perPage, totalPages se calcula (0 sin ítems) y totalItems nunca queda por debajo de los ítems ya vistos. Contadores negativos o fraccionarios se rechazan con VALIDATION_ERROR en strict. Una página más allá del final devuelve items: []. Si el gateway no envía la paginación, valen la página y el tamaño pedidos.
Referral:
| Campo | Qué es |
|---|---|
id, code | id del referido y código usado |
refereeName | nombre del referido; null cuando está vacío |
refereeEmailMasked | correo del referido enmascarado (consulta abajo); null si está vacío o es inválido |
status | pending, qualified, completed o expired (unión abierta) |
referrerBonus, refereeBonus | bono de quien refiere y del referido, en unidades menores |
createdAt, completedAt, expiresAt | ISO 8601 (UTC); completedAt/expiresAt son null cuando el gateway no los envía |
status viene de REFERRAL_STATUS_* del gateway, en minúsculas y sin el prefijo. Los cuatro valores vienen del bonus.proto; el gateway aún puede enviar unspecified (el cero del enum). Es una unión abierta: maneja el caso por defecto. El contrato no describe qué lleva de pending a qualified y a completed ni qué causa expired; quien decide es el servicio de bonos.
Correo enmascarado y por qué
El gateway devuelve el referee_email del referido sin máscara. Es un dato personal de otra persona, y una pantalla de "mis referidos" no lo necesita completo. Por eso el SDK nunca lo expone: entrega solo refereeEmailMasked, con el primer carácter de la parte local y un * por cada carácter restante, y el dominio completo:
| Gateway | refereeEmailMasked |
|---|---|
ana@exemplo.com | a**@exemplo.com |
maria.silva@exemplo.com.br | m**********@exemplo.com.br |
a@exemplo.com | *@exemplo.com (parte local de 1 carácter: no muestra nada de ella) |
vacío, sin @, sin parte local o sin dominio | null |
El referee_id del gateway tampoco se expone. El correo crudo y el referee_id no aparecen en el resultado, en los issues de onValidationIssue ni en los errores del SDK, tampoco en validation: 'warn': cuando un ítem del historial falla por completo (p. ej., null), el core devuelve la lista cruda y el SDK rehace cada referido con las mismas reglas (máscara, estado en minúsculas, dinero en unidades menores), descartando lo que no es un objeto.
El nombre del referido es un dato personal
refereeName es el nombre tal como lo envía el gateway. Muéstralo solo en la pantalla del propio jugador y no lo registres en logs ni en analytics.
El raw del issue
En onValidationIssue, la propiedad raw trae el cuerpo completo de la respuesta, con las claves sensibles enmascaradas por el core. Hoy la máscara cubre las claves referee_email y referee_name (el nombre de la clave contiene email o name), pero no cubre referee_id, y raw es del core y está fuera de lo que controla este paquete: si tu hook envía el issue a un servicio externo, descarta raw.
Registrar un código
Para quien se está registrando, el código va directo en el registro, con auth.register({ referralCode }) del core (campo opcional). referrals.register sirve para quien ya tiene cuenta e ingresa el código después:
async function useCode(code: string) {
try {
const result = await igaming.referrals.register({ code })
console.log(result.id, result.status, result.refereeBonus, result.createdAt)
} catch (error) {
if (isEnginexError(error, 'UNAUTHENTICATED')) goToLogin()
else showMessage('Could not use this code') // the contract does not list the refusal codes
}
}- Entrada:
codees un texto no vacío (solo espacios también se rechaza; los espacios en los extremos se eliminan). Fuera de eso la llamada se rechaza conCONFIGURATION_ERROR, sin request, y el mensaje no incluye el valor recibido. - Resultado:
{ id, code, status, refereeBonus, createdAt }; el gateway responde HTTP 201.refereeBonusen unidades menores;createdAtesnullcuando el gateway envía la fecha vacía. - Idempotencia: esta ruta no pasa por el middleware de idempotencia del gateway y el SDK no envía
Idempotency-Key. Bloquea el botón mientras la llamada está en curso.
Errores
| Código | Cuándo |
|---|---|
UNAUTHENTICATED (401) | sin sesión |
CONFIGURATION_ERROR | page/perPage o code inválidos (sin request) o cliente ya descartado |
VALIDATION_ERROR | en validation: 'strict': estado desconocido, dinero que no es un número finito o campo con formato inválido; en 'warn' solo cuando la raíz de la respuesta no tiene el formato esperado (p. ej., texto en lugar de objeto) |
Cuando el servicio rechaza el código (inexistente, ya usado, el propio código del jugador, fuera de plazo), el error llega con el code que devuelva el servicio. El contrato no lista esos códigos: decide siempre por error.code y usa un mensaje genérico para lo que no reconozcas. No supongas que un código específico (por ejemplo NOT_FOUND) es el que se usa en cada caso.
Lo que el gateway aún no ofrece
- Validar un código antes de usarlo: no hay ruta que diga si un código existe y de quién es; solo
registerresponde, y ya registra. - Correo del referido sin máscara: el gateway envía el correo completo de otra persona a quien lista el historial. El SDK lo enmascara en el cliente, pero el dato ya viajó; lo ideal es que el gateway lo enmascare.
- Reglas del referido: depósito mínimo, plazo de validez, cuándo pasa a
completedy cuándo se paga el bono no están en el contrato; confirma con el operador. - Aviso en tiempo real: ningún tópico de realtime para referidos; consulta de nuevo.
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 info = await igaming.referrals.get() // code MOCK123
const { items, totalItems } = await igaming.referrals.listHistory({ perPage: 2 }) // 2 of 3 referrals
await igaming.referrals.register({ code: 'BEMVINDO' }) // HTTP 201; other codes: NOT_FOUNDEl mock devuelve tres referidos fijos en el formato del gateway (paginación dentro de data, dinero en float de unidad mayor, correo sin máscara) y no guarda estado. Para simular otros errores o valores (como 0.1 + 0.2), sobrescribe la ruta en routes.