Metas

Uma Meta representa o objetivo financeiro principal do usuário. Cada usuário tem uma meta ativa por vez, e ela molda diretamente o tom e as prioridades do plano financeiro, money moves e respostas do coach de IA.

Tipos de meta:

• "savings" — o usuário está trabalhando para atingir um alvo de poupança (ex.: fundo de emergência, entrada para imóvel)
• "debt" — o usuário está focado em quitar dívidas (ex.: cartão de crédito, empréstimos estudantis)

---

Referência do objeto

Campo	Tipo	Descrição
id	string	Identificador único desta meta
user_id	string	O usuário Ozzie a quem esta meta pertence
goal_type	"savings" | "debt"	O tipo de meta financeira
goal_name	string	Um rótulo legível para a meta (ex.: "Fundo de Emergência")
target_amount	number	O valor em dinheiro que o usuário está tentando atingir ou eliminar
starting_amount	number	O saldo atual ou valor da dívida do usuário no momento da criação da meta
cadence	"weekly" | "biweekly" | "twice_monthly" | "monthly"	Com que frequência o usuário quer fazer contribuições de progresso
next_move_date	string (ISO 8601)	A próxima data agendada para uma contribuição de money move
created_at	string (ISO 8601)	Timestamp de quando a meta foi criada

---

GET /v1/users/{user_id}/goals

Recupera a meta atualmente ativa do usuário. Retorna um único objeto de meta (usuários têm uma meta ativa por vez).

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
user_id	string	Sim	O ID do usuário Ozzie

Requisição

curl

curl https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals \
  -H "Authorization: Bearer ozp_Y2xpZW50X2ExYjJjM2Q0OnNrX2xpdmVfeEs5bVAycVI3dEwu"

Node.js

const token = Buffer.from(
  `${process.env.OZZIE_CLIENT_ID}:${process.env.OZZIE_CLIENT_SECRET}`
).toString('base64');

const response = await fetch(
  'https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals',
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { data } = await response.json();
console.log(data);

Python

import base64, os, httpx

token = base64.b64encode(
    f"{os.environ['OZZIE_CLIENT_ID']}:{os.environ['OZZIE_CLIENT_SECRET']}".encode()
).decode()

response = httpx.get(
    "https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals",
    headers={"Authorization": f"Bearer {token}"},
)

print(response.json()["data"])

Resposta

{
  "object": "goal",
  "data": {
    "id": "goal_9c2e7a1b4d",
    "user_id": "usr_4f8a1b2c3d",
    "goal_type": "savings",
    "goal_name": "Emergency Fund",
    "target_amount": 10000.00,
    "starting_amount": 1200.00,
    "cadence": "biweekly",
    "next_move_date": "2025-05-19T00:00:00Z",
    "created_at": "2025-05-05T14:32:10Z"
  }
}

Erros

Código	Status HTTP	Quando ocorre
UNAUTHORIZED	401	Credenciais ausentes ou inválidas
NOT_FOUND	404	O usuário não existe, ou não tem meta ativa

---

POST /v1/users/{user_id}/goals

Cria ou atualiza a meta ativa do usuário. Se já existe uma meta, esta chamada a substitui completamente pelos novos valores. Não há endpoint PATCH separado — sempre envie o objeto de meta completo.

informação

Definir ou atualizar uma meta fará com que o coach de IA recalibre suas recomendações no próximo chat ou geração de money move. Se um plano existir, ele refletirá a nova meta na próxima vez que POST /plan for chamado.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
user_id	string	Sim	O ID do usuário Ozzie

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
goal_type	"savings" | "debt"	Sim	O tipo de meta
goal_name	string	Sim	Um rótulo curto para a meta. Máx 100 caracteres.
target_amount	number	Sim	O valor alvo em dinheiro. Deve ser positivo.
starting_amount	number	Sim	Saldo atual ou dívida atual. Deve ser ≥ 0.
cadence	"weekly" | "biweekly" | "twice_monthly" | "monthly"	Sim	Frequência de contribuição

Requisição

curl

curl -X POST https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals \
  -H "Authorization: Bearer ozp_Y2xpZW50X2ExYjJjM2Q0OnNrX2xpdmVfeEs5bVAycVI3dEwu" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "savings",
    "goal_name": "Emergency Fund",
    "target_amount": 10000.00,
    "starting_amount": 1200.00,
    "cadence": "biweekly"
  }'

Node.js

const token = Buffer.from(
  `${process.env.OZZIE_CLIENT_ID}:${process.env.OZZIE_CLIENT_SECRET}`
).toString('base64');

const response = await fetch(
  'https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      goal_type: 'savings',
      goal_name: 'Emergency Fund',
      target_amount: 10000.00,
      starting_amount: 1200.00,
      cadence: 'biweekly',
    }),
  }
);

const { data } = await response.json();
console.log(data);

Python

import base64, os, httpx

token = base64.b64encode(
    f"{os.environ['OZZIE_CLIENT_ID']}:{os.environ['OZZIE_CLIENT_SECRET']}".encode()
).decode()

response = httpx.post(
    "https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "goal_type": "savings",
        "goal_name": "Emergency Fund",
        "target_amount": 10000.00,
        "starting_amount": 1200.00,
        "cadence": "biweekly",
    },
)

print(response.json()["data"])

Resposta

Retorna o objeto de meta criado ou atualizado completo.

{
  "object": "goal",
  "data": {
    "id": "goal_9c2e7a1b4d",
    "user_id": "usr_4f8a1b2c3d",
    "goal_type": "savings",
    "goal_name": "Emergency Fund",
    "target_amount": 10000.00,
    "starting_amount": 1200.00,
    "cadence": "biweekly",
    "next_move_date": "2025-05-19T00:00:00Z",
    "created_at": "2025-05-05T14:32:10Z"
  }
}

Exemplo de quitação de dívida

curl -X POST https://api.ozzieapp.com/v1/users/usr_4f8a1b2c3d/goals \
  -H "Authorization: Bearer ozp_Y2xpZW50X2ExYjJjM2Q0OnNrX2xpdmVfeEs5bVAycVI3dEwu" \
  -H "Content-Type: application/json" \
  -d '{
    "goal_type": "debt",
    "goal_name": "Quitar Cartão de Crédito",
    "target_amount": 0,
    "starting_amount": 4850.00,
    "cadence": "monthly"
  }'

{
  "object": "goal",
  "data": {
    "id": "goal_7d3f9b2e1a",
    "user_id": "usr_4f8a1b2c3d",
    "goal_type": "debt",
    "goal_name": "Quitar Cartão de Crédito",
    "target_amount": 0,
    "starting_amount": 4850.00,
    "cadence": "monthly",
    "next_move_date": "2025-06-01T00:00:00Z",
    "created_at": "2025-05-05T15:00:00Z"
  }
}

Erros

Código	Status HTTP	Quando ocorre
UNAUTHORIZED	401	Credenciais ausentes ou inválidas
NOT_FOUND	404	O usuário não existe
VALIDATION_ERROR	422	Campos obrigatórios ausentes, goal_type ou cadence inválidos, target_amount negativo
INVALID_JSON	400	O corpo da requisição não é JSON válido

dica

Para metas de dívida, defina target_amount como 0 — esse é o estado da meta (dívida zero). Defina starting_amount como o saldo devedor atual.