Flujo y Secuencia de la API

Esta página describe la secuencia exacta de llamadas a la API para integrar Ozzie desde cero. Está diseñada para que cualquier desarrollador o agente LLM pueda leerla e inmediatamente entender el orden correcto de las operaciones, qué requiere cada llamada, qué desbloquea y cómo recuperarse de errores.

Dos patrones de integración

Ozzie soporta dos flujos: Flujo A (crear usuario primero, luego usar el UUID de Ozzie) y Flujo B (omitir la creación — usa external:{tu_id} directamente en cualquier endpoint y Ozzie aprovisiona al usuario automáticamente en el primer uso). La secuencia a continuación muestra el Flujo A. Para el Flujo B, consulta Integración con ID Externo.

Flujo de Integración Completo

┌─────────────────────────────────────────────────────────────────────┐
│                   SECUENCIA DE INTEGRACIÓN OZZIE                    │
└─────────────────────────────────────────────────────────────────────┘

  [1] POST /v1/users
        │
        │  Crea el registro del usuario. Devuelve user_id (UUID).
        ▼
  [2] POST /v1/users/{user_id}/financial-intake
        │
        │  Almacena ingresos mensuales, gastos y objetivo financiero.
        │  Requerido antes de generar un plan.
        ▼
  [3] POST /v1/users/{user_id}/plan/generate
        │
        │  Genera un plan personalizado de ahorro/deuda usando
        │  el snapshot de intake financiero más reciente.
        ▼
  [4] POST /v1/users/{user_id}/goals
        │
        │  Establece objetivos financieros específicos (ej: "Ahorrar
        │  $5.000 para fondo de emergencia para dic 2025").
        ▼
  [5] POST /v1/users/{user_id}/transactions
        │
        │  Envía gastos/ingresos (texto, imagen, PDF, CSV).
        │  Ozzie usa GPT-4o para analizarlos y categorizarlos.
        ▼
  [6] GET /v1/users/{user_id}/money-moves
        │
        │  Obtiene recomendaciones personalizadas de gasto
        │  basadas en el plan y las transacciones recientes.
        ▼
  [7] POST /v1/users/{user_id}/chat
        │
        │  Envía un mensaje al asistente financiero de Ozzie.
        │  Consciente del contexto: usa plan, metas y transacciones.
        ▼
       FIN (repite los pasos 5–7 para uso continuo)

Referencia Paso a Paso

Paso 1 — Crear Usuario

Endpoint: POST /v1/users Desbloquea: Todos los endpoints posteriores para este usuario.

Ejemplo de Solicitud:

POST https://api.ozzieapp.com/v1/users
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{
  "external_user_id": "usr_8821",
  "name": "Carlos García",
  "email": "carlos@example.com",
  "phone": "+5215512345678",
  "language": "es"
}

info

Guarda el campo id (ozz_usr_...). Este es el user_id usado en todas las llamadas posteriores.

Paso 2 — Enviar Intake Financiero

Endpoint: POST /v1/users/{user_id}/financial-intake Desbloquea: Generación del plan (Paso 3). El endpoint de plan devolverá INTAKE_REQUIRED hasta que se llame este.

POST https://api.ozzieapp.com/v1/users/ozz_usr_.../financial-intake
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{
  "monthly_income": 5000,
  "monthly_expenses": 3200,
  "financial_goal": "savings",
  "next_pay_date": "2025-05-15"
}

Paso 3 — Generar Plan

Endpoint: POST /v1/users/{user_id}/plan/generate Requiere: Intake financiero debe existir (Paso 2).

POST https://api.ozzieapp.com/v1/users/ozz_usr_.../plan/generate
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{}

Paso 4 — Establecer Metas

Endpoint: POST /v1/users/{user_id}/goals

POST https://api.ozzieapp.com/v1/users/ozz_usr_.../goals
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{
  "name": "Fondo de Emergencia",
  "target_amount": 5000,
  "currency": "USD",
  "target_date": "2025-12-31"
}

Paso 5 — Registrar Transacciones

Endpoint: POST /v1/users/{user_id}/transactions

POST https://api.ozzieapp.com/v1/users/ozz_usr_.../transactions
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{
  "type": "text",
  "content": "Gasté $45 en el supermercado y $12 en transporte",
  "language": "es"
}

Paso 6 — Obtener Money Moves

Endpoint: GET /v1/users/{user_id}/money-moves Requiere: Plan debe existir (Paso 3).

GET https://api.ozzieapp.com/v1/users/ozz_usr_.../money-moves
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=

Paso 7 — Chat

Endpoint: POST /v1/users/{user_id}/chat

POST https://api.ozzieapp.com/v1/users/ozz_usr_.../chat
Authorization: Bearer czJjbGllbnQ6czJzZWNyZXQ=
Content-Type: application/json

{
  "message": "¿Estoy en camino para alcanzar mi meta de fondo de emergencia?",
  "language": "es"
}

Flujo de Onboarding

La secuencia mínima para hacer el onboarding completo de un nuevo usuario son los Pasos 1–3:

POST /v1/users                              → obtener user_id
POST /v1/users/{user_id}/financial-intake   → almacenar ingresos/gastos/meta
POST /v1/users/{user_id}/plan/generate      → crear plan personalizado

Etapa	Valor de `onboarding_stage`	Qué está disponible
Después del Paso 1	`intake_pending`	Usuario creado, intake requerido
Después del Paso 2	`plan_pending`	Intake almacenado, plan requerido
Después del Paso 3	`active`	Acceso completo a la plataforma

Onboarding mínimo viable

Si quieres integrar usuarios a Ozzie lo más rápido posible, recoge monthly_income, monthly_expenses y financial_goal junto con la creación del usuario y dispara las tres llamadas en rápida sucesión.

Uso Continuo

Después del onboarding, las llamadas principales para un usuario activo son:

Llamada	Cuándo hacerla	Frecuencia
`POST /v1/users/{user_id}/transactions`	Usuario envía un gasto o ingreso	Por evento de transacción
`GET /v1/users/{user_id}/transactions`	Mostrar historial de transacciones	Bajo demanda
`GET /v1/users/{user_id}/money-moves`	Mostrar recomendaciones de gasto	Diario o bajo demanda
`POST /v1/users/{user_id}/chat`	Usuario envía un mensaje a Ozzie	Por mensaje de chat
`POST /v1/users/{user_id}/financial-intake`	Las finanzas del usuario cambian significativamente	Mensual o al cambiar
`POST /v1/users/{user_id}/plan/generate`	Después de actualizar el intake	Después de cada nuevo intake

Flujo de WhatsApp

Ozzie soporta ingesta basada en webhook de WhatsApp:

Usuario envía mensaje de WhatsApp
        │
        ▼
Webhook de WhatsApp de Ozzie recibe el mensaje
        │
        ▼
Ozzie identifica al usuario por número de teléfono (E.164)
        │  ── si no hay coincidencia → solicita al usuario que se registre
        ▼
POST /v1/users/{user_id}/transactions   (llamado internamente)
        │
        ▼
Ozzie responde vía WhatsApp con confirmación de la transacción analizada

Coincidencia de teléfono WhatsApp

Los números de teléfono deben almacenarse en formato E.164 (ej: +5215512345678). Los mensajes de WhatsApp de números que no coinciden con ningún registro de usuario recibirán un prompt de onboarding y no se registrarán como transacciones.

Estados de Error y Recuperación

Situación	Código de Error	Recuperación
Llamar `plan/generate` antes del intake	`INTAKE_REQUIRED`	Llama `POST /financial-intake` primero, luego reintenta
Llamar money-moves antes del plan	`PLAN_REQUIRED`	Llama `POST /plan/generate` primero, luego reintenta
Crear usuario con `external_user_id` duplicado	`CONFLICT`	Usa `GET /v1/users/{user_id}` para obtener el usuario existente
Valor de campo inválido	`VALIDATION_ERROR`	Corrige el campo según el `message` de error y reintenta
Demasiadas solicitudes	`RATE_LIMIT_EXCEEDED`	Respeta el header `Retry-After`; implementa backoff exponencial

Flujo de Integración Completo​

Referencia Paso a Paso​

Paso 1 — Crear Usuario​

Paso 2 — Enviar Intake Financiero​

Paso 3 — Generar Plan​

Paso 4 — Establecer Metas​

Paso 5 — Registrar Transacciones​

Paso 6 — Obtener Money Moves​

Paso 7 — Chat​

Flujo de Onboarding​

Uso Continuo​

Flujo de WhatsApp​

Estados de Error y Recuperación​