idType · usá tu propio ID de cuenta
Un flag opcional para mandar tu external_id directo en los endpoints de cuenta, sin el paso previo de traducción
Todos los endpoints de la API que referencian una cuenta por ID ahora aceptan un flag opcional idType. Con idType=EXTERNAL mandás el ID que ya usás en tu sistema y BehaviorOS lo resuelve —y crea la cuenta si es nueva— en la misma request.
Por defecto idType es INTERNAL. Si no lo mandás, todo se comporta exactamente como antes: no hay nada que cambiar en tu integración salvo que quieras aprovechar la nueva capacidad.
El cambio
Antes, para registrar un evento tenías que traducir tu ID al UUID interno en una llamada aparte, y recién ahí mandar el evento — dos idas y vueltas por cada acción.
Antes — 2 llamadas
// 1 · obtener el UUID interno de la cuenta
// → { "id": "3f2a9c14-…-8b7e" }
// 2 · mandar el evento con ese UUID
POST /gamification/triggers
{ "accountId": "3f2a9c14-…-8b7e", "event": "purchase" }Ahora — 1 llamada
POST /gamification/triggers
{ "accountId": "user-4821", "idType": "EXTERNAL", "event": "purchase" }
// BehaviorOS resuelve tu ID y crea la cuenta si no existeLos dos valores
| Valor | Cómo se interpreta el ID | Si la cuenta no existe |
|---|---|---|
INTERNAL (por defecto) | Es nuestro UUID interno. Se valida el formato: un ID malformado devuelve 400 limpio, no un 500. | 404 — nunca se crea. |
EXTERNAL (nuevo) | Es tu external_id, el que ya usás en tu sistema. | Se crea automáticamente, de forma segura ante requests concurrentes. |
Dónde va el flag
Depende de cómo el endpoint recibe hoy el ID de la cuenta.
Query param — por defecto
La mayoría de los endpoints lo leen del query string:
GET /accounts/user-4821/points?idType=EXTERNALAplica a:
| Método | Endpoint |
|---|---|
GET | accounts/:id/points |
GET | accounts/:id/points/history |
GET | progress/:id |
GET | completed/:id |
GET | my-rewards/:id |
GET | account/:id (feed de engagement) |
GET | :accountId (redenciones) |
GET | tournaments/account/:id |
GET | tournaments/:tid/predictions/:id |
POST | tournaments/:tid/predictions/:id |
GET | account/:id (leaderboard) |
En el body — solo 4 endpoints
Los endpoints que ya reciben un body JSON lo llevan como un campo más:
{ "accountId": "user-4821", "idType": "EXTERNAL" }| Método | Endpoint |
|---|---|
POST | /gamification/triggers |
POST | /gamification/triggers/async |
POST | publications/redeem/:id |
POST | products/:id/redeem |
El valor es case-insensitive (external funciona). Vacío o ausente ⇒ INTERNAL. Cualquier otra cosa ⇒ 400 "idType must be either INTERNAL or EXTERNAL".
Cambio de comportamiento en triggers
Solo afecta el hot path de triggers. Antes, un POST /gamification/triggers sobre una cuenta desconocida era un 200 silencioso (no-op). Ahora el resultado es explícito:
INTERNAL+ UUID válido pero desconocido ⇒404EXTERNAL+ ID desconocido ⇒ se crea la cuenta
El accountId se normaliza en el punto de entrada, así que un ID externo nunca queda persistido en registros internos (idempotencia, asignaciones de misión, evento emitido): aguas abajo siempre viaja el ID interno.
Referencia
Los docs de cada endpoint se actualizan solos desde el código. Vas a ver el parámetro idType en cada endpoint del Swagger.