Usuarios

Referencia de la API

Para detalles de los endpoints, ver la Referencia de la API de Usuarios.

¿Qué es un Usuario de Ozzie?

En la API de Ozzie, un usuario no es una identidad de autenticación — es un perfil financiero. Cuando creas un usuario en Ozzie, estás creando un registro persistente que acumula datos financieros, un plan personalizado, metas activas e historial de comportamiento a lo largo del tiempo.

Piensa en un usuario como el "avatar financiero" de uno de tus usuarios finales dentro de la plataforma Ozzie. Ozzie no gestiona credenciales de inicio de sesión ni sesiones. Esa responsabilidad permanece en tu aplicación. Ozzie solo gestiona lo que sabe sobre la vida financiera de una persona.

El Modelo Multi-Tenant

La API de Ozzie es multi-tenant. Cada cliente de la API (identificado por tu clave de API) opera en su propio espacio de nombres aislado. Los usuarios que creas están completamente en el ámbito de tu cliente — son invisibles para otros clientes de la API, y no puedes acceder a usuarios que pertenecen a otro cliente.

Esto significa:

• Puedes crear tantos usuarios como tu plan permita.
• Cada usuario pertenece exclusivamente a tu cliente de la API.
• No existe el concepto de "compartir" usuarios entre clientes.

Identidad del Usuario: Dos IDs

Todo usuario de Ozzie tiene dos identificadores:

Campo	Propietario	Propósito
external_user_id	Tú	Tu ID interno para esta persona (ej: UUID de tu base de datos o ID de cliente)
id	Ozzie	UUID propio de Ozzie, generado automáticamente al crear

Tú controlas external_user_id. Lo asignas al crear, y debe ser único dentro de tu cliente de la API. Este es el identificador principal que usarás para buscar usuarios — pasa tu propio ID de usuario y Ozzie lo resuelve al perfil financiero correcto.

El id de Ozzie (UUID) se devuelve en todas las respuestas y también puede usarse para búsquedas, pero la mayoría de las integraciones encuentran más conveniente trabajar con external_user_id.

Etapas de Onboarding

Un usuario pasa por tres etapas de onboarding a lo largo de su ciclo de vida:

financial_intake  →  plan  →  active

Etapa	Qué significa
financial_intake	Usuario creado, pero aún no ha enviado un intake financiero (ingresos, gastos, tipo de objetivo)
plan	Intake completo; Ozzie ha generado un plan personalizado, pero el usuario aún no ha comenzado su primer ciclo de Money Moves
active	El usuario tiene al menos una meta activa y está recibiendo Money Moves

Tu integración debe usar el campo onboarding_stage para guiar a los usuarios a través de los flujos de configuración. Un usuario en financial_intake debe ser solicitado a completar su intake antes de que se le muestre cualquier otra cosa.

Preferencia de Idioma

Los usuarios tienen un campo language_preference que acepta en, pt o es. Esta preferencia afecta el idioma de:

• Descripciones de planes generadas por IA
• Textos de tareas de Money Moves
• Resúmenes de insights

Establece este campo en el momento de la creación basándote en el locale de tu usuario, y actualízalo si el usuario cambia la configuración de idioma. Ozzie no detecta el idioma automáticamente.

Ciclo de Vida del Usuario

El flujo de integración típico se ve así:

Tu app crea el usuario  →  Usuario completa intake  →  Plan es generado
        ↓
   Meta es definida  →  Money Moves inician  →  Transacciones se acumulan  →  Insights aparecen

¿Cuándo crear usuarios? Tienes dos opciones comunes:

• Al registrarse: Crea el usuario de Ozzie cuando tu usuario se registre en tu app. Este es el enfoque más limpio y asegura que el perfil de Ozzie esté listo cuando se necesite.
• Creación lazy: Crea el usuario de Ozzie solo cuando el usuario acceda por primera vez a una función financiera. Útil si solo un subconjunto de tus usuarios usará las funciones de Ozzie.

Cualquier enfoque funciona. Lo importante es que un usuario debe existir en Ozzie antes de que cualquier dato financiero, meta o plan pueda asociarse con él.

Por qué Esto Importa para tu Integración

Entender el modelo de usuario moldea cómo construyes:

• Enrutamiento: Usa external_user_id para no tener que almacenar el UUID de Ozzie en tu base de datos.
• Gates de onboarding: Verifica onboarding_stage para decidir qué pantallas de UI mostrar.
• Localización: Establece language_preference correctamente al crear para asegurar que todo el contenido de IA esté en el idioma correcto desde el primer día.