ligbox-ops-platform/specs/041-desk-operational-feed/contracts/ops-inbox-api.md

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:

{
  "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:

{
  "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:

{
  "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:

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

note_type: reply | internal_note

Response 200:

{
  "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):

{
  "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