# B2BCall — Referência da API

Base URL (via Nginx): `http://<host>/api`
Documentação interativa (Swagger, quando `SWAGGER_ENABLED=true`): `http://<host>/api/docs`

## Autenticação

Todas as rotas exigem um `access_token` válido (cookie HttpOnly, definido pelo
login) **exceto** as marcadas `@Public()`:
`/api/auth/login`, `/api/auth/refresh`, `/api/auth/forgot-password`,
`/api/auth/reset-password`, `/api/health`, `/api/health/live`,
`/api/health/ready`, `GET /api`.

Cada rota protegida também é validada contra o RBAC do usuário
(`@RequirePermissions(...)`) — ver `packages/shared/src/permissions.ts` para
o catálogo completo de chaves de permissão.

## Mapa de rotas

| Módulo | Rotas |
|---|---|
| `auth` | `POST /auth/login`, `/refresh`, `/logout`, `/change-password`, `/forgot-password`, `/reset-password`, `GET /auth/me` |
| `users` | `GET /users`, `GET /users/:id`, `POST /users`, `PATCH /users/:id` |
| `roles` | `GET /roles/permissions` (catálogo), `GET/POST/PATCH/DELETE /roles` |
| `audit` | `GET /audit` (filtros: userId, action, entityType, from, to, paginação) |
| `trunks` | `GET/POST/PATCH/DELETE /trunks`, `GET /trunks/:id/status` |
| `extensions` | `GET/POST/PATCH/DELETE /extensions`, `POST /extensions/:id/reset-password` |
| `dialplans` | `GET/POST/PATCH/DELETE /dialplans`, `GET /dialplans/versions`, `POST /dialplans/publish`, `POST /dialplans/versions/:id/rollback` |
| `asterisk-admin` | `GET /asterisk/status`, `GET /asterisk/modules`, `GET /asterisk/diagnostic/allowed-commands`, `POST /asterisk/diagnostic`, `POST /asterisk/reload` |
| `queues` | `GET/POST/PATCH/DELETE /queues`, `POST /queues/:id/members`, `DELETE /queues/:id/members/:agentId` |
| `agents` | `GET/POST/PATCH/DELETE /agents` |
| `agent-console` | `GET /agent-console/me`, `POST /login`, `/available`, `/pause`, `/unpause`, `/logout`, `/dispose` |
| `pause-reasons` | `GET/POST/PATCH/DELETE /pause-reasons` |
| `dispositions` | `GET/POST/PATCH/DELETE /dispositions` |
| `callbacks` | `GET /callbacks?campaignId=` (somente leitura — agendamento via `agent-console/dispose`) |
| `campaigns` | `GET/POST/PATCH/DELETE /campaigns`, `POST /:id/start`, `/pause`, `/stop`, `/drain` |
| leads (sob campanhas) | `GET /campaigns/:campaignId/leads`, `GET .../imports`, `GET .../imports/:importId/rejected.csv`, `POST .../import` |
| `suppression` | `GET/POST /suppression`, `POST /suppression/import`, `DELETE /suppression/:id` |
| `reports` | `GET /reports/calls`, `/calls/export` (CSV), `/metrics`, `/agents/:agentId` |
| `dashboard` | `GET /dashboard`, `/calls-by-hour`, `/campaigns/:id` |
| `compliance` | `GET/PATCH /compliance/settings`, `GET /compliance/indicators` |
| `monitoring` | `GET /monitoring/extensions`, `/queues`, `/agents` |
| `metrics` | `GET /metrics` (Prometheus, texto plano) |
| `health` | `GET /health`, `/health/live`, `/health/ready` |

## Convenções

- Paginação server-side em endpoints que retornam listas potencialmente
  grandes (`audit`, `reports/calls`, `suppression`): `page`, `pageSize`,
  resposta com `{ items, total, page, pageSize }`.
- Erros nunca vazam detalhes internos: toda resposta de erro inclui
  `requestId` para correlação com o log estruturado do servidor.
- Datas em ISO 8601 UTC; conversão de timezone de campanha
  (`America/Sao_Paulo` por padrão) acontece no backend, nunca no cliente.
- Segredos (senha de ramal, senha de tronco) nunca retornam em `GET`/`PATCH`
  — só no `POST` de criação (senha de ramal) ou nunca em texto puro (senha
  de tronco, sempre `secretEncrypted` omitido da resposta).

## Exemplos rápidos

```bash
# Login
curl -c cookies.txt -X POST http://<host>/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@b2bcall.local","password":"..."}'

# Listar troncos (autenticado)
curl -b cookies.txt http://<host>/api/trunks

# Métricas Prometheus
curl -b cookies.txt http://<host>/api/metrics
```