# Contrato API — Operational Feed (Spec 041)

**Base URL:** `https://desk.ligbox.com.br/api/v1/ops-inbox`  
**Auth:** `Authorization: Bearer {jwt}`  
**Permissão (fase A):** `can_manage_users`  
**Implementação:** `OF-API-002` · `api/app/ops_inbox_routes.py`  
**Store:** `OF-API-001` · `api/app/ops_inbox_store.py`

---

## OF-EP-001 — GET /stats

KPIs e contadores por canal.

**Response 200:**

```json
{
  "events_today": 6,
  "pending": 6,
  "critical": 1,
  "awaiting_you": 5,
  "sla_avg_pct": 96,
  "channels": [
    { "id": "all", "label": "Todos os canais", "count": 6 },
    { "id": "whatsapp", "label": "WhatsApp API", "count": 1 },
    { "id": "email", "label": "Email", "count": 1 }
  ]
}
```

---

## OF-EP-002 — GET /events

**Query parameters:**

| Param | Tipo | Default | Descrição |
|-------|------|---------|-----------|
| channel | string | `all` | Filtrar canal |
| priority | string | — | `normal`, `high`, `critical` |
| status | string | — | `open`, `pending`, `resolved` |
| q | string | — | Busca title/preview/contact |
| limit | int | 128 | Max 500 |

**Response 200:**

```json
{
  "events": [
    {
      "id": "evt-wa-001",
      "channel": "whatsapp",
      "event_type": "message",
      "priority": "high",
      "title": "Cliente: Empresa Alpha — …",
      "preview": "Bom dia, após o login…",
      "tags": ["Cliente", "Acesso"],
      "assignee": "Editor",
      "status": "open",
      "contact_name": "Empresa Alpha",
      "contact_company": "Empresa Alpha Ltda",
      "contact_cnpj": "12.345.678/0001-90",
      "contact_client_id": "CLI-8842",
      "sla_minutes": 15,
      "sla_remaining_sec": 750,
      "created_at": "2026-06-29T…"
    }
  ],
  "total": 1
}
```

---

## OF-EP-003 — GET /events/{event_id}

**Response 200:**

```json
{
  "event": {
    "id": "evt-wa-001",
    "channel": "whatsapp",
    "messages": [
      {
        "id": 1,
        "author_type": "user",
        "author_label": "Empresa Alpha",
        "body": "Bom dia, não consigo acessar…",
        "created_at": "…"
      }
    ]
  }
}
```

**404:** event not found

---

## OF-EP-004 — POST /events/{event_id}/messages

**Request:**

```json
{
  "body": "Texto da resposta ou nota",
  "note_type": "reply"
}
```

`note_type`: `reply` | `internal_note`

**Response 200:**

```json
{
  "message": {
    "id": 4,
    "event_id": "evt-wa-001",
    "author_type": "operator",
    "author_label": "Roger",
    "body": "…",
    "created_at": "…"
  }
}
```

---

## OF-EP-005 — PATCH /events/{event_id}

**Request (campos opcionais):**

```json
{
  "status": "resolved",
  "assignee": "NOC",
  "priority": "high"
}
```

**Response 200:** `{ "event": { … } }`

---

## Códigos de erro

| HTTP | Condição |
|------|----------|
| 401 | Token inválido |
| 403 | Sem permissão |
| 404 | Evento não encontrado |

---

## Webhooks (fase B — não implementados)

| Código planeado | Método | Path |
|-----------------|--------|------|
| OF-EP-101 | POST | `/api/v1/ops-inbox/webhooks/email` |
| OF-EP-102 | POST | `/api/v1/ops-inbox/webhooks/whatsapp` |
| OF-EP-103 | POST | `/api/v1/ops-inbox/webhooks/telegram` |