Usuários

O objeto User é a entidade raiz no Ozzie. Todos os outros recursos — intakes financeiros, planos, metas, transações, mensagens de chat — têm escopo para um usuário. Você cria um usuário por pessoa no seu sistema, identificado pelo seu próprio external_user_id.

O Objeto User

{
  "object": "user",
  "data": {
    "id": "ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE",
    "external_user_id": "usr_8821",
    "name": "Maria Santos",
    "email": "maria@example.com",
    "phone": "+15551234567",
    "language": "en",
    "onboarding_stage": "active",
    "created_at": "2025-05-05T14:30:00Z"
  }
}

Campos do Objeto User

Campo	Tipo	Descrição
`id`	string	UUID gerado pelo Ozzie para este usuário. Use em todos os caminhos de API subsequentes.
`external_user_id`	string	Seu ID de usuário interno. Único por cliente de API.
`name`	string \| null	Nome de exibição do usuário.
`email`	string \| null	Endereço de e-mail do usuário.
`phone`	string \| null	Número de telefone do usuário no formato E.164. Necessário para integração com WhatsApp.
`language`	string	Preferência de idioma: `"en"`, `"pt"` ou `"es"`.
`onboarding_stage`	string	Estado atual do onboarding (veja tabela abaixo).
`created_at`	string	Timestamp UTC ISO 8601 de quando o usuário foi criado.

Valores de `onboarding_stage`

Valor	Significado
`intake_pending`	Usuário criado, nenhum intake financeiro enviado ainda
`plan_pending`	Intake enviado, plano ainda não gerado
`active`	Plano gerado — acesso completo à plataforma disponível

POST /v1/users

Cria um novo usuário sob seu cliente de API. Cada usuário deve ter um external_user_id único dentro da sua conta de cliente.

Corpo da Requisição

Campo	Tipo	Obrigatório	Restrições	Descrição
`external_user_id`	string	Sim	Máx 100 chars	Seu ID de usuário interno (ex.: chave primária do banco de dados ou UUID)
`name`	string	Não	Máx 200 chars	Nome de exibição do usuário
`email`	string	Não	Formato de e-mail válido	Endereço de e-mail do usuário
`phone`	string	Não	Formato E.164	Número de telefone, ex.: `+5511999999999`. Necessário para WhatsApp.
`language`	string	Não	`"en"` \| `"pt"` \| `"es"`	Idioma do chat e notificações. Padrão `"en"`.

Resposta

Retorna o objeto user criado com HTTP 201 Created.

Erros

Código	HTTP	Quando
`CONFLICT`	`409`	Já existe um usuário com este `external_user_id` sob seu cliente
`VALIDATION_ERROR`	`400`	Um campo falhou na validação (ex.: formato de e-mail inválido, telefone não em E.164)
`UNAUTHORIZED`	`401`	Credenciais ausentes ou inválidas

Exemplos

curl
Node.js
Python

curl -X POST https://api.ozzieapp.com/v1/users \
  -H "Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "usr_8821",
    "name": "Ana Silva",
    "email": "ana@exemplo.com.br",
    "phone": "+5511999999999",
    "language": "pt"
  }'

import fetch from 'node-fetch';

const token = Buffer.from('seu_client_id:seu_client_secret').toString('base64');

const response = await fetch('https://api.ozzieapp.com/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_user_id: 'usr_8821',
    name: 'Ana Silva',
    email: 'ana@exemplo.com.br',
    phone: '+5511999999999',
    language: 'pt',
  }),
});

const { data: user } = await response.json();
console.log('Usuário criado:', user.id);

import requests
import base64

token = base64.b64encode(b'seu_client_id:seu_client_secret').decode()

response = requests.post(
    'https://api.ozzieapp.com/v1/users',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'external_user_id': 'usr_8821',
        'name': 'Ana Silva',
        'email': 'ana@exemplo.com.br',
        'phone': '+5511999999999',
        'language': 'pt',
    }
)

user = response.json()['data']
print(f"Usuário criado: {user['id']}")

Exemplo de Resposta (201 Created):

{
  "object": "user",
  "data": {
    "id": "ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE",
    "external_user_id": "usr_8821",
    "name": "Ana Silva",
    "email": "ana@exemplo.com.br",
    "phone": "+5511999999999",
    "language": "pt",
    "onboarding_stage": "intake_pending",
    "created_at": "2025-05-05T14:30:00Z"
  }
}

Resposta de Erro — Usuário duplicado (409 Conflict):

{
  "error": {
    "code": "CONFLICT",
    "message": "A user with external_user_id 'usr_8821' already exists under your API client. Use GET /v1/users/{user_id} to retrieve them."
  }
}

Resposta de Erro — E-mail inválido (400 Validation Error):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' must be a valid email address. Received: 'not-an-email'."
  }
}

Tratando CONFLICT de forma elegante

Se não tiver certeza se um usuário já existe, capture o erro CONFLICT e imediatamente chame GET /v1/users/external:{external_user_id} para recuperar o registro existente. Isso é seguro para fazer em um fluxo estilo upsert.

GET /v1/users/{user_id}

Recupera um usuário pelo UUID Ozzie ou pelo external_user_id.

Parâmetro de Caminho

Parâmetro	Descrição
`user_id`	O UUID Ozzie (ex.: `ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE`) ou um ID externo com prefixo (ex.: `external:usr_8821`)

Busca por external_user_id

Para buscar um usuário pelo seu próprio ID em vez do UUID Ozzie, prefixe o valor com external::

GET /v1/users/external:usr_8821

Isso é equivalente a consultar por external_user_id e evita a necessidade de armazenar o UUID Ozzie no seu banco de dados no momento da criação.

Resposta

Retorna o objeto user com HTTP 200 OK.

Erros

Código	HTTP	Quando
`NOT_FOUND`	`404`	Nenhum usuário existe com este ID sob seu cliente
`UNAUTHORIZED`	`401`	Credenciais ausentes ou inválidas
`FORBIDDEN`	`403`	O usuário existe mas pertence a um cliente de API diferente

Exemplos

curl
Node.js
Python

# Por UUID Ozzie
curl https://api.ozzieapp.com/v1/users/ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE \
  -H "Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ="

# Por external_user_id
curl "https://api.ozzieapp.com/v1/users/external:usr_8821" \
  -H "Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ="

import fetch from 'node-fetch';

const token = Buffer.from('seu_client_id:seu_client_secret').toString('base64');

// Por UUID Ozzie
const res = await fetch(
  'https://api.ozzieapp.com/v1/users/ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE',
  { headers: { 'Authorization': `Bearer ${token}` } }
);

// Por external_user_id
const res2 = await fetch(
  'https://api.ozzieapp.com/v1/users/external:usr_8821',
  { headers: { 'Authorization': `Bearer ${token}` } }
);

const { data: user } = await res.json();
console.log('Estágio de onboarding:', user.onboarding_stage);

import requests
import base64

token = base64.b64encode(b'seu_client_id:seu_client_secret').decode()
headers = {'Authorization': f'Bearer {token}'}

# Por UUID Ozzie
response = requests.get(
    'https://api.ozzieapp.com/v1/users/ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE',
    headers=headers
)

# Por external_user_id
response2 = requests.get(
    'https://api.ozzieapp.com/v1/users/external:usr_8821',
    headers=headers
)

user = response.json()['data']
print(f"Estágio de onboarding: {user['onboarding_stage']}")

Exemplo de Resposta (200 OK):

{
  "object": "user",
  "data": {
    "id": "ozz_usr_01HX9KZMR4P5JQNBVT7YCW3DE",
    "external_user_id": "usr_8821",
    "name": "Ana Silva",
    "email": "ana@exemplo.com.br",
    "phone": "+5511999999999",
    "language": "pt",
    "onboarding_stage": "active",
    "created_at": "2025-05-05T14:30:00Z"
  }
}

Resposta de Erro — Não encontrado (404):

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No user found with id 'ozz_usr_NOTEXIST' under your API client."
  }
}

Verificando onboarding_stage

Use GET /v1/users/{user_id} para verificar o onboarding_stage de um usuário antes de decidir qual UI mostrar. Se o estágio for intake_pending, solicite ao usuário seus detalhes financeiros. Se plan_pending, mostre um estado de carregamento enquanto aciona a geração do plano.

O Objeto User​

Campos do Objeto User​

Valores de onboarding_stage​

POST /v1/users​

Corpo da Requisição​

Resposta​

Erros​

Exemplos​

GET /v1/users/{user_id}​

Parâmetro de Caminho​

Busca por external_user_id​

Resposta​

Erros​

Exemplos​

O Objeto User

Campos do Objeto User

Valores de `onboarding_stage`

POST /v1/users

Corpo da Requisição

Resposta

Erros

Exemplos

GET /v1/users/{user_id}

Parâmetro de Caminho

Busca por external_user_id

Resposta

Erros

Exemplos