# API Contract — Chamados & Discover (019)

**Base URL:** `https://api.ops.ligbox.com.br`  
**Auth:** `Authorization: Bearer <jwt>` (Spec 003)  
**Versão:** `v1` (draft)

---

## Chamados

### `GET /api/v1/chamados`

Lista chamados com filtros.

**Query:**

| Param | Tipo | Descrição |
|-------|------|-----------|
| `status` | string | `novo`, `assumido`, `em_correcao`, … |
| `domain` | string | Filtro domínio |
| `assignee` | string | Login ops |
| `source` | string | `wazuh`, `onboard`, `support`, `audit` |
| `limit` | int | default 50, max 200 |
| `offset` | int | paginação |

**Response 200:**

```json
{
  "chamados": [
    {
      "public_id": "CH-2026-00042",
      "status": "em_correcao",
      "domain": "myvexx.com",
      "session_id": "sess_abc123",
      "wizard_step": "dns_cloudflare",
      "wizard_step_label": "DNS Cloudflare",
      "sources": ["onboard", "wazuh"],
      "max_severity": 12,
      "assignee": "ops_lead",
      "title": "[wazuh L12] vm112 — brute force",
      "created_at": "2026-06-16T10:00:00Z",
      "updated_at": "2026-06-16T10:15:00Z",
      "event_count": 5
    }
  ],
  "total": 1
}
```

---

### `GET /api/v1/chamados/{public_id}`

Detalhe completo.

**Response 200:**

```json
{
  "public_id": "CH-2026-00042",
  "status": "assumido",
  "assignee": "ops_lead",
  "domain": "myvexx.com",
  "session_id": "sess_abc123",
  "wizard_step": "dns_cloudflare",
  "wizard_step_at": "2026-06-16T10:14:00Z",
  "assist": {
    "time_on_step_sec": 142,
    "last_error": null,
    "planned_email": "admin@myvexx.com"
  },
  "observables": [
    { "tipo": "domain", "valor": "myvexx.com", "fonte": "onboard" },
    { "tipo": "agent", "valor": "vm112-mail", "fonte": "wazuh" },
    { "tipo": "rule_id", "valor": "5712", "fonte": "wazuh" }
  ],
  "infra": {
    "score": "6/8",
    "status": "degraded",
    "checks": []
  },
  "links": {
    "wazuh_deep_link": "https://wazuh.itecnologys.com/app/wazuh?...",
    "wizard_admin": null
  },
  "timeline": [
    {
      "event_type": "wazuh.alert",
      "source": "wazuh",
      "created_at": "2026-06-16T10:00:00Z",
      "summary": "L12 ssh brute force",
      "severity": 12
    },
    {
      "event_type": "onboarding.failed",
      "source": "onboard",
      "created_at": "2026-06-16T10:05:00Z",
      "summary": "DNS apply timeout"
    }
  ],
  "acoes_pendentes": [
    {
      "runbook_code": "traefik_cert_sync",
      "nivel": "R1",
      "status": "pendente_aprovacao",
      "exec_id": 7
    }
  ],
  "legacy_ticket_id": 15
}
```

---

### `POST /api/v1/chamados/{public_id}/assumir`

**Body:** `{}` ou `{ "nota": "Assumido por NOC" }`

**Response 200:**

```json
{
  "public_id": "CH-2026-00042",
  "status": "assumido",
  "assignee": "ops_lead"
}
```

**Errors:** `409` se já assumido por outro (configurável override para `ops_lead` role).

---

### `POST /api/v1/chamados/{public_id}/eventos/anexar`

Anexa eventos Discover ao hub (investigação).

**Body:**

```json
{
  "webhook_event_ids": [901, 902]
}
```

**Response 200:**

```json
{
  "public_id": "CH-2026-00042",
  "attached": 2,
  "timeline_count": 7
}
```

---

### `POST /api/v1/chamados/{public_id}/notas`

Nota de investigação na timeline.

**Body:** `{ "texto": "Cliente confirmou DNS propagado" }`

---

### `GET /api/v1/chamados/{public_id}/links/wazuh`

Gera deep link para dashboard Wazuh VM104.

**Response 200:**

```json
{
  "url": "https://wazuh.itecnologys.com/...",
  "agent": "vm112-mail",
  "from": "2026-06-16T09:00:00Z",
  "to": "2026-06-16T11:00:00Z"
}
```

---

### `PATCH /api/v1/chamados/{public_id}`

**Body:**

```json
{
  "status": "em_correcao",
  "nota": "A corrigir cert admin"
}
```

---

### `POST /api/v1/chamados/{public_id}/runbooks/{code}/executar`

Enfileira runbook.

**Body:**

```json
{
  "params": { "domain": "myvexx.com" },
  "force_nivel": null
}
```

**Response 202:**

```json
{
  "exec_id": 7,
  "runbook_code": "traefik_cert_sync",
  "nivel": "R1",
  "status": "pendente_aprovacao"
}
```

---

## Discover

### `GET /api/v1/discover`

Feed unificado estilo Wazuh Discover.

**Query:** `source`, `domain`, `severity_min`, `from`, `to`, `q`, `limit`, `offset`

**Response 200:**

```json
{
  "events": [
    {
      "id": 901,
      "chamado_public_id": "CH-2026-00042",
      "source": "wazuh",
      "event_type": "wazuh.alert",
      "domain": "myvexx.com",
      "session_id": null,
      "severity": 12,
      "rule_id": "5712",
      "agent": "vm112-mail",
      "summary": "SSH brute force",
      "created_at": "2026-06-16T10:00:00Z"
    }
  ],
  "total": 901
}
```

---

## Aprovações

### `GET /api/v1/aprovacoes?status=pendente`

### `POST /api/v1/aprovacoes/{id}/aprovar`

**Body:** `{ "decisao": "aprovado", "nota": "OK executar" }`

### `POST /api/v1/aprovacoes/{id}/rejeitar`

**Body:** `{ "decisao": "rejeitado", "nota": "Risco alto" }`

---

## VM112 — Assist (LAN)

### `GET /api/onboarding/session/{session_id}/ops-status`

**Header:** `X-Ops-Secret: <shared secret>`  
**Caller:** VM122 worker ou API (nunca browser directo)

Ver [plan.md](../plan.md) Phase 5.

---

## WebSocket (Fase 6)

### `WS /api/v1/chamados/{public_id}/live`

**Auth:** query `?token=<jwt>` ou subprotocol

**Messages:**

```json
{ "type": "event", "event_type": "dns.applied", "created_at": "…" }
{ "type": "wizard_step", "step": "account_create", "time_on_step_sec": 30 }
```