> For the complete documentation index, see [llms.txt](https://digitalsac.gitbook.io/digicalls/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://digitalsac.gitbook.io/digicalls/api-rest/visao-geral.md).

# Visão geral

Documentação interativa: [**https://calls.digitalsac.io/docs/**](https://calls.digitalsac.io/docs/)

Especificação OpenAPI: `GET /api/openapi.yaml`

### Autenticação

| Tipo             | Header                              | Uso                       |
| ---------------- | ----------------------------------- | ------------------------- |
| **Sessão**       | `Authorization: Bearer <jwt_login>` | Painel web, operador      |
| **Device token** | `Authorization: Bearer dev_…`       | SDK, webphone, SSE        |
| **API key**      | `X-Api-Key: dgu_…`                  | Provisionamento Izing/ERP |

### Grupos de endpoints

#### Auth / Conta

* `POST /api/login`, `/logout`
* `GET /api/me`, `/api/me/apikey`
* `POST /api/password`, 2FA

#### Dispositivos (usuário logado)

* `GET/POST /api/sessions`
* Pareamento, chamadas, histórico, SIP config
* `GET/PUT /api/sessions/{sid}/settings` — comportamento por device (receber/gravar)

#### Chamadas

* `POST /api/sessions/{sid}/calls`
* `/accept`, `/reject`, `/webrtc`, `DELETE` (end)
* `GET /api/webrtc-config`

#### Oficial WABA

* `GET/POST/PUT/DELETE /api/official/devices`
* `POST /api/official/devices/{id}/call-permission`
* Webhook Meta (público)

#### Provisionamento (API key)

* `/api/devices/*`
* `/api/official/permission`
* `/api/recordings/{callId}`

#### Admin

* `/api/admin/users`, stats, limits

#### Eventos

* `GET /api/events` (SSE)

### Códigos comuns

| HTTP | Significado                            |
| ---- | -------------------------------------- |
| 401  | Não autenticado                        |
| 403  | Sem permissão / device de outro tenant |
| 404  | Não encontrado                         |
| 429  | Limite de chamadas                     |
| 503  | WhatsApp não pareado                   |

### SDK vs REST

O `@digitalsac/digicalls-sdk` encapsula REST + WebRTC + SSE. Use REST direto se sua stack não for browser (ex.: originar via backend — **não recomendado** para mídia; mídia sempre no cliente).

### Próximos

* Provisionamento
* Permissão WABA