Identificar usuarios

Dar de alta a tus usuarios, resolverlos por tu propio identificador, y asignarlos a audiencias

Es la primera escritura de tu integración, y se ejecuta una vez por usuario.

Anonimización de tus usuarios

UIN no almacena nombres, correos ni datos personales salvo que vos decidas enviarlos. Por defecto solo guardamos un código que se conecta con tu propio id.

Tu sistema                         UIN
──────────                         ───
Tu usuario                         Comportamiento anónimo
  USR-78421                          a7f3-e91c-8b2d
  nombre                                 │
  correo          ←── equivalen ──→      ├── misiones
  teléfono                               ├── puntos
  documento                              ├── recompensas
                                         └── rachas

El mismo usuario, dos códigos equivalentes. La identidad se queda de tu lado; el comportamiento corre del nuestro.

Siempre con tu propio id

Seguís usando el identificador que ya tenés. Cuando necesitás consultar a un usuario, lo pedís con tu propio código y nosotros lo resolvemos internamente.

1 · Nos llamás con TU id           accountId: "USR-78421", idType: "EXTERNAL"
2 · Traducimos los ids por dentro
3 · Recibís la respuesta lista

Cero cambios en tu base de datos. Nunca necesitás guardar ni conocer nuestro código interno.

Es como un guardarropa: el usuario llega, le das un ticket con un número, y guardamos lo que pasa con ese número. Quién es la persona nunca sale de tu lado.

email y name son campos opcionales del alta. Enviarlos tiene sentido si tu caso lo necesita —por ejemplo, para que UIN entregue una recompensa por correo— pero no es un requisito de la plataforma.

La decisión práctica que se desprende de todo esto: mandá tu externalId con idType=EXTERNAL y no guardes nada de UIN. El contrato completo del parámetro está en Identificadores.

El atajo recomendado: `resolve`

POST /accounts/resolve
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

{ "externalId": "user-4821" }

Devuelve la cuenta si existe, y la crea si no. Es seguro de repetir: llamarlo dos veces con el mismo externalId no crea dos cuentas.

Si además usás idType=EXTERNAL en el resto de las llamadas, ni siquiera necesitás guardar el id que devuelve. Ver Identificadores.

Alta explícita

POST /accounts
Content-Type: application/json

{
  "externalId": "user-4821",
  "email": "user@example.com",
  "name": "Juana Pérez"
}

Los tres campos son opcionales. email y name solo si tu caso los necesita — UIN no los requiere.

Si das de alta sin externalId, el id que devuelve la respuesta es el que tenés que guardar: es la única forma de volver a referenciar a ese usuario.

El alta implícita: casi todo endpoint crea la cuenta

Esto es lo más importante de la página, y no es obvio.

Cuando mandás idType=EXTERNAL y ese externalId no existe todavía, la cuenta se crea en el momento — no hace falta un alta previa. Aplica a casi todos los endpoints que reciben un accountId, incluidos los GET.

POST /gamification/triggers
{ "programmaticCode": "PAGO_SERVICIO", "accountId": "user-4821", "idType": "EXTERNAL" }

Si user-4821 no existía, queda creado y el evento se procesa contra esa cuenta nueva. Lo mismo si el primer contacto es una lectura: pedir el feed de un usuario desconocido lo crea.

Dónde aplica

Crea la cuenta si no existe	No la crea
`POST /gamification/triggers` `POST /gamification/triggers/async`	`GET /marketplace/reservations`
`GET /v1/feed/account/{id}`	`POST /marketplace/publications/unfreeze`
`GET /v1/gamification/missions/{progress, completed, my-rewards}/{id}`
`GET /loyalty/accounts/{id}/points` `GET /loyalty/accounts/{id}/points/history`
`POST /loyalty/products/{id}/redeem`
`POST /marketplace/publications/freeze` `POST /marketplace/publications/redeem/{id}`
`GET /redemptions/{accountId}`

Los dos de la derecha son idempotentes por naturaleza: "no hay cuenta" simplemente significa "no hay nada que hacer".

Qué significa en la práctica

Podés saltarte el alta. Si toda tu integración usa idType=EXTERNAL, no necesitás llamar a /accounts ni a /accounts/resolve: la primera vez que el usuario aparece en cualquier llamada, se crea. El alta explícita sirve si querés mandar email o name, o si preferís controlar el momento.
La creación es segura ante concurrencia. Dos llamadas simultáneas con el mismo externalId no crean dos cuentas.
Un typo crea una cuenta fantasma. Como no hay validación posible sobre un id que es tuyo, user-4821 con un espacio de más es un usuario nuevo. Normalizá el id antes de mandarlo.

Con idType=INTERNAL no hay creación implícita: un UUID válido pero desconocido devuelve 404, y un id malformado devuelve 400. La creación automática es exclusiva de EXTERNAL.

Los demás endpoints de cuenta

Método	Endpoint	Para qué
`GET`	`/accounts/{id}`	Leer una cuenta.
`PATCH`	`/accounts/{id}`	Actualizar atributos.
`GET`	`/accounts/paginated`	Listar. Ver Paginación y filtros.
`DELETE`	`/accounts/{id}`	Baja.

Todos aceptan ?idType=EXTERNAL para que mandes tu propio id.

Carga inicial del padrón

Si arrancás con un padrón que ya existe, no lo cargues de a un usuario por API: usá la carga por CSV del Control Center. Ver Cuentas.

Audiencias

Las audiencias se crean en el Control Center. Asignar usuarios es opcional por API: la misma asignación se hace desde la consola.

POST   /gamification/audiences/{audienceId}/accounts/assign
DELETE /gamification/audiences/{audienceId}/accounts/remove

Las audiencias trabajan con el id interno de UIN. Si manejás ids externos, resolvelos con POST /accounts/resolve antes de asignar.

Si la audiencia se administra desde el Control Center, este paso desaparece de tu integración y te quedan solo dos escrituras: alta de usuarios y emisión de eventos.

El orden completo

1 · POST /accounts/resolve                       ← una vez por usuario
       200 · id interno del usuario

2 · POST /gamification/audiences/{id}/accounts/assign   ← opcional
       200 · audiencia actualizada

3 · UIN activa la campaña                        ← del lado de UIN
       asigna las misiones a cada usuario de la audiencia

4 · GET /v1/feed/account/{accountId}
       200 · misiones activas del usuario

Hasta que la campaña no está activa, el feed del usuario viene vacío. Si el usuario entra a la audiencia con la campaña ya activa, recibe sus misiones en el momento.

Qué sigue

Emitir eventos — el único llamado que ocurre en caliente.