Developer
Cómo integrarse con BehaviorOS — las ocho etapas en orden, desde el catálogo de eventos hasta el go-live
BehaviorOS es una API. Vive detrás de tus sistemas y de tu app: no reemplaza nada, no exige migrar la experiencia y no impone una app nueva.
Tu sistema escribe dos cosas y lee una
Escribe · Usuarios
Una vez por usuario. Alta por API o carga inicial por CSV desde el Control Center.
Escribe · Eventos
Cada vez que el usuario hace la acción que interesa. Es el único llamado que ocurre en caliente.
Lee · Progreso
Una llamada devuelve todo lo que el usuario tiene activo, con el progreso ya calculado.
Todo lo demás ocurre del lado de UIN y no requiere desarrollo de tu lado: definir campañas y mecánicas, asignar misiones a cada usuario, sumar progreso, resolver la regla y entregar la recompensa.
| Responsabilidad | Tu sistema | UIN |
|---|---|---|
| Alta y actualización de usuarios | Sí, por API o CSV | — |
| Mantener la relación usuario ↔ id de UIN | Solo si no mandás externalId | — |
| Crear audiencias y asignar usuarios | Opcional, por API | Control Center |
| Detectar la acción del usuario y emitir el evento | Sí | — |
| Definir campañas, misiones, mecánicas y recompensas | — | Control Center |
| Asignar misiones, sumar progreso y entregar recompensas | — | BehaviorOS |
| Mostrar progreso y recompensas al usuario | Sí, leyendo el feed | — |
La integración mínima son tres llamados. El esfuerzo real del proyecto no está en la API: está en las pantallas de tu app.
Las etapas, en orden
1 · Requisitos
Qué necesitás resuelto, y el catálogo de eventos que acordás con UIN. Va antes de escribir código.
2 · Credenciales
Usar la API key, rotarla sin corte y, si tu política lo exige, mTLS.
3 · Identificar usuarios
Tu propio identificador, el alta implícita y la anonimización.
4 · Emitir eventos
El único llamado en caliente. Sincrónico o asincrónico.
5 · Leer progreso
El feed que alimenta tu pantalla, y cómo se pinta cada mecánica.
6 · Recompensas y entrega
Cómo llega lo que el usuario ganó, y la rama de espera.
7 · Recibir notificaciones
Construir el endpoint que recibe los avisos, y por qué debe ser idempotente.
8 · Ir a producción
Qué cambia respecto de sandbox, y la lista de verificación.
El recorrido
Requisitos Credenciales Identificar
catálogo de → API key desde → usuarios
eventos con UIN el Control Center alta o CSV inicial
│
▼
Ir a producción ← Leer progreso ← Emitir eventos
lista de el feed alimenta el único llamado
verificación tu pantalla en calienteDos reglas que atraviesan todo
La gamificación nunca puede hacer fracasar la operación de negocio. Si el usuario transfirió y BehaviorOS falla, la transferencia salió bien y lo único que no aparece es el progreso. Emití el evento fuera de tu transacción principal.
Un 200 con listas vacías no es un error y no se reintenta. Significa que el usuario no tenía esa misión activa, o que el evento no cumplió la condición. Ver Errores.
Antes de escribir el cliente HTTP
Las convenciones que atraviesan toda la API y que el Swagger no muestra: