Preguntas frecuentes - API e integraciones

¿Pueden los operadores sincronizar el inventario de la Tienda de Recompensas con un proveedor externo de cumplimiento mediante API?

Sí. La plataforma Gamanza Engage puede sincronizar el inventario de la Tienda de Recompensas con proveedores externos de cumplimiento mediante API. Por ejemplo, la integración con PrizeShark permite a los operadores conectar su Tienda de Recompensas con el catálogo de PrizeShark a través de una bandera de funciones y configuraciones de API. Una vez habilitado, el inventario, los detalles de los productos y los estados de los pedidos se actualizan automáticamente entre ambos sistemas.

¿Proporciona Gamanza Engage un conector certificado para Salesforce Marketing Cloud, o los operadores deben usar webhooks?

No existe un conector certificado para Salesforce Marketing Cloud. Las integraciones con sistemas externos se manejan a través de la API y los webhooks de Gamanza Engage, que se pueden configurar para enviar o recibir los datos necesarios.

¿Gamanza Engage envía alertas de fallos de webhooks a Slack o Microsoft Teams?

No. Gamanza Engage no envía alertas de fallos de webhooks a Slack o Teams. Los operadores que necesiten notificaciones pueden configurar su propio monitoreo o usar herramientas de terceros para reenviar los errores a los canales de colaboración.

¿Cómo maneja Gamanza Engage el versionado de la API y el soporte de endpoints obsoletos?****

La plataforma actualmente no define una política formal de versionado o de deprecación en su documentación de API. Los cambios incompatibles suelen introducirse agregando nuevos endpoints o especificaciones actualizadas, mientras que los endpoints existentes permanecen estables. No se proporciona un cronograma oficial para endpoints obsoletos, por lo que los operadores deben monitorear las notas de la versión y coordinarse con su Customer Success Manager para mantenerse informados sobre los cambios próximos.

¿Cómo pueden los operadores recuperar las promociones activas de un jugador mediante API para mostrarlas en una app móvil?

Los operadores pueden recuperar las promociones activas utilizando el Frontend API Gateway. Al inicializar los widgets requeridos y llamar a la función getPlayer, el sistema devuelve información específica del jugador, incluidas las promociones. Una vez que se cargan los datos, el evento GamanzaEngage_Client_Initialized confirma la disponibilidad para mostrarse en la app móvil.

¿Cómo maneja Gamanza Engage la entrega de webhooks y qué opciones existen para reintentos con retroceso exponencial?

Los eventos de webhooks se entregan en tiempo real, dando a los operadores acceso inmediato a la actividad del jugador y de la plataforma a medida que ocurre. Aunque no existe un SLA formal y no hay reintentos con retroceso exponencial integrados, los operadores tienen total flexibilidad para implementar su propio monitoreo y lógica de reintento. Este enfoque asegura que el manejo de webhooks pueda adaptarse a la infraestructura y los requisitos de fiabilidad de cada operador.

¿Cómo pueden los operadores actualizar tokens OAuth de forma programática sin exponer secretos en el lado del cliente?

Los tokens OAuth siempre deben renovarse del lado del servidor para evitar exponer credenciales sensibles en la aplicación cliente. Los operadores pueden usar el flujo Client Credentials de OAuth 2.0, donde el client ID y el client secret se almacenan de forma segura en el backend. El backend solicita entonces un nuevo token de acceso al servidor de autorización (/api/oauth/v1/token) e lo inyecta en las llamadas a la API en nombre del cliente. Esto asegura que los secretos permanezcan protegidos mientras la renovación de tokens se mantiene completamente automatizada.

¿Gamanza Engage proporciona un endpoint GraphQL o solo APIs REST?

Las APIs de Gamanza Engage se ofrecen mediante una arquitectura RESTful y están documentadas usando la especificación OpenAPI. En este momento, no hay un endpoint GraphQL disponible. Los operadores se integran a través de las APIs REST proporcionadas para integraciones de plataforma, frontend y operador.

¿Cómo se pueden reconciliar los webhooks de eventos asíncronos con consultas REST para lograr idempotencia?

Se deben usar IDs únicos como transactionId o eventId para evitar el procesamiento duplicado, y los flujos de trabajo deben diseñarse para ser idempotentes. Los webhooks en tiempo real pueden complementarse con consultas periódicas a la Data Fetch API (usando el parámetro delta) para garantizar integridad y consistencia.

¿Los límites de tasa son por IP, por clave o por tenant, y podemos solicitar límites más altos?

Los límites de tasa se aplican por clave de cliente de API (credenciales OAuth), no por IP. Para la Data Fetch API y las Credit APIs, el límite estándar es de 100 solicitudes por minuto dentro de una ventana deslizante de un minuto. Si se requieren límites más altos, los operadores deben coordinarse con el Customer Success Manager para solicitar una excepción.

¿Qué flujo de autenticación soporta la plataforma Gamanza Engage?

Gamanza Engage soporta el flujo Client Credentials de OAuth 2.0 para autenticar los sistemas backend de los operadores. Este proceso emite un token de acceso JWT válido que debe incluirse en las solicitudes API posteriores

¿Cómo pueden los operadores otorgar tokens manualmente, por ejemplo como un gesto de buena voluntad?

Los operadores pueden otorgar o eliminar tokens manualmente de dos maneras:

1. A través de la Tarjeta del Jugador: Ajustar XP seleccionando la acción (Agregar/Eliminar), ingresando la cantidad y proporcionando un comentario para la transacción. El saldo de XP del jugador se actualiza instantáneamente, y todos los detalles, incluidos los comentarios y el usuario que realiza la acción, se registran para auditoría y transparencia.

2. A través de la API: Usar la Credit Experience Points API para otorgar XP fuera de las reglas estándar de gamificación. Esto es especialmente útil para flujos de trabajo personalizados o para otorgar XP en masa. Cada solicitud API requiere el ID único del jugador, los detalles de la transacción y una fuente descriptiva, que luego es visible en la UI de administración para el seguimiento adecuado.

¿Cómo pueden los operadores exportar los datos de jugadores para solicitudes GDPR?

Los operadores pueden atender las solicitudes GDPR de "derecho de acceso" ya sea mediante la UI de administración, donde hay una opción de exportación de datos en la Tarjeta del Jugador, o a través de la Platform API. Ambos métodos permiten exportar todos los datos personales vinculados al jugador, asegurando el cumplimiento de los requisitos del GDPR.

¿PEP proporciona una API para recuperar el historial completo de interacción de un jugador para los equipos de Soporte al Cliente?

Sí. PEP proporciona APIs a través de la Data Fetch API que permiten a los operadores recuperar el historial de interacción a nivel de jugador. Los operadores pueden acceder a datos como:

• Misiones y Paquetes de Misiones: progreso actual y estados históricos.

• Rangos y Niveles: rango del jugador, cambios de nivel, saldos de XP e historiales.

• Tienda de Recompensas: compras, pedidos, proveedores y artículos de recompensa.

• Moneda Virtual: saldos de tokens, historial de la billetera, potenciadores de tokens y reglas de contribución.

• Eventos Transaccionales: transacciones de juego, dinero y deportes.

• Eventos del Jugador: inicios de sesión, cierres de sesión, registros, opt-ins, verificaciones KYC, etc.

Estas APIs pueden usarse para consolidar una línea de tiempo completa de interacción para un jugador específico, lo que facilita a los equipos de CS investigar problemas o responder a solicitudes de cumplimiento.

¿Hay límites sobre cuántas claves de API o clientes OAuth pueden crear los operadores?

No existe un límite fijo estricto para el número de claves de API o credenciales de cliente OAuth que se pueden generar en la UI de administración. Los operadores pueden crear múltiples credenciales para soportar diferentes sistemas o entornos (por ejemplo, staging vs. producción). Para seguridad y mantenibilidad, se recomienda:

• Generar credenciales separadas por integración o entorno.

• Rotar las claves regularmente siguiendo las mejores prácticas.

• Eliminar clientes no utilizados u obsoletos para reducir riesgos.

¿Cuáles son las APIs requeridas para CRM?

Las APIs requeridas para CRM son:

• Autenticación (OAuth 2.0) – para generar tokens de acceso.

• APIs de Campañas (Platform RX API) – para enviar y gestionar campañas (directas, contenido, disparadores, cancelación de suscripción).

• APIs de Eventos del Jugador – para alimentar el CRM con eventos del ciclo de vida del jugador (por ejemplo, inicio de sesión, cierre de sesión, registro, KYC).

Otras APIs, como Eventos Transaccionales y Data Fetch, son opcionales pero útiles para enriquecer las actividades del CRM.

¿Cómo pueden los operadores recuperar información de bonos mediante API?

Los operadores pueden usar la Data Fetch API para acceder a datos de bonos:

• Reward Processor → /api/data-fetch/v1/reward-processor/rewards (todas las recompensas otorgadas, incluidos los bonos).

• Bonus Granted → /api/data-fetch/v1/bonuses/granted (bonos otorgados a los jugadores).

• Bonus Released → /api/data-fetch/v1/bonuses/released (bonos liberados/activados para los jugadores).

• Reward Shop → /api/data-fetch/v1/reward-shop/item y /api/data-fetch/v1/reward-shop/order (artículos de bonos y compras).

¿Qué son los Webhooks en la Player Engagement Platform?

Los webhooks en la Gamanza Player Engagement Platform se utilizan efectivamente para entregar notificaciones en tiempo real a aplicaciones externas. Las áreas clave a considerar al trabajar con webhooks incluyen:

• Primeros pasos (cómo registrar y configurar webhooks)

• Características de seguridad (autenticación, firmas, verificación)

• Consideraciones y limitaciones (rendimiento, reintentos, límites de tasa)

• Eventos de webhooks (jugador, CRM, transaccionales, etc.)

• Integraciones de terceros

¿Qué endpoint se debe usar para obtener bonos?

Los operadores pueden usar la Data Fetch API para recuperar información relacionada con bonos. Los endpoints relevantes incluyen:

• /api/data-fetch/v1/bonuses/bonus-granted – recupera detalles de los bonos otorgados a los jugadores.

• /api/data-fetch/v1/bonuses/bonus-released – recupera detalles de los bonos que se han liberado a los jugadores.

¿Qué endpoints se requieren para integrar el Informe de Cancelación de Suscripción en el CRM?

Para gestionar y rastrear acciones de cancelación de suscripción en el CRM, los operadores deben usar el siguiente endpoint:

• POST /rx-api/analytics/v1/register/event/unsubscribe – da de baja a un jugador de una campaña de marketing específica.

Este endpoint requiere el playerId, campaignId, reason y la fecha de la Cancelación de Suscripción.