# Fluxo de Discagem (Telefonia)

## Fluxo correto

1. Usuário aciona a discagem ativa no OmniPlus.
2. O front chama `GET /integracao_telefonia/discagem_online` (com `dataType: 'json'`).
3. Somente após **HTTP 2xx** e corpo com `ok: true` é chamada a criação de atendimento (`POST /gestao/atendimento/adicionar_manualmente`).
4. O backend gera protocolo (`protocolGenerate`) e persiste:
   - `solicitacao_chat_whatsapp` (telefonia — canal 10), via `TelefoniaManualAtendimentoService`
   - `atendimento`

## Contrato JSON — `discagem_online`

Resposta de sucesso (HTTP 200):

```json
{
  "ok": true,
  "code": "success",
  "message": "Discagem iniciada com sucesso.",
  "correlation_id": "<uuid>"
}
```

Resposta de erro (HTTP 422, 404, 502 ou 500 conforme o caso):

```json
{
  "ok": false,
  "code": "dial_failed | validation | config | invalid_response | integration_unreachable | exception",
  "message": "Texto para exibição (toastr/alert).",
  "correlation_id": "<uuid>"
}
```

A lógica de chamada à PBX fica em `TelefoniaController::performDiscagemOnline()`; o endpoint público apenas serializa esse resultado.

## Multitenancy

A rota `integracao_telefonia/discagem_online` usa o middleware `Tenant`, alinhado às demais rotas de atendimento/integração.

## Indisponibilidade de rede / PBX

- Falhas de **cURL** (timeout, host inalcançável) retornam HTTP **503**, `code: integration_unreachable` e mensagem clara para o atendente — **sem** exceção não tratada (evita 500 no log por esse motivo).
- Falhas em `status_ramal_v2()` antes da discagem são isoladas em `tryAjustarPausaAntesDiscagem()` e não interrompem o fluxo com erro fatal.
- No navegador, se a requisição **não alcançar o OmniPlus** (`status === 0`, timeout ou `parsererror`), o front exibe mensagem específica (toastr/alert).

## Log

- Problemas esperados de rede usam `Log::warning` com `correlation_id` e detalhes técnicos (`curl_errno` / preview da resposta), não `ERROR` genérico de exceção.

## Momento da geração de protocolo

- O protocolo deve ser gerado apenas após confirmação de sucesso da discagem.
- No fluxo de discagem ativa da tela, a criação do atendimento foi mantida para ocorrer após o retorno de sucesso da API de discagem.

## Dependência da API OmniPBX

- A criação do atendimento depende do sucesso da API de discagem do OmniPBX.
- Em caso de falha de discagem, o atendimento não deve ser criado no fluxo ativo.

## Rastreabilidade

- `atendimento.id_chamada_integracao` recebe o identificador de integração (`chamada_integracao`/`uuid`) quando disponível.
- Em telefonia, se houver retorno de sucesso de discagem e falha de persistência de atendimento, é gravado log estruturado via `Funcoes->gravaLog`.

---

## Pausa (`lista_pausa` + `iniciar_pausa`)

Mensagens e códigos estão centralizados em `TelefoniaController` (`TELEFONIA_MSG_*`, `MOTIVO_*`).

- **`status_ramal_v2()`** devolve `_motivo` e `_mensagem_atendente` para distinguir:
  - **Integração não configurada** (`INTEGRACAO_NAO_CONFIGURADA`) → pausa **local** (sem API PBX), como antes.
  - **Usuário sem ramal** (`USUARIO_SEM_RAMAL`) → **bloqueio** com mensagem clara (HTTP 422).
  - **PBX sem conexão** (`PBX_SEM_CONEXAO`) → **bloqueio** (HTTP 503), não usar pausa interna “como sucesso”.
  - **Resposta inválida da PBX** (`PBX_RESPOSTA_INVALIDA`) → **bloqueio** (HTTP 502).
  - **Ramal inativo/inexistente na PBX** (`RAMAL_INATIVO_OU_INEXISTENTE`) → **bloqueio** (HTTP 422).
  - **`OK`** → pode chamar `efetuar_pausa_v2` / pausa produtiva na API.

- **`POST gestao/atendimento/iniciar_pausa`**: valida **antes** de efeitos colaterais (`SolicitacaoAtendente`, `AtendentePresente`). Resposta de bloqueio inclui `message`, `errors`, `telefonia_erro`, `agendar_solicitacao: false`.

- **Agendamento** (em atendimento / ramal tocando): resposta 404 mantém `agendar_solicitacao: true` para o front **só** nesse caso gravar pausa agendada.

- **`lista_pausa`**: sem integração ou sem ramal → **422** com as mesmas mensagens; falha Guzzle → **503** com `TELEFONIA_MSG_PBX_SEM_CONEXAO`.