Guia de Uso - APIs `/operations`

Base URL: https://csuite.internut.com.br/operations

Documentação Swagger: https://csuite.internut.com.br/operations/docs

📋 Índice

Visão Geral
Dashboard API
Decision Executor API
Alert Responder API
Workflow Orchestrator API
Feedback Collector API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Operations é um app operacional que conecta as decisões do 4C (nível cliente) com as ações executivas do C-Suite Executive (nível organização), criando uma ponte entre o operacional e o estratégico.

Funcionalidades Principais

Operations Dashboard - Visão consolidada de decisões, alertas e métricas
Decision Executor - Executar decisões do 4C com aprovação/modificação
Alert Responder - Responder a alertas do Executive criando planos de ação
Workflow Orchestrator - Criar e executar workflows personalizados
Feedback Collector - Coletar feedback de operadores para melhorar decisões

Arquitetura

┌─────────────────────────────────────────────────┐
│      C-Suite Operations                         │
│      (App Operacional)                          │
└─────────────────────────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
    ┌───▼───┐  ┌───▼───┐  ┌───▼───┐
    │ 4C    │  │Exec.  │  │Context│
    │ APIs  │  │ APIs  │  │ APIs  │
    └───────┘  └───────┘  └───────┘

Integrações

4C APIs:
- Decision API - Decisões e execução
- Feature Service - Features de clientes
- Scoring Service - Scores de intenção, oferta, canal, timing

Executive APIs:
- Dashboard Summary - Resumo executivo
- Alerts - Alertas e notificações
- Action Items - Itens de ação
- Agents - Execução de agentes

Context APIs:
- Events - Eventos de curto prazo
- Trends - Tendências de médio prazo
- Signals - Sinais detectados

Cashflow APIs:
- Timeline - Timeline de fluxo de caixa
- Simulator - Simulação de cenários

2. Dashboard API

Base Path: /dashboard

2.1 Dashboard Consolidado

Endpoint: GET /dashboard

Descrição: Dashboard consolidado com decisões pendentes, alertas prioritários, métricas operacionais e action items.

Parâmetros de Query:
- org_id (int, obrigatório) - ID da organização
- operator_id (int, opcional) - ID do operador (filtro)

Exemplo:

curl "https://csuite.internut.com.br/operations/dashboard?org_id=1"

# Com filtro de operador
curl "https://csuite.internut.com.br/operations/dashboard?org_id=1&operator_id=5"

Resposta:

{
  "pending_decisions": [
    {
      "decision_id": "decision-123",
      "customer_id": 12345,
      "recommended_action": "send_whatsapp",
      "score": 0.85,
      "created_at": "2024-12-01T10:00:00Z"
    }
  ],
  "high_priority_alerts": [
    {
      "alert_id": "alert-456",
      "title": "Alerta de Ruptura",
      "severity": "high",
      "description": "Produto X com estoque crítico",
      "created_at": "2024-12-01T09:00:00Z"
    }
  ],
  "action_items": [
    {
      "item_id": "item-789",
      "title": "Revisar política de desconto",
      "priority": "high",
      "status": "pending",
      "due_date": "2024-12-05T10:00:00Z"
    }
  ],
  "metrics": {
    "decisions_today": 25,
    "decisions_pending": 8,
    "alerts_open": 5,
    "alerts_high_priority": 2,
    "action_items_pending": 12,
    "completion_rate": 0.85,
    "avg_response_time_minutes": 15.5
  }
}

Campos da Resposta:
- pending_decisions: Lista de decisões pendentes do 4C (máx. 50)
- high_priority_alerts: Alertas com severidade "high" ou "critical"
- action_items: Action items pendentes do Executive
- metrics: Métricas operacionais consolidadas

3. Decision Executor API

Base Path: /decisions

3.1 Listar Decisões Pendentes

Endpoint: GET /decisions/pending

Descrição: Obtém lista de decisões pendentes do 4C.

Parâmetros de Query:
- limit (int, padrão: 50) - Número máximo de decisões

Exemplo:

curl "https://csuite.internut.com.br/operations/decisions/pending?limit=20"

Resposta:

{
  "decisions": [
    {
      "decision_id": "decision-123",
      "customer_id": 12345,
      "recommended_action": "send_whatsapp",
      "score": 0.85,
      "context": {
        "intent_score": 0.75,
        "offer_score": 0.80,
        "channel_score": 0.90
      },
      "created_at": "2024-12-01T10:00:00Z"
    }
  ],
  "count": 20
}

3.2 Executar Decisão

Endpoint: POST /decisions/{decision_id}/execute

Descrição: Executa decisão do 4C, permitindo modificações do operador.

Parâmetros de Path:
- decision_id (string, obrigatório) - ID da decisão

Request Body:

{
  "decision_id": "decision-123",
  "operator_id": 5,
  "modifications": {
    "channel": "email",
    "message": "Mensagem personalizada"
  },
  "notes": "Cliente preferiu email ao invés de WhatsApp"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/decisions/decision-123/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "decision-123",
    "operator_id": 5,
    "modifications": {
      "channel": "email",
      "message": "Mensagem personalizada"
    },
    "notes": "Cliente preferiu email"
  }'

Resposta:

{
  "id": "execution-uuid-123",
  "decision_id": "decision-123",
  "operator_id": 5,
  "executed_at": "2024-12-01T10:05:00Z",
  "status": "executed",
  "modifications": {
    "channel": "email",
    "message": "Mensagem personalizada"
  },
  "notes": "Cliente preferiu email",
  "created_at": "2024-12-01T10:05:00Z",
  "updated_at": "2024-12-01T10:05:00Z"
}

Campos do Request:
- decision_id: ID da decisão (deve corresponder ao path)
- operator_id: ID do operador que está executando
- modifications: Modificações opcionais à decisão original
- notes: Notas do operador sobre a execução

3.3 Criar e Executar Decisão Automática

Endpoint: POST /decisions/auto

Descrição: Cria e executa decisão automática do 4C.

Parâmetros de Query:
- customer_id (int, obrigatório) - ID do cliente
- operator_id (int, obrigatório) - ID do operador

Request Body (opcional):

{
  "context": {
    "goal": "reactivation",
    "constraints": {
      "min_intent": 0.5
    }
  },
  "modifications": {
    "channel": "whatsapp"
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/decisions/auto?customer_id=12345&operator_id=5" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "goal": "reactivation"
    },
    "modifications": {
      "channel": "whatsapp"
    }
  }'

Resposta (Executado):

{
  "status": "executed",
  "decision_id": "decision-456",
  "execution_id": "execution-uuid-456",
  "decision": {
    "decision_id": "decision-456",
    "customer_id": 12345,
    "recommended_action": "send_whatsapp",
    "score": 0.82,
    "approved": true
  }
}

Resposta (Pulado):

{
  "status": "skipped",
  "reason": "intent_score_below_threshold",
  "decision_id": "decision-456"
}

Casos de Uso:
- Reativação de clientes inativos
- Follow-up automático após evento
- Campanhas personalizadas
- Ações baseadas em contexto

3.4 Histórico de Execuções

Endpoint: GET /decisions/executions

Descrição: Obtém histórico de execuções de decisões.

Parâmetros de Query:
- operator_id (int, opcional) - Filtrar por operador
- status (string, opcional) - Filtrar por status (executed, failed, pending)
- limit (int, padrão: 50) - Número máximo de execuções

Exemplo:

# Todas as execuções
curl "https://csuite.internut.com.br/operations/decisions/executions"

# Execuções de um operador específico
curl "https://csuite.internut.com.br/operations/decisions/executions?operator_id=5"

# Execuções com status específico
curl "https://csuite.internut.com.br/operations/decisions/executions?status=executed&limit=20"

Resposta:

[
  {
    "id": "execution-uuid-123",
    "decision_id": "decision-123",
    "operator_id": 5,
    "executed_at": "2024-12-01T10:05:00Z",
    "status": "executed",
    "modifications": {
      "channel": "email"
    },
    "notes": "Cliente preferiu email",
    "created_at": "2024-12-01T10:05:00Z",
    "updated_at": "2024-12-01T10:05:00Z"
  }
]

4. Alert Responder API

Base Path: /alerts

4.1 Listar Alertas

Endpoint: GET /alerts

Descrição: Obtém lista de alertas do Executive.

Parâmetros de Query:
- org_id (int, opcional) - Filtrar por organização
- priority (string, opcional) - Filtrar por prioridade (low, medium, high, critical)
- status (string, padrão: open) - Filtrar por status (open, acknowledged, resolved)

Exemplo:

# Todos os alertas abertos
curl "https://csuite.internut.com.br/operations/alerts"

# Alertas de alta prioridade
curl "https://csuite.internut.com.br/operations/alerts?priority=high&status=open"

# Alertas de uma organização
curl "https://csuite.internut.com.br/operations/alerts?org_id=1&status=open"

Resposta:

{
  "alerts": [
    {
      "alert_id": "alert-456",
      "title": "Alerta de Ruptura",
      "description": "Produto X com estoque crítico",
      "severity": "high",
      "type": "inventory",
      "org_id": 1,
      "status": "open",
      "created_at": "2024-12-01T09:00:00Z"
    }
  ],
  "count": 5
}

4.2 Obter Detalhes de Alerta

Endpoint: GET /alerts/{alert_id}

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

Parâmetros de Path:
- alert_id (string, obrigatório) - ID do alerta

Exemplo:

curl "https://csuite.internut.com.br/operations/alerts/alert-456"

Resposta:

{
  "alert_id": "alert-456",
  "title": "Alerta de Ruptura",
  "description": "Produto X com estoque crítico",
  "severity": "high",
  "type": "inventory",
  "org_id": 1,
  "status": "open",
  "metadata": {
    "product_id": "BK4-2516",
    "current_stock": 5,
    "min_stock": 20
  },
  "created_at": "2024-12-01T09:00:00Z"
}

4.3 Responder a Alerta

Endpoint: POST /alerts/{alert_id}/respond

Descrição: Responde a alerta do Executive criando plano de ação e, opcionalmente, gerando decisões do 4C.

Parâmetros de Path:
- alert_id (string, obrigatório) - ID do alerta

Parâmetros de Query:
- operator_id (int, obrigatório) - ID do operador

Request Body:

{
  "alert_id": "alert-456",
  "title": "Resolver problema de ruptura",
  "description": "Acelerar reposição e notificar clientes",
  "actions": [
    {
      "title": "Acelerar reposição",
      "description": "Contatar fornecedor para reposição urgente",
      "priority": "high",
      "due_date": "2024-12-02T10:00:00Z"
    },
    {
      "title": "Notificar clientes",
      "description": "Enviar mensagem para clientes afetados",
      "priority": "medium",
      "due_date": "2024-12-01T18:00:00Z"
    }
  ],
  "scenario_name": "rupture_resolution",
  "parameters": {
    "product_id": "BK4-2516",
    "expected_delivery": "2024-12-05"
  },
  "generate_decisions": true,
  "customer_ids": [12345, 67890, 11111],
  "goal": "resolve_alert",
  "notes": "Ação imediata necessária"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/alerts/alert-456/respond?operator_id=5" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_id": "alert-456",
    "title": "Resolver problema de ruptura",
    "actions": [
      {
        "title": "Acelerar reposição",
        "description": "Contatar fornecedor",
        "priority": "high"
      }
    ],
    "generate_decisions": true,
    "customer_ids": [12345, 67890],
    "goal": "resolve_alert"
  }'

Resposta:

{
  "alert_id": "alert-456",
  "action_items_created": 2,
  "decisions_generated": 2,
  "impact_simulation": {
    "scenario": "rupture_resolution",
    "estimated_resolution_date": "2024-12-05",
    "affected_customers": 15
  },
  "action_items": [
    {
      "item_id": "item-789",
      "title": "Acelerar reposição",
      "priority": "high",
      "status": "pending"
    }
  ],
  "decisions": [
    {
      "decision_id": "decision-789",
      "customer_id": 12345,
      "recommended_action": "send_whatsapp",
      "approved": true
    }
  ]
}

Campos do Request:
- alert_id: ID do alerta (deve corresponder ao path)
- title: Título da resposta
- description: Descrição da resposta
- actions: Lista de ações a serem criadas como action items
- scenario_name: Nome do cenário para simulação (se alerta financeiro)
- parameters: Parâmetros para simulação
- generate_decisions: Se true, gera decisões do 4C para os clientes
- customer_ids: Lista de IDs de clientes para gerar decisões
- goal: Objetivo das decisões geradas
- notes: Notas adicionais

Fluxo:
1. Obtém alerta do Executive
2. Se alerta é financeiro e scenario_name fornecido, simula impacto via Cashflow API
3. Cria action items baseados na resposta
4. Se generate_decisions=true, gera decisões do 4C para os clientes
5. Retorna resumo da resposta

5. Workflow Orchestrator API

Base Path: /workflows

5.1 Criar Workflow

Endpoint: POST /workflows

Descrição: Cria workflow personalizado com múltiplos steps.

Request Body:

{
  "name": "Workflow de Reativação",
  "description": "Workflow para reativar clientes inativos",
  "steps": [
    {
      "action": "send_email",
      "decision_id": "decision-123",
      "delay_hours": 0,
      "parameters": {
        "template": "reactivation_email_1"
      }
    },
    {
      "action": "send_whatsapp",
      "decision_id": "decision-456",
      "delay_hours": 24,
      "condition": "no_response",
      "parameters": {
        "template": "reactivation_whatsapp"
      }
    },
    {
      "action": "escalate_to_seller",
      "delay_hours": 48,
      "condition": "no_response"
    }
  ],
  "created_by": 5
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/workflows" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workflow de Reativação",
    "description": "Workflow para reativar clientes inativos",
    "steps": [
      {
        "action": "send_email",
        "decision_id": "decision-123",
        "delay_hours": 0
      },
      {
        "action": "send_whatsapp",
        "decision_id": "decision-456",
        "delay_hours": 24,
        "condition": "no_response"
      }
    ],
    "created_by": 5
  }'

Resposta:

{
  "id": "workflow-uuid-123",
  "name": "Workflow de Reativação",
  "description": "Workflow para reativar clientes inativos",
  "steps": [
    {
      "action": "send_email",
      "decision_id": "decision-123",
      "delay_hours": 0
    },
    {
      "action": "send_whatsapp",
      "decision_id": "decision-456",
      "delay_hours": 24,
      "condition": "no_response"
    }
  ],
  "status": "active",
  "created_by": 5,
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

Ações Disponíveis:
- send_email: Envia email via decisão do 4C
- send_whatsapp: Envia WhatsApp via decisão do 4C
- schedule_followup: Agenda follow-up
- escalate_to_seller: Escala para vendedor

Condições:
- no_response: Executa apenas se não houver resposta no step anterior

5.2 Listar Workflows

Endpoint: GET /workflows

Descrição: Obtém lista de workflows.

Parâmetros de Query:
- status (string, padrão: active) - Filtrar por status (active, inactive, archived)
- limit (int, padrão: 50) - Número máximo de workflows

Exemplo:

# Workflows ativos
curl "https://csuite.internut.com.br/operations/workflows?status=active"

# Todos os workflows
curl "https://csuite.internut.com.br/operations/workflows?status=all&limit=100"

Resposta:

[
  {
    "id": "workflow-uuid-123",
    "name": "Workflow de Reativação",
    "description": "Workflow para reativar clientes inativos",
    "steps": [...],
    "status": "active",
    "created_by": 5,
    "created_at": "2024-12-01T10:00:00Z",
    "updated_at": "2024-12-01T10:00:00Z"
  }
]

5.3 Obter Detalhes de Workflow

Endpoint: GET /workflows/{workflow_id}

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

Parâmetros de Path:
- workflow_id (string, obrigatório) - ID do workflow

Exemplo:

curl "https://csuite.internut.com.br/operations/workflows/workflow-uuid-123"

Resposta:

{
  "id": "workflow-uuid-123",
  "name": "Workflow de Reativação",
  "description": "Workflow para reativar clientes inativos",
  "steps": [
    {
      "action": "send_email",
      "decision_id": "decision-123",
      "delay_hours": 0
    }
  ],
  "status": "active",
  "created_by": 5,
  "created_at": "2024-12-01T10:00:00Z",
  "updated_at": "2024-12-01T10:00:00Z"
}

5.4 Executar Workflow

Endpoint: POST /workflows/{workflow_id}/execute

Descrição: Executa workflow. Requer aprovação do Policy Engine.

Parâmetros de Path:
- workflow_id (string, obrigatório) - ID do workflow

Parâmetros de Query:
- approved (bool, padrão: false) - Se workflow foi aprovado manualmente

Request Body (opcional):

{
  "parameters": {
    "customer_id": 12345,
    "custom_message": "Mensagem personalizada"
  }
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/workflows/workflow-uuid-123/execute?approved=true" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "customer_id": 12345
    }
  }'

Resposta:

{
  "id": "execution-uuid-456",
  "workflow_id": "workflow-uuid-123",
  "status": "running",
  "current_step": 0,
  "started_at": "2024-12-01T10:05:00Z",
  "completed_at": null,
  "result": null,
  "error": null
}

Fluxo de Execução:
1. Valida workflow via Policy Engine (operations.execute_workflow)
2. Se outcome != ALLOW, retorna erro 409
3. Cria execução com status running
4. Executa steps em background (assíncrono)
5. Aplica delays entre steps
6. Verifica condições antes de executar cada step
7. Atualiza status para completed ou failed

Status da Execução:
- running: Em execução
- completed: Concluído com sucesso
- failed: Falhou (ver error)

5.5 Histórico de Execuções

Endpoint: GET /workflows/{workflow_id}/executions

Descrição: Obtém histórico de execuções de um workflow.

Parâmetros de Path:
- workflow_id (string, obrigatório) - ID do workflow

Parâmetros de Query:
- limit (int, padrão: 50) - Número máximo de execuções

Exemplo:

curl "https://csuite.internut.com.br/operations/workflows/workflow-uuid-123/executions?limit=20"

Resposta:

[
  {
    "id": "execution-uuid-456",
    "workflow_id": "workflow-uuid-123",
    "status": "completed",
    "current_step": 2,
    "started_at": "2024-12-01T10:05:00Z",
    "completed_at": "2024-12-01T10:10:00Z",
    "result": {
      "steps": [
        {"action": "send_email", "status": "success"},
        {"action": "send_whatsapp", "status": "success"}
      ]
    },
    "error": null
  }
]

6. Feedback Collector API

Base Path: /feedback

6.1 Coletar Feedback

Endpoint: POST /feedback

Descrição: Coleta feedback de operador sobre decisão ou execução.

Request Body:

{
  "decision_id": "decision-123",
  "execution_id": "execution-uuid-123",
  "operator_id": 5,
  "rating": 4,
  "notes": "Decisão funcionou bem, cliente respondeu positivamente",
  "outcome": "success"
}

Exemplo:

curl -X POST "https://csuite.internut.com.br/operations/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "decision-123",
    "execution_id": "execution-uuid-123",
    "operator_id": 5,
    "rating": 4,
    "notes": "Decisão funcionou bem",
    "outcome": "success"
  }'

Resposta:

{
  "id": "feedback-uuid-123",
  "decision_id": "decision-123",
  "execution_id": "execution-uuid-123",
  "operator_id": 5,
  "rating": 4,
  "notes": "Decisão funcionou bem",
  "outcome": "success",
  "created_at": "2024-12-01T10:15:00Z"
}

Campos do Request:
- decision_id: ID da decisão (opcional)
- execution_id: ID da execução (opcional)
- operator_id: ID do operador (obrigatório)
- rating: Nota de 1 a 5 (opcional)
- notes: Notas do operador (opcional)
- outcome: Resultado (success, failure, partial) (opcional)

6.2 Obter Feedback

Endpoint: GET /feedback

Descrição: Obtém feedback coletado.

Parâmetros de Query:
- decision_id (string, opcional) - Filtrar por decisão
- execution_id (string, opcional) - Filtrar por execução
- operator_id (int, opcional) - Filtrar por operador
- limit (int, padrão: 50) - Número máximo de feedbacks

Exemplo:

# Todos os feedbacks
curl "https://csuite.internut.com.br/operations/feedback"

# Feedbacks de uma decisão
curl "https://csuite.internut.com.br/operations/feedback?decision_id=decision-123"

# Feedbacks de um operador
curl "https://csuite.internut.com.br/operations/feedback?operator_id=5&limit=20"

Resposta:

[
  {
    "id": "feedback-uuid-123",
    "decision_id": "decision-123",
    "execution_id": "execution-uuid-123",
    "operator_id": 5,
    "rating": 4,
    "notes": "Decisão funcionou bem",
    "outcome": "success",
    "created_at": "2024-12-01T10:15:00Z"
  }
]

7. Exemplos Práticos

7.1 Fluxo Completo: Dashboard → Executar Decisão → Feedback

# 1. Ver dashboard
curl "https://csuite.internut.com.br/operations/dashboard?org_id=1"

# 2. Listar decisões pendentes
curl "https://csuite.internut.com.br/operations/decisions/pending?limit=10"

# 3. Executar decisão
curl -X POST "https://csuite.internut.com.br/operations/decisions/decision-123/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "decision-123",
    "operator_id": 5,
    "notes": "Executado com sucesso"
  }'

# 4. Coletar feedback
curl -X POST "https://csuite.internut.com.br/operations/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_id": "decision-123",
    "execution_id": "execution-uuid-123",
    "operator_id": 5,
    "rating": 5,
    "outcome": "success"
  }'

7.2 Responder a Alerta e Gerar Decisões

# 1. Listar alertas
curl "https://csuite.internut.com.br/operations/alerts?priority=high&status=open"

# 2. Obter detalhes do alerta
curl "https://csuite.internut.com.br/operations/alerts/alert-456"

# 3. Responder alerta e gerar decisões
curl -X POST "https://csuite.internut.com.br/operations/alerts/alert-456/respond?operator_id=5" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_id": "alert-456",
    "title": "Resolver ruptura",
    "actions": [
      {
        "title": "Notificar clientes",
        "priority": "high"
      }
    ],
    "generate_decisions": true,
    "customer_ids": [12345, 67890],
    "goal": "resolve_alert"
  }'

7.3 Criar e Executar Workflow

# 1. Criar workflow
curl -X POST "https://csuite.internut.com.br/operations/workflows" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reativação 3 Etapas",
    "steps": [
      {
        "action": "send_email",
        "decision_id": "decision-123",
        "delay_hours": 0
      },
      {
        "action": "send_whatsapp",
        "decision_id": "decision-456",
        "delay_hours": 24,
        "condition": "no_response"
      },
      {
        "action": "escalate_to_seller",
        "delay_hours": 48,
        "condition": "no_response"
      }
    ],
    "created_by": 5
  }'

# 2. Executar workflow
curl -X POST "https://csuite.internut.com.br/operations/workflows/workflow-uuid-123/execute?approved=true" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "customer_id": 12345
    }
  }'

# 3. Verificar execuções
curl "https://csuite.internut.com.br/operations/workflows/workflow-uuid-123/executions"

7.4 Decisão Automática para Reativação

curl -X POST "https://csuite.internut.com.br/operations/decisions/auto?customer_id=12345&operator_id=5" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "goal": "reactivation",
      "constraints": {
        "min_intent": 0.5
      }
    }
  }'

8. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-operations está rodando
Verifique se o path está correto (/operations/dashboard, /operations/decisions, etc.)
Verifique se o endpoint existe na documentação OpenAPI

Erro: "Unauthorized" (401)

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

Erro: "Forbidden" (403) em Workflow

Verifique se o workflow foi aprovado (approved=true)
Verifique se o Policy Engine permite a execução (operations.execute_workflow)
Verifique logs do Policy Engine

Erro ao Executar Decisão

Verifique se a decisão existe no 4C
Verifique se o 4C Decision API está acessível
Verifique logs do serviço csuite-operations

Erro ao Responder Alerta

Verifique se o alerta existe no Executive
Verifique se o Executive API está acessível
Verifique se customer_ids são válidos (se generate_decisions=true)

Workflow não executa steps

Verifique se o workflow foi aprovado
Verifique se as decisões referenciadas existem
Verifique logs do serviço para erros em steps específicos
Verifique se há delays muito longos entre steps

Dados não aparecem no Dashboard

Verifique se as APIs integradas (4C, Executive, Context) estão acessíveis
Verifique se há dados nas fontes (decisões pendentes, alertas, etc.)
Verifique logs do serviço para erros de integração

9. Documentação Relacionada

9.1 Documentação Interna

README: csuite-operations/README.md
Análise e Proposta: csuite-operations/docs/ANALISE_APIS_NOVO_APP_OPERACIONAL.md
Exemplos Práticos: csuite-operations/docs/EXEMPLOS_PRATICOS_APIS.md

9.2 Integrações

4C Decision API: Documentação do 4C
Executive API: Ver docs/GUIA_USO_APIS_EXECUTIVE.md
Context API: Ver docs/GUIA_USO_APIS_CONTEXT.md
Cashflow API: Ver docs/GUIA_USO_APIS_CASHFLOW.md

10. Schema do Banco

Tabelas Principais

operations_executions
- Armazena execuções de decisões
- Campos: id, decision_id, operator_id, executed_at, status, modifications, notes

operations_workflows
- Armazena workflows personalizados
- Campos: id, name, description, steps, status, created_by

operations_workflow_executions
- Armazena execuções de workflows
- Campos: id, workflow_id, status, current_step, started_at, completed_at, result, error

operations_feedback
- Armazena feedback de operadores
- Campos: id, decision_id, execution_id, operator_id, rating, notes, outcome

Ver csuite-operations/schema.sql para detalhes completos.

11. Próximos Passos

Adicionar webhooks para notificações de execuções
Adicionar exportação CSV/Excel de execuções e feedback
Adicionar métricas de performance (tempo de resposta, taxa de sucesso)
Adicionar cache para queries frequentes
Adicionar rate limiting por operador/org
Adicionar suporte a workflows condicionais mais complexos

12. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/operations/docs

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

ReDoc: https://csuite.internut.com.br/operations/redoc

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

Guia de Uso - APIs /operations

📋 Índice

1. Visão Geral

Funcionalidades Principais

Arquitetura

Integrações

2. Dashboard API

2.1 Dashboard Consolidado

3. Decision Executor API

3.1 Listar Decisões Pendentes

3.2 Executar Decisão

3.3 Criar e Executar Decisão Automática

3.4 Histórico de Execuções

4. Alert Responder API

4.1 Listar Alertas

4.2 Obter Detalhes de Alerta

4.3 Responder a Alerta

5. Workflow Orchestrator API

5.1 Criar Workflow

5.2 Listar Workflows

5.3 Obter Detalhes de Workflow

5.4 Executar Workflow

5.5 Histórico de Execuções

6. Feedback Collector API

6.1 Coletar Feedback

6.2 Obter Feedback

7. Exemplos Práticos

7.1 Fluxo Completo: Dashboard → Executar Decisão → Feedback

7.2 Responder a Alerta e Gerar Decisões

7.3 Criar e Executar Workflow

7.4 Decisão Automática para Reativação

8. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Forbidden" (403) em Workflow

Erro ao Executar Decisão

Erro ao Responder Alerta

Workflow não executa steps

Dados não aparecem no Dashboard

9. Documentação Relacionada

9.1 Documentação Interna

9.2 Integrações

10. Schema do Banco

Tabelas Principais

11. Próximos Passos

12. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/operations`