Guia de Uso - APIs `/context` (Context API)

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

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

📋 Índice

Visão Geral
Overview API
Radar API
Risk API
Opportunities API
Channel API
Alerts API
Context API
Signals API (Events, Trends, Shifts)
Jobs API
Exemplos Práticos
Troubleshooting

1. Visão Geral

O CSuite Context API fornece acesso a contexto temporal, incluindo:

Eventos de curto prazo: Sinais imediatos detectados
Tendências de médio prazo: Padrões de crescimento/declínio
Mudanças estruturais (Shifts): Alterações no terreno de negócio
Radar de oportunidades e riscos: Visão consolidada
Alertas críticos: Notificações de alto impacto

Características:
- ✅ API assíncrona (FastAPI + SQLAlchemy async)
- ✅ Paginação automática
- ✅ Filtros avançados (data, nível, tipo, busca)
- ✅ Integração com Policy Engine (jobs)
- ✅ Fallback para views alternativas

2. Overview API

Endpoint: GET /api/csuite/overview

Descrição: Retorna visão geral do contexto da organização.

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/overview?org_id=1"

Resposta:

{
  "data": {
    "org_id": 1,
    "org_name": "Minha Empresa",
    "total_context_items": 1250,
    "sensitive_items": 45
  }
}

Campos:
- org_id: ID da organização
- org_name: Nome da organização
- total_context_items: Total de itens de contexto
- sensitive_items: Itens sensíveis/críticos

Casos de uso:
- Dashboard inicial
- Métricas gerais de contexto
- Indicadores de sensibilidade

3. Radar API

Endpoint: GET /api/csuite/radar

Descrição: Retorna radar de sinais dos últimos 7 dias.

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/radar?org_id=1"

Resposta:

{
  "items": [
    {
      "id": 123,
      "org_id": 1,
      "source": "external",
      "title": "Novo concorrente no mercado",
      "signal_date": "2024-12-01T10:00:00Z",
      "level": "medium",
      "type": "competitive_threat"
    },
    {
      "id": 124,
      "org_id": 1,
      "source": "internal",
      "title": "Aumento de churn em 15%",
      "signal_date": "2024-12-02T14:30:00Z",
      "level": "high",
      "type": "churn_alert"
    }
  ]
}

Campos:
- id: ID do sinal
- org_id: ID da organização
- source: Origem do sinal (external, internal)
- title: Título do sinal
- signal_date: Data do sinal
- level: Nível (low, medium, high, critical)
- type: Tipo do sinal

Casos de uso:
- Painel de monitoramento
- Alertas visuais
- Dashboard executivo

4. Risk API

Endpoint: GET /api/csuite/risk

Descrição: Retorna painel de riscos da organização.

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/risk?org_id=1"

Resposta:

{
  "items": [
    {
      "org_id": 1,
      "low_count": 25,
      "medium_count": 10,
      "high_count": 5,
      "critical_count": 2
    }
  ]
}

Campos:
- org_id: ID da organização
- low_count: Número de riscos baixos
- medium_count: Número de riscos médios
- high_count: Número de riscos altos
- critical_count: Número de riscos críticos

Casos de uso:
- Análise de risco consolidada
- Dashboard de governança
- Alertas de segurança

5. Opportunities API

Endpoint: GET /api/csuite/opportunities

Descrição: Retorna painel de oportunidades da organização.

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/opportunities?org_id=1"

Resposta:

{
  "items": [
    {
      "id": 201,
      "org_id": 1,
      "title": "Expansão para novo mercado",
      "sensitivity_level": "high",
      "created_at": "2024-12-01T10:00:00Z",
      "type": "market_expansion"
    },
    {
      "id": 202,
      "org_id": 1,
      "title": "Parceria estratégica",
      "sensitivity_level": "medium",
      "created_at": "2024-12-02T14:30:00Z",
      "type": "partnership"
    }
  ]
}

Campos:
- id: ID da oportunidade
- org_id: ID da organização
- title: Título da oportunidade
- sensitivity_level: Nível de sensibilidade (low, medium, high, critical)
- created_at: Data de criação
- type: Tipo de oportunidade

Casos de uso:
- Identificação de oportunidades
- Planejamento estratégico
- Dashboard comercial

6. Channel API

Endpoint: GET /api/csuite/channel

Descrição: Retorna painel de canais (distribuição por canal de origem).

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/channel?org_id=1"

Resposta:

{
  "items": [
    {
      "org_id": 1,
      "source_channel": "whatsapp",
      "items_count": 450
    },
    {
      "org_id": 1,
      "source_channel": "email",
      "items_count": 320
    },
    {
      "org_id": 1,
      "source_channel": "crm",
      "items_count": 280
    }
  ]
}

Campos:
- org_id: ID da organização
- source_channel: Canal de origem
- items_count: Número de itens por canal

Casos de uso:
- Análise de canais
- Distribuição de origem
- Otimização de comunicação

7. Alerts API

Endpoint: GET /api/csuite/alerts/critical

Descrição: Retorna alertas críticos das últimas 24 horas.

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/alerts/critical?org_id=1"

Resposta:

{
  "items": [
    {
      "assessment_id": 301,
      "org_id": 1,
      "context_item_id": 501,
      "risk_level": "critical",
      "sensitivity_level": "critical",
      "created_at": "2024-12-01T15:00:00Z",
      "message": "Vazamento de dados detectado",
      "action_required": true
    }
  ]
}

Campos:
- assessment_id: ID da avaliação de risco
- org_id: ID da organização
- context_item_id: ID do item de contexto
- risk_level: Nível de risco (critical)
- sensitivity_level: Nível de sensibilidade
- created_at: Data de criação
- message: Mensagem do alerta
- action_required: Se ação é necessária

Casos de uso:
- Notificações críticas
- Monitoramento de segurança
- Alertas de compliance

8. Context API

Endpoint: GET /api/csuite/context/{context_id}

Descrição: Obtém detalhes de um contexto específico.

Parâmetros de Path:
- context_id (int, obrigatório) - ID do contexto

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

Exemplo:

curl "https://csuite.internut.com.br/context/api/csuite/context/501?org_id=1"

Resposta:

{
  "data": {
    "id": 501,
    "org_id": 1,
    "title": "Contexto de venda",
    "description": "Detalhes do contexto...",
    "sensitivity_level": "high",
    "created_at": "2024-12-01T10:00:00Z"
  }
}

Casos de uso:
- Detalhamento de contexto
- Análise profunda
- Auditoria

9. Signals API

Base Path: /api/csuite

9.1 Eventos

Endpoint: GET /api/csuite/events

Descrição: Lista eventos de curto prazo (signal_type = 'event').

Parâmetros de Query:
- org_id (int, obrigatório) - ID da organização
- limit (int, padrão: 50, min: 1, max: 500) - Limite de resultados
- offset (int, padrão: 0, min: 0) - Número de resultados para pular
- level (string, opcional) - Filtrar por nível (low, medium, high)
- start_date (string, opcional) - Data inicial (YYYY-MM-DD)
- end_date (string, opcional) - Data final (YYYY-MM-DD)
- search (string, opcional) - Buscar no campo message
- order_by (string, padrão: created_at) - Campo para ordenação
- order_dir (string, padrão: desc) - Direção (asc, desc)

Exemplo:

# Eventos recentes
curl "https://csuite.internut.com.br/context/api/csuite/events?org_id=1&limit=20"

# Eventos de alto nível
curl "https://csuite.internut.com.br/context/api/csuite/events?org_id=1&level=high"

# Eventos em período específico
curl "https://csuite.internut.com.br/context/api/csuite/events?org_id=1&start_date=2024-12-01&end_date=2024-12-31"

# Buscar eventos
curl "https://csuite.internut.com.br/context/api/csuite/events?org_id=1&search=vazamento"

Resposta:

{
  "data": [
    {
      "id": 1001,
      "org_id": 1,
      "signal_type": "event",
      "level": "high",
      "message": "Aumento de 30% em vendas",
      "created_at": "2024-12-01T10:00:00Z",
      "context_type": "sales"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

9.2 Tendências

Endpoint: GET /api/csuite/trends

Descrição: Lista tendências de médio prazo (signal_type = 'trend').

Parâmetros de Query:
- org_id (int, obrigatório) - ID da organização
- limit (int, padrão: 50, min: 1, max: 500) - Limite de resultados
- offset (int, padrão: 0, min: 0) - Número de resultados para pular
- level (string, opcional) - Filtrar por nível (low, medium, high)
- context_type (string, opcional) - Filtrar por tipo de contexto
- start_date (string, opcional) - Data inicial (YYYY-MM-DD)
- end_date (string, opcional) - Data final (YYYY-MM-DD)
- search (string, opcional) - Buscar no campo message
- order_by (string, padrão: created_at) - Campo para ordenação
- order_dir (string, padrão: desc) - Direção (asc, desc)

Exemplo:

# Tendências recentes
curl "https://csuite.internut.com.br/context/api/csuite/trends?org_id=1"

# Tendências de crescimento
curl "https://csuite.internut.com.br/context/api/csuite/trends?org_id=1&context_type=growth"

# Tendências de alto nível
curl "https://csuite.internut.com.br/context/api/csuite/trends?org_id=1&level=high"

Resposta:

{
  "data": [
    {
      "id": 2001,
      "org_id": 1,
      "signal_type": "trend",
      "level": "medium",
      "message": "Crescimento sustentado de 15% ao mês",
      "created_at": "2024-12-01T10:00:00Z",
      "context_type": "growth",
      "trend_direction": "up"
    }
  ],
  "pagination": {
    "total": 75,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

9.3 Mudanças Estruturais (Shifts)

Endpoint: GET /api/csuite/shifts

Descrição: Lista mudanças estruturais de terreno (context shifts).

Parâmetros de Query:
- org_id (int, obrigatório) - ID da organização
- limit (int, padrão: 50, min: 1, max: 500) - Limite de resultados
- offset (int, padrão: 0, min: 0) - Número de resultados para pular
- shift_direction (string, opcional) - Filtrar por direção (up, down)
- min_shift_value (float, opcional) - Valor mínimo de shift
- max_shift_value (float, opcional) - Valor máximo de shift
- start_date (string, opcional) - Data inicial (YYYY-MM-DD)
- end_date (string, opcional) - Data final (YYYY-MM-DD)
- search (string, opcional) - Buscar no campo description
- order_by (string, padrão: created_at) - Campo para ordenação
- order_dir (string, padrão: desc) - Direção (asc, desc)

Exemplo:

# Shifts recentes
curl "https://csuite.internut.com.br/context/api/csuite/shifts?org_id=1"

# Shifts positivos
curl "https://csuite.internut.com.br/context/api/csuite/shifts?org_id=1&shift_direction=up"

# Shifts com valor mínimo
curl "https://csuite.internut.com.br/context/api/csuite/shifts?org_id=1&min_shift_value=10.0"

Resposta:

{
  "data": [
    {
      "id": 3001,
      "org_id": 1,
      "shift_direction": "up",
      "shift_value": 25.5,
      "description": "Mudança estrutural no mercado",
      "created_at": "2024-12-01T10:00:00Z",
      "impact_level": "high"
    }
  ],
  "pagination": {
    "total": 30,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

10. Jobs API

Base Path: /api/jobs

10.1 Detectar Tendências

Endpoint: POST /api/jobs/trends/detect

Descrição: Executa o job de detecção de tendências (requer autorização do Policy Engine).

Parâmetros de Query:
- background (bool, padrão: false) - Se true, executa em background

Exemplo:

# Execução síncrona
curl -X POST "https://csuite.internut.com.br/context/api/jobs/trends/detect"

# Execução em background
curl -X POST "https://csuite.internut.com.br/context/api/jobs/trends/detect?background=true"

Resposta (Síncrona):

{
  "status": "completed",
  "result": {
    "trends_detected": 5,
    "processing_time_ms": 1250
  }
}

Resposta (Background):

{
  "status": "scheduled",
  "message": "Job de detecção de tendências agendado para execução em background"
}

Nota: Este endpoint requer autorização do Policy Engine. Se não autorizado, retorna 409 Conflict.

10.2 Status de Tendências

Endpoint: GET /api/jobs/trends/status

Descrição: Retorna status do job de detecção de tendências.

Exemplo:

curl "https://csuite.internut.com.br/context/api/jobs/trends/status"

Resposta:

{
  "job": "trends_detection",
  "status": "available",
  "description": "Job de detecção de tendências de crescimento"
}

10.3 Detectar Context Shift

Endpoint: POST /api/jobs/context-shift/detect

Descrição: Executa o job de detecção de mudanças estruturais de contexto (requer autorização do Policy Engine).

Parâmetros de Query:
- org_id (int, opcional) - ID da organização (se não fornecido, processa todas)
- background (bool, padrão: false) - Se true, executa em background

Exemplo:

# Execução síncrona para uma organização
curl -X POST "https://csuite.internut.com.br/context/api/jobs/context-shift/detect?org_id=1"

# Execução em background para todas
curl -X POST "https://csuite.internut.com.br/context/api/jobs/context-shift/detect?background=true"

Resposta (Síncrona):

{
  "status": "completed",
  "result": {
    "drift_detectado": true,
    "shifts_detected": 2,
    "processing_time_ms": 2100
  }
}

Nota: Este endpoint requer autorização do Policy Engine. Se não autorizado, retorna 409 Conflict.

10.4 Status de Context Shift

Endpoint: GET /api/jobs/context-shift/status

Descrição: Retorna status do job de detecção de context shift.

Exemplo:

curl "https://csuite.internut.com.br/context/api/jobs/context-shift/status"

Resposta:

{
  "job": "context_shift_detection",
  "status": "available",
  "description": "Job de detecção de mudanças estruturais de contexto",
  "frequency": "1 vez por dia"
}

10.5 Status Geral dos Jobs

Endpoint: GET /api/jobs/status

Descrição: Retorna status geral de todos os jobs, incluindo informações dos logs.

Exemplo:

curl "https://csuite.internut.com.br/context/api/jobs/status"

Resposta:

{
  "overall_status": "ok",
  "timestamp": "2024-12-01T10:00:00Z",
  "jobs": {
    "trends_detection": {
      "name": "Trends Detection",
      "log_exists": true,
      "last_modified": "2024-12-01T09:00:00Z",
      "errors_recent": 0,
      "status": "ok"
    },
    "context_shift_detection": {
      "name": "Context Shift Detection",
      "log_exists": true,
      "last_modified": "2024-12-01T08:00:00Z",
      "errors_recent": 0,
      "status": "ok"
    }
  }
}

Status possíveis:
- ok: Job executado recentemente (≤ 2h para trends, ≤ 25h para shifts)
- warning: Job executado há mais tempo (≤ 6h para trends, ≤ 48h para shifts)
- stale: Job não executado há muito tempo
- missing: Log não encontrado
- error: Erros recentes detectados

11. Exemplos Práticos

11.1 Dashboard Completo

# 1. Visão geral
curl "https://csuite.internut.com.br/context/api/csuite/overview?org_id=1"

# 2. Radar de sinais
curl "https://csuite.internut.com.br/context/api/csuite/radar?org_id=1"

# 3. Riscos
curl "https://csuite.internut.com.br/context/api/csuite/risk?org_id=1"

# 4. Oportunidades
curl "https://csuite.internut.com.br/context/api/csuite/opportunities?org_id=1"

# 5. Alertas críticos
curl "https://csuite.internut.com.br/context/api/csuite/alerts/critical?org_id=1"

11.2 Análise Temporal

# 1. Eventos dos últimos 7 dias
curl "https://csuite.internut.com.br/context/api/csuite/events?org_id=1&start_date=2024-11-24&end_date=2024-12-01&limit=100"

# 2. Tendências de crescimento
curl "https://csuite.internut.com.br/context/api/csuite/trends?org_id=1&context_type=growth&level=high"

# 3. Mudanças estruturais positivas
curl "https://csuite.internut.com.br/context/api/csuite/shifts?org_id=1&shift_direction=up&min_shift_value=10.0"

11.3 Execução de Jobs

# 1. Detectar tendências (background)
curl -X POST "https://csuite.internut.com.br/context/api/jobs/trends/detect?background=true"

# 2. Detectar context shift para uma organização
curl -X POST "https://csuite.internut.com.br/context/api/jobs/context-shift/detect?org_id=1"

# 3. Verificar status dos jobs
curl "https://csuite.internut.com.br/context/api/jobs/status"

12. Troubleshooting

Erro: "Not Found" (404)

Verifique se o serviço csuite-context está rodando
Verifique se o path está correto (/context/api/csuite ou /context/api/jobs)
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: "Conflict" (409) em `/jobs/*`

Policy Engine não autorizou a operação
Verifique reasons e notify na resposta
Verifique permissões do usuário

Erro: "Internal Server Error" (500)

Verifique logs do serviço
Verifique conexão com banco de dados
Verifique se as views existem no banco

Dados vazios

Verifique se existem dados no banco para a organização
Verifique se os jobs foram executados
Verifique se as views estão populadas

Paginação não funciona

Verifique se limit e offset estão corretos
Verifique se has_more indica mais resultados
Use offset para próxima página: offset = offset + limit

13. Documentação Relacionada

13.1 Documentação OpenAPI

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

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

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

13.2 Views SQL

As seguintes views são utilizadas pelos endpoints:

csuite.vw_org_context_overview - Overview
csuite.vw_radar_panel_7d - Radar
csuite.vw_context_risk_panel - Risk
csuite.vw_context_opportunity_panel - Opportunities
csuite.vw_channel_panel - Channel
context_risk.vw_critical_alerts_24h - Critical Alerts
context_radar.context_signals - Events/Trends
context_risk.context_shifts - Shifts

14. Próximos Passos

Adicionar webhooks para notificações de eventos críticos
Adicionar exportação CSV/Excel dos sinais
Adicionar cache para queries frequentes
Adicionar métricas de performance (tempo de resposta)
Adicionar filtros avançados (agregação, agrupamento)

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

Guia Uso Apis Context

Guia de Uso - APIs `/context` (Context API)

📋 Índice

1. Visão Geral

2. Overview API

3. Radar API

4. Risk API

5. Opportunities API

6. Channel API

7. Alerts API

8. Context API

9. Signals API

9.1 Eventos

9.2 Tendências

9.3 Mudanças Estruturais (Shifts)

10. Jobs API

10.1 Detectar Tendências

10.2 Status de Tendências

10.3 Detectar Context Shift

10.4 Status de Context Shift

10.5 Status Geral dos Jobs

11. Exemplos Práticos

11.1 Dashboard Completo

11.2 Análise Temporal

11.3 Execução de Jobs

12. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Conflict" (409) em `/jobs/*`

Erro: "Internal Server Error" (500)

Dados vazios

Paginação não funciona

13. Documentação Relacionada

13.1 Documentação OpenAPI

13.2 Views SQL

14. Próximos Passos

🔊 Text-to-Speech

Guia de Uso - APIs /context (Context API)

📋 Índice

1. Visão Geral

2. Overview API

3. Radar API

4. Risk API

5. Opportunities API

6. Channel API

7. Alerts API

8. Context API

9. Signals API

9.1 Eventos

9.2 Tendências

9.3 Mudanças Estruturais (Shifts)

10. Jobs API

10.1 Detectar Tendências

10.2 Status de Tendências

10.3 Detectar Context Shift

10.4 Status de Context Shift

10.5 Status Geral dos Jobs

11. Exemplos Práticos

11.1 Dashboard Completo

11.2 Análise Temporal

11.3 Execução de Jobs

12. Troubleshooting

Erro: "Not Found" (404)

Erro: "Unauthorized" (401)

Erro: "Conflict" (409) em /jobs/*

Erro: "Internal Server Error" (500)

Dados vazios

Paginação não funciona

13. Documentação Relacionada

13.1 Documentação OpenAPI

13.2 Views SQL

14. Próximos Passos

🔊 Text-to-Speech

Guia de Uso - APIs `/context` (Context API)

Erro: "Conflict" (409) em `/jobs/*`