🔍 Análise de APIs e Proposta de Novo App Operacional
Data: 2025-12-06
Versão: 1.0
📋 Índice
- Análise das APIs Existentes
- Proposta: C-Suite Operations
- Arquitetura do Novo App
- Casos de Uso Práticos
- Exemplos de Integração
- Roadmap de Implementação
🔍 Análise das APIs Existentes
1. 4C - Córtex Comercial (Nível Cliente)
Decision API
- Base URL:
https://csuite.internut.com.br/4c/decision - Endpoints Principais:
POST /decide- Decisão completa (cliente, oferta, canal, timing)POST /decide/auto- Decisão automática sem candidatosPOST /send- Executar ação (WhatsApp, Email, CRM)
Capacidades:
- ✅ Decisões 1:1 com clientes
- ✅ Scoring de intenção, oferta, canal e timing
- ✅ Explicações e justificativas
- ✅ Constraints e políticas
Feature Service
- Base URL:
https://csuite.internut.com.br/4c/feature-service - Endpoints:
POST /features/customer- Features agregadas por cliente/SKU/contexto
Capacidades:
- ✅ Agregação de dados históricos
- ✅ Cache Redis para performance
- ✅ Features contextuais
Scoring Service
- Base URL:
https://csuite.internut.com.br/4c/scoring-service - Endpoints:
POST /score/intent- Score de intenção de compraPOST /score/offer- Ranking de ofertas (Learning-to-Rank)POST /score/channel- Melhor canal de comunicaçãoPOST /score/timing- Melhor horário para envio
Capacidades:
- ✅ Modelos ML para cada dimensão
- ✅ Explicações (SHAP values)
- ✅ Versionamento de modelos
2. C-Suite Executive (Nível Organização)
CSuite API
- Base URL:
https://csuite.internut.com.br/executive - Endpoints Principais:
GET /dashboard/summary/{org_id}- Resumo executivoPOST /agents/{org_id}/{agent_type}/run- Executar agente (CFO, CEO, COO, CMO, CAIO)GET /agents/{org_id}/runs- Histórico de execuçõesGET /alerts- Alertas abertosGET /action-items- Itens de ação pendentesGET /policies- Políticas e regras
Capacidades:
- ✅ Agentes executivos automatizados
- ✅ Alertas e action items
- ✅ Políticas organizacionais
- ✅ Métricas e KPIs
3. C-Suite Context (Análise Temporal)
Context API
- Base URL:
https://csuite.internut.com.br/context/api/csuite - Endpoints:
GET /events- Eventos de curto prazoGET /trends- Tendências de médio prazoGET /shifts- Mudanças estruturais (context shifts)GET /radar- Radar de oportunidades/riscosGET /signals- Sinais detectados
Capacidades:
- ✅ Detecção de padrões temporais
- ✅ Identificação de tendências
- ✅ Alertas de mudanças estruturais
4. C-Suite Cashflow (Gestão Financeira)
Cashflow API
- Base URL:
https://csuite.internut.com.br/cashflow/api/cashflow - Endpoints:
GET /timeline- Timeline de fluxo de caixaGET /containers- Contêineres financeirosGET /scenarios- Cenários simuladosGET /alerts- Alertas financeirosPOST /simulator/run- Simular cenários
Capacidades:
- ✅ Previsão de fluxo de caixa
- ✅ Simulação de cenários
- ✅ Alertas de risco financeiro
5. C-Suite Sales Manager (Vendas B2B)
Manager API
- Base URL:
https://csuite.internut.com.br/sales-manager - Endpoints:
GET /manager/today- Tasks do diaGET /seller/{seller_id}/today- Tasks por vendedorPOST /tasks/{task_id}/complete- Completar task
Decision API (4C Lite)
- Base URL:
https://csuite.internut.com.br/sales-decision - Endpoints:
POST /4c/decide- Decisão 4C Lite para revendas
Capacidades:
- ✅ Priorização de tasks
- ✅ Decisões simplificadas para B2B
🎯 Proposta: C-Suite Operations
Visão Geral
C-Suite 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.
Problema que Resolve
Atualmente, há uma lacuna operacional:
- ✅ 4C toma decisões inteligentes (cliente certo, oferta certa, jeito certo, hora certa)
- ✅ C-Suite Executive gera alertas e action items estratégicos
- ❌ Falta: Um app que permita que operadores executem essas decisões e respondam aos alertas de forma integrada
Objetivos
- Execução Operacional: Permitir que operadores executem decisões do 4C
- Resposta a Alertas: Facilitar resposta rápida a alertas do Executive
- Visão Unificada: Consolidar visão operacional + estratégica
- Automação de Workflows: Orquestrar workflows entre sistemas
- Feedback Loop: Coletar feedback operacional para melhorar decisões
🏗️ Arquitetura do Novo App
Componentes Principais
┌─────────────────────────────────────────────────┐
│ C-Suite Operations │
│ (App Operacional) │
└─────────────────────────────────────────────────┘
│
┌───────────┼───────────┐
│ │ │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│ 4C │ │Exec. │ │Context│
│ APIs │ │ APIs │ │ APIs │
└───────┘ └───────┘ └───────┘
Módulos do App
1. Operations Dashboard
- Visão consolidada de decisões pendentes
- Alertas prioritários
- Métricas operacionais em tempo real
2. Decision Executor
- Executar decisões do 4C
- Aprovar/rejeitar decisões automáticas
- Modificar decisões antes de executar
3. Alert Responder
- Visualizar alertas do Executive
- Criar planos de ação
- Executar ações corretivas
4. Workflow Orchestrator
- Criar workflows personalizados
- Automatizar processos repetitivos
- Integrar com sistemas externos
5. Feedback Collector
- Coletar feedback de operadores
- Avaliar qualidade de decisões
- Enviar feedback para melhorar modelos
💡 Casos de Uso Práticos
Caso de Uso 1: Executar Decisão do 4C com Aprovação
Cenário: O 4C gerou uma decisão para contatar cliente com oferta especial. O operador precisa revisar e aprovar antes de executar.
Fluxo:
1. Operations Dashboard mostra decisão pendente
2. Operador visualiza detalhes (cliente, oferta, canal, timing)
3. Operador pode modificar (ex: mudar canal de WhatsApp para Email)
4. Operador aprova e executa
5. Sistema chama POST /4c/decision/send para executar
6. Feedback é coletado após execução
APIs Utilizadas:
# 1. Obter decisão pendente
GET /4c/decision/decisions?status=pending&limit=50
# 2. Obter detalhes da decisão
GET /4c/decision/decisions/{decision_id}
# 3. Modificar decisão (se necessário)
PATCH /4c/decision/decisions/{decision_id}
{
"channel": "email", # Mudança de WhatsApp para Email
"message": "Mensagem customizada pelo operador"
}
# 4. Executar decisão
POST /4c/decision/send
{
"decision_id": "uuid-123",
"approved_by": "operator-456",
"executed_at": "2025-12-06T14:30:00Z"
}
# 5. Coletar feedback
POST /operations/feedback
{
"decision_id": "uuid-123",
"outcome": "success",
"customer_response": "positive",
"notes": "Cliente respondeu positivamente"
}
Caso de Uso 2: Responder a Alerta do CFO
Cenário: O CFO detectou que o fluxo de caixa está abaixo do esperado. O operador precisa criar um plano de ação.
Fluxo:
1. Alert Responder mostra alerta do CFO
2. Operador visualiza detalhes (métrica, valor atual, valor esperado)
3. Operador cria plano de ação (ex: acelerar cobrança, reduzir despesas)
4. Sistema integra com Cashflow API para simular impacto
5. Operador executa ações
6. Sistema monitora resultado e fecha alerta quando resolvido
APIs Utilizadas:
# 1. Obter alertas prioritários
GET /executive/alerts?priority=high&status=open
# 2. Obter detalhes do alerta
GET /executive/alerts/{alert_id}
# 3. Obter contexto financeiro
GET /cashflow/api/cashflow/timeline?days=30
# 4. Simular impacto de ação
POST /cashflow/api/cashflow/simulator/run
{
"scenario": "accelerate_collection",
"parameters": {
"collection_days_reduction": 5
}
}
# 5. Criar action item
POST /executive/action-items
{
"alert_id": "alert-789",
"title": "Acelerar cobrança de clientes",
"description": "Contatar clientes com pagamento em atraso",
"priority": "high",
"due_date": "2025-12-10"
}
# 6. Executar ações do 4C para clientes com atraso
POST /4c/decision/decide/auto
{
"customer_ids": [123, 456, 789], # Clientes com atraso
"context": {
"goal": "collection",
"urgency": "high"
}
}
# 7. Fechar alerta quando resolvido
PATCH /executive/alerts/{alert_id}
{
"status": "resolved",
"resolution_notes": "Ações executadas com sucesso"
}
Caso de Uso 3: Workflow Automatizado de Reativação
Cenário: Cliente inativo há 90 dias. Sistema detecta oportunidade de reativação e cria workflow automático.
Fluxo:
1. Context API detecta cliente inativo (via /events ou /signals)
2. Operations cria workflow de reativação
3. Sistema chama 4C para gerar decisão de reativação
4. Operador revisa e aprova
5. Sistema executa sequência de ações:
- Envia email de reativação
- Agenda follow-up
- Monitora resposta
6. Se cliente não responder, escala para vendedor
APIs Utilizadas:
# 1. Detectar cliente inativo (via Context API)
GET /context/api/csuite/signals?type=customer_inactive&days=90
# 2. Obter features do cliente
POST /4c/feature-service/features/customer
{
"customer_id": 123,
"context": {"goal": "reactivation"}
}
# 3. Gerar decisão de reativação
POST /4c/decision/decide/auto
{
"customer_id": 123,
"context": {
"goal": "reactivation",
"urgency": "medium"
}
}
# 4. Criar workflow
POST /operations/workflows
{
"name": "Customer Reactivation",
"customer_id": 123,
"steps": [
{
"action": "send_email",
"decision_id": "decision-123",
"delay_hours": 0
},
{
"action": "schedule_followup",
"delay_hours": 48
},
{
"action": "escalate_to_seller",
"condition": "no_response",
"delay_hours": 120
}
]
}
# 5. Executar workflow
POST /operations/workflows/{workflow_id}/execute
# 6. Monitorar progresso
GET /operations/workflows/{workflow_id}/status
Caso de Uso 4: Priorização Inteligente de Tasks
Cenário: Operador tem 100 decisões pendentes. Sistema prioriza automaticamente baseado em impacto e urgência.
Fluxo:
1. Operations Dashboard consolida todas as decisões pendentes
2. Sistema calcula prioridade usando:
- Score de intenção do 4C
- Urgência do contexto
- Impacto financeiro (via Cashflow)
- Alertas relacionados (via Executive)
3. Operador vê lista priorizada
4. Sistema sugere ações em lote para decisões similares
APIs Utilizadas:
# 1. Obter todas as decisões pendentes
GET /4c/decision/decisions?status=pending
# 2. Para cada decisão, obter contexto
for decision in decisions:
# Obter features do cliente
POST /4c/feature-service/features/customer
{
"customer_id": decision["customer_id"]
}
# Obter alertas relacionados
GET /executive/alerts?customer_id={customer_id}
# Calcular impacto financeiro
GET /cashflow/api/cashflow/timeline?customer_id={customer_id}
# 3. Priorizar usando algoritmo próprio
POST /operations/prioritize
{
"decisions": [...],
"criteria": {
"intent_weight": 0.3,
"urgency_weight": 0.2,
"financial_impact_weight": 0.3,
"alert_priority_weight": 0.2
}
}
# 4. Retornar lista priorizada
GET /operations/dashboard/pending?sort=priority&limit=50
Caso de Uso 5: Integração com Sistema Externo (CRM)
Cenário: Decisão do 4C precisa criar oportunidade no CRM externo.
Fluxo:
1. 4C gera decisão
2. Operations recebe decisão
3. Sistema cria oportunidade no CRM via webhook/API
4. Sistema sincroniza status entre CRM e Operations
5. Feedback do CRM é usado para melhorar decisões
APIs Utilizadas:
# 1. Obter decisão aprovada
GET /4c/decision/decisions/{decision_id}
# 2. Criar oportunidade no CRM (webhook)
POST /operations/integrations/crm/create-opportunity
{
"decision_id": "uuid-123",
"customer_id": 123,
"offer": {
"sku": "BK4-2516",
"price": 1500.00
},
"channel": "whatsapp",
"timing": "2025-12-06T14:30:00Z"
}
# 3. Sincronizar status
GET /operations/integrations/crm/opportunities/{crm_opportunity_id}
# 4. Atualizar decisão com feedback do CRM
PATCH /4c/decision/decisions/{decision_id}
{
"crm_status": "won",
"crm_notes": "Cliente aceitou oferta"
}
# 5. Coletar feedback para melhorar modelos
POST /operations/feedback
{
"decision_id": "uuid-123",
"source": "crm",
"outcome": "won",
"revenue": 1500.00
}
🔌 Exemplos de Integração
Exemplo 1: Endpoint de Dashboard Operacional
# GET /operations/dashboard
@app.get("/operations/dashboard")
async def get_operations_dashboard(
org_id: int,
operator_id: Optional[int] = None
):
"""
Dashboard consolidado com:
- Decisões pendentes (4C)
- Alertas prioritários (Executive)
- Métricas operacionais
- Tasks do dia
"""
# 1. Obter decisões pendentes do 4C
async with httpx.AsyncClient() as client:
decisions_resp = await client.get(
f"{FOURC_DECISION_API_URL}/decisions",
params={"status": "pending", "limit": 50}
)
decisions = decisions_resp.json()
# 2. Obter alertas do Executive
alerts_resp = await client.get(
f"{CSUITE_EXECUTIVE_API_URL}/alerts",
params={"priority": "high", "status": "open"}
)
alerts = alerts_resp.json()
# 3. Obter action items
action_items_resp = await client.get(
f"{CSUITE_EXECUTIVE_API_URL}/action-items",
params={"status": "pending"}
)
action_items = action_items_resp.json()
# 4. Priorizar decisões
prioritized = prioritize_decisions(decisions, alerts, action_items)
return {
"pending_decisions": prioritized["decisions"],
"high_priority_alerts": alerts,
"action_items": action_items,
"metrics": {
"decisions_today": len(decisions),
"alerts_open": len(alerts),
"completion_rate": calculate_completion_rate()
}
}
Exemplo 2: Executar Decisão com Modificações
# POST /operations/decisions/{decision_id}/execute
@app.post("/operations/decisions/{decision_id}/execute")
async def execute_decision(
decision_id: str,
modifications: Optional[DecisionModifications] = None,
operator_id: int
):
"""
Executa decisão do 4C, permitindo modificações do operador
"""
# 1. Obter decisão original
async with httpx.AsyncClient() as client:
decision_resp = await client.get(
f"{FOURC_DECISION_API_URL}/decisions/{decision_id}"
)
decision = decision_resp.json()
# 2. Aplicar modificações (se houver)
if modifications:
decision.update(modifications.dict(exclude_none=True))
decision["modified_by"] = operator_id
decision["modified_at"] = datetime.utcnow().isoformat()
# 3. Executar via 4C Executor
execute_resp = await client.post(
f"{FOURC_DECISION_API_URL}/send",
json={
"decision_id": decision_id,
"customer_id": decision["customer_id"],
"offer": decision["offer"],
"channel": decision["channel"],
"message": decision.get("message"),
"send_at": decision.get("timing", {}).get("send_at")
}
)
# 4. Registrar execução
await db.execute(
"""
INSERT INTO operations.executions
(decision_id, operator_id, executed_at, status)
VALUES (:decision_id, :operator_id, NOW(), 'executed')
""",
{"decision_id": decision_id, "operator_id": operator_id}
)
return {
"decision_id": decision_id,
"status": "executed",
"execution_id": execute_resp.json().get("execution_id")
}
Exemplo 3: Workflow de Resposta a Alerta
# POST /operations/alerts/{alert_id}/respond
@app.post("/operations/alerts/{alert_id}/respond")
async def respond_to_alert(
alert_id: str,
response: AlertResponse,
operator_id: int
):
"""
Responde a alerta do Executive criando plano de ação
"""
# 1. Obter alerta
async with httpx.AsyncClient() as client:
alert_resp = await client.get(
f"{CSUITE_EXECUTIVE_API_URL}/alerts/{alert_id}"
)
alert = alert_resp.json()
# 2. Criar action items baseados na resposta
action_items = []
for action in response.actions:
action_item_resp = await client.post(
f"{CSUITE_EXECUTIVE_API_URL}/action-items",
json={
"alert_id": alert_id,
"title": action["title"],
"description": action["description"],
"priority": action.get("priority", "medium"),
"due_date": action.get("due_date"),
"assigned_to": operator_id
}
)
action_items.append(action_item_resp.json())
# 3. Se alerta é financeiro, simular impacto
if alert["type"] == "financial":
cashflow_resp = await client.post(
f"{CASHFLOW_API_URL}/simulator/run",
json={
"scenario": response.scenario_name,
"parameters": response.parameters
}
)
impact = cashflow_resp.json()
# 4. Se necessário, gerar decisões do 4C
if response.generate_decisions:
for customer_id in response.customer_ids:
decision_resp = await client.post(
f"{FOURC_DECISION_API_URL}/decide/auto",
json={
"customer_id": customer_id,
"context": {
"alert_id": alert_id,
"goal": response.goal
}
}
)
# Adicionar decisão ao workflow
await create_workflow_step(alert_id, decision_resp.json())
# 5. Atualizar status do alerta
await client.patch(
f"{CSUITE_EXECUTIVE_API_URL}/alerts/{alert_id}",
json={
"status": "in_progress",
"responded_by": operator_id,
"response_notes": response.notes
}
)
return {
"alert_id": alert_id,
"action_items_created": len(action_items),
"decisions_generated": len(response.customer_ids) if response.generate_decisions else 0,
"impact_simulation": impact if alert["type"] == "financial" else None
}
🗺️ Roadmap de Implementação
Fase 1: MVP (4 semanas)
Objetivo: Dashboard básico + Execução de decisões
- [ ] Estrutura do app (FastAPI)
- [ ] Integração com 4C Decision API
- [ ] Dashboard de decisões pendentes
- [ ] Execução de decisões com aprovação
- [ ] Coleta básica de feedback
APIs a Implementar:
- GET /operations/dashboard - Dashboard consolidado
- GET /operations/decisions/pending - Lista de decisões pendentes
- POST /operations/decisions/{id}/execute - Executar decisão
- POST /operations/feedback - Coletar feedback
Fase 2: Alertas e Action Items (3 semanas)
Objetivo: Integração com Executive + Resposta a alertas
- [ ] Integração com C-Suite Executive API
- [ ] Visualização de alertas
- [ ] Criação de action items
- [ ] Workflow básico de resposta
APIs a Implementar:
- GET /operations/alerts - Lista de alertas
- POST /operations/alerts/{id}/respond - Responder a alerta
- GET /operations/action-items - Lista de action items
- POST /operations/action-items/{id}/complete - Completar action item
Fase 3: Workflows e Automação (4 semanas)
Objetivo: Workflows personalizados + Automação
- [ ] Engine de workflows
- [ ] Criação de workflows via UI
- [ ] Execução automática de workflows
- [ ] Integração com Context API para triggers
APIs a Implementar:
- POST /operations/workflows - Criar workflow
- GET /operations/workflows - Lista de workflows
- POST /operations/workflows/{id}/execute - Executar workflow
- GET /operations/workflows/{id}/status - Status do workflow
Fase 4: Integrações e Priorização (3 semanas)
Objetivo: Integrações externas + Priorização inteligente
- [ ] Integração com CRM (webhooks)
- [ ] Priorização inteligente de tasks
- [ ] Execução em lote
- [ ] Dashboard avançado com métricas
APIs a Implementar:
- POST /operations/integrations/crm/* - Integração CRM
- POST /operations/prioritize - Priorizar decisões
- POST /operations/batch/execute - Executar em lote
- GET /operations/metrics - Métricas operacionais
📊 Estrutura de Dados
Tabelas Principais
-- Execuções de decisões
CREATE TABLE operations.executions (
id UUID PRIMARY KEY,
decision_id UUID NOT NULL,
operator_id INT NOT NULL,
executed_at TIMESTAMP NOT NULL,
status VARCHAR(50) NOT NULL,
modifications JSONB,
feedback JSONB,
created_at TIMESTAMP DEFAULT NOW()
);
-- Workflows
CREATE TABLE operations.workflows (
id UUID PRIMARY KEY,
name VARCHAR(255) NOT NULL,
description TEXT,
steps JSONB NOT NULL,
status VARCHAR(50) NOT NULL,
created_by INT NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);
-- Execuções de workflows
CREATE TABLE operations.workflow_executions (
id UUID PRIMARY KEY,
workflow_id UUID NOT NULL,
status VARCHAR(50) NOT NULL,
current_step INT,
started_at TIMESTAMP NOT NULL,
completed_at TIMESTAMP,
result JSONB
);
-- Feedback de operadores
CREATE TABLE operations.feedback (
id UUID PRIMARY KEY,
decision_id UUID,
execution_id UUID,
operator_id INT NOT NULL,
rating INT, -- 1-5
notes TEXT,
outcome VARCHAR(50), -- success, failure, partial
created_at TIMESTAMP DEFAULT NOW()
);
🎯 Benefícios Esperados
Para Operadores
- ✅ Interface única para todas as operações
- ✅ Priorização automática de tasks
- ✅ Execução rápida de decisões
- ✅ Visão clara de alertas e ações
Para Gestores
- ✅ Visibilidade completa das operações
- ✅ Métricas de performance operacional
- ✅ Rastreabilidade de decisões
- ✅ Feedback loop para melhorias
Para o Ecossistema
- ✅ Integração completa entre 4C e Executive
- ✅ Automação de workflows
- ✅ Melhoria contínua via feedback
- ✅ Escalabilidade operacional
🔗 Próximos Passos
- Validar proposta com stakeholders
- Definir prioridades de implementação
- Criar protótipo do dashboard
- Testar integrações com APIs existentes
- Implementar MVP (Fase 1)
Última atualização: 2025-12-06