Metas

Una Meta representa el objetivo financiero principal del usuario. Cada usuario tiene una meta activa a la vez, y moldea directamente el tono y las prioridades de su plan financiero, money moves y respuestas del coach de IA.

Tipos de meta:

"savings" — el usuario está trabajando para alcanzar un objetivo de ahorro (ej.: fondo de emergencia, pago inicial de vivienda)
"debt" — el usuario está enfocado en pagar deudas (ej.: tarjeta de crédito, préstamos estudiantiles)

Referencia del objeto

Campo	Tipo	Descripción
`id`	string	Identificador único de esta meta
`user_id`	string	El usuario Ozzie al que pertenece esta meta
`goal_type`	`"savings"` \| `"debt"`	El tipo de meta financiera
`goal_name`	string	Una etiqueta legible para la meta (ej.: `"Fondo de Emergencia"`)
`target_amount`	number	El monto en dinero que el usuario intenta alcanzar o eliminar
`starting_amount`	number	El saldo actual o monto de deuda del usuario al crear la meta
`cadence`	`"weekly"` \| `"biweekly"` \| `"twice_monthly"` \| `"monthly"`	Con qué frecuencia el usuario quiere hacer contribuciones de progreso
`next_move_date`	string (ISO 8601)	La próxima fecha programada para una contribución de money move
`created_at`	string (ISO 8601)	Timestamp de cuando se creó la meta

GET /v1/users/{user_id}/goals

Recupera la meta actualmente activa del usuario. Devuelve un único objeto de meta (los usuarios tienen una meta activa a la vez).

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`user_id`	string	Sí	El ID de usuario de Ozzie

Solicitud

curl
Node.js
Python

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

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);

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"])

Respuesta

{
  "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"
  }
}

Errores

Código	Estado HTTP	Cuándo ocurre
`UNAUTHORIZED`	401	Credenciales ausentes o inválidas
`NOT_FOUND`	404	El usuario no existe, o no tiene meta activa

POST /v1/users/{user_id}/goals

Crea o actualiza la meta activa del usuario. Si ya existe una meta, esta llamada la reemplaza completamente con los nuevos valores. No hay endpoint PATCH separado — siempre envía el objeto de meta completo.

info

Establecer o actualizar una meta hará que el coach de IA recalibre sus recomendaciones en el próximo chat o generación de money move. Si existe un plan, reflejará la nueva meta la próxima vez que se llame a POST /plan.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`user_id`	string	Sí	El ID de usuario de Ozzie

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`goal_type`	`"savings"` \| `"debt"`	Sí	El tipo de meta
`goal_name`	string	Sí	Una etiqueta corta para la meta. Máx 100 caracteres.
`target_amount`	number	Sí	El monto objetivo en dinero. Debe ser positivo.
`starting_amount`	number	Sí	Saldo actual o deuda actual. Debe ser ≥ 0.
`cadence`	`"weekly"` \| `"biweekly"` \| `"twice_monthly"` \| `"monthly"`	Sí	Frecuencia de contribución

Solicitud

curl
Node.js
Python

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": "Fondo de Emergencia",
    "target_amount": 10000.00,
    "starting_amount": 1200.00,
    "cadence": "biweekly"
  }'

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: 'Fondo de Emergencia',
      target_amount: 10000.00,
      starting_amount: 1200.00,
      cadence: 'biweekly',
    }),
  }
);

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

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": "Fondo de Emergencia",
        "target_amount": 10000.00,
        "starting_amount": 1200.00,
        "cadence": "biweekly",
    },
)

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

Respuesta

Devuelve el objeto de meta creado o actualizado completo.

{
  "object": "goal",
  "data": {
    "id": "goal_9c2e7a1b4d",
    "user_id": "usr_4f8a1b2c3d",
    "goal_type": "savings",
    "goal_name": "Fondo de Emergencia",
    "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"
  }
}

Ejemplo de pago de deuda

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": "Pagar Tarjeta 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": "Pagar Tarjeta 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"
  }
}

Errores

Código	Estado HTTP	Cuándo ocurre
`UNAUTHORIZED`	401	Credenciales ausentes o inválidas
`NOT_FOUND`	404	El usuario no existe
`VALIDATION_ERROR`	422	Campos requeridos faltantes, `goal_type` o `cadence` inválidos, `target_amount` negativo
`INVALID_JSON`	400	El cuerpo de la solicitud no es JSON válido

tip

Para metas de deuda, establece target_amount en 0 — ese es el estado de la meta (deuda cero). Establece starting_amount en el saldo pendiente actual.

Referencia del objeto​

GET /v1/users/{user_id}/goals​

Parámetros de ruta​

Solicitud​

Respuesta​

Errores​

POST /v1/users/{user_id}/goals​

Parámetros de ruta​

Cuerpo de la solicitud​

Solicitud​

Respuesta​

Ejemplo de pago de deuda​

Errores​

Referencia del objeto

GET /v1/users/{user_id}/goals

Parámetros de ruta

Solicitud

Respuesta

Errores

POST /v1/users/{user_id}/goals

Parámetros de ruta

Cuerpo de la solicitud

Solicitud

Respuesta

Ejemplo de pago de deuda

Errores