b03bb2c37c
Commita governance, user-wizard, operational-feed e catálogo RBAC; adiciona deploy-desk-full.sh, smoke-desk.sh e regra anti-deploy parcial; documenta credencial VM112 @betinplace. Co-authored-by: Cursor <cursoragent@cursor.com>
164 lines
3.1 KiB
Markdown
164 lines
3.1 KiB
Markdown
# 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` |
|