Guia Uso Apis Cashflow

Guia de Uso - APIs /cashflow/api

Base URL: https://csuite.internut.com.br/cashflow/api


📋 Índice

  1. Visão Geral
  2. Timeline API
  3. Containers API
  4. Scenarios API
  5. Simulator API
  6. Alerts API
  7. Cash Accounts API
  8. Fixed Expenses API
  9. Sales Forecast API
  10. Parameters API
  11. Exemplos Práticos
  12. Troubleshooting

1. Visão Geral

O CSuite Cashflow é uma API para gestão de fluxo de caixa, permitindo:

Características:
- ✅ API assíncrona (FastAPI + SQLAlchemy async)
- ✅ Autenticação via csuite-auth
- ✅ Integração com Policy Engine
- ✅ Rate limiting (100 req/min IP, 1000 req/min usuário)


2. Timeline API

Base Path: /api/cashflow/timeline

2.1 Timeline de Caixa

Endpoint: GET /api/cashflow/timeline

Descrição: Retorna timeline diária com saldo acumulado.

Parâmetros de Query:
- from_date (date, opcional) - Data inicial (YYYY-MM-DD). Padrão: hoje
- to_date (date, opcional) - Data final (YYYY-MM-DD). Padrão: hoje + 180 dias
- scenario (string, opcional) - Tag do cenário
- account_id (int, opcional) - ID da conta específica
- days (int, padrão: 180) - Número de dias (usado se from/to não informados)

Exemplo:

# Timeline padrão (180 dias)
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline"

# Timeline com período específico
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline?from_date=2024-12-01&to_date=2025-06-30"

# Timeline de um cenário específico
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline?scenario=baseline&days=365"

# Timeline de uma conta específica
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline?account_id=1"

Resposta:

{
  "from_date": "2024-12-01",
  "to_date": "2025-06-30",
  "scenario": "baseline",
  "days": [
    {
      "date": "2024-12-01",
      "balance": 1000000.00,
      "inflows": 50000.00,
      "outflows": -30000.00,
      "net_flow": 20000.00,
      "movements": [
        {
          "type": "INFLOW",
          "amount": 50000.00,
          "description": "Recebimento de vendas",
          "source": "sales_forecast"
        },
        {
          "type": "OUTFLOW",
          "amount": -30000.00,
          "description": "Pagamento de fornecedores",
          "source": "container"
        }
      ]
    }
  ],
  "summary": {
    "min_balance": 850000.00,
    "min_balance_date": "2025-03-15",
    "max_balance": 1200000.00,
    "max_balance_date": "2025-01-10",
    "total_inflows": 9000000.00,
    "total_outflows": -8500000.00,
    "net_flow": 500000.00
  }
}

Casos de uso:
- Visualizar projeção de caixa diária
- Identificar períodos de aperto
- Analisar impacto de cenários


2.2 Resumo da Timeline

Endpoint: GET /api/cashflow/timeline/summary

Descrição: Retorna resumo da timeline (menor saldo, dia de maior aperto, necessidade máxima).

Parâmetros de Query:
- scenario (string, opcional) - Tag do cenário
- days (int, padrão: 180) - Número de dias para análise

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline/summary?scenario=baseline&days=180"

Resposta:

{
  "scenario": "baseline",
  "days": 180,
  "min_balance": 850000.00,
  "min_balance_date": "2025-03-15",
  "max_need": 150000.00,
  "max_need_date": "2025-03-15",
  "avg_balance": 1050000.00,
  "volatility": 0.15
}

3. Containers API

Base Path: /api/cashflow/containers

3.1 Criar Container

Endpoint: POST /api/cashflow/containers

Descrição: Cria um novo container e gera movimentos de caixa relacionados.

Request:

{
  "container_number": "CONT-2024-001",
  "bl_date": "2024-12-01",
  "arrival_date": "2025-01-15",
  "total_value": 500000.00,
  "payment_terms": "30/70",
  "scenario_tag": "baseline",
  "description": "Container de produtos eletrônicos"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/containers" \
  -H "Content-Type: application/json" \
  -d '{
    "container_number": "CONT-2024-001",
    "bl_date": "2024-12-01",
    "arrival_date": "2025-01-15",
    "total_value": 500000.00,
    "payment_terms": "30/70",
    "scenario_tag": "baseline"
  }'

Resposta:

{
  "id": 1,
  "container_number": "CONT-2024-001",
  "bl_date": "2024-12-01",
  "arrival_date": "2025-01-15",
  "transit_days": 45,
  "total_value": 500000.00,
  "payment_terms": "30/70",
  "scenario_tag": "baseline",
  "status": "ACTIVE",
  "created_at": "2024-12-01T10:00:00Z",
  "movements": [
    {
      "date": "2024-12-31",
      "amount": -150000.00,
      "type": "OUTFLOW",
      "description": "Pagamento 30% - CONT-2024-001"
    },
    {
      "date": "2025-01-30",
      "amount": -350000.00,
      "type": "OUTFLOW",
      "description": "Pagamento 70% - CONT-2024-001"
    }
  ]
}

3.2 Listar Containers

Endpoint: GET /api/cashflow/containers

Descrição: Lista containers de importação.

Parâmetros de Query:
- scenario_tag (string, opcional) - Filtrar por cenário
- status (string, opcional) - Filtrar por status (ACTIVE, CANCELLED, etc.)

Exemplo:

# Todos os containers
curl "https://csuite.internut.com.br/cashflow/api/cashflow/containers"

# Containers de um cenário
curl "https://csuite.internut.com.br/cashflow/api/cashflow/containers?scenario_tag=baseline"

# Containers ativos
curl "https://csuite.internut.com.br/cashflow/api/cashflow/containers?status=ACTIVE"

3.3 Obter Container

Endpoint: GET /api/cashflow/containers/{container_id}

Descrição: Obtém detalhes de um container.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/containers/1"

3.4 Atualizar Container

Endpoint: PUT /api/cashflow/containers/{container_id}

Descrição: Atualiza um container e regera movimentos de caixa.

Request:

{
  "bl_date": "2024-12-05",
  "arrival_date": "2025-01-20",
  "total_value": 550000.00,
  "payment_terms": "20/80"
}

3.5 Deletar Container

Endpoint: DELETE /api/cashflow/containers/{container_id}

Descrição: Remove um container e seus movimentos de caixa.

Exemplo:

curl -X DELETE "https://csuite.internut.com.br/cashflow/api/cashflow/containers/1"

Resposta:

{
  "message": "Container removido com sucesso"
}

3.6 Regenerar Movimentos

Endpoint: POST /api/cashflow/containers/{container_id}/regenerate-movements

Descrição: Regenera movimentos de caixa para um container.

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/containers/1/regenerate-movements"

4. Scenarios API

Base Path: /api/cashflow/scenarios

4.1 Criar Cenário

Endpoint: POST /api/cashflow/scenarios

Descrição: Cria um novo cenário.

Request:

{
  "tag": "scenario_optimistic",
  "name": "Cenário Otimista",
  "description": "Cenário com crescimento de 20%",
  "is_active": true
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/scenarios" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "scenario_optimistic",
    "name": "Cenário Otimista",
    "description": "Cenário com crescimento de 20%",
    "is_active": true
  }'

4.2 Listar Cenários

Endpoint: GET /api/cashflow/scenarios

Descrição: Lista todos os cenários.

Parâmetros de Query:
- active_only (bool, padrão: true) - Apenas cenários ativos

Exemplo:

# Apenas ativos
curl "https://csuite.internut.com.br/cashflow/api/cashflow/scenarios?active_only=true"

# Todos os cenários
curl "https://csuite.internut.com.br/cashflow/api/cashflow/scenarios?active_only=false"

4.3 Obter Cenário

Endpoint: GET /api/cashflow/scenarios/{scenario_tag}

Descrição: Obtém detalhes de um cenário.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/scenarios/baseline"

4.4 Atualizar Cenário

Endpoint: PUT /api/cashflow/scenarios/{scenario_tag}

Descrição: Atualiza um cenário.


4.5 Duplicar Cenário

Endpoint: POST /api/cashflow/scenarios/{scenario_tag}/duplicate

Descrição: Duplica um cenário com uma nova tag.

Query Parameters:
- new_tag (string, obrigatório) - Nova tag do cenário

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/scenarios/baseline/duplicate?new_tag=baseline_copy"

5. Simulator API

Base Path: /api/cashflow/simulator

5.1 Executar Simulação

Endpoint: POST /api/cashflow/simulator/run

Descrição: Executa uma simulação what-if.

Request:

{
  "from_date": "2024-12-01",
  "to_date": "2025-06-30",
  "scenario_tag": "baseline",
  "adjustments": {
    "containers": [
      {
        "container_id": 1,
        "transit_days": 70,
        "payment_terms": "20/80",
        "bl_date": "2024-12-05"
      }
    ],
    "sales_forecast_multiplier": 1.2,
    "fixed_expenses_multiplier": 1.1
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/simulator/run" \
  -H "Content-Type: application/json" \
  -d '{
    "from_date": "2024-12-01",
    "to_date": "2025-06-30",
    "scenario_tag": "baseline",
    "adjustments": {
      "containers": [
        {
          "container_id": 1,
          "transit_days": 70,
          "payment_terms": "20/80"
        }
      ]
    }
  }'

Resposta:

{
  "from_date": "2024-12-01",
  "to_date": "2025-06-30",
  "scenario_tag": "baseline",
  "simulated": true,
  "timeline": {
    "days": [...],
    "summary": {
      "min_balance": 800000.00,
      "min_balance_date": "2025-03-20",
      "max_need": 200000.00
    }
  }
}

5.2 Comparar Cenários

Endpoint: POST /api/cashflow/simulator/compare

Descrição: Compara cenário base vs simulado com ajustes de containers.

Request:

{
  "from_date": "2024-12-01",
  "to_date": "2025-06-30",
  "base_scenario": "baseline",
  "simulated_scenario": "baseline",
  "adjustments": {
    "containers": [
      {
        "container_id": 1,
        "transit_days": 70,
        "payment_terms": "20/80"
      }
    ]
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/simulator/compare" \
  -H "Content-Type: application/json" \
  -d '{
    "from_date": "2024-12-01",
    "to_date": "2025-06-30",
    "base_scenario": "baseline",
    "simulated_scenario": "baseline",
    "adjustments": {
      "containers": [
        {
          "container_id": 1,
          "transit_days": 70,
          "payment_terms": "20/80"
        }
      ]
    }
  }'

Resposta:

{
  "from_date": "2024-12-01",
  "to_date": "2025-06-30",
  "base_summary": {
    "min_balance": 850000.00,
    "min_balance_date": "2025-03-15",
    "max_need": 150000.00
  },
  "simulated_summary": {
    "min_balance": 800000.00,
    "min_balance_date": "2025-03-20",
    "max_need": 200000.00
  },
  "differences": {
    "min_balance_delta": -50000.00,
    "max_need_delta": 50000.00,
    "worst_month": "2025-03",
    "cash_shortage": true,
    "shortage_amount": 200000.00
  },
  "monthly_comparison": [
    {
      "month": "2024-12",
      "base_balance": 1000000.00,
      "simulated_balance": 1000000.00,
      "difference": 0.00
    },
    {
      "month": "2025-03",
      "base_balance": 850000.00,
      "simulated_balance": 800000.00,
      "difference": -50000.00
    }
  ]
}

5.3 Impacto de Container

Endpoint: GET /api/cashflow/simulator/containers/{container_id}/impact

Descrição: Obtém o impacto de um container específico no caixa por mês.

Parâmetros de Query:
- scenario (string, opcional) - Tag do cenário

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/simulator/containers/1/impact?scenario=baseline"

Resposta:

{
  "container_id": 1,
  "container_number": "CONT-2024-001",
  "monthly_impact": [
    {
      "month": "2024-12",
      "outflow": -150000.00,
      "description": "Pagamento 30%"
    },
    {
      "month": "2025-01",
      "outflow": -350000.00,
      "description": "Pagamento 70%"
    }
  ],
  "total_impact": -500000.00
}

6. Alerts API

Base Path: /api/cashflow/alerts

6.1 Listar Alertas

Endpoint: GET /api/cashflow/alerts

Descrição: Retorna alertas calculados.

Parâmetros de Query:
- scenario (string, opcional) - Tag do cenário
- severity (string, opcional) - Filtrar por severidade (critical, warning, strategic)
- days_ahead (int, padrão: 90) - Período em dias para verificar alertas

Exemplo:

# Todos os alertas
curl "https://csuite.internut.com.br/cashflow/api/cashflow/alerts"

# Alertas críticos
curl "https://csuite.internut.com.br/cashflow/api/cashflow/alerts?severity=critical"

# Alertas de um cenário
curl "https://csuite.internut.com.br/cashflow/api/cashflow/alerts?scenario=baseline&days_ahead=180"

Resposta:

[
  {
    "id": 1,
    "scenario": "baseline",
    "severity": "critical",
    "alert_type": "LOW_BALANCE",
    "date": "2025-03-15",
    "message": "Saldo mínimo previsto: R$ 850.000,00",
    "current_balance": 850000.00,
    "min_threshold": 1000000.00,
    "shortage": 150000.00,
    "recommendations": [
      "Negociar condições de pagamento com fornecedores",
      "Acelerar recebíveis",
      "Considerar linha de crédito"
    ]
  },
  {
    "id": 2,
    "scenario": "baseline",
    "severity": "warning",
    "alert_type": "HIGH_VOLATILITY",
    "date": "2025-04-01",
    "message": "Alta volatilidade no fluxo de caixa",
    "volatility": 0.25,
    "threshold": 0.20
  }
]

6.2 Calcular Alertas

Endpoint: POST /api/cashflow/alerts/calculate

Descrição: Força recálculo de alertas para um cenário (requer autorização do Policy Engine).

Query Parameters:
- scenario (string, opcional) - Tag do cenário

Exemplo:

curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/alerts/calculate?scenario=baseline"

Resposta:

{
  "scenario": "baseline",
  "alerts_calculated": 5,
  "critical_count": 1,
  "warning_count": 3,
  "strategic_count": 1,
  "calculated_at": "2024-12-01T10:00:00Z"
}

Nota: Este endpoint requer autorização do Policy Engine. Se não autorizado, retorna 409 Conflict.


7. Cash Accounts API

Base Path: /api/cashflow/cash-accounts

7.1 Listar Contas

Endpoint: GET /api/cashflow/cash-accounts

Descrição: Lista contas de caixa.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/cash-accounts"

7.2 Criar Conta

Endpoint: POST /api/cashflow/cash-accounts

Descrição: Cria uma nova conta de caixa.

Request:

{
  "name": "Conta Principal",
  "initial_balance": 1000000.00,
  "currency": "BRL"
}

7.3 Obter Conta

Endpoint: GET /api/cashflow/cash-accounts/{account_id}

Descrição: Obtém detalhes de uma conta.


7.4 Linhas de Crédito

Endpoint: GET /api/cashflow/cash-accounts/{account_id}/credit-lines

Descrição: Lista linhas de crédito de uma conta.


8. Fixed Expenses API

Base Path: /api/cashflow/fixed-expenses

8.1 Listar Despesas Fixas

Endpoint: GET /api/cashflow/fixed-expenses

Descrição: Lista despesas fixas.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/fixed-expenses"

8.2 Criar Despesa Fixa

Endpoint: POST /api/cashflow/fixed-expenses

Descrição: Cria uma nova despesa fixa.

Request:

{
  "name": "Aluguel",
  "amount": 50000.00,
  "frequency": "MONTHLY",
  "start_date": "2024-12-01",
  "end_date": null,
  "scenario_tag": "baseline"
}

8.3 Obter Despesa Fixa

Endpoint: GET /api/cashflow/fixed-expenses/{expense_id}

Descrição: Obtém detalhes de uma despesa fixa.


9. Sales Forecast API

Base Path: /api/cashflow/sales-forecast

9.1 Listar Previsões

Endpoint: GET /api/cashflow/sales-forecast

Descrição: Lista previsões de vendas.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/sales-forecast"

9.2 Criar Previsão

Endpoint: POST /api/cashflow/sales-forecast

Descrição: Cria uma nova previsão de vendas.

Request:

{
  "month": "2024-12",
  "forecasted_revenue": 500000.00,
  "payment_terms": "30/60/10",
  "scenario_tag": "baseline"
}

9.3 Obter Previsão

Endpoint: GET /api/cashflow/sales-forecast/{forecast_id}

Descrição: Obtém detalhes de uma previsão.


9.4 Recebíveis

Endpoint: GET /api/cashflow/sales-forecast/{forecast_id}/receivables

Descrição: Lista recebíveis de uma previsão.


10. Parameters API

Base Path: /api/cashflow/parameters

10.1 Listar Parâmetros

Endpoint: GET /api/cashflow/parameters

Descrição: Lista parâmetros do sistema.

Exemplo:

curl "https://csuite.internut.com.br/cashflow/api/cashflow/parameters"

10.2 Criar Parâmetro

Endpoint: POST /api/cashflow/parameters

Descrição: Cria um novo parâmetro.

Request:

{
  "key": "default_transit_days",
  "value": "45",
  "description": "Dias de trânsito padrão para containers"
}

10.3 Obter Parâmetro

Endpoint: GET /api/cashflow/parameters/{parameter_key}

Descrição: Obtém valor de um parâmetro.


10.4 Atualizar Parâmetro

Endpoint: PUT /api/cashflow/parameters/{parameter_key}

Descrição: Atualiza um parâmetro.


10.5 Deletar Parâmetro

Endpoint: DELETE /api/cashflow/parameters/{parameter_key}

Descrição: Remove um parâmetro.


11. Exemplos Práticos

11.1 Análise Completa de Fluxo de Caixa

# 1. Obter timeline padrão
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline"

# 2. Resumo executivo
curl "https://csuite.internut.com.br/cashflow/api/cashflow/timeline/summary"

# 3. Alertas críticos
curl "https://csuite.internut.com.br/cashflow/api/cashflow/alerts?severity=critical"

11.2 Simulação What-If

# 1. Comparar cenário base vs ajustado
curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/simulator/compare" \
  -H "Content-Type: application/json" \
  -d '{
    "from_date": "2024-12-01",
    "to_date": "2025-06-30",
    "base_scenario": "baseline",
    "simulated_scenario": "baseline",
    "adjustments": {
      "containers": [
        {
          "container_id": 1,
          "transit_days": 70,
          "payment_terms": "20/80"
        }
      ]
    }
  }'

# 2. Ver impacto de um container específico
curl "https://csuite.internut.com.br/cashflow/api/cashflow/simulator/containers/1/impact"

11.3 Gestão de Containers

# 1. Criar container
curl -X POST "https://csuite.internut.com.br/cashflow/api/cashflow/containers" \
  -H "Content-Type: application/json" \
  -d '{
    "container_number": "CONT-2024-001",
    "bl_date": "2024-12-01",
    "arrival_date": "2025-01-15",
    "total_value": 500000.00,
    "payment_terms": "30/70",
    "scenario_tag": "baseline"
  }'

# 2. Listar containers
curl "https://csuite.internut.com.br/cashflow/api/cashflow/containers?scenario_tag=baseline"

# 3. Atualizar container
curl -X PUT "https://csuite.internut.com.br/cashflow/api/cashflow/containers/1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_terms": "20/80"
  }'

12. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Conflict" (409) em /alerts/calculate

Erro: "Internal Server Error" (500)

Timeline vazia

Simulação não reflete mudanças


13. Documentação Relacionada

13.1 Documentação Interna

13.2 Frontend

URL: https://csuite.internut.com.br/cashflow

Interface web Vue.js com:
- Dashboard de fluxo de caixa
- Simulador visual
- Gestão de containers
- Alertas e notificações


14. Próximos Passos

  1. Adicionar exportação CSV/Excel da timeline
  2. Adicionar webhooks para notificações de alertas
  3. Adicionar integração com ERP para importação automática
  4. Adicionar métricas de performance (tempo de resposta)
  5. Adicionar cache para queries frequentes

15. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/cashflow/api/docs

OpenAPI JSON: https://csuite.internut.com.br/cashflow/api/openapi.json

ReDoc: https://csuite.internut.com.br/cashflow/api/redoc


Última atualização: 2024-12-20
Versão: 1.0.0

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir