Reportar canje de premio

Ingesta server-to-server de canjes de premios de mini-juegos in-app.

Endpoint server-to-server: lo llama tu backend (no el SDK cliente) cuando el premio que un cliente gano en la ruleta se hace efectivo en tu plataforma — una compra con el descuento aplicado, un cupon cobrado, etc. Con estos datos el portal calcula el ROI de la campana (ventas atribuidas, descuento invertido, ticket promedio) en el detalle del mini-juego.

Usa la misma autenticacion que el resto de la API REST (Authorization: Bearer <api_key> + X-Org-Id), con una API key de escritura de tu organizacion.

De donde salen notificationId y awardId

Ambos identificadores te llegan por los canales server-side existentes del mini-juego — no hay que construirlos a mano:

• Webhook inapp_game.won (recomendado): el payload trae notificationId y awardId del premio recien ganado. Ver Webhooks > Eventos.
• Resultado del SDK (onGameResult / evento result:): el mismo awardId viaja en la respuesta del endpoint spin que el SDK entrega al app host.

awardId ("{spinPeriod}_{clientId}") identifica de forma unica el premio de ese cliente en ese periodo de giro — es la misma clave de idempotencia que ya usas para acreditar el premio.

Si tu backend no guarda el awardId (solo tu id de usuario y tu id de premio), salta a la seccion Identificacion alternativa (sin awardId) mas abajo.

Request body

Los montos son enteros en unidades menores de la moneda: 15990 con currency: "CLP" son $15.990 (el peso chileno no usa decimales); 15990 con currency: "USD" son US$159,90.

La validacion de currency es de forma, no de catalogo: cualquier codigo de 3 letras mayusculas se acepta y se registra tal cual, aunque no sea un codigo ISO-4217 real ("XYZ" pasa). Lo que no cumple la forma ("clp", "PESO", 152) responde 400.

Ejemplo

curl -X POST https://southgames.ai/api/v1/inapp-games/redemptions \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif_abc123",
    "awardId": "2026-08_cliente42",
    "saleTotal": 15990,
    "discountAmount": 3000,
    "currency": "CLP",
    "redeemedAt": "2026-08-05T14:30:00Z",
    "externalReference": "boleta-778899"
  }'

Respuesta (200)

{
  "ok": true,
  "awardId": "2026-08_cliente42",
  "redemption": {
    "saleTotal": 15990,
    "discountAmount": 3000,
    "currency": "CLP",
    "redeemedAt": "2026-08-05T14:30:00.000Z",
    "externalReference": "boleta-778899"
  }
}

Identificacion alternativa (sin awardId)

Muchos backends no persisten nuestro awardId: guardan su id de usuario y su id de premio. Para esos casos el endpoint acepta, en lugar de awardId, el par:

• clientExternalId — el externalId con el que registras al usuario en SouthGames (el mismo que mandas en identify / register).
• segmentExternalId — el codigo del gajo que declaraste en el editor de la ruleta (campo "Id externo" del gajo). Es el mismo valor que viaja como segmentExternalId en el webhook inapp_game.won y como externalId en el resultado del SDK.

El resto del body (saleTotal, discountAmount, currency, redeemedAt, externalReference, override) es identico y se valida igual.

Regla XOR: manda awardId o el par clientExternalId + segmentExternalId, nunca los dos. Los dos juntos, ninguno de los dos, o solo uno de la pareja responden 400.

Regla FIFO: si el cliente gano ese mismo gajo varias veces, se canjea el premio mas antiguo que aun no tenga canje (el cliente canjea primero lo que gano primero); el siguiente reporte tomara el que sigue.

Como se busca el premio: el id de un award es siempre {periodo}_{clientId}, asi que la resolucion construye las claves de periodo de la campana (segun su cadencia de giro: sin renovacion, diaria, semanal o mensual) desde que la campana existe hasta hoy, y lee esos ids directamente. El resultado es exacto y su costo depende del numero de periodos de la campana, nunca de cuantos premios lleva repartidos.

Limite de periodos: una campana que acumule mas de 400 periodos de giro (por ejemplo, una diaria de mas de 13 meses, o una en cadencia minute de QA que lleve horas corriendo) responde 409 TOO_MANY_PERIODS. No es una degradacion silenciosa: para esas campanas usa el modo awardId, que no tiene este limite.

{
  "error": "Esta campana tiene mas de 400 periodos de giro: usa awardId para reportar sus canjes",
  "code": "TOO_MANY_PERIODS"
}

curl -X POST https://southgames.ai/api/v1/inapp-games/redemptions \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif_abc123",
    "clientExternalId": "usuario-9931",
    "segmentExternalId": "SKU-GIFTCARD-5000",
    "saleTotal": 15990,
    "discountAmount": 3000,
    "currency": "CLP",
    "redeemedAt": "2026-08-05T14:30:00Z",
    "externalReference": "boleta-778899"
  }'

La respuesta 200 es la misma del modo clasico e incluye el awardId resuelto, para que sepas exactamente que premio quedo marcado (y puedas corregirlo despues con override usando ese awardId):

{
  "ok": true,
  "awardId": "2026-08_HkQ2v9xTa1",
  "redemption": {
    "saleTotal": 15990,
    "discountAmount": 3000,
    "currency": "CLP",
    "redeemedAt": "2026-08-05T14:30:00.000Z",
    "externalReference": "boleta-778899"
  }
}

Si todos los premios del cliente para ese gajo ya tienen canje, la respuesta es 409 ALL_REDEEMED con el ultimo canje conocido y su awardId:

{
  "error": "Todos los premios de ese gajo para este cliente ya tienen canje registrado",
  "code": "ALL_REDEEMED",
  "awardId": "2026-08_HkQ2v9xTa1",
  "redemption": {
    "saleTotal": 12990,
    "discountAmount": 2000,
    "currency": "CLP",
    "redeemedAt": "2026-08-04T10:00:00.000Z",
    "externalReference": "boleta-1",
    "recordedAt": "2026-08-04T10:00:05.000Z"
  }
}

Para corregir un canje ya registrado (override: true) usa el modo awardId con el id que te devolvio el 200 o el 409: el modo alternativo siempre apunta al proximo premio sin canjear, nunca a uno ya reportado.

Errores propios de este modo:

Canje unico (409 y override)

Cada premio admite un solo canje. Si el award ya tiene un canje registrado, un segundo reporte responde 409 con el canje existente en el body — asi puedes reconciliar sin otra llamada:

# Segundo reporte del mismo premio, sin override
curl -X POST https://southgames.ai/api/v1/inapp-games/redemptions \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif_abc123",
    "awardId": "2026-08_cliente42",
    "saleTotal": 12990,
    "discountAmount": 2000,
    "currency": "CLP"
  }'

Respuesta 409:

{
  "error": "El premio ya tiene un canje registrado",
  "code": "ALREADY_REDEEMED",
  "redemption": {
    "saleTotal": 9990,
    "discountAmount": 1000,
    "currency": "CLP",
    "redeemedAt": "2026-08-02T18:00:00.000Z",
    "externalReference": "boleta-1",
    "recordedAt": "2026-08-02T18:00:05.000Z"
  }
}

Para corregir un canje mal reportado, repite el POST con "override": true: el canje nuevo reemplaza al vigente y el anterior queda guardado en redemption.previous (una sola generacion de historia — un segundo override reemplaza previous, no lo anida):

curl -X POST https://southgames.ai/api/v1/inapp-games/redemptions \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif_abc123",
    "awardId": "2026-08_cliente42",
    "saleTotal": 20000,
    "discountAmount": 5000,
    "currency": "CLP",
    "override": true
  }'

La respuesta del override incluye el canje anterior en redemption.previous.

Gajos que no son premio (422)

Solo los premios se canjean: si el gajo del award esta marcado explicitamente como no premio (isPrize: false, un "sigue participando"), el endpoint responde 422:

# El awardId apunta a un gajo "sigue participando" (isPrize: false)
curl -X POST https://southgames.ai/api/v1/inapp-games/redemptions \
  -H "Authorization: Bearer sg_live_xxx" \
  -H "X-Org-Id: mi-empresa" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif_abc123",
    "awardId": "2026-08_cliente77",
    "saleTotal": 8990,
    "discountAmount": 0,
    "currency": "CLP"
  }'

Respuesta 422:

{
  "error": "El gajo de este premio no es canjeable (no es premio)",
  "code": "NOT_A_PRIZE"
}

Si el gajo del award ya no existe en la config vigente de la ruleta (fue renombrado o eliminado despues del giro), el canje se acepta: el premio historico es legitimo.

Errores