Identificadores
Cómo se referencia una cuenta en la API — el parámetro idType y sus dos valores
Casi todos los endpoints que operan sobre un usuario reciben un accountId. Cómo se interpreta ese valor lo define el parámetro idType.
Es la decisión de la que dependen todas las demás de tu integración, porque determina cuánto estado tenés que guardar de tu lado.
Los dos valores
| Valor | Cómo se interpreta el accountId | Si la cuenta no existe |
|---|---|---|
INTERNAL (por defecto) | El UUID interno de BehaviorOS. Se valida el formato: un id malformado devuelve 400, no 500. | 404 — nunca se crea. |
EXTERNAL | Tu propio identificador, el que ya usás en tu sistema. | Se crea automáticamente, de forma segura ante requests concurrentes. |
El valor es case-insensitive (external funciona). Vacío o ausente equivale a INTERNAL; cualquier otro valor devuelve 400.
EXTERNAL es la opción recomendada. No tenés que guardar ningún identificador de BehaviorOS ni mantener una tabla de correspondencia: mandás el tuyo y la plataforma resuelve el resto.
Dónde viaja el parámetro
Depende de cómo el endpoint recibe el identificador.
En el query string
La mayoría de los endpoints lo leen de ahí:
GET /loyalty/accounts/user-4821/points?idType=EXTERNALEn el body
Los endpoints que ya reciben un cuerpo JSON lo llevan como un campo más:
{ "accountId": "user-4821", "idType": "EXTERNAL" }La forma exacta de cada endpoint está en el Swagger, que muestra el parámetro donde corresponde.
La creación implícita
Con idType=EXTERNAL, un identificador desconocido crea la cuenta en el momento, en casi cualquier operación — incluidas las de lectura. No hace falta un alta previa.
Es la propiedad que hace que la integración se pueda reducir a dos escrituras. El detalle de dónde aplica y dónde no está en Identificar usuarios.
Como nada puede validar un identificador que es tuyo, un error de tipeo crea una cuenta fantasma en lugar de devolver un error. Normalizá el valor antes de enviarlo.
Qué datos guarda la plataforma
Por defecto, sólo un código interno vinculado a tu propio identificador. No se almacenan nombres, correos ni datos personales salvo que decidas enviarlos — email y name son campos opcionales del alta.