Fluxo e Sequência da API

Esta página descreve a sequência exata de chamadas de API para integrar o Ozzie do zero. Foi projetada para que qualquer desenvolvedor ou agente LLM possa lê-la e imediatamente entender a ordem correta das operações, o que cada chamada requer, o que ela desbloqueia e como recuperar de erros.

Dois padrões de integração

O Ozzie suporta dois fluxos: Fluxo A (criar usuário primeiro, depois usar o UUID do Ozzie) e Fluxo B (pular a criação — use external:{seu_id} diretamente em qualquer endpoint e o Ozzie cria o usuário automaticamente no primeiro uso). A sequência abaixo mostra o Fluxo A. Para o Fluxo B, veja Integração com ID Externo.

Fluxo de Integração Completo

┌─────────────────────────────────────────────────────────────────────┐
│                   SEQUÊNCIA DE INTEGRAÇÃO OZZIE                     │
└─────────────────────────────────────────────────────────────────────┘

  [1] POST /v1/users
        │
        │  Cria o registro do usuário. Retorna user_id (UUID).
        ▼
  [2] POST /v1/users/{user_id}/financial-intake
        │
        │  Armazena renda mensal, despesas e objetivo financeiro.
        │  Obrigatório antes de gerar um plano.
        ▼
  [3] POST /v1/users/{user_id}/plan/generate
        │
        │  Gera um plano personalizado de poupança/dívida usando
        │  o snapshot de intake financeiro mais recente.
        ▼
  [4] POST /v1/users/{user_id}/goals
        │
        │  Define objetivos financeiros específicos (ex: "Economizar
        │  R$5.000 para fundo de emergência até dez 2025").
        ▼
  [5] POST /v1/users/{user_id}/transactions
        │
        │  Envia despesas/receitas (texto, imagem, PDF, CSV).
        │  O Ozzie usa GPT-4o para analisá-las e categorizá-las.
        ▼
  [6] GET /v1/users/{user_id}/money-moves
        │
        │  Busca recomendações personalizadas de gastos
        │  com base no plano e nas transações recentes.
        ▼
  [7] POST /v1/users/{user_id}/chat
        │
        │  Envia uma mensagem ao assistente financeiro do Ozzie.
        │  Consciente do contexto: usa plano, metas e transações.
        ▼
       FIM (repita os passos 5–7 para uso contínuo)

Referência Passo a Passo

Passo 1 — Criar Usuário

Endpoint: POST /v1/users Desbloqueia: Todos os endpoints subsequentes para este usuário.

Exemplo de Requisição:

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

{
  "external_user_id": "usr_8821",
  "name": "Maria Santos",
  "email": "maria@example.com",
  "phone": "+5511999999999",
  "language": "pt"
}

informação

Salve o campo id (ozz_usr_...). Este é o user_id usado em todas as chamadas subsequentes.

Passo 2 — Enviar Intake Financeiro

Endpoint: POST /v1/users/{user_id}/financial-intake Desbloqueia: Geração do plano (Passo 3). O endpoint de plano retornará INTAKE_REQUIRED até que este seja chamado.

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

Passo 3 — Gerar Plano

Endpoint: POST /v1/users/{user_id}/plan/generate Requer: Intake financeiro deve existir (Passo 2).

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

{}

Passo 4 — Definir 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": "Fundo de Emergência",
  "target_amount": 5000,
  "currency": "BRL",
  "target_date": "2025-12-31"
}

Passo 5 — Registrar Transações

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": "Gastei R$45 no supermercado e R$12 na condução",
  "language": "pt"
}

Passo 6 — Buscar Money Moves

Endpoint: GET /v1/users/{user_id}/money-moves Requer: Plano deve existir (Passo 3).

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

Passo 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": "Estou no caminho certo para atingir minha meta de fundo de emergência?",
  "language": "pt"
}

Fluxo de Onboarding

A sequência mínima para fazer o onboarding completo de um novo usuário são os Passos 1–3:

POST /v1/users                              → obter user_id
POST /v1/users/{user_id}/financial-intake   → armazenar renda/despesas/meta
POST /v1/users/{user_id}/plan/generate      → criar plano personalizado

Estágio	Valor de `onboarding_stage`	O que está disponível
Após Passo 1	`intake_pending`	Usuário criado, intake necessário
Após Passo 2	`plan_pending`	Intake armazenado, plano necessário
Após Passo 3	`active`	Acesso completo à plataforma

Onboarding mínimo viável

Se você quer integrar usuários ao Ozzie o mais rápido possível, colete monthly_income, monthly_expenses e financial_goal junto com a criação do usuário e dispare as três chamadas em rápida sucessão.

Uso Contínuo

Após o onboarding, as chamadas principais para um usuário ativo são:

Chamada	Quando fazer	Frequência
`POST /v1/users/{user_id}/transactions`	Usuário envia uma despesa ou receita	Por evento de transação
`GET /v1/users/{user_id}/transactions`	Exibir histórico de transações	Sob demanda
`GET /v1/users/{user_id}/money-moves`	Mostrar recomendações de gastos	Diário ou sob demanda
`POST /v1/users/{user_id}/chat`	Usuário envia uma mensagem ao Ozzie	Por mensagem de chat
`POST /v1/users/{user_id}/financial-intake`	As finanças do usuário mudam significativamente	Mensal ou na mudança
`POST /v1/users/{user_id}/plan/generate`	Após atualizar o intake	Após cada novo intake

Fluxo WhatsApp

O Ozzie suporta ingestão baseada em webhook do WhatsApp. Quando um usuário envia uma mensagem via WhatsApp, o fluxo é:

Usuário envia mensagem WhatsApp
        │
        ▼
Webhook WhatsApp do Ozzie recebe a mensagem
        │
        ▼
Ozzie identifica o usuário pelo número de telefone (E.164)
        │  ── se não encontrar → solicita ao usuário que se registre
        ▼
POST /v1/users/{user_id}/transactions   (chamado internamente)
        │
        ▼
Ozzie responde via WhatsApp com confirmação da transação analisada

Correspondência de telefone WhatsApp

Os números de telefone devem ser armazenados no formato E.164 (ex: +5511999999999). Mensagens WhatsApp de números que não correspondem a nenhum registro de usuário receberão um prompt de onboarding e não serão registradas como transações.

Estados de Erro e Recuperação

Situação	Código de Erro	Recuperação
Chamar `plan/generate` antes do intake	`INTAKE_REQUIRED`	Chame `POST /financial-intake` primeiro, depois tente novamente
Chamar money-moves antes do plano	`PLAN_REQUIRED`	Chame `POST /plan/generate` primeiro, depois tente novamente
Criar usuário com `external_user_id` duplicado	`CONFLICT`	Use `GET /v1/users/{user_id}` para buscar o usuário existente
Valor de campo inválido	`VALIDATION_ERROR`	Corrija o campo conforme a `message` de erro e tente novamente
Muitas requisições	`RATE_LIMIT_EXCEEDED`	Respeite o header `Retry-After`; implemente backoff exponencial

Fluxo de Integração Completo​

Referência Passo a Passo​

Passo 1 — Criar Usuário​

Passo 2 — Enviar Intake Financeiro​

Passo 3 — Gerar Plano​

Passo 4 — Definir Metas​

Passo 5 — Registrar Transações​

Passo 6 — Buscar Money Moves​

Passo 7 — Chat​

Fluxo de Onboarding​

Uso Contínuo​

Fluxo WhatsApp​

Estados de Erro e Recuperação​