📚 Documentação Consolidada de APIs - C-Suite

Este documento consolida a documentação de todas as APIs do ecossistema C-Suite, incluindo exemplos de requisições, respostas e códigos de erro padronizados.

💡 Nota: Todos os apps expõem documentação interativa Swagger/OpenAPI em /docs quando rodando.

📋 Índice

1. Códigos de Erro Padronizados
2. 4c - Córtex Comercial
3. csuite-executive - Córtex Executivo
4. 4c-suite - Orquestrador
5. csuite-context - API de Contexto
6. csuite-sales-manager - Gerente de Vendas

🚨 Códigos de Erro Padronizados

Todos os apps seguem este padrão de códigos HTTP:

Formato Padrão de Erro

Todos os erros retornam no formato:

{
  "detail": "Mensagem de erro descritiva"
}

Exemplo:

{
  "detail": "Revenda não encontrada"
}

🔵 4c - Córtex Comercial

Base URL: http://localhost:8080-8085 (dependendo do serviço)
Documentação: http://localhost:8083/docs (Decision API)

Feature Service

Endpoint: POST /features/customer

Descrição: Agrega features de um cliente para uso em modelos ML.

Request:

{
  "customer_id": 12345
}

Response (200):

{
  "customer_id": 12345,
  "features": {
    "recency_days": 15,
    "frequency_90d": 3,
    "monetary_90d": 1250.50,
    "rfm_score": 452
  }
}

Erros:
- 404: Cliente não encontrado
- 500: Erro ao calcular features

Scoring Service

Endpoint: POST /score/intent

Descrição: Calcula score de intenção de compra usando modelo ML.

Request:

{
  "customer_id": 12345,
  "context": {
    "sku": "SX900S-5",
    "channel": "whatsapp"
  }
}

Response (200):

{
  "customer_id": 12345,
  "intent_score": 0.85,
  "confidence": 0.92,
  "factors": {
    "recency": 0.3,
    "frequency": 0.4,
    "monetary": 0.3
  }
}

Erros:
- 400: Dados inválidos
- 404: Cliente não encontrado
- 500: Erro no modelo ML

Decision API

Endpoint: POST /decide

Descrição: Orquestra decisão completa dos 4 Certos (Cliente, Oferta, Jeito, Hora).

Request:

{
  "customer_id": 12345,
  "org_id": 1,
  "include_explanations": true,
  "include_natural_justification": false
}

Response (200):

{
  "decision_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": 12345,
  "org_id": 1,
  "recommendation": {
    "sku": "SX900S-5",
    "channel": "whatsapp",
    "timing": "2024-12-01T14:30:00Z",
    "intent_score": 0.85,
    "offer_score": 0.78,
    "channel_score": 0.92,
    "timing_score": 0.65
  },
  "explanations": {
    "intent": "Alto score devido a compras recentes...",
    "offer": "SKU recomendado baseado em histórico...",
    "channel": "WhatsApp tem melhor taxa de resposta...",
    "timing": "Horário otimizado para este cliente..."
  },
  "natural_justification": null
}

Erros:
- 400: Dados inválidos
- 404: Cliente não encontrado
- 422: Validação falhou
- 500: Erro interno

🟢 csuite-executive - Córtex Executivo

Base URL: http://localhost:8000
Produção: https://csuite.internut.com.br
Documentação: http://localhost:8000/docs

Health Check

Endpoint: GET /health

Response (200):

{
  "status": "ok"
}

Dashboard Summary

Endpoint: GET /dashboard/summary/{org_id}

Descrição: Retorna resumo do dashboard executivo para uma organização.

Parâmetros:
- org_id (path, required): ID da organização

Response (200):

{
  "org_id": 1,
  "alerts_open": 5,
  "alerts_closed": 12,
  "items_pending": 8,
  "items_completed": 45,
  "last_run": "2024-12-01T10:00:00Z",
  "metrics": {
    "revenue_30d": 125000.50,
    "orders_30d": 450,
    "customers_active": 1250
  }
}

Erros:
- 404: Organização não encontrada
- 500: Erro ao buscar dados

Executar Agente

Endpoint: POST /agents/{org_id}/{agent_type}/run

Descrição: Executa um agente executivo (CFO, CEO, COO, CMO, CAIO) para uma organização.

Parâmetros:
- org_id (path, required): ID da organização
- agent_type (path, required): Tipo do agente (cfo, ceo, coo, cmo, caio)

Request Body (opcional):

{
  "force": false,
  "context": {}
}

Response (200):

{
  "run_id": 123,
  "org_id": 1,
  "agent_type": "cfo",
  "status": "completed",
  "started_at": "2024-12-01T10:00:00Z",
  "completed_at": "2024-12-01T10:05:00Z",
  "alerts_generated": 2,
  "action_items_created": 3,
  "summary": "Análise financeira concluída..."
}

Erros:
- 400: Tipo de agente inválido
- 404: Organização não encontrada
- 500: Erro ao executar agente

Listar Alerts

Endpoint: GET /alerts

Descrição: Lista alertas de uma organização.

Query Parameters:
- org_id (required): ID da organização
- status (optional): Filtrar por status (open, closed)
- level (optional): Filtrar por nível (low, medium, high)
- limit (optional): Limite de resultados (padrão: 50)
- offset (optional): Offset para paginação (padrão: 0)

Response (200):

{
  "total": 25,
  "limit": 50,
  "offset": 0,
  "alerts": [
    {
      "alert_id": 1,
      "org_id": 1,
      "level": "high",
      "title": "Receita abaixo do esperado",
      "message": "Receita dos últimos 30 dias está 15% abaixo...",
      "status": "open",
      "created_at": "2024-12-01T08:00:00Z"
    }
  ]
}

Erros:
- 400: Parâmetros inválidos
- 404: Organização não encontrada

🟡 4c-suite - Orquestrador

Base URL: http://localhost:8000
Documentação: http://localhost:8000/docs

Health Check

Endpoint: GET /health

Response (200):

{
  "status": "ok"
}

Status do Organismo

Endpoint: GET /organismo/{org_id}/status

Descrição: Retorna visão consolidada do organismo (4c + csuite-executive) para uma organização.

Parâmetros:
- org_id (path, required): ID da organização

Response (200):

{
  "org_id": 1,
  "fourc_decisions_today": 1250,
  "fourc_last_decision_at": "2024-12-01T14:30:00Z",
  "csuite_last_run_at": "2024-12-01T10:00:00Z",
  "csuite_open_alerts": 5,
  "csuite_pending_action_items": 8,
  "notes": {
    "csuite_dashboard": {
      "alerts_open": 5,
      "items_pending": 8
    },
    "fourc_decisions": {
      "decisions_today": 1250,
      "last_decision_at": "2024-12-01T14:30:00Z"
    }
  }
}

Erros:
- 404: Organização não encontrada
- 503: Serviço dependente indisponível (4c ou csuite-executive offline)

Notas:
- Se um serviço dependente estiver offline, o campo correspondente será null e o erro será registrado em notes

🟣 csuite-context - API de Contexto

Base URL: http://localhost:8000
Produção: https://csuite-context.internut.com.br
Documentação: http://localhost:8000/docs

Health Check

Endpoint: GET /health

Response (200):

{
  "status": "ok"
}

Eventos

Endpoint: GET /api/csuite/events

Descrição: Retorna eventos de curto prazo de uma organização.

Query Parameters:
- org_id (required): ID da organização
- limit (optional): Limite de resultados (1-500, padrão: 50)
- offset (optional): Offset para paginação (padrão: 0)
- level (optional): Filtrar por nível (low, medium, high)
- start_date (optional): Data inicial (YYYY-MM-DD)
- end_date (optional): Data final (YYYY-MM-DD)
- search (optional): Busca texto na mensagem/descrição

Response (200):

{
  "total": 150,
  "limit": 50,
  "offset": 0,
  "events": [
    {
      "id": 1,
      "org_id": 1,
      "level": "high",
      "message": "Receita aumentou 25% nos últimos 7 dias",
      "context_type": "revenue",
      "created_at": "2024-12-01T10:00:00Z"
    }
  ]
}

Erros:
- 400: Parâmetros inválidos
- 404: Organização não encontrada

Tendências

Endpoint: GET /api/csuite/trends

Descrição: Retorna tendências de médio prazo detectadas.

Query Parameters:
- org_id (required): ID da organização
- limit (optional): Limite de resultados (padrão: 50)
- offset (optional): Offset para paginação
- level (optional): Filtrar por nível
- context_type (optional): Filtrar por tipo de contexto
- order_by (optional): Campo para ordenação
- order_dir (optional): Direção (asc, desc)

Response (200):

{
  "total": 30,
  "limit": 50,
  "offset": 0,
  "trends": [
    {
      "id": 1,
      "org_id": 1,
      "level": "medium",
      "context_type": "revenue",
      "message": "Tendência de crescimento de receita detectada",
      "direction": "up",
      "strength": 0.75,
      "detected_at": "2024-12-01T09:00:00Z"
    }
  ]
}

Context Shifts

Endpoint: GET /api/csuite/shifts

Descrição: Retorna mudanças estruturais (shifts) detectadas.

Query Parameters:
- org_id (required): ID da organização
- limit (optional): Limite de resultados
- offset (optional): Offset para paginação
- shift_direction (optional): Filtrar por direção (up, down)
- min_shift_value (optional): Valor mínimo do shift
- max_shift_value (optional): Valor máximo do shift
- search (optional): Busca texto

Response (200):

{
  "total": 10,
  "limit": 50,
  "offset": 0,
  "shifts": [
    {
      "id": 1,
      "org_id": 1,
      "metric_key": "revenue_30d",
      "shift_direction": "up",
      "shift_value": 0.25,
      "message": "Mudança estrutural detectada: receita aumentou 25%",
      "detected_at": "2024-12-01T08:00:00Z"
    }
  ]
}

🔴 csuite-sales-manager - Gerente de Vendas

Manager API

Base URL: http://localhost:8001
Produção: https://sales-manager.internut.com.br
Documentação: http://localhost:8001/docs

Health Check

Endpoint: GET /health

Response (200):

{
  "status": "ok"
}

Resumo do Dia

Endpoint: GET /manager/today

Descrição: Retorna resumo de tasks do dia para todos os vendedores.

Query Parameters:
- ref_date (optional): Data de referência (YYYY-MM-DD, padrão: hoje)

Response (200):

{
  "ref_date": "2024-12-01",
  "total_tasks": 150,
  "por_status": {
    "pendente": 100,
    "concluida": 50
  },
  "por_seller": {
    "1 - João": 25,
    "2 - Maria": 30,
    "3 - Pedro": 20
  }
}

Erros:
- 400: Data inválida
- 500: Erro ao buscar dados

Tasks do Vendedor

Endpoint: GET /seller/{seller_id}/today

Descrição: Retorna lista de tasks de um vendedor específico para o dia.

Parâmetros:
- seller_id (path, required): ID do vendedor
- ref_date (query, optional): Data de referência (padrão: hoje)

Response (200):

[
  {
    "task_id": 1,
    "ref_date": "2024-12-01",
    "seller_id": 1,
    "revenda_id": 100,
    "revenda_nome": "Revenda ABC",
    "cidade": "São Paulo",
    "estado": "SP",
    "prioridade": "alta",
    "tipo_acao": "contato",
    "motivo": "Sem pedido há 30 dias",
    "status": "pendente",
    "decision": {
      "offer": {
        "sku": "SX900S-5",
        "reason": "segmento=jeans; receita_90d=5000"
      },
      "channel": "whatsapp",
      "tone": "tecnico_direto",
      "message": "Olá Revenda ABC de São Paulo, tudo bem?...",
      "send_at": null
    }
  }
]

Erros:
- 404: Vendedor não encontrado
- 400: Data inválida
- 500: Erro ao buscar tasks

Completar Task

Endpoint: POST /tasks/{task_id}/complete

Descrição: Marca uma task como concluída.

Parâmetros:
- task_id (path, required): ID da task

Response (200):

{
  "status": "ok",
  "task_id": 1
}

Erros:
- 404: Task não encontrada
- 500: Erro ao atualizar task

Decision API

Base URL: http://localhost:8002
Produção: https://sales-decision.internut.com.br
Documentação: http://localhost:8002/docs

Health Check

Endpoint: GET /health

Response (200):

{
  "status": "ok"
}

Decisão 4C Lite

Endpoint: POST /4c/decide

Descrição: Gera decisão 4C Lite (oferta, canal, mensagem, horário) para uma revenda.

Request:

{
  "revenda_id": 100
}

Response (200):

{
  "offer": {
    "sku": "SX900S-5",
    "reason": "segmento=jeans; receita_90d=5000"
  },
  "channel": "whatsapp",
  "tone": "tecnico_direto",
  "message": "Olá Revenda ABC de São Paulo, tudo bem?\n\nVimos que suas vendas têm potencial para aumentar com o modelo SX900S-5. Quero te mostrar uma condição especial para repor ou atualizar seu mix com essa máquina. Podemos falar hoje sobre isso?",
  "send_at": null
}

Erros:
- 400: Dados inválidos (revenda_id faltando)
- 404: Revenda não encontrada
- 500: Erro ao gerar decisão

🔗 Integração entre APIs

Exemplo: Fluxo Completo Sales Manager → 4C

# 1. Obter tasks do vendedor
curl http://localhost:8001/seller/1/today

# 2. Para cada task, enriquecer com decisão 4C Lite
curl -X POST http://localhost:8002/4c/decide \
  -H "Content-Type: application/json" \
  -d '{"revenda_id": 100}'

# 3. Marcar task como concluída após ação
curl -X POST http://localhost:8001/tasks/1/complete

Exemplo: Orquestração 4c-suite

# Obter status consolidado do organismo
curl http://localhost:8000/organismo/1/status

📝 Notas de Uso

Autenticação

⚠️ Status Atual: A maioria dos apps não tem autenticação implementada. Em produção, implemente:
- OAuth2/JWT
- API Keys
- Rate limiting

Rate Limiting

Recomendações:
- 4c: 100 req/min por IP
- csuite-executive: 50 req/min por org_id
- csuite-context: 200 req/min por IP
- sales-manager: 100 req/min por seller_id

Versionamento

⚠️ Status Atual: APIs não estão versionadas. Recomendação:
- Adicionar /v1/ nos paths
- Manter compatibilidade com versões anteriores
- Documentar breaking changes

🔍 Testando as APIs

Usando cURL

# Health check
curl http://localhost:8000/health

# Com autenticação (quando implementado)
curl -H "Authorization: Bearer TOKEN" http://localhost:8000/health

Usando Swagger UI

1. Inicie o app
2. Acesse http://localhost:PORT/docs
3. Use a interface interativa para testar endpoints
4. Veja exemplos de requisições/respostas

Usando Postman

Coleções Postman disponíveis:
- 4c/postman/4C_API_Collection.json
- csuite-executive/CSuite_API.postman_collection.json

📚 Referências

• FastAPI Documentation
• OpenAPI Specification
• RELACAO_ENTRE_APPS.md - Visão geral dos apps
• ARQUITETURA.md - Diagramas de arquitetura
• GLOSSARIO.md - Glossário de termos técnicos e de negócio

Última atualização: 2025-12-01