Guia de Uso - APIs /cashflow/api
Base URL: https://csuite.internut.com.br/cashflow/api
📋 Índice
- Visão Geral
- Timeline API
- Containers API
- Scenarios API
- Simulator API
- Alerts API
- Cash Accounts API
- Fixed Expenses API
- Sales Forecast API
- Parameters API
- Exemplos Práticos
- Troubleshooting
1. Visão Geral
O CSuite Cashflow é uma API para gestão de fluxo de caixa, permitindo:
- Previsão de caixa: Timeline diária com saldo acumulado
- Simulação de cenários: What-if com ajustes de containers, condições de pagamento, etc.
- Alertas financeiros: Detecção automática de riscos de liquidez
- Gestão de containers: Importações e seus impactos no caixa
- Previsão de vendas: Integração com forecast de recebíveis
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)
- Verifique se o serviço
csuite-cashflowestá rodando - Verifique se o path está correto (
/cashflow/api/cashflow) - Verifique se o endpoint existe na documentação OpenAPI
Erro: "Unauthorized" (401)
- Verifique autenticação via
csuite-auth - Faça login em
/loginprimeiro
Erro: "Conflict" (409) em /alerts/calculate
- Policy Engine não autorizou a operação
- Verifique
reasonsenotifyna resposta - Verifique permissões do usuário
Erro: "Internal Server Error" (500)
- Verifique logs do serviço
- Verifique conexão com banco de dados
- Verifique se os dados necessários existem (cenários, containers, etc.)
Timeline vazia
- Verifique se existem movimentos de caixa (containers, despesas fixas, previsões)
- Verifique se o cenário existe
- Verifique se as datas estão corretas
Simulação não reflete mudanças
- Verifique se os ajustes foram aplicados corretamente
- Verifique se o container existe e está ativo
- Verifique se o cenário está correto
13. Documentação Relacionada
13.1 Documentação Interna
- README:
csuite-cashflow/README.md - STATUS:
csuite-cashflow/STATUS.md - Plan:
csuite-cashflow/Plan.md
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
- Adicionar exportação CSV/Excel da timeline
- Adicionar webhooks para notificações de alertas
- Adicionar integração com ERP para importação automática
- Adicionar métricas de performance (tempo de resposta)
- 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