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 función y la configuración de la 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 deberían los operadores usar webhooks?

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

¿Envía Gamanza Engage 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 errores a los canales de colaboración.

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

La plataforma no define actualmente una política formal de versionado o desaprobación en su documentación de la API. Los cambios incompatibles normalmente se introducen agregando nuevos endpoints o especificaciones actualizadas, mientras que los endpoints existentes permanecen estables. No se proporciona un cronograma oficial para los endpoints desaprobados, 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 aplicación 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 los datos se cargan, el evento GamanzaEngage_Client_Initialized confirma la disponibilidad para mostrarlos en la aplicación móvil.

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

Los eventos de webhook se entregan en tiempo real, dando a los operadores acceso inmediato a la actividad del jugador y de la plataforma conforme ocurre. Si bien no existe un SLA formal y los reintentos con backoff exponencial no están integrados, los operadores tienen plena 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 programáticamente 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 OAuth 2.0 Client Credentials, donde el client ID y el client secret se almacenan de forma segura en el backend. El backend solicita un nuevo token de acceso al servidor de autorización (/api/oauth/v1/token) y lo inyecta en las llamadas a la API en nombre del cliente. Esto garantiza que los secretos permanezcan protegidos y que la renovación de tokens sea totalmente automatizada.

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

Las APIs de Gamanza Engage se entregan 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 conciliar los webhooks de eventos asincrónicos con consultas REST para garantizar idempotencia?

Deben usarse 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 completitud 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 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 admite la plataforma Gamanza Engage?

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

¿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 Ficha del Jugador: Ajuste 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 al instante, y todos los detalles —incluidos los comentarios y el usuario que realizó la acción— se registran para auditoría y transparencia.

2. A través de la API: Use 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 interfaz de administrador para su correcto seguimiento.

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

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

¿Proporciona PEP 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 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, facilitando a los equipos de CS investigar problemas o responder a solicitudes de cumplimiento.

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

No existe un límite rígido fijo para la cantidad de claves API o credenciales de cliente OAuth que se puedan generar en la interfaz de administrador. 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 el riesgo.

¿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ña (Platform RX API) – para enviar y gestionar campañas (directas, de contenido, disparadores, baja de suscripción).

• APIs de Eventos del Jugador – para alimentar el CRM con eventos del ciclo de vida del jugador (por ejemplo, login, logout, registro, KYC).

Otras APIs, como Transactional Events 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 los 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 jugadores).

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

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

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

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

• Comenzar (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 webhook (jugador, CRM, transaccionales, etc.)

• Integraciones de terceros

¿Qué endpoint debe usarse 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 han sido liberados a los jugadores.

¿Qué endpoints se requieren para integrar el Informe de Baja en el CRM?

Para gestionar y rastrear las acciones de baja 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 playerId, campaignId, motivo y fecha de la baja.