Guia de Uso - APIs `/csuite-customer-decisions`

Base URL: https://csuite.internut.com.br/csuite-customer-decisions

📋 Índice

Visão Geral
Endpoints do Orchestrator
Integração com 4C Decision API
Integração com CSuite Executive
Exemplos Práticos
Troubleshooting

1. Visão Geral

O csuite-customer-decisions é um orchestrator que integra:

4C (nível cliente): Decisões micro (Cliente, Oferta, Jeito, Hora)
CSuite Executive (nível organização): Agentes executivos e políticas

Propósito: Camada fina de orquestração que fornece visão consolidada do "organismo digital" (4C + CSuite).

2. Endpoints do Orchestrator

2.1 Status do Organismo (v1 - Recomendado)

Endpoint: GET /v1/organismo/{org_id}/status

Descrição: Retorna visão consolidada do organismo (4C + CSuite Executive) para uma organização.

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

Exemplo:

curl "https://csuite.internut.com.br/csuite-customer-decisions/v1/organismo/1/status"

Resposta:

{
  "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": {
    "fourc_decisions": {
      "decisions_today": 1250,
      "last_decision_at": "2024-12-01T14:30:00Z"
    },
    "csuite_dashboard": {
      "alerts_open": 5,
      "items_pending": 8
    },
    "csuite_monitoring": {
      "last_run": "2024-12-01T10:00:00Z"
    }
  }
}

Campos:
- fourc_decisions_today: Número de decisões 4C hoje
- fourc_last_decision_at: Última decisão 4C
- csuite_last_run_at: Última execução de agente CSuite
- csuite_open_alerts: Alertas abertos no CSuite
- csuite_pending_action_items: Action items pendentes
- notes: Detalhes adicionais (erros, dados completos)

2.2 Status do Organismo (Legacy)

Endpoint: GET /organismo/{org_id}/status

Descrição: Versão legacy (deprecated). Use /v1/organismo/{org_id}/status.

Status: ⚠️ Deprecated - Use /v1/organismo/{org_id}/status

2.3 Informações da API

Endpoint: GET /api/info

Descrição: Informações gerais da API.

Exemplo:

curl "https://csuite.internut.com.br/csuite-customer-decisions/api/info"

Resposta:

{
  "message": "4C-Suite – Organismo Digital de Gestão",
  "docs": "/docs",
  "health": "/health",
  "organismo_example": "/v1/organismo/1/status",
  "ui": "/"
}

2.4 Health Check

Endpoint: GET /health

Descrição: Verifica saúde da API e dependências (4C Decision API e CSuite API).

Exemplo:

curl "https://csuite.internut.com.br/csuite-customer-decisions/health"

Resposta:

{
  "status": "healthy",
  "dependencies": {
    "fourc_decision_api": {
      "status": "healthy",
      "response_time_ms": 45
    },
    "csuite_api": {
      "status": "healthy",
      "response_time_ms": 120
    }
  }
}

2.5 Dashboard UI

Endpoint: GET /

Descrição: Interface web do dashboard (HTML).

Exemplo:

# Abrir no navegador
https://csuite.internut.com.br/csuite-customer-decisions/

3. Integração com 4C Decision API

O orchestrator faz proxy para a 4C Decision API (sistema de decisões micro).

3.1 Endpoints 4C (via Proxy)

Nota: O orchestrator não expõe diretamente os endpoints 4C. Para usar os endpoints 4C, acesse diretamente:

Base URL 4C Decision API: http://decision-api:8080 (interno) ou via gateway se configurado

Principais endpoints 4C:

POST /decide (ou /v1/decide)

Decisão completa para um cliente (4 Certos: Cliente, Oferta, Jeito, Hora).

Request:

{
  "customer_id": 123,
  "candidates": [
    {"sku": "BK4-2516", "price": 1500.00},
    {"sku": "BK4-2517", "price": 2000.00}
  ],
  "constraints": {
    "min_intent": 0.45,
    "max_contacts_per_day": 2,
    "respect_opt_out": true
  },
  "include_explanations": true,
  "include_natural_justification": false
}

Response:

{
  "decision_id": "uuid-123",
  "approved": true,
  "customer_id": 123,
  "offer": {
    "sku": "BK4-2516",
    "price": 1500.00,
    "margin_pct": 25.5
  },
  "channel": "whatsapp",
  "timing": {
    "send_at": "2025-01-27T14:30:00Z",
    "score": 0.85
  },
  "scores": {
    "intent": 0.72,
    "offer": 0.88,
    "channel": 0.91,
    "timing": 0.85
  }
}

POST /decide/auto (ou /v1/decide/auto)

Decisão automática sem candidatos (sistema escolhe automaticamente).

Request:

{
  "customer_id": 123,
  "include_explanations": true,
  "include_natural_justification": true
}

GET /4c-suite/decisions/summary

Resumo de decisões 4C (usado pelo orchestrator).

Parâmetros:
- org_id (int, obrigatório) - ID da organização

Response:

{
  "decisions_today": 1250,
  "last_decision_at": "2024-12-01T14:30:00Z"
}

4. Integração com CSuite Executive

O orchestrator faz proxy para o CSuite Executive (agentes executivos).

4.1 Endpoints CSuite (via Proxy)

Nota: O orchestrator não expõe diretamente os endpoints CSuite. Para usar os endpoints CSuite, acesse diretamente:

Base URL CSuite Executive: https://csuite.internut.com.br/executive

Principais endpoints CSuite usados pelo orchestrator:

GET /dashboard/summary/{org_id}

Resumo do dashboard executivo.

Response:

{
  "alerts_open": 5,
  "items_pending": 8,
  "last_run": "2024-12-01T10:00:00Z"
}

GET /monitoring/summary/{org_id}

Resumo de monitoramento (execuções de agentes).

Response:

{
  "last_run": "2024-12-01T10:00:00Z",
  "runs_today": 12,
  "success_rate": 0.95
}

5. Exemplos Práticos

5.1 Verificar Status do Organismo

# Status consolidado (recomendado)
curl "https://csuite.internut.com.br/csuite-customer-decisions/v1/organismo/1/status"

# Status legacy (deprecated)
curl "https://csuite.internut.com.br/csuite-customer-decisions/organismo/1/status"

5.2 Health Check Completo

# Health check do orchestrator
curl "https://csuite.internut.com.br/csuite-customer-decisions/health"

# Verificar se 4C Decision API está acessível
# (depende da configuração interna)

# Verificar se CSuite Executive está acessível
curl "https://csuite.internut.com.br/executive/health"

5.3 Dashboard Web

# Abrir dashboard no navegador
open "https://csuite.internut.com.br/csuite-customer-decisions/"

5.4 Workflow Completo: Monitoramento do Organismo

# 1. Verificar saúde geral
curl "https://csuite.internut.com.br/csuite-customer-decisions/health"

# 2. Obter status consolidado
curl "https://csuite.internut.com.br/csuite-customer-decisions/v1/organismo/1/status" | jq

# 3. Verificar decisões 4C (se endpoint estiver exposto)
# curl "https://csuite.internut.com.br/4c/decisions/summary?org_id=1"

# 4. Verificar alertas CSuite
curl "https://csuite.internut.com.br/executive/dashboard/summary/1"

6. Arquitetura

6.1 Fluxo de Dados

Cliente/App
    ↓
csuite-customer-decisions (orchestrator)
    ↓
    ├─→ 4C Decision API (decisões micro)
    └─→ CSuite Executive (agentes macro)
    ↓
Status Consolidado

6.2 Circuit Breaker

O orchestrator usa circuit breaker para resiliência:

4C Decision API: Timeout 5s, failure threshold 3, timeout 30s
CSuite Executive: Timeout 5s, failure threshold 3, timeout 30s

Se um serviço estiver indisponível, o orchestrator retorna dados parciais (apenas do serviço disponível).

7. Configuração

7.1 Variáveis de Ambiente

# URLs dos serviços dependentes
FOURC_DECISION_API_URL=http://decision-api:8080
CSUITE_API_URL=http://csuite-api:8000

# Path routing (Traefik)
ROOT_PATH=/csuite-customer-decisions

# Autenticação
AUTH_ENABLED=true

# Logging
LOG_LEVEL=INFO
ENV=production

8. Troubleshooting

Erro: "Not Found"

Verifique se o serviço csuite-customer-decisions está rodando
Verifique se o Traefik está configurado corretamente
Verifique se o path /csuite-customer-decisions está correto

Erro: "Service Unavailable"

Verifique se FOURC_DECISION_API_URL está acessível
Verifique se CSUITE_API_URL está acessível
Verifique circuit breaker (pode estar aberto)

Dados parciais no status

Normal quando um serviço dependente está indisponível
Verifique notes no response para detalhes de erros
Circuit breaker pode estar aberto para um serviço

Timeout

Aumente timeout se necessário (padrão: 5s)
Verifique latência dos serviços dependentes
Considere cache para dados não-críticos

9. Documentação Relacionada

9.1 4C Decision API

Documentação completa: 4c/docs/MANUAL_APIS_4C.md

Principais serviços:
- Decision API (/decide, /decide/auto)
- Feature Service (/features/customer)
- Scoring Service (/score/intent, /score/offer, etc)
- Executor (/execute)

9.2 CSuite Executive

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

Principais endpoints:
- Policy Engine (/v1/policy/evaluate)
- Policy Guardian (/v1/policy/guardian/*)
- Memory API (/v1/memory/*)
- Dashboard (/dashboard/summary/{org_id})

10. Próximos Passos

Expor endpoints 4C via orchestrator (opcional)
Adicionar cache para status consolidado
Métricas agregadas (4C + CSuite)
Alertas consolidados (4C + CSuite)

11. Documentação OpenAPI

Swagger UI: https://csuite.internut.com.br/csuite-customer-decisions/docs

OpenAPI JSON: https://csuite.internut.com.br/csuite-customer-decisions/openapi.json

ReDoc: https://csuite.internut.com.br/csuite-customer-decisions/redoc

Última atualização: 2024-01-15
Versão: v0.1.0

Guia Uso Apis Customer Decisions

Guia de Uso - APIs `/csuite-customer-decisions`

📋 Índice

1. Visão Geral

2. Endpoints do Orchestrator

2.1 Status do Organismo (v1 - Recomendado)

2.2 Status do Organismo (Legacy)

2.3 Informações da API

2.4 Health Check

2.5 Dashboard UI

3. Integração com 4C Decision API

3.1 Endpoints 4C (via Proxy)

POST /decide (ou /v1/decide)

POST /decide/auto (ou /v1/decide/auto)

GET /4c-suite/decisions/summary

4. Integração com CSuite Executive

4.1 Endpoints CSuite (via Proxy)

GET /dashboard/summary/{org_id}

GET /monitoring/summary/{org_id}

5. Exemplos Práticos

5.1 Verificar Status do Organismo

5.2 Health Check Completo

5.3 Dashboard Web

5.4 Workflow Completo: Monitoramento do Organismo

6. Arquitetura

6.1 Fluxo de Dados

6.2 Circuit Breaker

7. Configuração

7.1 Variáveis de Ambiente

8. Troubleshooting

Erro: "Not Found"

Erro: "Service Unavailable"

Dados parciais no status

Timeout

9. Documentação Relacionada

9.1 4C Decision API

9.2 CSuite Executive

10. Próximos Passos

11. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs /csuite-customer-decisions

📋 Índice

1. Visão Geral

2. Endpoints do Orchestrator

2.1 Status do Organismo (v1 - Recomendado)

2.2 Status do Organismo (Legacy)

2.3 Informações da API

2.4 Health Check

2.5 Dashboard UI

3. Integração com 4C Decision API

3.1 Endpoints 4C (via Proxy)

POST /decide (ou /v1/decide)

POST /decide/auto (ou /v1/decide/auto)

GET /4c-suite/decisions/summary

4. Integração com CSuite Executive

4.1 Endpoints CSuite (via Proxy)

GET /dashboard/summary/{org_id}

GET /monitoring/summary/{org_id}

5. Exemplos Práticos

5.1 Verificar Status do Organismo

5.2 Health Check Completo

5.3 Dashboard Web

5.4 Workflow Completo: Monitoramento do Organismo

6. Arquitetura

6.1 Fluxo de Dados

6.2 Circuit Breaker

7. Configuração

7.1 Variáveis de Ambiente

8. Troubleshooting

Erro: "Not Found"

Erro: "Service Unavailable"

Dados parciais no status

Timeout

9. Documentação Relacionada

9.1 4C Decision API

9.2 CSuite Executive

10. Próximos Passos

11. Documentação OpenAPI

🔊 Text-to-Speech

Guia de Uso - APIs `/csuite-customer-decisions`