Guia de Uso - APIs `/cfo-ops`

Base URL: https://csuite.internut.com.br/cfo-ops

📋 Índice

Visão Geral
Cost-to-Serve API
Pricing Engine API
Endpoints Auxiliares
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite CFO-Ops é uma API read-only que expõe análises financeiras e operacionais baseadas em Time-Driven Activity-Based Costing (TDABC).

Principais funcionalidades:
- Cost-to-Serve (CTS): Análise de margem e eficiência logística por pedido e cliente
- Pricing Engine: Cenários de preço, análise de markup e sensibilidade
- Views Financeiras: Acesso direto a views vw_cfo_* do banco de dados

Características:
- ✅ API read-only (apenas SELECT em views)
- ✅ Autenticação via csuite-auth
- ✅ Cache em memória (5-10 minutos)
- ✅ Paginação para grandes volumes
- ✅ Otimizações de performance (índices SQL)

2. Cost-to-Serve API

Base Path: /api/view/cost-to-serve

2.1 Pedidos (Orders)

Endpoint: GET /api/view/cost-to-serve/orders

Descrição: Retorna cost-to-serve por pedido com filtros avançados.

Parâmetros de Query:
- customer_ref (string, opcional) - Filtrar por cliente
- days_back (int, padrão: 30, min: 1, max: 365) - Dias para trás
- min_margin_pct (float, opcional) - Margem mínima %
- max_margin_pct (float, opcional) - Margem máxima %
- margin_category (string, opcional) - LOSS|LOW_MARGIN|NORMAL|HIGH_MARGIN
- logistics_efficiency (string, opcional) - EFFICIENT|NORMAL|INEFFICIENT|NO_LOGISTICS_DATA
- limit (int, padrão: 100, min: 1, max: 1000) - Limite de resultados

Exemplo:

# Pedidos dos últimos 30 dias
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?days_back=30"

# Pedidos com margem negativa
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?margin_category=LOSS"

# Pedidos ineficientes de um cliente
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?customer_ref=40306&logistics_efficiency=INEFFICIENT"

Resposta:

[
  {
    "order_ref": "ORD-12345",
    "order_date": "2024-12-01",
    "customer_ref": "40306",
    "gross_revenue": 15000.00,
    "net_revenue": 13500.00,
    "cogs_accounting": 10000.00,
    "gross_margin": 3500.00,
    "gross_margin_pct": 25.93,
    "total_weight_kg": 150.50,
    "total_volume_m3": 0.75,
    "total_items": 5,
    "revenue_per_kg": 89.70,
    "margin_per_kg": 23.26,
    "revenue_per_m3": 18000.00,
    "margin_per_m3": 4666.67,
    "freight_per_kg": 2.50,
    "margin_category": "NORMAL",
    "logistics_efficiency": "EFFICIENT"
  }
]

Casos de uso:
- Identificar pedidos com margem negativa
- Analisar eficiência logística por pedido
- Comparar margem/kg entre pedidos

2.2 Clientes (Customers)

Endpoint: GET /api/view/cost-to-serve/customers

Descrição: Retorna ranking de clientes por cost-to-serve.

Parâmetros de Query:
- customer_tier (string, opcional) - PREMIUM|GOOD|AVERAGE|EXPENSIVE_TO_SERVE|UNPROFITABLE|NO_LOGISTICS_DATA
- customer_segment (string, opcional) - STRATEGIC|CORE|REGULAR|AT_RISK|NEW_OR_OCCASIONAL
- min_score (float, opcional, 0-100) - Score mínimo
- sort_by (string, padrão: customer_score) - Campo para ordenação
- sort_desc (bool, padrão: true) - Ordenar descendente
- limit (int, padrão: 100, min: 1, max: 1000) - Limite de resultados

Campos de ordenação válidos:
- customer_score
- total_orders
- total_gross_margin
- margin_per_kg
- revenue_per_kg
- pct_profitable_orders

Exemplo:

# Top 10 clientes premium
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customers?customer_tier=PREMIUM&limit=10"

# Clientes em risco
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customers?customer_segment=AT_RISK"

# Clientes ordenados por margem/kg
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customers?sort_by=margin_per_kg&sort_desc=true"

Resposta:

[
  {
    "customer_ref": "40306",
    "total_orders": 25,
    "days_with_orders": 20,
    "customer_lifetime_days": 180,
    "total_gross_revenue": 375000.00,
    "total_net_revenue": 337500.00,
    "total_gross_margin": 87500.00,
    "avg_order_revenue": 15000.00,
    "avg_order_margin": 3500.00,
    "avg_margin_pct": 25.93,
    "total_weight_kg": 3750.00,
    "total_volume_m3": 18.75,
    "revenue_per_kg": 90.00,
    "margin_per_kg": 23.33,
    "revenue_per_m3": 18000.00,
    "margin_per_m3": 4666.67,
    "freight_per_kg": 2.50,
    "pct_profitable_orders": 96.00,
    "margin_stddev": 5.20,
    "customer_tier": "PREMIUM",
    "customer_segment": "STRATEGIC",
    "customer_score": 90.50
  }
]

Casos de uso:
- Identificar clientes premium (alta margem/kg)
- Detectar clientes caros de atender
- Segmentação para ações comerciais

2.3 Estatísticas (Stats)

Endpoint: GET /api/view/cost-to-serve/stats

Descrição: Estatísticas gerais de cost-to-serve (cacheado por 5 minutos).

Parâmetros de Query:
- days_back (int, padrão: 90, min: 1, max: 365) - Dias para trás

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/stats?days_back=90"

Resposta:

{
  "total_customers": 150,
  "total_orders": 1250,
  "tier_distribution": {
    "PREMIUM": 25,
    "GOOD": 45,
    "AVERAGE": 50,
    "EXPENSIVE_TO_SERVE": 20,
    "UNPROFITABLE": 5,
    "NO_LOGISTICS_DATA": 5
  },
  "avg_margin_per_kg": 18.50,
  "avg_revenue_per_kg": 85.00,
  "avg_customer_score": 65.30,
  "top_5_customers": ["40306", "723434", "730464", "11030", "732044"],
  "bottom_5_customers": ["50001", "50002", "50003", "50004", "50005"]
}

Casos de uso:
- Visão executiva do portfólio
- KPIs de eficiência logística
- Benchmarks internos

2.4 Detalhes do Cliente

Endpoint: GET /api/view/cost-to-serve/customer/{customer_ref}/detail

Descrição: Detalhamento completo de cost-to-serve de um cliente (métricas, histórico, tendências, comparação).

Parâmetros de Path:
- customer_ref (string, obrigatório) - Referência do cliente

Parâmetros de Query:
- days_back (int, padrão: 90, min: 1, max: 365) - Dias para trás
- page (int, padrão: 1, min: 1) - Página de pedidos
- page_size (int, padrão: 50, min: 1, max: 200) - Itens por página

Exemplo:

# Detalhes completos do cliente
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customer/40306/detail?days_back=90"

# Com paginação
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customer/40306/detail?page=2&page_size=25"

Resposta:

{
  "customer": {
    "customer_ref": "40306",
    "total_orders": 25,
    "total_gross_margin": 87500.00,
    "customer_score": 90.50,
    "customer_tier": "PREMIUM",
    "margin_per_kg": 23.33,
    "pct_profitable_orders": 96.00
  },
  "orders": {
    "data": [
      {
        "order_ref": "ORD-12345",
        "order_date": "2024-12-01",
        "gross_margin": 3500.00,
        "gross_margin_pct": 25.93,
        "margin_per_kg": 23.26,
        "total_weight_kg": 150.50,
        "margin_category": "NORMAL",
        "logistics_efficiency": "EFFICIENT"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 50,
      "total": 25,
      "total_pages": 1
    }
  },
  "trends": [
    {
      "week_start": "2024-11-25",
      "avg_margin_pct": 25.50,
      "avg_margin_per_kg": 23.10,
      "order_count": 5
    }
  ],
  "portfolio_comparison": {
    "customer_score": {
      "value": 90.50,
      "portfolio_avg": 65.30,
      "diff": 25.20
    },
    "margin_per_kg": {
      "value": 23.33,
      "portfolio_avg": 18.50,
      "diff": 4.83
    },
    "pct_profitable_orders": {
      "value": 96.00,
      "portfolio_avg": 85.00,
      "diff": 11.00
    }
  }
}

Casos de uso:
- Análise profunda de um cliente específico
- Histórico de pedidos com paginação
- Tendências de margem ao longo do tempo
- Comparação com média do portfólio

2.5 Insights

Endpoint: GET /api/view/cost-to-serve/insights

Descrição: Insights automáticos baseados em cost-to-serve.

Parâmetros de Query:
- days_back (int, padrão: 90, min: 1, max: 365) - Dias para trás

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/insights?days_back=90"

Resposta:

[
  {
    "type": "concentration",
    "severity": "WARNING",
    "title": "Concentração de Margem",
    "message": "Top 10 clientes representam 75.50% da margem total",
    "value": 75.50,
    "recommendation": "Diversificar portfólio se concentração > 70%"
  },
  {
    "type": "negative_margin",
    "severity": "CRITICAL",
    "title": "Pedidos com Prejuízo",
    "message": "15 pedidos (1.20%) tiveram margem negativa nos últimos 90 dias",
    "value": 15,
    "recommendation": "Revisar pricing e custos imediatamente"
  },
  {
    "type": "logistics_inefficiency",
    "severity": "WARNING",
    "title": "Eficiência Logística",
    "message": "45 pedidos (3.60%) são logisticamente ineficientes",
    "value": 3.60,
    "recommendation": "Consolidar entregas por região"
  },
  {
    "type": "customer_risk",
    "severity": "WARNING",
    "title": "Clientes em Risco",
    "message": "12 clientes estão no segmento AT_RISK",
    "value": 12,
    "recommendation": "Revisar relacionamento e condições comerciais"
  }
]

Tipos de insights:
- concentration: Concentração de margem (top 10 clientes)
- negative_margin: Pedidos com prejuízo
- logistics_inefficiency: Pedidos ineficientes
- customer_risk: Clientes em risco
- low_margin_per_kg: Margem/kg baixa

Severidades:
- CRITICAL: Ação imediata necessária
- WARNING: Atenção recomendada
- INFO: Informativo

3. Pricing Engine API

Base Path: /api/pricing

3.1 Criar Cenário de Pricing

Endpoint: POST /api/pricing/scenario

Descrição: Cria um cenário de pricing baseado em CTI_FINAL (Custo Total Incorporado).

Request:

{
  "shipment_id": 12345,
  "scenario_name": "Cenário Base + 30%",
  "markup_percent": 30.0,
  "discount_percent": 0.0,
  "icms_dest_percent": 0.0,
  "notes": "Cenário de teste"
}

Fórmula: Preço = CTI * (1 + markup%) * (1 - discount%) * (1 + ICMS%)

Exemplo:

curl -X POST "https://csuite.internut.com.br/cfo-ops/api/pricing/scenario" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": 12345,
    "scenario_name": "Cenário Base + 30%",
    "markup_percent": 30.0,
    "discount_percent": 0.0,
    "icms_dest_percent": 0.0
  }'

Resposta:

{
  "scenario_id": 1,
  "shipment_id": 12345,
  "scenario_name": "Cenário Base + 30%",
  "total_revenue": 195000.00,
  "total_cost": 150000.00,
  "total_margin": 45000.00,
  "margin_percent": 23.08
}

3.2 Listar Cenários

Endpoint: GET /api/pricing/scenarios/{shipment_id}

Descrição: Lista todos os cenários de pricing de um shipment.

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/pricing/scenarios/12345"

Resposta:

[
  {
    "scenario_id": 1,
    "scenario_name": "Cenário Base + 30%",
    "markup_percent": 30.0,
    "discount_percent": 0.0,
    "icms_dest_percent": 0.0,
    "total_revenue": 195000.00,
    "total_cost": 150000.00,
    "total_margin": 45000.00,
    "margin_percent": 23.08,
    "created_at": "2024-12-01T10:00:00Z"
  }
]

3.3 Análise de Sensibilidade

Endpoint: GET /api/pricing/sensitivity/{shipment_id}

Descrição: Obtém análise de sensibilidade (what-if) para um shipment.

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/pricing/sensitivity/12345"

Resposta:

{
  "shipment_id": 12345,
  "base_scenario": {
    "scenario_id": 1,
    "scenario_name": "Cenário Base",
    "markup_percent": 30.0,
    "discount_percent": 0.0,
    "icms_dest_percent": 0.0,
    "revenue": 195000.00,
    "cost": 150000.00,
    "profit": 45000.00,
    "margin_percent": 23.08
  },
  "sensitivity": {
    "markup_variations": {
      "+20%": 54000.00,
      "+10%": 49500.00,
      "+5%": 47250.00,
      "-5%": 42750.00,
      "-10%": 40500.00,
      "-20%": 36000.00
    },
    "discount_variations": {
      "+5%": 42750.00,
      "+10%": 40500.00,
      "+15%": 38250.00
    },
    "icms_variations": {
      "+5%": 47250.00,
      "+2%": 45900.00,
      "-2%": 44100.00,
      "-5%": 42750.00
    }
  }
}

3.4 Calcular Markup

Endpoint: GET /api/pricing/markup/{item_id}

Descrição: Calcula markup necessário para atingir um preço desejado.

Parâmetros de Query:
- target_price (float, obrigatório) - Preço desejado

Fórmula: markup = (preço - CTI) / CTI * 100

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/pricing/markup/123?target_price=1500.00"

Resposta:

{
  "item_id": 123,
  "target_price": 1500.00,
  "unit_cti_final": 1000.00,
  "markup_percent": 50.0,
  "markup_required": true
}

4. Endpoints Auxiliares

4.1 Health Check

Endpoint: GET /health

Descrição: Verifica saúde da API e conexão com banco de dados.

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/health"

Resposta (OK):

{
  "status": "ok",
  "db": "connected"
}

Resposta (Degraded):

{
  "status": "degraded",
  "db": "unreachable",
  "message": "Connection timeout"
}

Nota: Retorna 200 OK mesmo se DB não estiver disponível (degraded mode) para não quebrar healthcheck do Docker.

4.2 Acesso Direto a Views

Endpoint: GET /api/view/{view_name}

Descrição: Acesso direto a views vw_cfo_* do banco de dados.

Views disponíveis:
- vw_cfo_cost_to_serve_order
- vw_cfo_cost_to_serve_customer
- vw_cfo_margin_volume_profit
- vw_cfo_markup_analysis
- vw_cfo_pricing_sensitivity
- vw_cfo_sku_cost_explanation
- vw_cfo_cost_breakdown
- vw_cfo_expense_impact
- vw_cfo_price_breakdown
- vw_cfo_allocation_trace
- vw_cfo_cost_margin_status

Exemplo:

curl "https://csuite.internut.com.br/cfo-ops/api/view/vw_cfo_margin_volume_profit"

Nota: Use com cuidado - retorna dados brutos sem paginação ou cache.

4.3 Autenticação

Endpoints:
- GET /login - Redireciona para login
- GET /auth/callback - Callback após autenticação
- GET /logout - Logout

Nota: Todos os endpoints (exceto /health) requerem autenticação via csuite-auth.

5. Exemplos Práticos

5.1 Análise Completa de Cliente Premium

# 1. Listar top 10 clientes premium
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customers?customer_tier=PREMIUM&limit=10"

# 2. Detalhes do melhor cliente
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/customer/40306/detail?days_back=90"

# 3. Pedidos desse cliente
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?customer_ref=40306&days_back=90"

5.2 Detectar Problemas Operacionais

# 1. Pedidos com prejuízo
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?margin_category=LOSS"

# 2. Pedidos ineficientes
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/orders?logistics_efficiency=INEFFICIENT"

# 3. Insights automáticos
curl "https://csuite.internut.com.br/cfo-ops/api/view/cost-to-serve/insights?days_back=90"

5.3 Análise de Pricing

# 1. Criar cenário de pricing
curl -X POST "https://csuite.internut.com.br/cfo-ops/api/pricing/scenario" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": 12345,
    "scenario_name": "Markup 30%",
    "markup_percent": 30.0
  }'

# 2. Análise de sensibilidade
curl "https://csuite.internut.com.br/cfo-ops/api/pricing/sensitivity/12345"

# 3. Calcular markup necessário
curl "https://csuite.internut.com.br/cfo-ops/api/pricing/markup/123?target_price=1500.00"

6. Otimizações e Performance

6.1 Cache

Stats: Cache de 5 minutos
Customer Metrics: Cache de 5 minutos
Portfolio Average: Cache de 10 minutos

6.2 Paginação

Orders: Limite padrão 100, máximo 1000
Customers: Limite padrão 100, máximo 1000
Customer Detail: Paginação com page e page_size

6.3 Índices SQL

Índices otimizados aplicados em:
- idx_order_date_customer
- idx_order_date_desc
- idx_itemlog_order_agg
- idx_order_customer_date

7. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-cfo-ops está rodando
Verifique se o path está correto (/cfo-ops ou /api/view/cost-to-serve)
Verifique se a view existe no banco de dados

Erro: "Unauthorized" (401)

Verifique autenticação via csuite-auth
Faça login em /login primeiro

Erro: "Internal Server Error" (500)

Verifique logs do serviço
Verifique conexão com banco de dados
Verifique collation de strings (utf8mb4_unicode_ci)

Dados não atualizados

Verifique se o job diário run_daily.sql está rodando
Verifique cache (pode estar usando dados antigos)
Limpe cache se necessário (não exposto via API)

Performance lenta

Use filtros para reduzir volume de dados
Use paginação para grandes volumes
Verifique se índices SQL estão aplicados

8. Documentação Relacionada

8.1 Documentação Interna

Arquitetura: docs/01-architecture.md
Data Model: docs/02-data-model.md
Motor TDABC: docs/03-motor-tdabc.md
Views Contract: docs/04-views-contract.md
API Status: docs/API_COST_TO_SERVE_STATUS.md

8.2 Grafana Dashboard

URL: https://grafana.internut.com.br/d/cfo_ops_cost_to_serve

Dashboard visual com:
- Métricas de cost-to-serve
- Distribuição por tier
- Tendências de margem
- Alertas automáticos

9. Próximos Passos

Adicionar endpoints de alertas (/api/alerts/cost-to-serve)
Adicionar exportação CSV/Excel
Adicionar webhooks para notificações
Adicionar rate limiting por usuário
Adicionar métricas de performance (tempo de resposta)

10. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/cfo-ops/docs

OpenAPI JSON: https://csuite.internut.com.br/cfo-ops/openapi.json

ReDoc: https://csuite.internut.com.br/cfo-ops/redoc

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

Guia Uso Apis Cfo Ops

Guia de Uso - APIs `/cfo-ops`

📋 Índice

1. Visão Geral

2. Cost-to-Serve API

2.1 Pedidos (Orders)

2.2 Clientes (Customers)

2.3 Estatísticas (Stats)

2.4 Detalhes do Cliente

2.5 Insights

3. Pricing Engine API

3.1 Criar Cenário de Pricing

3.2 Listar Cenários

3.3 Análise de Sensibilidade

3.4 Calcular Markup

4. Endpoints Auxiliares

4.1 Health Check

4.2 Acesso Direto a Views

4.3 Autenticação

5. Exemplos Práticos

5.1 Análise Completa de Cliente Premium

5.2 Detectar Problemas Operacionais

5.3 Análise de Pricing

6. Otimizações e Performance

6.1 Cache

6.2 Paginação

6.3 Índices SQL

7. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Internal Server Error" (500)

Dados não atualizados

Performance lenta

8. Documentação Relacionada

8.1 Documentação Interna

8.2 Grafana Dashboard

9. Próximos Passos

10. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs /cfo-ops

📋 Índice

1. Visão Geral

2. Cost-to-Serve API

2.1 Pedidos (Orders)

2.2 Clientes (Customers)

2.3 Estatísticas (Stats)

2.4 Detalhes do Cliente

2.5 Insights

3. Pricing Engine API

3.1 Criar Cenário de Pricing

3.2 Listar Cenários

3.3 Análise de Sensibilidade

3.4 Calcular Markup

4. Endpoints Auxiliares

4.1 Health Check

4.2 Acesso Direto a Views

4.3 Autenticação

5. Exemplos Práticos

5.1 Análise Completa de Cliente Premium

5.2 Detectar Problemas Operacionais

5.3 Análise de Pricing

6. Otimizações e Performance

6.1 Cache

6.2 Paginação

6.3 Índices SQL

7. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Internal Server Error" (500)

Dados não atualizados

Performance lenta

8. Documentação Relacionada

8.1 Documentação Interna

8.2 Grafana Dashboard

9. Próximos Passos

10. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/cfo-ops`