Usuários

Referência da API

Para detalhes dos endpoints, veja a Referência da API de Usuários.

O que é um Usuário Ozzie?

Na API Ozzie, um usuário não é uma identidade de autenticação — é um perfil financeiro. Quando você cria um usuário no Ozzie, você está criando um registro persistente que acumula dados financeiros, um plano personalizado, metas ativas e histórico de comportamento ao longo do tempo.

Pense em um usuário como o "avatar financeiro" de um dos seus usuários finais dentro da plataforma Ozzie. O Ozzie não gerencia credenciais de login ou sessões. Essa responsabilidade fica com a sua aplicação. O Ozzie gerencia apenas o que sabe sobre a vida financeira de uma pessoa.

O Modelo Multi-Tenant

A API Ozzie é multi-tenant. Cada cliente da API (identificado pela sua chave de API) opera em seu próprio namespace isolado. Os usuários que você cria são completamente escopo do seu cliente — eles são invisíveis para outros clientes da API, e você não pode acessar usuários que pertencem a outro cliente.

Isso significa:

• Você pode criar quantos usuários seu plano permitir.
• Cada usuário pertence exclusivamente ao seu cliente da API.
• Não existe conceito de "compartilhamento" de usuários entre clientes.

Identidade do Usuário: Dois IDs

Todo usuário Ozzie tem dois identificadores:

Campo	Proprietário	Propósito
external_user_id	Você	Seu ID interno para essa pessoa (ex: UUID do seu banco de dados ou ID de cliente)
id	Ozzie	UUID próprio do Ozzie, gerado automaticamente na criação

Você controla o external_user_id. Você o atribui na criação, e ele deve ser único dentro do seu cliente da API. Este é o identificador principal que você usará para buscar usuários — passe seu próprio ID de usuário e o Ozzie resolve para o perfil financeiro correto.

O id Ozzie (UUID) é retornado em todas as respostas e também pode ser usado para buscas, mas a maioria das integrações acha mais conveniente trabalhar com external_user_id.

Estágios de Onboarding

Um usuário passa por três estágios de onboarding durante seu ciclo de vida:

financial_intake  →  plan  →  active

Estágio	O que significa
financial_intake	Usuário criado, mas ainda não enviou um intake financeiro (renda, despesas, tipo de objetivo)
plan	Intake completo; Ozzie gerou um plano personalizado, mas o usuário ainda não iniciou seu primeiro ciclo de Money Moves
active	O usuário tem pelo menos uma meta ativa e está recebendo Money Moves

Sua integração deve usar o campo onboarding_stage para guiar os usuários pelos fluxos de configuração. Um usuário em financial_intake deve ser solicitado a completar seu intake antes que qualquer outra coisa seja apresentada a ele.

Preferência de Idioma

Os usuários têm um campo language_preference que aceita en, pt ou es. Essa preferência afeta o idioma de:

• Descrições de planos geradas por IA
• Textos das tarefas de Money Moves
• Resumos de insights

Defina esse campo no momento da criação com base no locale do seu usuário, e atualize-o se o usuário mudar a configuração de idioma. O Ozzie não detecta o idioma automaticamente.

Ciclo de Vida do Usuário

O fluxo de integração típico é assim:

Seu app cria o usuário  →  Usuário completa intake  →  Plano é gerado
        ↓
   Meta é definida  →  Money Moves iniciam  →  Transações acumulam  →  Insights aparecem

Quando criar usuários? Você tem duas opções comuns:

• No cadastro: Crie o usuário Ozzie quando seu usuário se registrar no seu app. Esta é a abordagem mais limpa e garante que o perfil Ozzie esteja pronto quando necessário.
• Criação lazy: Crie o usuário Ozzie apenas quando o usuário acessar pela primeira vez um recurso financeiro. Útil se apenas um subconjunto dos seus usuários usará os recursos do Ozzie.

Qualquer abordagem funciona. O importante é que um usuário deve existir no Ozzie antes que qualquer dado financeiro, meta ou plano possa ser associado a ele.

Por que Isso Importa para sua Integração

Entender o modelo de usuário molda como você constrói:

• Roteamento: Use external_user_id para nunca precisar armazenar o UUID do Ozzie no seu banco de dados.
• Gates de onboarding: Verifique onboarding_stage para decidir quais telas de UI mostrar.
• Localização: Defina language_preference corretamente na criação para garantir que todo conteúdo de IA esteja no idioma correto desde o primeiro dia.