Emitir eventos

El único llamado en caliente de tu integración — sincrónico, asincrónico e idempotente

Cada vez que el usuario hace la acción que interesa, tu sistema emite un evento. Es el único llamado que ocurre en caliente.

Descubrir qué eventos podés emitir

Antes de emitir nada necesitás los códigos válidos para tu organización:

GET /gamification/triggers
Authorization: Bearer <YOUR_API_KEY>

Devuelve los eventos configurados, cada uno con su programmaticCode —la constante que vas a enviar— y su type, que determina qué metadata acepta:

`type`	Qué mandar en `metadata`
`SINGLE`	`{}` — la sola ocurrencia cuenta
`AMOUNT`	`{ "amount": 1500 }` — se suma el monto

El código nombra la acción, no la campaña: PAGO_SERVICIO, no CAMPANA_VERANO. Así el mismo evento sirve para todas las campañas que premien esa acción, y marketing puede armar campañas nuevas sin tocar tu integración.

El catálogo se acuerda con UIN antes de la implementación. Si el negocio pide premiar una acción que tu plataforma todavía no emite, ahí sí hay desarrollo de tu lado — por eso conviene mapear generosamente desde el principio.

El request

POST /gamification/triggers
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

{
  "programmaticCode": "PAGO_SERVICIO",
  "accountId": "user-4821",
  "idType": "EXTERNAL",
  "metadata": { "amount": 1500 },
  "operationId": "7f3d9a4c-2e5b-4a6f-9c1d-8e2b3a4d5e6f"
}

Campo	Requerido	Detalle
`programmaticCode`	Sí	El código del evento, de la lista de arriba.
`accountId`	Sí	Tu `externalId` o el UUID interno, según `idType`.
`idType`	No	`EXTERNAL` o `INTERNAL` (por defecto). Ver Account.
`metadata`	Depende	Su forma la define el `type` del evento — ver arriba.
`operationId`	Recomendado	Clave de idempotencia derivada del id de tu operación. Ver Idempotencia.

La respuesta

Cuando la respuesta llega, el progreso ya está guardado y la recompensa ya está entregada.

{
  "progressedMissions": [ /* misiones cuyo progreso avanzó */ ],
  "rewards": [ /* recompensas entregadas por este evento */ ]
}

Respuesta	Qué significa	Qué mostrar
`200` con progreso	La misión avanzó pero no llegó al objetivo.	"Vas 2 de 3", con la barra actualizada.
`200` completada con recompensa	Objetivo alcanzado y recompensa entregada.	Celebración, y el código o los puntos acreditados.
`200` completada sin recompensa	La entrega no se pudo resolver en el momento.	"Misión cumplida, tu recompensa llega en breve". Reconciliá con `my-rewards`.
`200` con listas vacías	No tenía la misión activa, o el evento no cumplió la condición (por ejemplo, monto mínimo).	Nada. No es un error ni una misión perdida.

Emití el evento fuera de tu transacción principal. Si el usuario transfirió y BehaviorOS falla, la transferencia salió bien: lo único que no aparece es el progreso. La gamificación nunca puede hacer fracasar la operación de negocio.

El camino asincrónico

Cuando no podés esperar la respuesta —un core con latencia crítica, una cola, un batch— emitís por el camino asincrónico:

POST /gamification/triggers/async

Responde 200 sin cuerpo y seguís con tu transacción. UIN suma progreso y entrega la recompensa fuera del request, y el resultado llega a tu endpoint por webhook.

1 · POST /gamification/triggers/async
       200 sin cuerpo · seguís con tu transacción
                              │
                              ▼  UIN procesa en segundo plano
2 ·                    recompensa entregada → POST a tu webhook
                              │
3 · GET /v1/gamification/missions/my-rewards/{accountId}
       200 · recompensas ganadas, para reconciliar

La entrega del webhook es best-effort y sin reintentos. Si tu endpoint falla, la recompensa ya quedó entregada igual: dejá un job que reconcilie con my-rewards. Si necesitás el resultado en la misma transacción, usá el camino sincrónico.

Errores

Código	Causa	Qué hace tu sistema
`400`	Payload mal armado.	Loguear con `traceId` y corregir la integración. No reintentar.
`401`	API key vencida o revocada.	Alerta operativa: toda la gamificación está caída.
`404`	El `programmaticCode` no existe, o la cuenta no existe con `idType=INTERNAL`.	Revisar el id y el `idType`.
`409`	El mismo `operationId` ya se está procesando.	Reintento con backoff, mismo `operationId`.
`5xx` o timeout	Servicio no disponible.	Reintento con backoff. La operación de negocio no se toca.

Ninguno de estos se le muestra al usuario como fallo de su operación. Ver Errores.

Qué sigue

Progreso y recompensas — la lectura que alimenta tu pantalla.