# ÁQUILA AI CORE - Documentação da API

O módulo **ÁQUILA AI CORE** é o cérebro de automação e inteligência artificial do ÁQUILA Control Center. Ele gerencia conversas via WhatsApp, detecta intenções, responde a dúvidas comuns usando uma base de conhecimento, executa automações baseadas em eventos e gerencia a transferência de conversas para operadores humanos.

Todas as rotas da API requerem autenticação via Bearer Token (exceto webhooks) e retornam respostas no formato JSON.

## URL Base
`https://api.seudominio.com/api/ai-core`

## Autenticação
Envie o token no cabeçalho da requisição:
`Authorization: Bearer SEU_TOKEN_AQUI`

---

## 1. Conversation Engine

O Conversation Engine é responsável por processar as mensagens recebidas e orquestrar a inteligência artificial.

### 1.1 Processar Mensagem
Processa uma mensagem recebida e retorna a resposta gerada pela IA.

**Endpoint:** `POST /conversations/process`

**Corpo da Requisição:**
```json
{
  "phone": "5511999999999",
  "message": "Quero renovar meu plano",
  "metadata": {
    "client_id": 1234,
    "content_type": "text"
  }
}
```

**Resposta (200 OK):**
```json
{
  "session_id": 45,
  "response": "Entendi! Vamos renovar seu plano atual. Vou gerar o PIX para renovação. Aguarde um momento...",
  "intent": "renew",
  "confidence": 0.95,
  "actions": ["renewal_flow_started", "pix_generation_requested"],
  "escalated": false
}
```

### 1.2 Consultar Histórico da Sessão
Retorna todas as mensagens trocadas em uma sessão específica.

**Endpoint:** `GET /conversations/sessions/{id}`

### 1.3 Encerrar Sessão
Encerra uma sessão ativa.

**Endpoint:** `POST /conversations/sessions/{id}/close`

**Corpo da Requisição:**
```json
{
  "summary": "Cliente renovou o plano com sucesso via PIX."
}
```

### 1.4 Consultar Contexto do Cliente
Retorna o contexto atual de um cliente (plano, plataforma, vencimento).

**Endpoint:** `GET /conversations/context/{phone}`

---

## 2. Intent Engine

O Intent Engine detecta a intenção do cliente com base na mensagem enviada.

### 2.1 Detectar Intenção
Testa a detecção de intenção para uma mensagem específica.

**Endpoint:** `POST /intents/detect`

**Corpo da Requisição:**
```json
{
  "message": "Meu aplicativo não está abrindo os canais"
}
```

**Resposta (200 OK):**
```json
{
  "intent": "support",
  "confidence": 0.85,
  "all_matches": [
    {
      "intent": "support",
      "name": "Suporte",
      "confidence": 0.85,
      "priority": 7
    }
  ]
}
```

### 2.2 Listar Intenções
Retorna todas as intenções cadastradas.

**Endpoint:** `GET /intents`

### 2.3 Criar Intenção
Cadastra uma nova intenção no sistema.

**Endpoint:** `POST /intents`

**Corpo da Requisição:**
```json
{
  "slug": "tutorial",
  "name": "Tutorial",
  "keywords": ["como usar", "tutorial", "passo a passo", "guia"],
  "priority": 5,
  "is_active": true
}
```

---

## 3. Knowledge Base (Base de Conhecimento)

A Base de Conhecimento fornece respostas automáticas para dúvidas comuns.

### 3.1 Buscar Artigos
Busca respostas na base de conhecimento.

**Endpoint:** `GET /knowledge?q=configurar dns&platform=samsung`

**Resposta (200 OK):**
```json
{
  "data": [
    {
      "id": 12,
      "category": "config",
      "title": "Configurar DNS na Samsung",
      "question": "Como configuro o DNS na minha TV Samsung?",
      "answer": "Para configurar o DNS na TV Samsung: 1. Vá em Configurações > Rede. 2. Status da Rede > Config. IP. 3. Mude Config. DNS para 'Digitar Manualmente'. 4. Insira o DNS fornecido.",
      "platform": "samsung"
    }
  ]
}
```

### 3.2 Listar Categorias
**Endpoint:** `GET /knowledge/categories`

### 3.3 Marcar como Útil
Registra que um artigo ajudou a resolver o problema do cliente.

**Endpoint:** `POST /knowledge/{id}/helpful`

---

## 4. Automation Engine

O Automation Engine executa ações automáticas baseadas em eventos (ex: vencimento de plano).

### 4.1 Disparar Evento
Dispara um evento manualmente para testar ou forçar a execução de regras.

**Endpoint:** `POST /automations/trigger`

**Corpo da Requisição:**
```json
{
  "event": "client_expired",
  "context": {
    "client_id": 1234,
    "phone": "5511999999999",
    "plan_name": "Premium Anual"
  }
}
```

### 4.2 Listar Regras
**Endpoint:** `GET /automations`

### 4.3 Criar Regra
**Endpoint:** `POST /automations`

**Corpo da Requisição:**
```json
{
  "name": "Mensagem de Vencimento",
  "trigger_event": "client_expiring",
  "conditions": {
    "days_left": 3
  },
  "actions": {
    "type": "send_message",
    "template": "expiring_warning"
  },
  "priority": 10,
  "is_active": true
}
```

---

## 5. WhatsApp Connector

O WhatsApp Connector gerencia a comunicação com os provedores de WhatsApp.

### 5.1 Webhook de Recebimento (Público)
Recebe mensagens do provedor de WhatsApp (Evolution API, Z-API, etc). Não requer token.

**Endpoint:** `POST /whatsapp/webhook`

### 5.2 Status da Conexão
Verifica se o WhatsApp está conectado.

**Endpoint:** `GET /whatsapp/status`

### 5.3 Enviar Mensagem Manual
Envia uma mensagem via API.

**Endpoint:** `POST /whatsapp/send`

**Corpo da Requisição:**
```json
{
  "phone": "5511999999999",
  "message": "Sua fatura está disponível."
}
```

---

## 6. Human Handoff (Tickets)

Gerencia a transferência de conversas da IA para operadores humanos.

### 6.1 Listar Tickets Abertos
**Endpoint:** `GET /tickets`

### 6.2 Atribuir Ticket
Atribui um ticket a um operador específico.

**Endpoint:** `POST /tickets/{id}/assign`

**Corpo da Requisição:**
```json
{
  "operator_id": 5
}
```

### 6.3 Resolver Ticket
Marca um ticket como resolvido e fecha a sessão.

**Endpoint:** `POST /tickets/{id}/resolve`

**Corpo da Requisição:**
```json
{
  "resolution": "Cliente configurou o DNS corretamente e o serviço voltou a funcionar."
}
```

---

## 7. Dashboard AI

Fornece métricas e estatísticas de uso da inteligência artificial.

### 7.1 Widgets de Hoje
Retorna os dados em tempo real para o painel de controle.

**Endpoint:** `GET /dashboard/today`

**Resposta (200 OK):**
```json
{
  "data": {
    "conversations_today": {
      "label": "Conversas Hoje",
      "value": 145,
      "icon": "chat",
      "color": "primary"
    },
    "auto_renewals": {
      "label": "Renovações Automáticas",
      "value": 32,
      "icon": "refresh",
      "color": "success"
    },
    "tickets_open": {
      "label": "Tickets Abertos",
      "value": 5,
      "icon": "ticket",
      "color": "danger"
    }
  }
}
```

### 7.2 Métricas Agregadas
Retorna totais de um período, incluindo taxas de resolução automática.

**Endpoint:** `GET /dashboard/aggregated?start_date=2026-07-01&end_date=2026-07-10`

---

## 8. StreamCore Connector

Gerencia a comunicação com a API oficial do painel de IPTV (StreamCore).

### 8.1 Status da Conexão
**Endpoint:** `GET /streamcore/health`

### 8.2 Criar Linha de Teste
Cria um teste temporário no painel IPTV.

**Endpoint:** `POST /streamcore/lines/trial`

**Corpo da Requisição:**
```json
{
  "duration_hours": 24,
  "notes": "Teste solicitado via WhatsApp"
}
```

### 8.3 Renovar Linha
**Endpoint:** `PUT /streamcore/lines/{lineId}/renew`

**Corpo da Requisição:**
```json
{
  "plan_id": 3
}
```