aPABX AtendaiVoltar ao painel

CONTRATO 0.23.0

Integre com exemplos prontos para adaptar

Consulte a API, copie os cURLs e use os exemplos de WebPhone com JsSIP na sua integração. A referência para agentes de IA inclui o guia completo e os códigos.

API do PABX Atendai

Documentação da implementação publicada. Base REST: https://pabx.atendai.chat/api/v1. Os nomes próprios dos campos e rotas estão em português. Termos de telefonia como originate, hangup, transfer e DTMF preservam seus nomes técnicos.

Siga-me e nome exibido nas chamadas (0.22.0)

No painel, abra **Ramais → Ver acessos → Siga-me**. Configure uma ou mais condições, marque **Siga-me ativado** e salve. Desativar pelo painel ou pelo código mantém os destinos para a próxima ativação. Ramais existentes começam sem desvio.

CondiçãoComportamento
SempreEncaminha imediatamente, sem tocar na origem. Prevalece sobre as outras regras.
Se não atenderToca na origem por tempo_toque segundos e encaminha após NOANSWER.
Se ocupadoDesvia quando já existe chamada no ramal ou o aparelho responde ocupado (BUSY). Inclui aparelhos que aceitariam chamada em espera.
Offline / indisponívelDesvia quando não há contato disponível ou a tentativa retorna CHANUNAVAIL/CONGESTION.

Cada condição aceita null (sem desvio), {"tipo":"ramal","id":"UUID"} ou {"tipo":"externo","numero":"11900001234"}. O ramal de destino precisa estar ativo na mesma empresa. O telefone externo segue a formatação das rotas de saída da empresa; não é o UUID de um recurso.

tempo_toque: 5–120 segundos, padrão 20. Só substitui o tempo normal de toque quando há regra nao_atende habilitada. O número de toques varia por aparelho; por isso o painel usa segundos. tempo_externo: 5–120 segundos, padrão 45, limita a espera de atendimento no destino externo.

Para ativar pelo aparelho, primeiro salve destinos no painel. Em **Controle pelo telefone**, habilite a opção e defina os códigos (padrão **#21 ativar**, **#22 desativar**). Disque o código e pressione Ligar; o sistema confirma por voz. Pode-se configurar uma tecla de discagem rápida do aparelho para chamar o código. Não é um código a digitar durante outra conversa, não recebe o número do destino e não configura automaticamente uma tecla física ou sua luz BLF. Os códigos controlam todas as regras salvas do próprio ramal autenticado, inclusive via WebPhone; não permitem controlar outro ramal. Aceitam um ou dois caracteres #/* seguidos de 1–4 dígitos e não podem conflitar com os códigos de captura da empresa. Desligar permitir_telefone mantém o controle pelo painel/API.

API do Siga-me

- GET /ramais/{id}/siga-me: escopo ramais:ler; retorna ramal_id, numero, nome, versao e siga_me, dentro de dados.

- PUT /ramais/{id}/siga-me: escopo ramais:escrever; exige versao atual e objeto siga_me. Substitui somente esse objeto, preservando os outros dados do ramal; campos omitidos dentro dele recebem os padrões. Retorna a mesma estrutura do GET com a nova versão.

- Também se aceita configuracao.siga_me no cadastro geral do ramal. Omitir esse campo em um PUT antigo preserva a configuração atual. Não enviar null; para desligar, use habilitado:false.

- Versão vencida retorna 409. Ciclos retornam 409 CICLO_ENCAMINHAMENTO. Destinos de outra empresa retornam 404; permissão externa insuficiente retorna 403; valores inválidos retornam 422.

- POST /webphone/preparar reconhece os códigos do próprio ramal e retorna tipo:"siga_me". Essa preparação apenas valida; a alteração acontece quando o INVITE autenticado chega ao PABX.

Exemplos fictícios, com jq instalado:

BASE='https://pabx.atendai.chat/api/v1'
RAMAL_ID='00000000-0000-4000-8000-000000000001'
DESTINO_ID='00000000-0000-4000-8000-000000000002'
# CHAVE deve conter uma chave da empresa com os escopos necessários.

# Consultar sem alterar.
curl -fsS "$BASE/ramais/$RAMAL_ID/siga-me" -H "Authorization: Bearer $CHAVE"

# Se não atender em 20 segundos, encaminhar ao ramal de destino.
# Preserve as demais regras retornadas pelo GET.
curl -fsS "$BASE/ramais/$RAMAL_ID/siga-me" -H "Authorization: Bearer $CHAVE" \
  | jq --arg destino "$DESTINO_ID" '.dados | {versao,siga_me} |
      .siga_me.habilitado=true | .siga_me.sempre=null |
      .siga_me.tempo_toque=20 | .siga_me.nao_atende={tipo:"ramal",id:$destino}' \
  | curl -fsS -X PUT "$BASE/ramais/$RAMAL_ID/siga-me" \
      -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' --data-binary @-

# Sempre encaminhar a um telefone externo, se houver permissão e rota.
curl -fsS "$BASE/ramais/$RAMAL_ID/siga-me" -H "Authorization: Bearer $CHAVE" \
  | jq '.dados | {versao,siga_me} | .siga_me.habilitado=true |
      .siga_me.sempre={tipo:"externo",numero:"11900001234"}' \
  | curl -fsS -X PUT "$BASE/ramais/$RAMAL_ID/siga-me" \
      -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' --data-binary @-

# Desativar conservando os destinos.
curl -fsS "$BASE/ramais/$RAMAL_ID/siga-me" -H "Authorization: Bearer $CHAVE" \
  | jq '.dados | {versao,siga_me} | .siga_me.habilitado=false' \
  | curl -fsS -X PUT "$BASE/ramais/$RAMAL_ID/siga-me" \
      -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' --data-binary @-

Execução, limites e gravações

O desvio externo usa as permissões externas/internacional **do ramal que encaminha**, mesmo quando quem ligou é externo. O sistema revalida permissões e rotas na execução, respeita o limite de simultâneas dos troncos e evita retorno a um DID cadastrado na própria empresa. A operadora pode cobrar esse trecho; uma ligação recebida e desviada pode ocupar duas linhas do tronco. Não se garante transferência se a operadora estiver indisponível ou sem capacidade.

Chamadas internas, entradas diretas e ramais escolhidos por URA aplicam as mesmas regras. Em filas, o Siga-me atua somente após a fila escolher o membro: membros offline/ocupados podem ser pulados antes disso. Os limites de espera da fila e da campanha continuam valendo e podem encerrar a tentativa antes do desvio. Para contingência de toda a fila, configure o destino alternativo da própria fila. No originate por API, o ramal de origem precisa atender; seu Siga-me não transfere essa primeira etapa.

Desvios internos podem seguir regras do próximo ramal; ciclos e cadeias acima de 12 etapas são recusados, inclusive nas regras salvas desativadas. Não configure retorno por redes externas de terceiros, cujas rotas o PABX não conhece. Se a tentativa de Siga-me falhar, o fluxo original ainda pode executar seu destino_nao_atendido. A mudança só afeta novas tentativas; não transfere conversas já estabelecidas.

O UUID REST da chamada é mantido durante o Siga-me. call.forwarded informa origem, destino, motivo:"siga_me_sempre|siga_me_nao_atende|siga_me_ocupado|siga_me_indisponivel" e etapa. O envelope do evento contém chamada_id. call.sigame_dial informa ramal_id, tronco_id, numero_digitado e numero_enviado. Cada perna SIP pode ter Call-ID diferente; use a correlação já documentada, nunca telefone/horário aproximados. O histórico do ramal registra alterações e encaminhamentos.

Ao atender outro ramal, valem as opções de gravação do ramal que atendeu. Ao atender um telefone externo por Siga-me, o trecho usa a opção **gravar recebidas do ramal que encaminhou**. O áudio só estará disponível depois de finalizado/processado; consulte GET /chamadas/{id}/gravacoes ou GET /ramais/{id}/gravacoes. Nenhum desvio ativa gravação automaticamente.

Nome mostrado ao receber uma ligação interna

Em **Editar ramal → Nome exibido nas chamadas**, informe por exemplo **Ramal 101 · Setor TI**. Se vazio, usa o **Nome** do cadastro. O número interno continua o mesmo; não altera o login SIP.

Campo API: configuracao.nome_identificacao, string de até 60 caracteres, sem caracteres de controle, aspas, barra invertida ou delimitadores SIP. Omitido em PUT preserva o valor; vazio remove a personalização. GET /ramais/{id}/configuracao-sip retorna nome_identificacao já resolvido. O servidor define a identificação nas chamadas internas, incluindo chamadas originadas por API, sem confiar no nome enviado pelo aparelho. O telefone pode dar prioridade à sua agenda local. Em chamadas externas, a operadora continua controlando a identificação numérica e a apresentação de nome.

curl -fsS "$BASE/ramais/$RAMAL_ID" -H "Authorization: Bearer $CHAVE" \
  | jq '.dados | {nome,versao,ativo,configuracao} |
      .configuracao.nome_identificacao="Ramal 101 · Setor TI"' \
  | curl -fsS -X PUT "$BASE/ramais/$RAMAL_ID" -H "Authorization: Bearer $CHAVE" \
      -H 'Content-Type: application/json' --data-binary @-

Usuário SIP opcional sem símbolos

Desde a versão 0.18.0, em **Ramais → Ver acessos → Editar**, marque **Habilitar também usuário SIP sem símbolos**. O painel mostra o usuário calculado antes de salvar. Depois do provisionamento, consulte **Configuração SIP** e use **Copiar configuração sem símbolos** após revelar a senha.

Exemplo fictício: o ramal 1002 da empresa 1 conserva T1_1002 e passa a aceitar também T1R1002. Os dois acessos usam a mesma senha SIP e podem registrar simultaneamente. No aparelho, preencha **usuário** e **autenticação** com T1R1002; servidor, porta 5060, transporte UDP e codecs permanecem os mesmos. Maiúsculas e minúsculas fazem diferença. Não remova apenas o sublinhado manualmente: R separa a empresa do número e evita colisões. A alternativa acompanha o **número do ramal**, independentemente de um sufixo SIP personalizado.

- configuracao.sip_sem_simbolos: booleano; padrão false na criação. Omitido no PUT conserva a opção atual; false remove somente o acesso alternativo após provisionamento.

- configuracao.usuario_sip_alternativo: calculado pelo servidor como T{empresa_id}R{numero}. Não é editável. No PUT, omita este campo ao alterar o número ou desligar a opção. O servidor recusa identidades forjadas.

- GET /ramais/{id}/configuracao-sip retorna sip_sem_simbolos e usuario_sip_alternativo (nulo quando desabilitado), além de usuario e autenticacao principais. POST /ramais/{id}/revelar-credencial retorna a mesma configuração com a senha, mediante permissão de escrita e auditoria.

- POST /ramais/lote/previa e /ramais/lote aceitam a opção em configuracao. Ao usar um modelo, copiam a opção e calculam um usuário diferente por número. Prévia e criação retornam usuario_sip_alternativo por item.

- Renumerar ou desativar a alternativa durante uma participação de chamada ativa retorna 409. Ao renumerar, atualize o aparelho que usa o acesso alternativo. O login principal continua regido por sufixo_sip.

- Os logins ficam reservados ao ramal após renomeação/desativação. Excluir definitivamente o ramal segue as regras de exclusão existentes. Desativar o ramal ou a empresa remove ambos os acessos.

Filas, captura, histórico de registros e IP, chamadas e gravações tratam os dois acessos como **um único ramal da mesma empresa**. Disque apenas 1002 internamente, inclusive após o código de captura direta. O WebPhone mantém suas próprias credenciais entregues por GET /webphone. PDF e TXT incluem a alternativa quando habilitada. A mudança é auditada e não ativa automaticamente a opção nos ramais existentes.

# Criar com ambos os acessos; a senha SIP é gerada pelo servidor.
curl -X POST "$BASE/ramais" -H "Authorization: Bearer $CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"nome":"Recepção","configuracao":{"numero":"1002","sip_sem_simbolos":true,"webphone":true}}'

# Habilitar em ramal existente sem descartar as demais configurações (requer jq).
curl -fsS "$BASE/ramais/$RAMAL_ID" -H "Authorization: Bearer $CHAVE" \
  | jq '.dados | {nome,versao,ativo,configuracao} | .configuracao.sip_sem_simbolos=true | del(.configuracao.usuario_sip_alternativo)' \
  | curl -X PUT "$BASE/ramais/$RAMAL_ID" -H "Authorization: Bearer $CHAVE" \
    -H 'Content-Type: application/json' --data-binary @-

curl "$BASE/ramais/$RAMAL_ID/configuracao-sip" -H "Authorization: Bearer $CHAVE"

Defina BASE=https://pabx.atendai.chat/api/v1, CHAVE e RAMAL_ID no ambiente da integração. A chave pertence ao cliente: leitura exige ramais:ler; escrita e revelação, ramais:escrever. O PUT exige versão atual e configuração completa. Registro conectado só é confirmado quando o aparelho autentica; salvar o cadastro não equivale a registrar o telefone.

IP de registro dos ramais

O resumo de cada ramal mostra os IPs de seus dispositivos; Configuração e conexão detalha tipo, dispositivo, IP/porta e latência. Histórico e atividade conserva registros e renovações com endereço e fonte do IP. Não confunda cadastro configurado com conexão ativa.

GET /ramais/conexoes acrescenta, em cada dispositivo: ip (IPv4/IPv6 ou null), porta_origem (inteiro ou null), endereco, fonte_ip, ip_registro e origem_via_proxy. contato_sip significa o endereço do Contact após a reescrita NAT do Asterisk. acesso_webphone significa o IP da requisição HTTPS autenticada que forneceu a configuração ao navegador, correlacionada ao registro; a porta SIP do proxy não é apresentada como porta do navegador. ip_registro mantém o IP visto pelo Asterisk e pode ser 127.0.0.1.

O WebPhone usa contato_uri retornado por GET /webphone no parâmetro contact_uri do JsSIP.UA. Integrações externas devem fazer o mesmo, como no exemplo completo fornecido. A correlação dura 24 horas e não altera autenticação nem roteamento. Uma conexão antiga ou aplicação sem esse parâmetro mostra o IP do proxy com rótulo explícito; reconecte o WebPhone para obter a nova configuração. Mudanças de rede durante a mesma conexão exigem reconexão para atualizar o IP de acesso. O servidor usa REMOTE_ADDR, não um X-Forwarded-For informado pelo cliente. O histórico anterior mantém seu endereço Via original (fonte_ip: via_sip); não há reconstrução retroativa do IP público.

Desativar ou excluir ramais

No painel: **Ramais → Ver acessos → Desativar ou excluir**. O diálogo mostra a quantidade de gravações, vínculos e acessos afetados. Desativação é a opção inicial. A exclusão exige marcar a confirmação definitiva.

- **Desativar:** mantém cadastro, número/usuários SIP reservados, gravações e histórico. Atendentes vinculados perdem acesso; para voltar, reative ramal e acessos separadamente.

- **Excluir sem gravações:** remove o cadastro e as credenciais SIP, liberando número e usuários SIP para novo cadastro.

- **Excluir com gravações:** exige autorização explícita para remover também todos os áudios pertencentes ao ramal. Para preservar os áudios, escolha desativar.

A auditoria e o histórico geral de chamadas/registros são mantidos com o UUID original. Um novo cadastro com o mesmo número tem outro UUID e não herda o histórico. A remoção alcança somente gravações cujo ramal_id corresponde ao excluído; trechos gravados por outros ramais na mesma chamada permanecem. Os logins de atendentes são desativados e seus vínculos removidos na exclusão; contas administrativas mantêm o acesso administrativo, com vínculo ao ramal removido e sessões revogadas.

OperaçãoCorpo / permissão
GET /ramais/{id}/exclusaoramais:escrever. Retorna ramal com versao, quantidade_gravacoes, tamanho_gravacoes em bytes, em_chamada, dependencias e acessos_vinculados.
POST /ramais/{id}/desativar{versao: VERSAO_ATUAL}; ramais:escrever.
POST /ramais/{id}/excluir{versao: VERSAO_ATUAL, confirmar: true, excluir_gravacoes: false}; ramais:escrever. Se houver gravações, enviar excluir_gravacoes=true e ter também gravacoes:escrever.
DELETE /ramais/{id}Continua desativando por compatibilidade. Não executa exclusão definitiva.

A prévia não reserva o ramal: a execução verifica tudo novamente na transação. Recusa chamadas ativas, reservas e gravações em andamento (409 RAMAL_EM_CHAMADA). A exclusão recusa qualquer referência em filas, URAs, rotas e outros cadastros, mesmo desativados (409 EM_USO); retire o vínculo primeiro. Desativação só bloqueia referências ativas. Versão divergente retorna 409 VERSAO_CONFLITANTE. Ramal com gravações sem autorização retorna 409 GRAVACOES_EXISTENTES. Booleanos precisam ser JSON true/false; não envie strings. 403 indica falta de escopo; 404 também protege recursos de outra empresa.

A resposta contém excluido, desativado, gravacoes_excluidas e arquivos_pendentes. A exclusão revoga imediatamente o acesso aos áudios e remove seus metadados na mesma transação. O worker provisionar apaga os WAVs em seguida, repetindo falhas a cada minuto; arquivos_pendentes é a quantidade enfileirada naquele instante. A fila durável app.exclusoes_gravacoes permite acompanhar pendências operacionalmente. Não exclui cópias anteriormente baixadas ou armazenadas em backups externos. Não existe desfazer ou restauração pela API. Se a resposta se perder, consulte o UUID: 404 indica cadastro já removido, não recrie nem repita contra outro ramal.

RAMAL_ID='SUBSTITUA_PELO_UUID_DO_RAMAL'
curl --fail-with-body -sS "$BASE/ramais/$RAMAL_ID/exclusao" \
  -H "Authorization: Bearer $CHAVE_API"

# Opção que preserva gravações; substitua a versão pela atual.
curl --fail-with-body -sS -X POST "$BASE/ramais/$RAMAL_ID/desativar" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  -d '{"versao":1}'

# Alternativa definitiva: execute somente com autorização para remover os áudios.
# Obtenha novamente a versão se tiver desativado ou editado antes.
curl --fail-with-body -sS -X POST "$BASE/ramais/$RAMAL_ID/excluir" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  -d '{"versao":2,"confirmar":true,"excluir_gravacoes":true}'

Documento de configuração para o cliente

Em **Ramais → Documentação dos ramais**, selecione ativos (padrão), desativados ou todos. Em **Personalizar logo e marca-d’água**, envie as imagens da empresa ou remova as atuais. Marque **Incluir as senhas SIP** somente para entregar credenciais ao responsável autorizado. Clique em **Gerar PDF → Baixar PDF**. O PDF A4 possui logo, marca-d’água discreta em todas as páginas, paginação, dados SIP, preferências de WebPhone/gravação e instruções de uso. **Copiar dados como texto** permanece disponível.

POST /ramais/documentacao recebe {"situacao":"ativos","incluir_senhas":false,"formato":"pdf"}. formato aceita pdf (padrão desde 0.13.0) ou txt. Requer ramais:ler e, para incluir senhas, também ramais:escrever. Sessões usam CSRF; administradores globais devem selecionar a empresa. Nenhum campo empresa_id muda o cliente da chave. Inclui todos os ramais do filtro, sem o limite de 500 da listagem genérica, ordenados numericamente.

Resposta JSON: dados:{nome_arquivo,tipo_conteudo,quantidade,inclui_senhas,formato,codificacao,conteudo}. Em PDF, tipo_conteudo=application/pdf, codificacao=base64 e conteudo precisa ser decodificado para bytes. Em TXT, codificacao=utf-8 e conteudo é texto. Integrações antigas que precisam de TXT devem enviar formato:"txt" explicitamente. Não trate o conteúdo como URL.

A resposta usa Cache-Control: private, no-store; o PDF não é salvo como documento no servidor. A auditoria gerar_documentacao_ramais registra responsável, empresa, quantidade, formato e inclusão de credenciais, sem texto ou senhas. Senhas SIP são distintas das senhas do painel/WebPhone; estas últimas não são exportáveis. Proteja o arquivo baixado e a área de transferência.

# Sem senhas por padrão. Gere com true apenas se autorizado a entregá-las.
umask 077
curl --fail-with-body -sS -X POST "$BASE/ramais/documentacao" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  -d '{"situacao":"ativos","incluir_senhas":false,"formato":"pdf"}' \
  > documento-ramais.json
jq -er '.dados.conteudo' documento-ramais.json | base64 --decode > ramais-cliente.pdf

Logo e marca-d’água por empresa

GET /empresa/documentacao exige ramais:ler e retorna logo e marca_dagua, cada uma null ou com url, tipo_conteudo, tamanho em bytes, largura e altura. GET /empresa/documentacao/logo ou /empresa/documentacao/marca_dagua entrega a imagem binária autenticada da empresa atual; não há URL pública. A ausência da imagem retorna 404.

POST nessas mesmas duas rotas exige ramais:escrever e multipart com arquivo. Aceita somente PNG/JPEG válidos até 3 MB, 4000 pixels por lado e 8 milhões de pixels no total; SVG, URLs e caminhos locais não são aceitos. DELETE remove a imagem escolhida. POST/DELETE retornam o mesmo objeto de identidade visual atualizado. Sessões precisam de CSRF e, no painel, X-Empresa-ID. Auditorias: alterar_identidade_documento e remover_identidade_documento.

curl --fail-with-body -sS -X POST "$BASE/empresa/documentacao/logo" \
  -H "Authorization: Bearer $CHAVE_API" -F 'arquivo=@logo.jpg'
curl --fail-with-body -sS -X POST "$BASE/empresa/documentacao/marca_dagua" \
  -H "Authorization: Bearer $CHAVE_API" -F 'arquivo=@marca-dagua.png'
curl --fail-with-body -sS -X DELETE "$BASE/empresa/documentacao/marca_dagua" \
  -H "Authorization: Bearer $CHAVE_API"

Imagens são privadas em armazenamento/identidade/<empresa_id>/, incluídas no backup completo e excluídas do Git. Uploads são verificados por conteúdo e dimensões. O PDF usa o canvas da biblioteca Dompdf, com fontes Unicode e sem interpretar HTML, PHP, JavaScript ou imagens remotas. As imagens são redimensionadas proporcionalmente; a marca-d’água recebe transparência somente na renderização do documento.

URA simples: áudio seguido de atendimento

Em **URAs → Adicionar URA → Tipo de URA**, escolha **URA simples · tocar áudio e encaminhar**. Selecione uma mensagem existente ou use **Gerar, gravar ou enviar mensagem**. Em **Para onde encaminhar após o áudio?**, escolha uma fila ou um ramal; é possível cadastrá-los nessa tela. Salve e selecione essa URA como destino da rota de entrada desejada. Criar a URA não altera automaticamente os números recebidos.

A URA simples atende a ligação, toca o áudio inteiro uma única vez e só então encaminha. Não pede teclas, não tem espera por dígitos e não interrompe a mensagem quando a pessoa digita. **Se ninguém atender (opcional)** permite tentar outra fila, ramal ou URA depois das alternativas do destino. A fila continua respeitando seu horário, pausa e disponibilidade; fora do expediente segue o destino configurado nela. Para bloquear também a saudação fora do expediente, coloque uma regra de horário antes da URA na rota de entrada.

POST /uras e PUT /uras/{id} usam configuracao.modo, com simples ou teclas. Criação sem modo mantém o padrão teclas; edição sem modo preserva o modo salvo. Áudio é obrigatório nos dois modos. Em simples, destino deve apontar para fila ou ramal ativo da empresa. opcoes, timeout e repeticoes são ignorados e normalizados para [], 5 e 0; os dois números não controlam a reprodução neste modo. horarios_filas deve estar vazio; configure a agenda no cadastro da fila. Converter uma URA com teclas para simples remove suas opções de teclado; para voltar, cadastre as teclas novamente. Versão, auditoria, isolamento e bloqueio de ciclos continuam valendo.

curl --fail-with-body -sS -X POST "$BASE/uras" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data '{"nome":"Boas-vindas e atendimento","configuracao":{"modo":"simples","audio_id":"00000000-0000-4000-8000-000000000001","destino":{"tipo":"fila","id":"00000000-0000-4000-8000-000000000002"}}}'

Para encaminhar a ramal, use destino:{"tipo":"ramal","id":"UUID_DO_RAMAL"}. Para editar, obtenha o GET, preserve os campos que deseja manter e envie a versao atual. Permissões: uras:ler para consulta e uras:escrever para criar/editar. As permissões de áudios ou filas só são necessárias para consultar ou alterar esses cadastros separadamente.

Ao completar a mensagem, call.audio_played inclui audio_id, ura_id, modo=simples e motivo=reproduzido; depois call.forwarded registra motivo=audio_concluido. Isso representa encaminhamento tentado, não atendimento humano. Falta do arquivo ou erro de reprodução emite call.audio_failed e encerra sem encaminhar. Desligamento durante o áudio também impede o encaminhamento. Os eventos permanecem na empresa e na mesma chamada/CDR.

Criar ramais em lote

No painel, abra **Ramais → Criar em lote**. Informe o número inicial, a quantidade e confira a sequência antes de criar. Dentro de um ramal ativo, **Criar sequência a partir deste ramal** sugere o próximo número e usa suas configurações como modelo. O ramal modelo permanece inalterado e não entra na contagem de novos cadastros.

A quantidade inclui o número inicial informado: 1002 + 83 ramais resulta em 1002 até 1084. Para criar 83 novos ramais depois de um 1002 já existente, informe 1003: o último será 1085. O usuário SIP recebe automaticamente o prefixo fixo da empresa, por exemplo T1_1002; disque apenas 1002 entre colegas.

As duas operações exigem ramais:escrever e atuam somente na empresa da credencial:

- POST /ramais/lote/previa: retorna a sequência, conflitos, configuração e solicitacao pronta para criação. Não cria nem reserva ramais.

- POST /ramais/lote: cria todos os cadastros em uma transação; exige Idempotency-Key. Responde 201 com quantidade, prefixo_sip, ramais (UUID, nome, número e usuário SIP) e provisionamento: "pendente".

Campos do corpo:

CampoUso
numero_inicialObrigatório, texto de 2 a 6 dígitos, sem T1_. Toda a sequência deve caber em 6 dígitos.
quantidadeInteiro de 1 a 100, incluindo o primeiro número.
sufixo_inicialOpcional, usa numero_inicial. Até 24 caracteres ASCII: letras, números, _ e -, começando por alfanumérico e terminando em 1 a 6 dígitos. O final numérico é incrementado: S_0098, S_0099, S_0100. Zeros à esquerda são preservados.
nome_padraoPadrão Ramal {numero}. Aceita {numero} e {usuario_sip}. Cada nome gerado deve ter 2 a 100 caracteres.
ramal_modelo_idOpcional, UUID de ramal ativo da mesma empresa. Copia permissões, WebPhone, tempo de toque, gravações e encaminhamento sem atendimento.
versao_modeloObrigatória ao criar com modelo; use a retornada em solicitacao na prévia. Alterações no modelo exigem nova prévia.
configuracaoUsada somente sem modelo. Aceita webphone, externas, internacional, timeout, gravar_realizadas, gravar_recebidas e destino_nao_atendido. Padrões iguais ao cadastro individual: WebPhone habilitado, externas/internacionais/gravações desabilitadas, toque de 30 segundos, sem outro encaminhamento.

Os novos ramais ficam ativos. O lote não copia senha, endpoint, contatos SIP, usuários WebPhone, histórico ou participação em filas. Cada senha SIP é gerada individualmente e guardada cifrada; não aparece na prévia, resposta do lote, auditoria ou registro de idempotência. Consulte pelo acesso autenticado a /ramais/{id}/revelar-credencial quando necessário. Cadastre logins WebPhone em cada ramal e vincule os novos membros às filas desejadas.

Exemplo completo com cURL e jq, usando as variáveis BASE e CHAVE da seção de autenticação:

curl --fail-with-body -sS "$BASE/ramais/lote/previa" \
  -H "Authorization: Bearer $CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"numero_inicial":"1002","quantidade":83,"nome_padrao":"Ramal {numero}"}' \
  > previa-lote.json

# Confira números, configurações e conflitos antes de continuar.
jq '.dados | {quantidade,pode_criar,total_conflitos,configuracao,ramais}' previa-lote.json
jq -e '.sucesso == true and .dados.pode_criar == true' previa-lote.json
jq '.dados.solicitacao' previa-lote.json > criar-lote.json

# Escolha uma chave nova para este lote; mantenha a mesma em uma repetição.
IDEMPOTENCIA="lote-$(openssl rand -hex 16)"
curl --fail-with-body -sS "$BASE/ramais/lote" \
  -H "Authorization: Bearer $CHAVE" \
  -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data-binary @criar-lote.json

Para copiar um modelo, envie na prévia {"numero_inicial":"1003","quantidade":83,"ramal_modelo_id":"UUID_REAL_DO_MODELO"} e depois use integralmente dados.solicitacao. Não envie configuracao junto com o modelo.

Número cadastrado, mesmo desativado, ou usuário SIP reservado no histórico bloqueia o lote inteiro. A prévia sinaliza pode_criar: false, total_conflitos e motivos em cada item. Nenhum número é pulado, sobrescrito ou reativado. A criação confere novamente sob bloqueio da empresa, protegendo contra alterações simultâneas. Conflito retorna 409 LOTE_CONFLITANTE; versão do modelo retorna VERSAO_CONFLITANTE. Não há criação parcial de cadastros, auditoria ou tarefas de provisionamento.

Idempotency-Key aceita 12 a 128 letras, números, _ e -. Repita a mesma chave e o mesmo corpo se a resposta se perder: retorna os mesmos UUIDs sem duplicar. Corpo diferente com chave já concluída retorna 409 IDEMPOTENCIA_CONFLITANTE. Chaves são isoladas por empresa e operação. Falhas transacionais não consomem a chave. Uma repetição retorna o resultado original mesmo se o modelo mudar depois.

O provisionamento no Asterisk ocorre após a transação, por ramal, com repetição automática em caso de falha. pendente na resposta original ou repetida não é uma consulta do estado atual. A presença continua disponível em /ramais/conexoes; cadastro concluído não significa telefone registrado. Cada criação individual e o resumo criar_lote aparecem na auditoria com o responsável.

Comece por aqui

1. Entre no painel e selecione o cliente que será integrado.

2. Abra Integrações → Chaves de API → Criar chave. Dê um nome à integração e selecione somente os escopos necessários.

3. Copie a chave exibida na criação. Ela não poderá ser consultada novamente. Para substituir uma chave perdida, crie outra e revogue a anterior.

4. Configure a chave no servidor da integração. Não a coloque em JavaScript público, URLs ou aplicativos distribuídos aos usuários.

5. Consulte os ramais, guarde os UUIDs retornados e use esses UUIDs nos relacionamentos.

Os comandos desta página são exemplos para Bash com curl. Requerem substituição dos valores ilustrativos. Os exemplos de chamada, campanha e alteração executam operações reais quando usados com uma chave válida.

BASE='https://pabx.atendai.chat/api/v1'
read -r -s -p 'Chave de API: ' CHAVE_API
printf '\n'
ID='SUBSTITUA_PELO_UUID_DO_RECURSO'

curl --fail-with-body --silent --show-error "$BASE/ramais" \
  -H "Authorization: Bearer $CHAVE_API"

Prefixo SIP e captura de chamadas por empresa

Em **Ramais → Telefonia desta empresa**, consulte o prefixo fixo e ative **Permitir que os ramais desta empresa capturem chamadas uns dos outros**. A configuração vale só para o cliente selecionado. Novas empresas começam com captura desativada. A alteração é auditada.

O usuário SIP dos novos ramais segue T{empresa_id}_{sufixo_sip}: empresa 1 e sufixo 101 produzem T1_101; empresa 2 produz T2_101. O prefixo deriva do ID imutável da empresa, não da ordem da lista ou do nome. Mudar o nome da empresa não muda seu prefixo. Ele não é editável. O sufixo aceita de 1 a 24 letras ASCII, números, hífen e sublinhado, começando com letra ou número; o login completo não ultrapassa 40 caracteres. Letras maiúsculas/minúsculas fazem diferença. O login fica reservado para o mesmo ramal mesmo após renomeação ou desativação, evitando que um telefone com cadastro antigo passe a representar outro ramal.

- numero: número discado pelos colegas, de 2 a 6 dígitos, por exemplo 101.

- sufixo_sip: parte editável do login; na criação, omitido ou vazio usa numero. No PUT, omitido mantém o login. Mudar o número posteriormente não renomeia o login.

- senha: opcional, somente escrita; 5 a 128 caracteres ASCII imprimíveis, sem espaços. Vazio gera uma senha na criação e mantém a existente na edição. Senhas são cifradas e ocultadas na auditoria.

- configuracao.usuario_sip: resultado calculado pelo servidor, não é campo de edição. Ao montar um PUT para mudar o sufixo, omita usuario_sip. Consulte os dados atuais em /ramais/{id}/configuracao-sip.

Ramais existentes conservam login, senha e registros atuais. Para migrar um deles, abra Editar → **Adotar o novo usuário com prefixo**, revise o sufixo e salve. Na API envie sufixo_sip. Depois atualize o usuário no telefone SIP; o login anterior deixa de autenticar após provisionamento. O servidor recusa renomear durante uma participação de chamada ativa. O identificador interno WebRTC e o login individual de acesso ao painel são preservados; integrações WebPhone devem sempre usar as credenciais entregues por GET /webphone.

# Ler o prefixo e os códigos. Requer ramais:ler.
curl --fail-with-body "$BASE/empresa/telefonia" -H "Authorization: Bearer $CHAVE_API"

# Ativar somente na empresa da chave. Requer ramais:escrever.
curl --fail-with-body -X PUT "$BASE/empresa/telefonia" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  -d '{"captura_chamadas":true,"codigo_captura_geral":"#0","prefixo_captura_direta":"#1"}'

# Criar ramal com login T{empresa_id}_101 e senha gerada.
curl --fail-with-body -X POST "$BASE/ramais" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  -d '{"nome":"Recepção","configuracao":{"numero":"101","sufixo_sip":"101","senha":"","webphone":true}}'

GET e PUT /empresa/telefonia retornam, dentro de dados: prefixo_sip, captura_chamadas, codigo_captura_geral (#0) e prefixo_captura_direta (#1). O PUT exige um booleano captura_chamadas; os dois campos de código são editáveis e, quando omitidos, mantêm o valor salvo. Aceitam um ou dois sinais # ou * seguidos de 1 a 4 números (^[*#]{1,2}[0-9]{1,4}$). Códigos iguais ou que comecem um pelo outro são recusados (422). A mudança é imediata e auditada; não exige reiniciar telefones ou Asterisk. Painel, WebPhone e PDF/TXT usam os valores atuais de cada empresa. Não fixe esses códigos na integração: consulte GET antes de montar a discagem. Sessões usam CSRF; no painel o administrador global também envia X-Empresa-ID para detectar troca de cliente em outra aba. Chaves usam ramais:ler/escrever e permanecem na própria empresa.

Código discado em uma nova ligaçãoResultado
#1101Captura uma chamada tocando no ramal 101 da mesma empresa
#0Captura a chamada mais antiga entre as que estão tocando em outros ramais da empresa

Para o ramal 2000, disque #12000. A captura deve estar ativada em Ramais → Telefonia desta empresa (novas empresas começam desativadas). Desde 0.15.0 os padrões são #0 e #1; o prefixo anterior ##0 só funciona se for configurado explicitamente. Para puxar o ramal 1002 com o padrão atual, disque #11002. Digite o código completo antes de iniciar a chamada; não envie como DTMF durante uma conversa. Se o aparelho usa # como terminador de discagem, ajuste-o para permitir enviar esses códigos.

Os códigos são discados no telefone SIP ou no WebPhone antes de iniciar uma ligação; não são DTMF para enviar durante uma conversa. Use o número do ramal, não o login T1_101. Inclui chamadas internas e externas, inclusive ligações que uma fila já está fazendo tocar em um ramal. Não captura uma ligação apenas aguardando na fila, conversas atendidas ou ramais de outro cliente. Uma pessoa com ramal autenticado nessa empresa pode capturar as chamadas quando a opção geral está ativa, mesmo sem pertencer à fila que distribuiu a ligação.

A autorização vem de CHANNEL(endpoint), associada ao cadastro no servidor. O servidor consulta canais em Ringing, cruza endpoint, chamada e empresa e usa PickupChan com o nome completo de um único canal. Não usa grupos globais, Caller-ID, prefixos informados pelo telefone nem busca por partes do nome. A seleção do canal e a captura não são uma reserva: se alguém atender primeiro, a tentativa falha sem interromper a conversa. Referência técnica: PickupChan do Asterisk 22.

O WebPhone prepara o código por POST /webphone/preparar com numero e ramal_id, recebe tipo=captura e então chama ua.call(dados.numero, opções de mídia). Não use /chamadas/originate ou /transfer para pescar. Possíveis erros de preparação: CAPTURA_DESATIVADA (403), RAMAL_CAPTURA_INVALIDO (404), SEM_CHAMADA_PARA_CAPTURAR (409), CAPTURA_INDISPONIVEL (503). Telefones SIP recebem recusa/indisponibilidade e mostram o aviso conforme o aparelho. Não encaminhe uma tentativa de captura para o tronco externo.

A chamada original é conservada. O evento call.pickup e as ações capturar_chamada / chamada_capturada identificam chamada_id, ramal_origem_id/numero (quem capturou) e ramal_destino_id/numero (onde tocava). O histórico de cada ramal mostra a ação. Captura autentica um ramal, não identifica uma pessoa quando várias pessoas compartilham o telefone. A gravação do capturador segue gravar_recebidas; a gravação da origem continua conforme sua configuração. O ramal que deixou de tocar não deve receber uma gravação da conversa atendida por outro.

Autenticação, clientes e permissões

Integrações usam Authorization: Bearer atd_.... Cada chave pertence a um único cliente. Não há chave Bearer global. Enviar empresa_id no corpo ou X-Empresa-ID não muda o cliente da chave. Uma referência a recurso de outro cliente é recusada.

Conexões, SIP e gravações

Em Ramais, expanda Ver acessos no ramal desejado. O resumo mantém nome, número, SIP/WebPhone, situação, conexão e opção de gravação; os botões ficam agrupados dentro do ramal. Em Configuração e conexão, consulte os dispositivos registrados, servidor, porta, usuário de autenticação, codecs, DTMF e acesso WebPhone. Telefones SIP usam UDP 5060 e RTP, com codecs alaw/ulaw; o navegador usa WSS 443 e DTLS-SRTP. O protocolo SIP é atendido pelo driver PJSIP; não há chan_sip legado nesta instalação. O mesmo ramal pode receber no navegador e em telefones SIP. Use o usuário devolvido por GET /ramais/{id}/configuracao-sip para configurar telefones; o endpoint do WebPhone é diferente. POST /ramais/{id}/revelar-credencial consulta a senha existente com auditoria e requer ramais:escrever. A renovação em /credencial substitui a senha em todos os dispositivos desse ramal.

GET /ramais/conexoes requer ramais:ler e retorna {consultado_em, disponivel, ramais:[{ramal_id, numero, estado, dispositivos}]}. Os estados são conectado, desconectado, indisponivel, verificando, desconhecido e desativado. Cada dispositivo informa tipo SIP/WebPhone, identificação, endereço registrado, latência e expiração. Conectado significa que ao menos um dispositivo respondeu ao Asterisk; não garante que há uma pessoa disponível para atender nem comprova o áudio. A verificação SIP ocorre a cada 30 segundos e o painel consulta a cada 15 segundos. Quando o AMI não responde, disponivel=false e o estado é desconhecido; não interprete isso como desconectado.

Os campos booleanos configuracao.gravar_realizadas e configuracao.gravar_recebidas são independentes e têm padrão false. Altere em Editar ramal ou envie o cadastro completo no PUT, preservando versao. Valem para novas chamadas, inclusive internas. No atendimento por fila, a opção de recebidas é avaliada no ramal que atendeu. No originate, o primeiro ramal é considerado origem. São gravados os dois lados da conversa, somente durante a conexão de áudio. A alteração não liga/desliga uma gravação já iniciada.

GET /chamadas/{id}/gravacoes requer gravacoes:ler. Retorna uma lista com id, chamada_id, ramal_id, numero_ramal, direcao (realizada/recebida), estado, duracao em segundos, tamanho em bytes, criada_em e finalizada_em. Estados: gravando, disponivel, sem_audio ou falhou. Uma chamada pode ter vários trechos identificados pelo ramal, especialmente em transferências e chamadas internas com ambas as opções habilitadas. Chamadas sem conversa podem ficar sem áudio. O histórico informa a quantidade no campo gravacoes e permite ouvir/baixar os trechos. Administradores e supervisores podem acessar; atendentes do WebPhone não têm acesso às gravações do cliente.

Gravações diretamente no ramal

Use Ramais → Ver acessos → Gravações para ouvir e baixar os áudios do ramal, filtrar chamadas feitas/recebidas, atualizar a lista ou carregar anteriores. A lista mostra sentido, origem/destino da chamada, data, duração, estado e identificador da chamada. Fechar a janela ou trocar o filtro interrompe a reprodução. Desativar o ramal ou desligar a gravação preserva os áudios anteriores; o painel informa separadamente a opção atual e o histórico disponível.

GET /ramais/{id}/gravacoes?direcao=todas&pagina=1 requer os dois escopos ramais:ler e gravacoes:ler, ou sessão de administrador/supervisor da empresa. Retorna dados:{ramal,gravacoes,pagina,proxima_pagina}. ramal contém id, nome, numero, ativo, gravar_realizadas e gravar_recebidas. Cada gravação contém os metadados acima e origem, destino, iniciada_em e encerrada_em da chamada. duracao é um número em segundos e tamanho é inteiro em bytes. Não retorna canal interno, caminho de armazenamento ou credenciais.

São até 50 trechos por página, ordenados por criada_em e id decrescentes. direcao aceita todas (padrão), realizada ou recebida. pagina vai de 1 a 100.000; siga proxima_pagina até null e elimine duplicações por id caso novas gravações entrem durante a paginação. A consulta usa o UUID do ramal, inclusive desativado, e retorna somente gravações cujo ramal_id corresponde a ele. A participação numa chamada não faz aparecer aqui os trechos autorizados por outro ramal; para todos os trechos da chamada use /chamadas/{id}/gravacoes.

RAMAL_ID='SUBSTITUA_PELO_UUID_DO_RAMAL'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $CHAVE_API" \
  "$BASE/ramais/$RAMAL_ID/gravacoes?direcao=recebida&pagina=1"

# Escolha um id com estado disponivel na resposta autorizada:
GRAVACAO_ID='SUBSTITUA_PELO_UUID_DA_GRAVACAO'
curl --fail --silent --show-error \
  -H "Authorization: Bearer $CHAVE_API" \
  "$BASE/gravacoes/$GRAVACAO_ID/arquivo?baixar=1" --output gravacao.wav

Uma lista vazia não habilita gravação retroativa. gravando, falhou e sem_audio são estados informativos, sem botão de reprodução. Somente disponivel permite ouvir/baixar. 401 pede autenticação, 403 indica escopo/perfil insuficiente, 404 protege ramal de outra empresa/inexistente e 422 indica filtro inválido. O acesso binário continua autenticado e auditado como descrito abaixo.

GET /gravacoes/{id}/arquivo?baixar=1 retorna o WAV binário (não um objeto JSON), somente após o estado disponivel. Requer a mesma sessão/permissão ou Bearer com gravacoes:ler, registra auditoria de acesso e suporta Range: bytes=0-1023 (206). Sem Range, retorna 200; 409 indica gravação ainda indisponível e 404 também protege IDs de outra empresa. Não coloque tokens na URL. Arquivos ficam fora da pasta pública. O backup diário completo exclui as gravações WAV; planeje uma coleta separada se precisar preservá-las externamente. Não há exclusão automática por idade nesta versão; monitore o armazenamento. Se houver menos de 256 MiB livres, uma nova gravação falha sem derrubar a chamada e gera evento gravacao.falhou.

Escopos são literais, como ramais:ler, ramais:escrever, horarios:ler, horarios:escrever, filas:ler, filas:escrever, uras:ler, uras:escrever, chamadas:ler, chamadas:escrever e eventos:ler. Escrever não concede leitura. Operações de fila usam operar_filas:escrever; iniciar, pausar e encerrar campanha usam operar_campanhas:escrever. Importar contatos usa campanhas:escrever.

O cadastro de chaves admite ler/escrever para cada recurso do catálogo e para painel, chamadas, eventos, operar_filas e operar_campanhas. Nem todo par representa uma rota existente: conceda apenas os escopos indicados na referência. Usuários, chaves, auditoria, entrega de webhooks e administração global são operações de sessão; não há escopo Bearer disponível para essas operações.

O limite é de 120 requisições por janela de 60 segundos por chave. HTTP 429 pede espera antes de tentar novamente. O bloqueio de login usa limites adicionais por usuário e IP.

Respostas, identificadores e erros

{
  "sucesso": true,
  "dados": {
    "id": "00000000-0000-4000-8000-000000000001",
    "empresa_id": 123,
    "nome": "Recepção",
    "configuracao": {"numero": "101", "webphone": true},
    "ativo": true,
    "versao": 1
  }
}

Cadastros usam UUID; empresas e registros de auditoria usam identificadores numéricos. Os campos de data/hora retornam valores com fuso. configuracao contém os campos específicos de cada cadastro. dados pode ser objeto ou lista, conforme a operação. Os exemplos de resposta omitem campos para facilitar a leitura.

{
  "sucesso": false,
  "erro": {
    "codigo": "VERSAO_CONFLITANTE",
    "mensagem": "Este registro foi alterado. Atualize antes de salvar.",
    "requisicao_id": "00000000-0000-4000-8000-000000000002"
  }
}
HTTPSignificado e tratamento
200Consulta ou operação concluída
201Cadastro criado
202Chamada aceita para processamento; ainda não significa atendimento
401Chave inválida ou sessão ausente/expirada
403Escopo ou perfil insuficiente; CSRF inválido; troca inicial de senha pendente
404Recurso inexistente, de outro cliente ou rota não encontrada
405Método não aceito nas rotas que fazem essa distinção; outras rotas podem responder 404
409Versão desatualizada, duplicidade, dependência ativa, contexto trocado ou idempotência conflitante
413Corpo JSON maior que 1 MiB
422Dados ou referências inválidos, ou ausência de rota de saída
429Limite de requisições ou tentativas atingido
500Falha interna; informe o código de suporte/requisição

Todas as respostas incluem X-Request-ID. Registre esse identificador junto com o método e a rota. Não registre Authorization, senhas, credenciais SIP ou segredos de webhook. Validações também podem usar o código genérico DADOS_INVALIDOS; não presuma um código único por causa de erro.

Criar, editar e desativar cadastros

POST recebe {nome, configuracao, ativo?}. PUT recebe o cadastro completo com versao obtida no GET. PUT não é PATCH: campos omitidos podem voltar ao padrão. O servidor mantém internamente as credenciais que não podem ser retornadas; para troncos, senha vazia preserva a senha SIP atual. IDs, empresa_id e timestamps são definidos pelo servidor.

# Consulte antes de editar. Este exemplo usa jq para preservar todos os campos.
curl --fail-with-body --silent --show-error "$BASE/ramais/$ID" \
  -H "Authorization: Bearer $CHAVE_API" > ramal.json
jq '.dados | {nome:"Recepção atualizada", configuracao, versao, ativo}' \
  ramal.json > atualizacao.json
curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' --data-binary @atualizacao.json

Em 409, refaça o GET e revise as diferenças antes de reaplicar. DELETE desativa; não exclui histórico. Cadastros referenciados por recursos ativos ou usuários ativos podem recusar a desativação. Não existe DELETE para usuários: use a atualização com ativo:false.

Listagens de cadastros retornam até 500 itens, incluindo desativados, ordenados por criação decrescente. Não há paginação dessas listas nesta versão. Chamadas têm paginação de 100 por pagina; eventos e entregas retornam os últimos 100. Auditoria usa páginas de 50 e cursor antes_de.

Alterações em ramais, filas, domínios e operadoras geram provisionamento assíncrono. O sucesso do cadastro não confirma registro SIP; consulte Diagnósticos no painel e o diagnóstico do tronco quando necessário.

Destinos, URA e horários reutilizáveis

Destino simples: {tipo:"encerrar"} ou {tipo:"ramal|fila|ura|horario|audio", id:"UUID"}. Sempre use um recurso ativo da mesma empresa. Os destinos também aceitam horario_id e destino_fechado: dentro do horário usa-se o destino principal; fora dele usa-se destino_fechado. O mecanismo recusa ciclos durante o roteamento.

A URA tem audio_id, opcoes como objeto cujas chaves são 0–9, * ou #, e destino para ausência de opção válida. A mensagem precisa anunciar as mesmas teclas configuradas. Crie a mensagem por texto em /audios/gerar-voz, envie um arquivo ou grave pelo painel; depois use o id retornado em audio_id. O timeout varia de 1 a 120 segundos. A execução limita repetições a três além da primeira reprodução.

Horários novos usam periodos, com até 50 faixas. Cada faixa tem dias (1=segunda, 7=domingo), inicio e fim no formato HH:MM. Exemplo: segunda das 08:00 às 12:00 e das 13:00 às 22:00 são duas faixas com dias [1]. Outros dias podem ter faixas diferentes. Sobreposições são recusadas. O início está incluído e o fim está excluído: às 12:00 a primeira faixa já está fechada.

Uma faixa 22:00–06:00 termina no dia seguinte; o dia selecionado é o dia do início. Feriados são datas YYYY-MM-DD, uma por linha, e fecham o dia civil inteiro no fuso do cliente. Por padrão, o fuso é America/Sao_Paulo. periodos tem precedência sobre dias, inicio, fim e intervalos legados. Configurações antigas continuam válidas; não misture os dois formatos em novas integrações.

Quando horário é usado como condição (horario_id), somente os dias, faixas e feriados da regra são consultados; os destinos são definidos na tecla ou na fila. Quando o destino é {tipo:"horario",id}, usam-se os destinos destino_aberto/destino_fechado da própria regra. Assim é possível reutilizar a mesma agenda com destinos diferentes.

Uma fila aceita horario_id e destino_fechado. Isso vale para qualquer encaminhamento à fila, inclusive outras URAs, rotas de entrada e campanhas. Quando fechada, seu status retorna aberta:false e prontos:0; campanhas aguardam capacidade e horário. Chamadas que já entraram na fila não são retiradas na virada do horário. O destino por falta de atendimento continua sendo configuracao.destino e é separado do destino fora do expediente.

{
  "nome": "Suporte",
  "configuracao": {
    "ramais": ["UUID_DO_RAMAL"],
    "horario_id": "UUID_DO_HORARIO",
    "destino_fechado": {"tipo": "encerrar"},
    "destino": {"tipo": "encerrar"},
    "estrategia": "rrmemory",
    "timeout": 20,
    "espera": 60,
    "descanso": 5
  }
}

Ao salvar uma URA, o campo superior opcional horarios_filas permite atualizar os horários de filas vinculadas em uma única transação com a URA. Cada item deve conter fila_id, versao, horario_id (vazio remove a regra) e destino_fechado. Requer também filas:escrever. Conflito na versão da fila impede toda a gravação. Para manter horários somente naquela tecla, coloque horario_id/destino_fechado no destino da opção e omita horarios_filas. Se uma fila já tiver seu próprio horário, ambas as condições serão respeitadas.

{
  "horarios_filas": [
    {
      "fila_id": "UUID_DA_FILA",
      "versao": 3,
      "horario_id": "UUID_DO_HORARIO",
      "destino_fechado": {"tipo": "encerrar"}
    }
  ]
}

Esse fragmento complementa o corpo completo de criação/edição da URA; não é um corpo completo sozinho.

Áudio fora do expediente e encerramento

Em **Horários → Editar → O que acontece com a ligação? → Fora do expediente**, selecione uma opção do grupo **Áudio · tocar e encerrar**. O botão **Gerar, gravar ou enviar áudio** abre o cadastro de mensagem no próprio formulário; pode usar a voz local, o microfone ou um arquivo. **Ouvir áudio selecionado** permite conferir antes de salvar.

O destino é { "tipo": "audio", "id": "UUID_DO_AUDIO" }. O identificador é de um áudio ativo da mesma empresa. O PABX atende, reproduz a mensagem inteira uma vez e encerra normalmente. Não é uma URA: não exige uma tecla, não solicita senha e não repete a mensagem. Use uma URA quando for necessário anunciar e receber escolhas. Caminhos de arquivo e URLs não são aceitos no campo id.

Quando uma rota de entrada aponta para {tipo:"horario",id}, o áudio deve ficar em configuracao.destino_fechado da regra. Quando a agenda é reutilizada como condição horario_id em uma fila ou tecla, configure destino_fechado naquele local. As ações próprias da regra não são herdadas por essas condições; isso permite reutilizar os mesmos horários com mensagens diferentes. O áudio também é aceito em outros seletores de destino, inclusive alternativas por falta de atendimento, sempre com reprodução e encerramento.

**Encerrar ligação** confirma o recebimento e termina sem mensagem (SIP 200/ACK/BYE, causa 16). Antes da correção, encerrar uma entrada ainda não atendida enviava SIP 603. A recusa pode receber outro tratamento da operadora; mensagens de senha ou caixa postal não são geradas pelo dialplan do PABX Atendai. A confirmação técnica é registrada em atendida_em; ela não prova atendimento humano. A operadora pode contabilizar esse breve atendimento conforme o contrato, assim como a reprodução de um aviso.

Se quem ligou desligar durante o áudio, a reprodução para e não há nova tentativa. Se o arquivo estiver indisponível, a chamada termina normalmente e o evento call.audio_failed informa audio_id e motivo (arquivo_indisponivel ou falha_reproducao). Uma reprodução completa emite call.audio_played, com audio_id e motivo:reproduzido, correlacionado por chamada_id. Um desligamento durante a mensagem não gera o evento de reprodução completa. Nenhum desses eventos comprova que uma pessoa ouviu o conteúdo.

cURL: gerar aviso e vincular à regra existente

O exemplo exige audios:escrever, horarios:ler e horarios:escrever, além das variáveis BASE e CHAVE_API apresentadas no início do guia. Confira o texto e os horários reais antes de publicar. O aviso abaixo não inventa dias ou horários da empresa.

HORARIO_ID='UUID_DA_REGRA_DE_HORARIO'
RESPOSTA_AUDIO=$(curl --fail-with-body --silent --show-error -X POST "$BASE/audios/gerar-voz" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data '{"nome":"Aviso fora do expediente","texto":"Olá! No momento estamos fora do nosso horário de atendimento. Por favor, entre em contato durante o expediente. Agradecemos a sua ligação.","voz":"faber","velocidade":1}')
AUDIO_ID=$(printf '%s' "$RESPOSTA_AUDIO" | jq -er '.dados.id')
curl --fail-with-body --silent --show-error "$BASE/horarios/$HORARIO_ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq --arg audio "$AUDIO_ID" '.dados | {nome,ativo,versao,configuracao} | .configuracao.destino_fechado={tipo:"audio",id:$audio}' > horario-audio.json
curl --fail-with-body --silent --show-error -X PUT "$BASE/horarios/$HORARIO_ID" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @horario-audio.json

Em uma fila, use esse mesmo destino em configuracao.destino_fechado e mantenha horario_id. Em uma tecla, use configuracao.opcoes["1"].destino_fechado junto do horario_id da opção. horarios_filas permite salvar a ação da fila pela URA, com a versão e permissão próprias, como os outros destinos. Campanhas fechadas continuam aguardando expediente e capacidade, sem discar apenas para transmitir o aviso.

Para terminar sem mensagem, volte a { "tipo": "encerrar" }. Preserve os demais campos e versao no PUT. /simular com tipo destino, destino horário e data com fuso retorna tipo:audio ou tipo:encerrar fora do expediente; a simulação não toca áudio nem faz ligação.

Encaminhar quando ninguém atender

No painel, edite um ramal ou fila e abra **Se ninguém atender**. Na URA, use **4. Se o destino escolhido não atender**, ou abra uma tecla e configure a alternativa apenas dela. Os destinos podem ser outro ramal, fila, URA, regra de horário ou áudio para tocar e encerrar, sempre ativos e do mesmo cliente. É possível cadastrar o destino sem sair da configuração.

LocalCampo em configuracaoQuando é usado
Ramaldestino_nao_atendidoChamada direta ao ramal sem resposta, ocupado, desconectado ou com falha de conexão
FiladestinoTempo máximo esgotado ou fila cheia, vazia ou indisponível, conforme o resultado do Asterisk
URA, alternativa geraldestino_nao_atendidoA pessoa escolhe uma tecla e o destino, incluindo suas alternativas, não atende
URA, alternativa de uma teclaopcoes["1"].destino_nao_atendidoSubstitui a alternativa geral somente naquela tecla
URA, sem escolha válidadestinoNinguém digita uma tecla válida após as repetições; é independente da falta de atendimento

**Ordem:** primeiro o destino escolhido e suas alternativas próprias; se ninguém atender, a alternativa específica da tecla; se a tecla não tiver alternativa específica, a alternativa geral da URA. A alternativa específica substitui a geral, inclusive se também não atender. Exemplo: tecla 1 → fila Vendas → reserva da fila → alternativa da tecla (ou geral).

O padrão de ramais, filas e URAs é { "tipo": "encerrar" }, apresentado como **Sem outro encaminhamento**. Nesse campo do recurso, ele significa que não há alternativa própria: a URA que o chamou ainda pode tratar a falha. Sem alternativa restante, a ligação termina. Dentro da tecla, a ausência de destino_nao_atendido ou o valor null herda a geral; { "tipo": "encerrar" } explícito na tecla encerra sem usar a geral. Escolher encerrar como destino principal, inclusive fora do horário, encerra diretamente.

O ramal espera timeout (1–120 segundos); se ocupado/desconectado, pode desviar antes desse prazo. A fila usa timeout por tentativa de atendente e espera (1–300 segundos) para o limite de espera; não use zero para esperar indefinidamente. Cadastros antigos fora desse intervalo são limitados entre 1 e 300 durante o roteamento e devem ser corrigidos ao editar. Os tempos são controlados pelo Asterisk e podem incluir o encerramento da tentativa em curso.

A regra do ramal se aplica a chamadas diretas, inclusive internas, recebidas, transferidas e à etapa de destino do originate. Dentro de uma fila, a fila controla o desvio; o encaminhamento pessoal de cada membro não é executado em paralelo. No originate, o primeiro ramal continua sendo a origem e precisa atender antes de iniciar o destino. Campanhas de URA reversa usam a política própria de reserva e espera_atendente; não executam essa cadeia de alternativas da fila. Sua falta de atendimento continua gerando sem_atendente e retentativa conforme a campanha.

**Não há desvio após atendimento ou desligamento de quem ligou.** As regras de horário de cada novo destino continuam valendo. Cada chamada tem limite de 12 destinos executados; ciclos automáticos são recusados ao salvar com HTTP 409 e erro.codigo=CICLO_ENCAMINHAMENTO. A escolha manual de voltar a um menu não é um ciclo automático de cadastro, mas permanece sujeita ao limite durante a ligação. A simulação de destino resolve horários, sem simular resposta, ocupação ou tempo de espera de um telefone.

Os campos são aceitos nos POST/PUT existentes; não há endpoint separado para “ativar o desvio”. PUT substitui a configuração: faça GET, preserve os campos e envie a versao atual. Requer ramais:escrever, filas:escrever ou uras:escrever, além de leitura para consultar o cadastro. Referência de outro cliente retorna 404; inativa ou tipo inválido retorna 422. Alterações são auditadas com o responsável autenticado.

cURL: ramal sem resposta para uma fila reserva

Substitua os UUIDs pelos recursos do cliente. Os exemplos abaixo usam Bash e jq e alteram configurações reais; os ramais e filas de reserva devem ser distintos do destino original e não podem formar ciclos.

RAMAL_ID='UUID_DO_RAMAL_PRINCIPAL'
FILA_RESERVA_ID='UUID_DA_FILA_RESERVA'
curl --fail-with-body --silent --show-error "$BASE/ramais/$RAMAL_ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq --arg fila "$FILA_RESERVA_ID" '.dados | {nome,ativo,versao,configuracao} | .configuracao.timeout=20 | .configuracao.destino_nao_atendido={tipo:"fila",id:$fila}' > ramal-desvio.json
curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$RAMAL_ID" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @ramal-desvio.json

cURL: fila sem atendimento para um ramal reserva

FILA_ID='UUID_DA_FILA_PRINCIPAL'
RAMAL_RESERVA_ID='UUID_DO_RAMAL_RESERVA'
curl --fail-with-body --silent --show-error "$BASE/filas/$FILA_ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq --arg ramal "$RAMAL_RESERVA_ID" '.dados | {nome,ativo,versao,configuracao} | .configuracao.espera=60 | .configuracao.destino={tipo:"ramal",id:$ramal}' > fila-desvio.json
curl --fail-with-body --silent --show-error -X PUT "$BASE/filas/$FILA_ID" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @fila-desvio.json

Para encaminhar a outra URA, use { "tipo": "ura", "id": "UUID_DA_URA_RESERVA" } no mesmo campo.

cURL: alternativa geral da URA e alternativa específica da tecla 1

O exemplo exige uma tecla 1 já configurada. Preserva a mensagem, as demais teclas, horários e o destino sem escolha válida. A tecla 1 passa a usar o ramal reserva; teclas sem alternativa específica usam a fila reserva.

URA_ID='UUID_DA_URA_PRINCIPAL'
curl --fail-with-body --silent --show-error "$BASE/uras/$URA_ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq --arg fila "$FILA_RESERVA_ID" --arg ramal "$RAMAL_RESERVA_ID" \
    '.dados | {nome,ativo,versao,configuracao} | .configuracao.destino_nao_atendido={tipo:"fila",id:$fila} | .configuracao.opcoes["1"].destino_nao_atendido={tipo:"ramal",id:$ramal}' > ura-desvio.json
curl --fail-with-body --silent --show-error -X PUT "$BASE/uras/$URA_ID" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @ura-desvio.json

Para voltar a herdar a alternativa geral, remova opcoes["1"].destino_nao_atendido (ou envie null) no próximo PUT completo. Para impedir a alternativa geral somente nessa tecla, envie { "tipo": "encerrar" } nesse campo. Para remover a alternativa própria de um ramal/URA, envie configuracao.destino_nao_atendido={"tipo":"encerrar"}; na fila, use configuracao.destino={"tipo":"encerrar"}.

Acompanhar os desvios

Cada tentativa de encaminhamento automático gera call.forwarded no histórico de eventos e nos webhooks inscritos. O mesmo chamada_id é preservado. Os dados contêm id da chamada, origem:{tipo,id}, destino:{tipo,id}, motivo e etapa. Motivos de ramal: NOANSWER, BUSY, CHANUNAVAIL, CONGESTION; de fila: TIMEOUT, FULL, JOINEMPTY, LEAVEEMPTY, JOINUNAVAIL, LEAVEUNAVAIL; de alternativa da URA: destino_sem_atendimento; de alternativa específica: alternativa_destino. O evento informa a tentativa, não comprova atendimento do novo destino. Datas e participantes continuam no histórico de chamadas e de ramais.

curl --fail-with-body --silent --show-error "$BASE/eventos" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq '.dados[] | select(.tipo=="call.forwarded")'

Simulação antes de usar na telefonia

POST /simular não faz ligação. Use tipo:saida com ramal_id e numero; tipo:entrada com tronco_id e did; tipo:horario com horario_id e data; ou tipo:destino com destino e data. data deve conter fuso explícito, como 2026-10-12T12:30:00-03:00. O resultado de entrada informa o destino cadastrado; para resolver horários desse destino, faça uma simulação de tipo destino.

curl --fail-with-body --silent --show-error -X POST "$BASE/simular" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{"tipo":"saida","ramal_id":"UUID_DO_RAMAL","numero":"102"}'

Integração de WebPhone em aplicações externas

Este capítulo explica o telefone publicado no PABX Atendai e entrega um exemplo adaptável, com as mesmas chamadas de biblioteca e contratos usados pelo painel. A interface de exemplo é simples; os controles e os eventos podem ser ligados aos componentes do seu CRM, React, Vue ou JavaScript puro. Contrato da API: 0.16.0. Dependências verificadas no package-lock.json em 14/10/2026; use npm ci no projeto existente para reproduzi-las.

Captura de chamadas no telefone integrado

A credencial SIP legível T{empresa_id}_{sufixo} é usada por telefones SIP comuns. No navegador, continue usando usuario, senha, dominio e wss devolvidos por GET /webphone; o adaptador mantém a identidade WebRTC estável. Não construa o usuário do navegador a partir do número do ramal.

Quando a empresa habilitar captura, aceite no campo de número os códigos configurados nessa empresa. Os padrões são #0 para geral e #1 seguido de um ramal (exemplo #11002 para 1002). Administradores e integrações com ramais:ler consultam GET /empresa/telefonia; não fixe códigos na integração nem exija esse escopo de atendentes: POST /webphone/preparar valida a configuração atual para a sessão do ramal. Envie o texto completo a POST /webphone/preparar e então use ua.call(dados.numero, opcoes), com as mesmas opções de áudio das ligações normais. tipo=captura identifica essa preparação. Os exemplos abaixo já usam o número retornado sem remover os sinais #. Não envie o código por sendDTMF nem por originate/transfer. Trate CAPTURA_DESATIVADA, RAMAL_CAPTURA_INVALIDO, SEM_CHAMADA_PARA_CAPTURAR e CAPTURA_INDISPONIVEL exibindo a mensagem do servidor. O JsSIP normaliza # para %23 no usuário da URI SIP; mantenha o código original em ua.call, sem codificar a URI inteira. Telefones físicos que usam # como tecla de envio precisam permitir os códigos completos no plano de discagem do aparelho. O prefixo antigo ##0 só funciona se o administrador o configurar explicitamente em Ramais → Telefonia desta empresa. A consulta não reserva a chamada: o atendimento por outra pessoa pode fazer a captura falhar em seguida.

Escolha o tipo de integração

ObjetivoCaminho disponívelOnde passa o áudio
Abrir o telefone pronto a partir de um CRMLink para https://pabx.atendai.chat/webphone; login individual do atendenteNavegador do atendente e Asterisk
Botão de ligar usando telefone já conectadoBackend do CRM chama POST /chamadas/originate com BearerRamal de origem e destino, ligados pelo Asterisk
Telefone dentro de uma interface própriaJsSIP, WebRTC e os adaptadores de sessão descritos aquiNavegador da interface e Asterisk

O link do WebPhone já funciona a partir de outro sistema. Não aceita login, senha, número de destino ou comando de ligação pela URL. A pessoa entra e digita o destino na tela. O endpoint originate toca primeiro o ramal; não abre o microfone do navegador da aplicação externa e não substitui ua.call().

<a href="https://pabx.atendai.chat/webphone" target="_blank" rel="noopener">
  Abrir telefone da empresa
</a>

Bibliotecas e responsabilidades da implementação

ComponenteVersão instaladaComo usamos
JsSIP3.13.8; package.json permite ^3.10.1UA SIP, REGISTER, INVITE, respostas, sessões WebRTC, DTMF, hold e REFER
APIs nativas do navegadorSem pacote npmgetUserMedia, RTCPeerConnection, MediaStream, elemento audio e AudioContext
esbuild0.25.12Empacota import JsSIP from 'jssip' e o código da interface em JavaScript para navegador
htmx.org2.0.11Infraestrutura do painel; não transporta SIP nem áudio e não é necessário no exemplo
Tailwind CSS4.3.3Compilação de estilos do painel; não controla as chamadas
Node.js22.23.3Ferramenta de compilação; não é o servidor de mídia
Playwright1.63.0Testes de registro, interface, chamadas e áudio entre navegadores

No repositório, interface/telefone.js concentra o comportamento do telefone; interface/conexao-webphone.js supervisiona transporte e registro, com o relógio de interface/relogio-webphone.js. interface/aplicacao.js fornece o adaptador HTTP com sessão, CSRF, contexto do cliente e erro.codigo. src/Aplicacao/Http.php aplica as permissões; DialplanRouter resolve números/rotas; CapacidadeSaida consulta e reserva linhas; RealtimeProvisioner configura PJSIP e WebRTC. A compilação do painel é npm run construir; a do exemplo isolado está abaixo. Não copie o bundle inteiro do painel para outro sistema: compile o exemplo ou integre JsSIP nos componentes da sua aplicação.

Conexões, autenticação e limites entre origens

Há três conexões diferentes. A API HTTPS entrega configuração e valida a discagem. O WebSocket SIP, wss://pabx.atendai.chat/ws, leva a sinalização SIP via Nginx até o PJSIP. O áudio segue por WebRTC/DTLS-SRTP entre navegador e Asterisk; não é transmitido pela API REST nem pelo WebSocket de eventos do painel.

Aplicação do atendente -- HTTPS + sessão --> API: credencial do próprio ramal e preparação
Aplicação + JsSIP      -- WSS /ws + SIP --> Nginx: sessão --> Asterisk PJSIP
Navegador             == WebRTC/DTLS-SRTP/ICE == Asterisk == destino SIP/tronco
Backend do CRM        -- HTTPS + Bearer --> API: originate, histórico e webhooks

O login atual usa formulário POST /entrar, cookie atendai_sessao e CSRF. Não há login JSON, JWT, OAuth, token SIP temporário ou SDK de autenticação publicado. O cookie é Secure, HttpOnly e SameSite=Lax. GET /api/v1/webphone exige sessão autorizada e devolve a credencial SIP do ramal. O upgrade de /ws também depende da sessão: Nginx consulta internamente /autorizar-ws. Senha SIP correta sem essa sessão não basta para abrir o WebSocket.

Uma chave Bearer não substitui a sessão em /webphone e não autentica /ws. O construtor WebSocket do navegador não aceita um cabeçalho Authorization arbitrário; o JsSIP instalado usa new WebSocket(url, 'sip'). O WebSocket /eventos-ws e seu ticket de 30 segundos são outro serviço, destinado a eventos administrativos, não à sinalização de chamadas.

O exemplo abaixo pressupõe a mesma origem HTTPS do PABX e valores de sessão inseridos pelo servidor. Não funciona por simplesmente abrir um arquivo HTML local ou trocar a URL da API para o domínio do PABX em uma página de outro site. Não há CORS publicado para essa integração, cookies entre sites têm restrições, e o painel usa frame-ancestors 'none': o WebPhone pronto não pode ser colocado em iframe. Mesmo subdomínios diferentes são origens diferentes para fetch.

Para uma aplicação própria, há dois caminhos de implantação: hospedar a tela sob a origem autorizada, com o mesmo contexto autenticado; ou implementar um backend/proxy de integração que mantenha sessões individuais por usuário, autorize empresa/ramal no servidor e autentique também o upgrade WSS. Esse segundo caminho exige implementação e homologação específicas; não existe um endpoint pronto de bootstrap externo nesta versão. Não use uma sessão de administrador compartilhada, não libere CORS com credenciais para qualquer origem e não remova /autorizar-ws para fazer o exemplo conectar. Em um proxy novo, valide a origem do navegador, preserve o subprotocolo sip e não exponha os serviços internos AMI/ARI/Asterisk HTTP.

Preparação do usuário e contratos utilizados

Crie o ramal com webphone:true e, para chamadas à operadora, externas:true. Cadastre o acesso individual em Ramais → Acesso WebPhone. A conta de atendente recebe seu ramal fixo e conectar_automaticamente:true; passar outro ramal_id na URL não autoriza trocar de ramal. Administradores podem selecionar um ramal ativo da empresa em gestão. A senha de login do usuário é diferente da senha SIP e nunca deve ser usada como password do JsSIP.

Operação relativa a /api/v1Uso pelo navegadorContrato relevante
GET /webphone?ramal_id=UUIDObtém a identidade WebRTC autorizadadados: ramal_id, numero, usuario, senha, dominio, wss
POST /webphone/prepararValida número, permissão, rota e capacidadeCorpo: ramal_id e numero; dados: numero, numero_enviado, tipo, destino
GET /webphone/filas?ramal_id=UUIDLista as filas do próprio atendentedados: lista com id, nome, ramal_id e pausado
POST /filas/UUID/disponibilidadePausa/retoma o próprio ramalCorpo: ramal_id e pausado; motivo opcional; permissão operar_filas

Todas usam a sessão do usuário. Para mutações, envie X-CSRF-Token. X-Empresa-ID confere o cliente já selecionado; não muda o cliente. O JSON usa sucesso/dados ou sucesso:false/erro. Em 401, refaça o login; em CSRF_INVALIDO ou CONTEXTO_ALTERADO, recarregue o contexto antes de repetir. Nunca capture o corpo de /webphone em logs, analytics ou ferramentas de erro.

Resposta ilustrativa de GET /webphone, com valores fictícios:

{"sucesso":true,"dados":{"ramal_id":"00000000-0000-4000-8000-000000000001","numero":"101","usuario":"t123-e00000000000040008000000000000001","senha":"CREDENCIAL_SIP_SOMENTE_EM_MEMORIA","dominio":"empresa.exemplo.com","wss":"wss://pabx.atendai.chat/ws"}}

Use exatamente usuario/dominio/wss retornados. O usuário WebRTC não é o login web nem o número 101, e é diferente do usuário do telefone SIP UDP. Não chame /credencial para conectar: esse endpoint troca a senha e afeta outros dispositivos. A UA precisa manter material de autenticação enquanto estiver em uso; apagar acesso.senha depois da construção apenas evita uma cópia adicional, não elimina a credencial de dentro do JsSIP.

cURLs para preparar e diagnosticar sem discar

Autentique conforme a seção API de sessão e administração do guia completo. Estes comandos pressupõem sessao.txt, CSRF, EMPRESA_ID e RAMAL_ID já obtidos no contexto correto. Não coloque a chave Bearer em nenhum desses comandos de sessão.

BASE='https://pabx.atendai.chat/api/v1'
curl --fail-with-body --silent --show-error -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID" "$BASE/webphone?ramal_id=$RAMAL_ID" \
  | jq 'if .dados then .dados |= del(.senha) else . end'

curl --fail-with-body --silent --show-error -X POST -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' "$BASE/webphone/preparar" \
  --data "{\"ramal_id\":\"$RAMAL_ID\",\"numero\":\"102\"}"

Preparar não inicia uma chamada nem reserva uma linha. Use dados.numero em ua.call(); numero_enviado serve para diagnóstico. Discar numero_enviado aplicaria a transformação da rota novamente. LINHAS_OCUPADAS/409 pede aviso e nova tentativa manual, sem retentativa automática. Se a capacidade acabar depois da preparação, o SIP retorna ocupado e a aplicação trata failed/Busy/486.

Montar e compilar o exemplo

Salve os cinco arquivos na mesma pasta: webphone.html, webphone.js, conexao-webphone.js, relogio-webphone.js e correlacao-webphone.js. Os blocos completos estão abaixo. O HTML entregue como exemplo não contém sessão válida; antes de servir a tela, o seu backend deve autenticar a pessoa e preencher CSRF_DA_SESSAO_AUTENTICADA, ID_DA_EMPRESA_DA_SESSAO e UUID_DO_RAMAL_AUTORIZADO usando os valores do contexto autorizado, escapados para HTML. Não receba esses valores como autorização de um parâmetro arbitrário do navegador.

mkdir exemplo-webphone
cd exemplo-webphone
npm init -y
npm install --save-exact jssip@3.13.8
npm install --save-dev --save-exact esbuild@0.25.12
# Depois de salvar os quatro arquivos nesta pasta:
npx esbuild webphone.js --bundle --minify --outfile=webphone-compilado.js

Sirva o HTML autenticado, webphone-compilado.js e relogio-webphone.js em HTTPS sob a origem configurada para a integração. O exemplo busca o relógio em /relogio-webphone.js; ajuste urlRelogio se usar outro caminho, com Content-Type de JavaScript e CSP permitindo worker-src 'self'. O arquivo baixado da documentação é um anexo de texto para copiar, não uma URL de execução. O PABX atual não instala automaticamente essa página personalizada. Para desenvolvimento, localhost permite algumas APIs de mídia, mas isso não fornece a sessão do PABX nem remove os requisitos de origem/WSS. Conserve o package-lock.json gerado e use npm ci nas compilações seguintes.

Exemplo HTML do telefone

<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="csrf-token" content="CSRF_DA_SESSAO_AUTENTICADA">
  <title>Exemplo de integração WebPhone</title>
</head>
<!-- O servidor preenche estes valores a partir do usuário autorizado. -->
<body data-empresa="ID_DA_EMPRESA_DA_SESSAO" data-ramal="UUID_DO_RAMAL_AUTORIZADO">
  <h1>Telefone da aplicação</h1>
  <p id="conexao" role="status">Desconectado</p>
  <button id="conectar" type="button">Conectar</button>
  <button id="ativar-audio" type="button">Ativar áudio e microfone</button>
  <p id="aviso-audio" role="status">Permita o microfone para conversar.</p>
  <p id="estado" role="status">Aguardando conexão</p>
  <p id="detalhe"></p><output id="duracao">00:00</output>
  <label>Número <input id="numero" type="tel" maxlength="30" autocomplete="off"></label>
  <button id="ligar" type="button" disabled>Ligar</button>
  <button id="atender" type="button" disabled>Atender</button>
  <button id="rejeitar" type="button" disabled>Rejeitar</button>
  <button id="encerrar" type="button" disabled>Encerrar</button>
  <button id="mudo" type="button" disabled>Mudo</button>
  <button id="espera" type="button" disabled>Espera</button>
  <label>Teclas DTMF <input id="digitos" maxlength="20" placeholder="123#"></label>
  <button id="enviar-dtmf" type="button" disabled>Enviar DTMF</button>
  <label>Transferir para o ramal <input id="ramal-transferencia" inputmode="numeric" maxlength="6"></label>
  <button id="transferir" type="button" disabled>Transferir</button>
  <audio id="audio-remoto" autoplay></audio>
  <script src="./webphone-compilado.js" defer></script>
</body>
</html>

Exemplo JavaScript com JsSIP

O exemplo atende uma chamada por vez, rejeita a segunda com 486, trata autoplay, habilita áudio somente por gesto da pessoa, usa os mesmos eventos principais do painel e não armazena senhas em localStorage. Ajuste apresentação e acessibilidade aos componentes da sua aplicação. O código não liga automaticamente ao montar a página.

import JsSIP from 'jssip';
import {acompanharConexao} from './conexao-webphone.js';
import {resolverCorrelacaoSip} from './correlacao-webphone.js';

// Adaptador para a sessão do PABX na mesma origem HTTPS.
const elemento=id=>document.getElementById(id);
const ramalId=document.body.dataset.ramal;
const csrf=document.querySelector('meta[name="csrf-token"]').content;
async function requisitar(caminho,corpo) {
  const resposta=await fetch('/api/v1'+caminho,{
    method:corpo===undefined?'GET':'POST',credentials:'same-origin',cache:'no-store',
    headers:{'Content-Type':'application/json','X-CSRF-Token':csrf,'X-Empresa-ID':document.body.dataset.empresa},
    ...(corpo===undefined?{}:{body:JSON.stringify(corpo)})
  });
  const resultado=await resposta.json();
  if(!resposta.ok || !resultado.sucesso){const falha=new Error(resultado.erro?.mensagem || 'Falha na API.');falha.codigo=resultado.erro?.codigo;throw falha;}
  return resultado.dados;
}

let agente,sessao,contextoAudio,pulsoToque,relogio,preparando=false,conectando=false;
let osciladores=[],pararSupervisao,retomarPagina=false,geracaoConexao=0;
const audio=elemento('audio-remoto');
const midia={mediaConstraints:{audio:true,video:false},pcConfig:{iceServers:[]}};
const mensagens={Busy:'A linha ou o destino está ocupado. Tente novamente em instantes.',
  'Not Found':'Destino não localizado. Confira o número e a rota.',Rejected:'Chamada recusada.',
  Unavailable:'Destino indisponível.', 'No Answer':'Ninguém atendeu.',Canceled:'Chamada cancelada.',
  'User Denied Media Access':'Permita o microfone.', 'WebRTC Error':'Não foi possível estabelecer o áudio.',
  'Authentication Error':'Registro recusado. Confira o acesso do ramal.',Terminated:'Chamada encerrada.'};

function atualizarBotoes(){
  const ativa=sessao && !sessao.isEnded(),atendida=ativa && sessao.isEstablished();
  elemento('conectar').disabled=Boolean(ativa || conectando);
  elemento('ligar').disabled=Boolean(navigator.onLine===false || !agente?.isRegistered() || ativa || preparando);
  elemento('atender').disabled=elemento('rejeitar').disabled=!(ativa && sessao.direction==='incoming' && !atendida);
  elemento('encerrar').disabled=!ativa;
  for(const id of ['mudo','espera','enviar-dtmf','transferir'])elemento(id).disabled=!atendida;
  elemento('mudo').textContent=sessao?.isMuted().audio?'Ativar microfone':'Mudo';
  elemento('espera').textContent=sessao?.isOnHold().local?'Retomar':'Espera';
}
function mostrar(estado,detalhe=''){elemento('estado').textContent=estado;elemento('detalhe').textContent=detalhe;atualizarBotoes();}
function pararToques(){clearInterval(pulsoToque);osciladores.forEach(tom=>{try{tom.stop();}catch{}});osciladores=[];}
function emitirTom(frequencia,inicio,duracao){
  if(contextoAudio?.state!=='running')return;
  const tom=contextoAudio.createOscillator(),ganho=contextoAudio.createGain();
  tom.frequency.value=frequencia;ganho.gain.value=.035;tom.connect(ganho);ganho.connect(contextoAudio.destination);
  tom.start(inicio);tom.stop(inicio+duracao);osciladores.push(tom);
  tom.onended=()=>{tom.disconnect();ganho.disconnect();osciladores=osciladores.filter(item=>item!==tom);};
}
function tocar(tipo){
  pararToques();
  const pulso=()=>{if(contextoAudio?.state!=='running')return;const agora=contextoAudio.currentTime;
    if(tipo==='entrada'){for(const deslocamento of [0,.5])for(const frequencia of [440,480])emitirTom(frequencia,agora+deslocamento,.35);}
    else if(tipo==='ocupado'){for(let i=0;i<4;i++)emitirTom(425,agora+i*.5,.25);}
    else emitirTom(425,agora,1);
  };pulso();if(tipo!=='ocupado')pulsoToque=setInterval(pulso,tipo==='entrada'?3000:5000);
}
async function ativarAudio(){
  contextoAudio ??= new AudioContext();await contextoAudio.resume();
  const fluxo=await navigator.mediaDevices.getUserMedia({audio:true});fluxo.getTracks().forEach(faixa=>faixa.stop());
  // JsSIP abrirá a mídia da chamada; esta captura apenas valida a permissão.
  elemento('aviso-audio').textContent='Áudio ativado. Pode trocar de aba; mantenha o WebPhone aberto e o computador ligado.';
  if(audio.srcObject)await audio.play();
}
async function conectar(){
  if(conectando || sessao && !sessao.isEnded())return;
  conectando=true;const geracao=++geracaoConexao;atualizarBotoes();
  try{
    const acesso=await requisitar('/webphone?ramal_id='+encodeURIComponent(ramalId));
    if(geracao!==geracaoConexao){delete acesso.senha;return;}
    pararSupervisao?.();
    if(agente){agente.removeAllListeners();agente.stop();}
    agente=new JsSIP.UA({sockets:[new JsSIP.WebSocketInterface(acesso.wss)],
      uri:`sip:${acesso.usuario}@${acesso.dominio}`,password:acesso.senha,...(acesso.contato_uri?{contact_uri:acesso.contato_uri}:{}),
      display_name:acesso.numero,register:true,register_expires:600,connection_recovery_min_interval:2,connection_recovery_max_interval:15,session_timers:false});
    delete acesso.senha; // UA mantém internamente o necessário para autenticar.
    agente.on('connecting',()=>{elemento('conexao').textContent='Conectando…';});
    agente.on('registered',()=>{elemento('conexao').textContent=`Ramal ${acesso.numero} conectado`;atualizarBotoes();});
    agente.on('unregistered',evento=>{if(!evento.cause)elemento('conexao').textContent='Ramal desconectado';atualizarBotoes();});
    agente.on('disconnected',()=>{elemento('conexao').textContent='Conexão SIP perdida; reconectando…';atualizarBotoes();});
    pararSupervisao=acompanharConexao(agente,{urlRelogio:'/relogio-webphone.js',
      aoRetomar:()=>{elemento('conexao').textContent=`Ramal ${acesso.numero} conectado`;atualizarBotoes();},
      aoFalhar:({temporario,espera})=>{
        elemento('conexao').textContent=temporario?'Reconectando…':'Registro recusado';
        if(!sessao||sessao.isEnded())mostrar('Falha no registro',temporario?`Nova tentativa automática em cerca de ${espera} segundos.`:'Confira o acesso e reconecte o ramal.');
      }});
    agente.on('newRTCSession',novaSessao);agente.start();
  }finally{if(geracao===geracaoConexao){conectando=false;atualizarBotoes();}}
}
function novaSessao(evento){
  if(sessao && !sessao.isEnded()){evento.session.terminate({status_code:486});return;}
  sessao=evento.session;const atual=sessao,recebida=evento.originator==='remote';let terminou=false;
  // Capture o Call-ID público do evento, mantendo o vínculo com esta sessão específica.
  const sipCallId=evento.request.getHeader('Call-ID');
  const correlacionar=()=>resolverCorrelacaoSip(requisitar,ramalId,sipCallId).then(dados=>{
    atual.data.correlacao_pabx=dados;
    document.dispatchEvent(new CustomEvent('pabx:correlacao',{detail:{sessao:atual,dados}}));
  }).catch(erro=>document.dispatchEvent(new CustomEvent('pabx:correlacao-pendente',{detail:{sessao:atual,codigo:erro.codigo||'CORRELACAO_INDISPONIVEL'}})));
  void correlacionar();
  clearInterval(relogio);relogio=null;elemento('duracao').textContent='00:00';
  mostrar(recebida?'Ligação recebida':'Ligando…',atual.remote_identity.uri.user);
  if(recebida)tocar('entrada');
  const conectarMidia=conexao=>conexao.addEventListener('track',eventoAudio=>{
    audio.srcObject=eventoAudio.streams[0] || new MediaStream([eventoAudio.track]);
    audio.play().catch(()=>{elemento('aviso-audio').textContent='Clique em Ativar áudio e microfone para ouvir.';});
  });
  if(atual.connection)conectarMidia(atual.connection);else atual.on('peerconnection',eventoConexao=>conectarMidia(eventoConexao.peerconnection));
  atual.on('progress',progresso=>{
    if(recebida)return;
    if(progresso.response?.status_code===183 && progresso.response.body){pararToques();mostrar('Conectando chamada','A operadora está enviando áudio.');}
    else{mostrar('Chamando…','Aguardando atendimento');tocar('saida');}
  });
  const atendida=()=>{pararToques();mostrar('Em ligação');if(!relogio){const inicio=Date.now();relogio=setInterval(()=>{const segundos=Math.floor((Date.now()-inicio)/1000);elemento('duracao').textContent=String(Math.floor(segundos/60)).padStart(2,'0')+':'+String(segundos%60).padStart(2,'0');},1000);}};
  atual.on('accepted',atendida);atual.on('confirmed',atendida);
  for(const nome of ['muted','unmuted','hold','unhold'])atual.on(nome,atualizarBotoes);
  const finalizar=fim=>{if(terminou)return;terminou=true;void correlacionar();pararToques();clearInterval(relogio);relogio=null;audio.srcObject=null;
    const ocupado=fim.cause==='Busy' || fim.message?.status_code===486;
    mostrar(ocupado?'Linha ocupada':'Ligação encerrada',mensagens[fim.cause] || 'Consulte o histórico para mais detalhes.');if(ocupado)tocar('ocupado');
  };atual.on('failed',finalizar);atual.on('ended',finalizar);
}
async function ligar(){
  if(preparando || sessao && !sessao.isEnded())return;
  preparando=true;atualizarBotoes();
  try{
    if(!agente?.isRegistered())throw new Error('Conecte o ramal antes de ligar.');
    pararToques();await ativarAudio();
    const destino=await requisitar('/webphone/preparar',{ramal_id:ramalId,numero:elemento('numero').value});
    // numero_enviado é apenas diagnóstico. O dialplan aplica a rota uma única vez.
    agente.call(destino.numero,midia);
  }catch(falha){mostrar(falha.codigo==='LINHAS_OCUPADAS'?'Linhas ocupadas':'Não foi possível ligar',falha.message);if(falha.codigo==='LINHAS_OCUPADAS')tocar('ocupado');}
  finally{preparando=false;atualizarBotoes();}
}
function aoClicar(id,acao){elemento(id).onclick=async()=>{try{await acao();}catch(falha){mostrar('Verifique a operação',falha.message);}};}
aoClicar('conectar',conectar);aoClicar('ativar-audio',ativarAudio);aoClicar('ligar',ligar);
aoClicar('atender',async()=>{await ativarAudio();if(sessao && !sessao.isEnded()){pararToques();sessao.answer(midia);}});
aoClicar('rejeitar',()=>sessao?.terminate({status_code:486}));aoClicar('encerrar',()=>sessao?.terminate());
aoClicar('mudo',()=>{if(sessao?.isEstablished())sessao.isMuted().audio?sessao.unmute({audio:true}):sessao.mute({audio:true});});
aoClicar('espera',()=>{if(sessao?.isEstablished()){const aceito=sessao.isOnHold().local?sessao.unhold():sessao.hold();if(aceito===false)throw new Error('Aguarde a negociação anterior e tente novamente.');}});
aoClicar('enviar-dtmf',()=>{const digitos=elemento('digitos').value;if(!/^[0-9*#]{1,20}$/.test(digitos))throw new Error('Use somente 0 a 9, * e #.');if(sessao?.isEstablished())sessao.sendDTMF(digitos);});
aoClicar('transferir',()=>{
  const destino=elemento('ramal-transferencia').value;if(!/^[0-9]{2,6}$/.test(destino))throw new Error('Informe um ramal da mesma empresa.');
  if(!sessao?.isEstablished())return;const origem=sessao;
  origem.refer(destino,{eventHandlers:{accepted:()=>{mostrar('Transferência aceita','Isso não comprova atendimento no destino.');if(!origem.isEnded())origem.terminate();},failed:()=>mostrar('Transferência falhou'),requestFailed:()=>mostrar('Transferência recusada')}});
});
window.addEventListener('pagehide',()=>{retomarPagina=Boolean(agente||conectando);geracaoConexao++;conectando=false;pararSupervisao?.();pararToques();clearInterval(relogio);relogio=null;agente?.stop();contextoAudio?.close();contextoAudio=null;});
window.addEventListener('pageshow',evento=>{if(evento.persisted&&retomarPagina){retomarPagina=false;conectar().catch(falha=>mostrar('Falha ao reconectar',falha.message));}});
window.addEventListener('offline',()=>{elemento('conexao').textContent='Sem conexão de rede';atualizarBotoes();});
atualizarBotoes();
// Para conectar ao montar a tela, chame conectar() uma única vez após o login.
// A permissão de áudio ainda depende da interação da pessoa com a página.

Conexão em segundo plano e recuperação

Trocar de aba não deve encerrar a UA nem remover o registro. O painel e o exemplo usam o mesmo supervisor: um Web Worker emite um pulso a cada 10 segundos; a janela envia keepalive SIP CRLF a cada 20 segundos e antecipa a renovação do REGISTER a cada 120 segundos, solicitando validade de 600 segundos. O JsSIP continua processando OPTIONS, chamadas e sua própria renovação por registrationExpiring. Nenhuma credencial ou mídia é enviada ao Worker. A janela continua responsável pela sinalização; não se responde OPTIONS artificialmente para marcar como disponível um telefone incapaz de atender.

Falhas temporárias de REGISTER (timeout, conexão, SIP 408/480/5xx) recebem nova tentativa com espera progressiva de 15 a 120 segundos; Retry-After é respeitado até uma hora. Recusas permanentes de acesso exigem corrigir a configuração e reconectar. O transporte usa recuperação de 2 a 15 segundos. online, focus, visibilitychange visível, resume e pageshow verificam a conexão sem recriar a UA nem desligar a conversa. A página só chama stop() ao sair/fechar (pagehide), nunca em blur ou visibilitychange oculto. Se o navegador restaurar a página do cache de navegação, o telefone busca novamente a configuração autorizada e se conecta.

O Worker reduz a dependência dos temporizadores da aba, mas não impede suspensão ou descarte pelo navegador/sistema. Computador suspenso, navegador fechado, perda de rede ou aba descartada podem impedir o recebimento; voltar à página recupera o registro, não uma chamada já perdida. Para postos de atendimento, mantenha o computador acordado e adicione o domínio à lista de sites sempre ativos nas configurações de desempenho do Chrome/Edge se a economia de memória/energia suspender o WebPhone. Não mantenha o microfone aberto nem reproduza silêncio continuamente para contornar essas políticas. Referências: temporizadores do Chrome, ciclo de vida da página.

O helper abaixo também pode ser usado num serviço estável de React/Vue. Chame acompanharConexao uma vez por UA, antes de start(), e guarde a função retornada para limpar Worker, listeners e timers antes de substituir/parar a UA. A opção aoFalhar informa temporario e espera em segundos; aoRetomar serve para atualizar o indicador a partir do estado registrado do JsSIP. Não habilite chamadas apenas porque o WSS abriu.

// Supervisão do JsSIP sem recriar a UA ou encerrar sessões em andamento.
export function acompanharConexao(agente,{urlRelogio='/recursos/relogio-webphone.js',aoFalhar=()=>{},aoRetomar=()=>{}}={}) {
  let encerrado=false,bloqueado=false,proximoRegistro=Date.now()+120000,permitidoApos=0,ultimoPulso=Date.now(),ultimoKeepAlive=0,tentativas=0;
  let trabalhador,temporizador;
  const eventos=[];
  const escutar=(alvo,nome,funcao)=>{alvo.addEventListener(nome,funcao);eventos.push(()=>alvo.removeEventListener(nome,funcao));};
  const observar=(nome,funcao)=>{agente.on(nome,funcao);eventos.push(()=>agente.removeListener(nome,funcao));};
  function registrar() {
    if(encerrado || bloqueado || Date.now()<permitidoApos || navigator.onLine===false || !agente.isConnected())return;
    proximoRegistro=Date.now()+120000;
    agente.register(); // O próprio JsSIP impede REGISTERs simultâneos.
  }
  function verificar(retomando=false) {
    if(encerrado || navigator.onLine===false || bloqueado)return;
    const agora=Date.now(),atrasado=agora-ultimoPulso>45000;ultimoPulso=agora;
    if(!agente.isConnected()) {
      // connect é idempotente, inclusive enquanto há handshake/recovery pendente.
      agente.transport.connect();return;
    }
    if(agora-ultimoKeepAlive>=20000) {
      ultimoKeepAlive=agora;agente.transport.send('\r\n\r\n');
    }
    if(agora>=proximoRegistro || ((retomando || atrasado) && proximoRegistro-agora<115000))registrar();
  }
  observar('registered',()=>{bloqueado=false;tentativas=0;proximoRegistro=Date.now()+120000;aoRetomar();});
  observar('registrationExpiring',registrar);
  observar('registrationFailed',evento=>{
    const codigo=evento.response?.status_code;
    const temporario=evento.cause==='Connection Error' || evento.cause==='Request Timeout' || codigo===408 || codigo===480 || (codigo>=500 && codigo<600);
    bloqueado=!temporario;
    const retryAfter=Number.parseInt(evento.response?.getHeader?.('Retry-After'),10);
    const espera=Math.max(Math.min(120,15*2**Math.min(tentativas++,3)),Number.isFinite(retryAfter)?Math.min(3600,Math.max(0,retryAfter)):0);
    permitidoApos=proximoRegistro=Date.now()+espera*1000;
    aoFalhar({temporario,espera});
  });
  observar('unregistered',()=>{if(!bloqueado)proximoRegistro=Math.min(proximoRegistro,Date.now()+15000);});
  const retomar=()=>{verificar(true);if(!encerrado && navigator.onLine!==false && agente.isRegistered())aoRetomar();};
  escutar(window,'online',retomar);
  escutar(window,'pageshow',retomar);
  escutar(window,'focus',retomar);
  escutar(document,'resume',retomar);
  escutar(document,'visibilitychange',()=>{if(document.visibilityState==='visible')retomar();});
  function usarTemporizador() {
    if(encerrado)return;
    trabalhador?.terminate();trabalhador=null;
    temporizador ??= setInterval(()=>verificar(),10000);
  }
  try {
    trabalhador=new Worker(urlRelogio);
    trabalhador.onmessage=()=>verificar();
    trabalhador.onerror=evento=>{evento.preventDefault();usarTemporizador();};
  }catch{usarTemporizador();}
  return ()=>{
    if(encerrado)return;encerrado=true;
    trabalhador?.terminate();clearInterval(temporizador);eventos.forEach(remover=>remover());
  };
}

Arquivo relogio-webphone.js, servido como JavaScript na mesma origem:

// Relógio independente dos timers da janela. Não recebe credenciais nem áudio.
setInterval(()=>postMessage('pulso'),10000);

Para homologar em um servidor preparado, execute os comandos abaixo. O cenário cria uma empresa temporária e dois ramais sem rotas externas. O teste com janela requer Chromium do Playwright e xvfb; não ativa flags que desabilitam a limitação de timers e usa connectOverCDP com noDefaults para impedir foco artificial. Confira document.visibilityState=hidden, OPTIONS reais e recebimento de chamadas antes de concluir que o segundo plano funciona. O segundo comando de navegador injeta uma única resposta SIP 503 no teste e valida recuperação, queda de WSS e retorno da rede. Finalize o cenário mesmo se um teste falhar.

node testes/conexao-webphone.cjs
php testes/webphone-segundo-plano-cenario.php preparar
MINUTOS_TESTE=7 xvfb-run -a node testes/webphone-segundo-plano.cjs
MINUTOS_TESTE=0 xvfb-run -a node testes/webphone-segundo-plano.cjs --recuperacao
php testes/webphone-segundo-plano-cenario.php finalizar

Eventos e controles para reproduzir a experiência

Evento/operaçãoTratamento no PABX e no exemplo
UA registeredHabilitar Ligar; connected sozinho só confirma transporte, não registro SIP
UA disconnected / registrationFailedMostrar perda de conexão ou recusa; reconectar SIP não recupera automaticamente uma conversa perdida
newRTCSessionCriar estado da conversa, detectar entrada por originator=remote e preparar os listeners antes de atender
progress / 180Mostrar Chamando e gerar ringback local
progress / 183 com SDPParar ringback local para ouvir o áudio antecipado da telefonia
accepted / confirmedMostrar Em ligação; iniciar um único contador e parar o toque
failed / endedFinalizar uma única vez, remover áudio/temporizadores e habilitar nova discagem
Busy ou SIP 486Aviso de linha/destino ocupado e quatro pulsos de 425 Hz
answer / terminateAtender entrada; rejeitar, cancelar ou desligar conforme o estado da sessão
mute / unmuteSilenciar/restaurar o microfone, sem colocar a chamada em espera
hold / unholdNegociar espera; tratar retorno false enquanto outra negociação está em andamento
sendDTMFEnviar 0–9, * e # durante a conversa; com a biblioteca instalada o padrão é SIP INFO
referTransferência simples para ramal da mesma empresa; tratar accepted, failed e requestFailed
pagehide / desmontagemEncerrar o agente e liberar tom, temporizadores, listeners e mídia conforme a política da aplicação

O servidor anuncia RFC4733 para telefones SIP, mas o painel chama sendDTMF sem opções e o JsSIP 3.13.8 usa INFO por padrão. Não confunda o transporte de DTMF dos telefones UDP com o padrão desta biblioteca. Se optar por transportType:'RFC2833', homologue a negociação e o recebimento no seu fluxo antes de mudar. A transferência usa o contexto autorizado do PABX; não oferece transferência externa arbitrária ou transferência assistida/conferência no exemplo. O accepted do REFER é um sucesso de sinalização e não comprova conversa humana no destino.

Em React/Vue, mantenha uma única UA e a sessão em uma referência/serviço estável, fora das renderizações. Atualize os componentes pelos eventos, registre listeners uma única vez e remova-os na desmontagem. Não reconstrua a UA a cada alteração de estado. Se precisar manter a conversa ao trocar de rota, monte o telefone no nível da aplicação; desmontar e chamar stop() encerra sessões. Evite várias abas registrando o mesmo ramal sem uma política explícita.

Filas, histórico e integração com o backend externo

Depois de registered, o painel consulta /webphone/filas. Para pausar, envie {ramal_id:UUID,pausado:true} para /filas/UUID/disponibilidade; false retoma. Atendentes só alteram sua própria participação. Ramal registrado não significa atendente livre: chamadas, pausa, descanso e reservas influenciam as filas e campanhas no servidor.

Uma aplicação externa que precisa apenas do botão Ligar pode usar o contrato abaixo em seu backend com chamadas:escrever. O navegador chama uma rota autenticada do próprio CRM; o CRM obtém o ramal permitido a partir do usuário, não confia em um ramal_id de outro cliente e mantém a chave Bearer no servidor. O áudio ocorre no ramal já conectado, inclusive no WebPhone aberto em outra aba.

curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/originate" \
  -H "Authorization: Bearer $CHAVE_API" -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data '{"ramal_id":"UUID_DO_RAMAL_AUTORIZADO","destino":"102"}'

Guarde a Idempotency-Key por ação e reutilize-a se houver timeout de rede. 202 não comprova atendimento. Acompanhe /chamadas/UUID com chamadas:ler ou eventos/webhooks conforme o guia. O id de JsSIP.RTCSession e o Call-ID SIP não são o UUID de app.chamadas: não os envie diretamente para /chamadas/UUID. Chamadas feitas com ua.call() não recebem esse UUID da preparação. Desde 0.19.0, resolva a sessão com POST /chamadas/correlacionar-sip, conforme o contrato abaixo. Não envie um UUID de chamada escolhido pelo cliente.

Correlação exata entre WebPhone, atendimento do CRM e gravações (0.19.0)

Rota principal: **POST /api/v1/chamadas/correlacionar-sip**. O PABX persiste o vínculo observado entre cada diálogo SIP de um ramal e suas chamadas REST. A consulta não cria chamadas nem aceita que o navegador determine o UUID correspondente. Não use telefone, horário, Caller-ID, RTCSession.id, linkedid ou a chamada mais recente como substituto.

POST /webphone/preparar mantém exatamente sua função e resposta anteriores; ua.call() continua iniciando a chamada. Capture o Call-ID da requisição pública do evento newRTCSession, tanto para recebidas quanto realizadas:

agente.on('newRTCSession', evento => {
  const sessaoDestaLigacao = evento.session;
  const sipCallId = evento.request.getHeader('Call-ID');
  // Vincule este identificador ao registro local desta sessão, não a uma variável
  // global de "último atendimento". O backend confirma a associação com o PABX.
  // Nunca use sessaoDestaLigacao.id como UUID REST.
});

Registre esse listener antes de agente.start()/agente.call(). Não leia propriedades privadas como _request. Preserve o Call-ID exatamente, inclusive maiúsculas e eventual @. O Call-ID do navegador e o da outra ponta podem ser diferentes: o PABX faz o vínculo por ramal e conexão observada, não presume uma identidade SIP única para toda a chamada.

No **backend do CRM**, use uma chave da empresa com chamadas:ler. O backend deve autenticar seu usuário, determinar o ramal permitido a partir do cadastro e validar o atendimento local que será atualizado. Informar ramal_id não autoriza o navegador a escolher outro atendente. Chaves API têm escopo de empresa e não identificam individualmente o usuário do CRM.

BASE=https://pabx.atendai.chat/api/v1
# CHAVE_API fica somente no servidor. RAMAL_ID é determinado pelo contexto autorizado.
# SIP_CALL_ID é o valor exato de evento.request.getHeader('Call-ID').
jq -n --arg ramal "$RAMAL_ID" --arg sip "$SIP_CALL_ID" \
  '{ramal_id:$ramal,sip_call_id:$sip}' |
  curl --silent --show-error --fail-with-body -X POST "$BASE/chamadas/correlacionar-sip" \
    -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
    --data-binary @-

Corpo: sip_call_id (obrigatório, 1–512 caracteres ASCII sem espaços) e ramal_id (UUID). Não envie empresa_id, chamada_id ou canais. A empresa vem da credencial. Sessões administrativas/supervisoras também podem consultar; uma sessão de **atendente** só pode consultar o próprio ramal vinculado e pode omitir ramal_id. POST com sessão exige CSRF. Não coloque Bearer no navegador nem crie um proxy CRM que aceite qualquer empresa/ramal do corpo sem autorização.

Resposta HTTP 200, exemplo fictício:

{
  "sucesso": true,
  "dados": {
    "estado": "correlacionada",
    "sip_call_id": "exemplo-call-id@crm.example.invalid",
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "dialogo_id": "00000000-0000-4000-8000-000000000002",
    "chamadas": [{
      "chamada_id": "00000000-0000-4000-8000-000000000003",
      "chamada_pai_id": null,
      "chamada_raiz_id": "00000000-0000-4000-8000-000000000003",
      "ramal_id": "00000000-0000-4000-8000-000000000001",
      "estado": "bridged",
      "iniciada_em": "2026-10-28 13:00:00+00",
      "atendida_em": "2026-10-28 13:00:05+00",
      "encerrada_em": null,
      "participacao_id": "123",
      "numero_ramal": "101",
      "direcao": "recebida",
      "participacao_iniciada_em": "2026-10-28 13:00:02+00",
      "participacao_atendida_em": "2026-10-28 13:00:05+00",
      "participacao_encerrada_em": null
    }],
    "tentar_novamente_em_ms": null
  }
}

dialogo_id é a identidade persistente dessa conexão SIP no PABX; chamada_id é o UUID usado nos endpoints REST já existentes. participacao_id é texto e identifica o trecho de participação do ramal. Os timestamps de participação são observados no servidor e podem ser atualizados pelos eventos de telefonia. atendida_em da chamada pode indicar atendimento de uma URA/fila; para identificar atendimento humano daquele ramal, use participacao_atendida_em.

RespostaTratamento
200 / correlacionadaPersistir dialogo_id e **todos** os vínculos retornados, com atualização idempotente por atendimento local + diálogo + chamada + participação.
202 / pendentedialogo_id:null, chamadas:[], tentar_novamente_em_ms:1000 e cabeçalho Retry-After: 1. Repetir a cada segundo por até 30 segundos.
403Falta de escopo/permissão. Não repetir automaticamente.
404Ramal inexistente ou inacessível no contexto autenticado. Não tentar outra empresa.
409 / CORRELACAO_AMBIGUACall-ID reutilizado em diálogos distintos do mesmo ramal ou identidade conflitante. Não selecionar um resultado arbitrário.
409 / CORRELACAO_COMPLEXACadeia de transferências cíclica/inválida ou acima do limite de 100 etapas. Não agrupar por aproximação.
422Corpo ou Call-ID inválido. Corrigir a requisição.

202 significa somente que o vínculo ainda não foi observado para aquele ramal. Pode permanecer pendente em tentativa que não chegou ao PABX, falha anterior à criação do CDR, Call-ID incorreto ou chamada antiga. Após o prazo, mantenha o registro local sem gravação associada e permita consultar novamente explicitamente. Não troque de Call-ID nem use telefone/horário como fallback. Um UUID resolvido não comprova atendimento nem gravação: consulte os estados.

#### Filas, transferências, vários dispositivos e captura

- Em fila ou toque simultâneo, cada conexão SIP recebe seu próprio dialogo_id, ligado ao mesmo UUID de chamada e ao ramal correspondente. O vínculo pode aparecer enquanto toca; participação sem participacao_atendida_em não significa conversa atendida.

- A transferência pela API conserva o UUID existente. O novo ramal recebe outro diálogo vinculado à mesma chamada.

- SIP/REFER pode criar outra chamada com chamada_pai_id; chamada_raiz_id permite agrupar a sequência sem usar canais internos. Um diálogo pode ter mais de um vínculo, por isso a resposta contém chamadas, não um UUID único sobrescrito.

- A resposta lista os vínculos **observados para o diálogo e ramal consultados**. Ela não concede acesso automático a todos os descendentes da raiz. Consulte a sessão de quem recebeu a transferência ou os webhooks v2 para as novas etapas. Uma chamada de consulta separada não deve ser agregada ao atendimento só porque ocorreu durante uma transferência; use apenas relações efetivamente registradas.

- A captura mantém a chamada original e vincula o diálogo do capturador. A autorização continua limitada à mesma empresa.

- Não alteramos o significado dos campos legados ramal_id e ramal_atendimento_id de /chamadas/{id}. Eles podem ser nulos e não substituem a participação específica retornada pela correlação.

#### Gravações e permissões

Depois de resolver, o backend usa **GET /chamadas/{chamada_id}/gravacoes**, com gravacoes:ler. Cada item inclui id da gravação, chamada_id, ramal_id, sentido e estado. Uma chamada pode ter várias gravações; não escolha automaticamente a primeira. Filtre pelo ramal/trecho autorizado para aquele atendimento. Para gravação disponivel, use **GET /gravacoes/{id}/arquivo**. Revalide a autorização do usuário do CRM ao reproduzir ou baixar; mantenha a chave no backend e entregue o áudio por uma rota autenticada do próprio CRM.

Atendentes podem resolver sua sessão, mas continuam **sem permissão para listar ou baixar gravações do cliente** diretamente. As permissões anteriores desses endpoints foram preservadas. A correlação, inclusive chamada_raiz_id, não é um token de acesso ao áudio.

A gravação é opcional. gravando indica metadados já criados e arquivo ainda não publicado; disponivel indica finalização e WAV validado; sem_audio e falhou não disponibilizam áudio. A resposta do arquivo continua validando estado e existência. Uma lista vazia não comprova, isoladamente, que jamais haverá gravação; confirme encerramento/estado e a configuração do ramal. O fim da chamada e o fim do processamento do áudio são momentos distintos.

#### Webhook v2 opcional, mantendo o v1

Em **Webhooks → Editar → Formato do webhook**, selecione a versão 2. Na API, envie configuracao.versao_payload:"2" no cadastro completo, preservando versao, URL e filtro de eventos. O padrão é "1"; webhooks existentes, inclusive os que recebem todos os eventos, continuam com o corpo v1. Omitir o novo campo num PUT mantém a versão já escolhida.

Assine pelo menos gravacao.disponivel, gravacao.falhou, gravacao.sem_audio, call.created, call.completed e call.failed, conforme a necessidade. Não precisa receber eventos novos: v2 acrescenta identificadores explícitos aos eventos existentes. Exemplo de gravacao.disponivel:

{
  "versao": 2,
  "evento_id": "456",
  "chamada_id": "00000000-0000-4000-8000-000000000003",
  "chamada_pai_id": null,
  "chamada_raiz_id": "00000000-0000-4000-8000-000000000003",
  "gravacao_id": "00000000-0000-4000-8000-000000000004",
  "evento": "gravacao.disponivel",
  "empresa_id": 1,
  "dados": {"id":"00000000-0000-4000-8000-000000000004","duracao":12.5},
  "criado_em": "2026-10-28 13:00:18+00"
}

gravacao_id é nulo em outros tipos de evento; IDs de chamada/raiz são nulos quando o evento não corresponde a uma chamada. dados mantém seu formato anterior. Assinatura HMAC, cabeçalhos de entrega e política de retentativas permanecem os mesmos. Valide a assinatura sobre o corpo bruto recebido e deduplique por empresa + evento_id; não dependa da ordem de entrega. Webhooks são avisos: consulte a API para o estado atual e autorize o acesso ao atendimento no CRM. Mesmo em v2, o evento não contém o Call-ID SIP: a resolução da sessão é feita pela rota autenticada acima.

No CRM, a sequência é: registrar atendimento local e Call-ID da sessão → resolver no backend → persistir UUIDs autorizados → receber gravacao.disponivel v2 ou consultar depois → validar acesso ao atendimento → listar e reproduzir o trecho correto. O ID local do CRM nunca é usado diretamente na rota de gravações.

A correlação é garantida para os vínculos capturados após a instalação da versão 0.19.0. Não existe reconstrução retroativa segura por telefone/horário. O contrato não exige cabeçalhos SIP personalizados nem expõe senha, chave de API, canal Asterisk ou caminho de arquivo.

Arquivo auxiliar correlacao-webphone.js, usado pelo exemplo completo:

/** requisitar usa a sessão autorizada ou o backend do CRM; nunca uma chave Bearer no navegador. */
export async function resolverCorrelacaoSip(requisitar,ramalId,sipCallId,{prazoMs=30000}={}) {
  if(typeof sipCallId!=='string'||!sipCallId)throw new Error('Call-ID SIP ausente.');
  const limite=Date.now()+Math.max(0,Math.min(30000,prazoMs));
  do {
    const resultado=await requisitar('/chamadas/correlacionar-sip',{ramal_id:ramalId,sip_call_id:sipCallId});
    if(resultado.estado==='correlacionada'&&resultado.chamadas?.length)return resultado;
    if(resultado.estado!=='pendente')throw new Error('Resposta de correlação inválida.');
    if(Date.now()>=limite)break;
    await new Promise(resolver=>setTimeout(resolver,Math.min(1000,limite-Date.now())));
  }while(Date.now()<=limite);
  const erro=new Error('Correlação ainda não disponível. Não associe por número ou horário.');
  erro.codigo='CORRELACAO_PENDENTE';throw erro;
}

O exemplo dispara pabx:correlacao com {sessao,dados} e salva a resposta em sessao.data.correlacao_pabx. No CRM, associe ao atendimento daquela sessão e confirme os dados no backend; não confie em UUIDs enviados pelo navegador como autorização. O evento pabx:correlacao-pendente inclui sessao e codigo, inclusive para falta de permissão ou ambiguidade; trate cada código sem fallback aproximado. Uma nova consulta é feita ao terminar a sessão. As consultas não interrompem o áudio. O requisitar do exemplo funciona sob a sessão HTTPS autorizada; uma aplicação em outra origem deve adaptar essa função para seu backend autenticado.

Rede, privacidade e diagnóstico

O servidor usa WSS 443 e Asterisk Realtime/PJSIP com WebRTC, DTLS-SRTP, ICE e codecs alaw/ulaw. A faixa RTP configurada é UDP 10000–10199. O WebPhone atual usa iceServers:[]; não há TURN implantado. Isso não garante áudio em qualquer NAT, VPN ou rede corporativa. Para redes restritivas, a implantação de STUN/TURN e credenciais próprias deve ser planejada e homologada; não use servidores gratuitos aleatórios nem anuncie um TURN inexistente.

SintomaO que conferir
HTTP 401/403 ao obter acessoSessão individual, troca inicial de senha, CSRF/perfil e ramal ativo habilitado para WebPhone
Falha ao abrir WSSCookie de sessão, /autorizar-ws, HTTPS/certificado, proxy Upgrade, subprotocolo sip e política do navegador
Transporte conectado, mas sem registroEvento registrationFailed, identidade WebRTC devolvida pela API e autenticação PJSIP
Registrado sem toque ou somClique em Ativar áudio e microfone; confira permissão, saída de áudio, volume e autoplay
Atendeu, mas não há áudioFaixas remotas, ICE/DTLS, NAT/firewall e pacotes WebRTC; registro SIP sozinho não comprova mídia
HTTP 409 LINHAS_OCUPADASTodos os troncos permitidos da rota atingiram capacidade; avisar e aguardar nova tentativa manual
Destino não localizado / SIP 404Número, DDD e transformação da rota; não confundir com falta de linhas
Chamadas duplicadasMais de uma UA/listener, duplo clique, múltiplas abas ou Idempotency-Key diferente em uma repetição

Não coloque senha SIP, cookie, Bearer, SDP completo ou dumps de JsSIP em telemetria. A credencial SIP precisa chegar ao navegador autorizado, em HTTPS e somente em memória; não é uma credencial temporária. Desativação de usuário/sessão não deve ser descrita como hangup de uma conversa já estabelecida. Não exponha páginas de exemplo preenchidas com dados de um cliente como arquivos públicos estáticos.

Para validar uma integração, use ramais de homologação: registro, ligação entre dois navegadores, recebimento/toque, áudio nos dois sentidos, mudo, espera, DTMF na URA, transferência simples, cancelamento, ocupado, falta de microfone, expiração da sessão e reconexão. Teste também a rede real do atendente; testes no servidor não comprovam todos os cenários NAT. Só depois use um destino externo autorizado para verificar a rota da operadora.

Validação do exemplo publicado

Em 08/10/2026, testes automatizados compilaram estes arquivos com JsSIP 3.13.8 e usaram dois navegadores de homologação contra a API e o WSS reais. Foram verificados registro, preparação, toque recebido, recusa SIP 486 com tom de ocupado, atendimento, pacotes WebRTC enviados/recebidos nos dois lados, mudo, espera/retomada, envio de DTMF por SIP INFO, transferência REFER para telefone SIP com RTP e encerramento. Os arquivos servidos por HTTPS coincidiram com as fontes documentadas.

O microfone dos testes usa áudio sintético do navegador; não houve chamada para operadora. Esse resultado comprova o exemplo na implantação e rede de homologação, sem garantir áudio em outras redes/NAT. O teste de DTMF confirma o envio de INFO; a escolha de teclas na URA da integração também deve ser homologada. No repositório, execute testes/documentacao.php e testes/webphone-documentacao.cjs conforme o procedimento de validação; o segundo exige o cenário isolado preparado e sua suspensão ao terminar.

Referências técnicas consultadas

JsSIP: UA e registro, JsSIP: RTCSession e controles, Asterisk: clientes WebRTC, MDN: getUserMedia e MDN: WebSocket. A versão instalada e os detalhes específicos do PABX foram conferidos no código e no package-lock.json, não presumidos a partir da versão mais recente da biblioteca.

IP do navegador no registro

GET /webphone também retorna contato_uri. Passe esse valor ao parâmetro contact_uri do JsSIP.UA, como no exemplo. Ele correlaciona o Contact SIP ao IP da requisição HTTPS autenticada por até 24 horas. Não altere o valor nem use o identificador como credencial. A autenticação continua usando usuario e senha; contato_uri só permite mostrar a origem correta apesar do proxy. WebPhones antigos precisam reconectar. Uma mudança de rede também requer buscar novamente a configuração para atualizar a origem.

Chamadas e idempotência

O Click-to-Call toca primeiro o ramal de origem. Depois que ele atende, o PABX chama o destino. Para saída externa, o ramal precisa de permissão, rota compatível, operadora ativa e capacidade. Não use o endpoint de originate para iniciar uma chamada WebRTC no navegador: o WebPhone usa SIP sobre WSS.

Se todos os troncos ativos da rota atingirem seu limite, a preparação do WebPhone e POST /chamadas/originate retornam HTTP 409 com erro.codigo=LINHAS_OCUPADAS e a mensagem **“Todas as linhas estão ocupadas. Tente novamente em instantes.”**. Essa recusa antecipada não inicia uma ligação nem cria registro de chamada. No WebPhone, aparece um aviso acompanhado por quatro pulsos curtos de ocupado; o botão Ligar fica disponível para uma nova tentativa manual.

A consulta antecipada não reserva uma linha. Se a capacidade terminar antes de o dialplan executar, a reserva definitiva continua protegida por transação: uma chamada ainda não atendida recebe SIP 486 / causa 17, e o histórico e o evento de conclusão preservam dial_status=BUSY, sip_status=486 e a mensagem de linhas ocupadas. No Click-to-Call que já atendeu o ramal de origem, há um tom de ocupado por até dois segundos antes de encerrar com causa 17; sip_status permanece null, pois nesse caso não foi enviada uma recusa 486. Telefones SIP recebem o sinal de ocupado; a apresentação sonora/visual depende do aparelho. Uma alternativa livre na mesma rota continua podendo ser usada. O destino ocupado pela operadora mantém seu motivo próprio, diferente de capacidade local esgotada.

Não aumente automaticamente o limite contratado nem tente novamente em laço ao receber LINHAS_OCUPADAS. Uma resposta 202 previamente aceita continua sendo recuperada pela mesma Idempotency-Key, mesmo que todas as linhas tenham ficado ocupadas depois. A simulação de rotas continua verificando a configuração, sem prometer capacidade disponível.

IDEMPOTENCIA="crm-$(python3 -c 'import uuid; print(uuid.uuid4())')"
# Guarde esta chave junto com a operação. Em retentativas, reutilize a MESMA chave e corpo.
curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/originate" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data '{"ramal_id":"UUID_DO_RAMAL","destino":"102"}'
{"sucesso":true,"dados":{"id":"UUID_DA_CHAMADA","estado":"created"}}

Idempotency-Key aceita 12–128 caracteres de A–Z, a–z, 0–9, hífen e sublinhado. A mesma chave com os mesmos parâmetros recupera a resposta; parâmetros diferentes retornam 409. Não gere nova chave quando houver timeout de rede. O resumo usa os parâmetros recebidos; mantenha inclusive a mesma formatação do número. A implementação atual não define uma expiração pública para a chave; use um identificador novo para cada nova ação de negócio.

Acompanhe GET /chamadas/{id} ou eventos. Estados incluem created, originating, ringing, answered, queued, completed e failed; eventos intermediários dependem do fluxo. Consulte dial_status, sip_status, hangup_cause e mensagem_resultado quando disponíveis. 202 não comprova que o telefone tocou ou atendeu.

Números aceitam 2–18 dígitos após remoção de espaços, parênteses, +, ponto e hífen. Números locais de 8–9 dígitos recebem o DDD do cliente. Um zero inicial em 0+DDD+número é removido antes da rota; os campos remover/adicionar da rota determinam o formato enviado à operadora. Formatos 55+DDD dependem da rota cadastrada. Não presuma normalização E.164 para todas as operadoras.

Transfer usa o número do ramal de destino, não seu UUID. Hangup e transfer exigem uma chamada ainda ativa e com canal associado. Originate é o único endpoint com garantia de idempotência por cabeçalho.

Voz natural local e conversão de arquivos

Em Áudios → Adicionar áudio, ou no botão de cadastrar mensagem dentro de uma URA/campanha, escolha **Gerar voz a partir de texto**, **Enviar arquivo de áudio ou vídeo** ou **Gravar com meu microfone**. Dê um nome à mensagem, confira a prévia e clique em Salvar e usar mensagem. O áudio salvo entra no catálogo da empresa e pode ser reutilizado em qualquer campo de mensagem do sistema. Gerar um áudio não o associa automaticamente a outras configurações já salvas.

O motor instalado é Piper, executado localmente em CPU, sem conta externa nem cobrança por geração. As vozes disponíveis são Faber, Cadu e Jeff, em português brasileiro. A qualidade e a pronúncia variam por voz; a telefonia utiliza banda de 8 kHz. Escreva números e siglas por extenso quando necessário e escute a prévia antes de publicar a mensagem. Não há clonagem de voz nem SSML. A instalação inicial baixa modelos; a síntese não envia o texto a terceiros.

OperaçãoEntrada / permissãoResultado
GET /audios/vozesaudios:lerdisponivel, motor, vozes e limites
POST /audios/previa-voztexto, voz, velocidade; audios:escreverBinário audio/wav; não cria cadastro
POST /audios/gerar-voznome, texto, voz, velocidade; audios:escreverHTTP 201 com sucesso/dados do áudio
POST /audiosMultipart nome e arquivo; audios:escreverHTTP 201 com o áudio convertido
GET /audios/{id}/arquivoaudios:ler; baixar=1 opcionalBinário WAV autenticado

Texto: de 2 a 1.000 caracteres. Nome: de 2 a 100 caracteres. Voz: faber (padrão), cadu ou jeff, conforme disponibilidade consultada. Velocidade: número entre 0.8 e 1.2, padrão 1. Não envie JSON no lugar do multipart de upload; geração usa as rotas próprias. Prévia e download retornam WAV diretamente em caso de sucesso, sem envelope JSON. Em erro, retornam o envelope JSON usual e status 4xx/5xx. Não grave uma resposta de erro com extensão WAV sem conferir o status HTTP.

O servidor admite uma síntese por vez para preservar recursos da telefonia. Se estiver ocupado, retorna 429: aguarde alguns segundos e tente novamente com espera crescente. O prazo de síntese é de até 45 segundos; textos que excederem esse prazo são recusados com 422. Motor ou espaço em disco indisponível retorna 503. Uma requisição de criação repetida pode criar outro áudio; não há idempotência nesse endpoint. Após timeout de rede, consulte o catálogo antes de repetir a criação.

Uploads aceitam WAV, MP3, MP4, M4A, OGG e WebM, até 20 MB e dez minutos de áudio. Um MP4 deve conter uma faixa de áudio; vídeo sem áudio é recusado. Usa-se a primeira faixa de áudio; o vídeo é descartado. Arquivos inválidos, vazios ou com mais de dez minutos são recusados, sem cadastro parcial e sem corte silencioso. A saída é WAV PCM de 16 bits, mono, 8.000 Hz. Gravações do navegador passam pela mesma conversão.

A configuracao do áudio informa arquivo (identificador interno, não URL pública), duracao em segundos, tamanho em bytes, formato, codec, frequencia, canais e origem (envio ou tts). Em TTS há motor, voz, velocidade e caracteres; em envio há mime_original. O texto digitado não é armazenado no cadastro, na auditoria nem nos logs de aplicação. A prévia é temporária e não aparece no catálogo; para manter a mensagem, use gerar-voz. A gravação de chamadas continua sendo um recurso separado, com escopo gravacoes:ler.

PUT /audios/{id} altera nome/ativo e mantém arquivo e metadados. Para trocar a mensagem, gere/envie outro áudio e atualize audio_id na URA ou campanha, preservando os demais campos e versao. DELETE desativa e recusa referências ativas.

Exemplo de envio de vídeo com extração automática do áudio:

curl --fail-with-body --silent --show-error -X POST "$BASE/audios" \
  -H "Authorization: Bearer $CHAVE_API" \
  -F 'nome=Mensagem de boas-vindas' -F 'arquivo=@mensagem.mp4'

Histórico de vida de cada ramal

Em Ramais → Histórico e atividade, consulte a criação, conexão atual, chamadas em andamento e a linha do tempo. A tela atualiza a situação a cada dez segundos e permite filtrar registros SIP, chamadas ou ações administrativas. Carregar anteriores preserva a leitura dos registros antigos.

GET /ramais/{id}/historico?tipo=todos&pagina=1 exige **ramais:ler e chamadas:ler** com Bearer, ou perfil administrador/supervisor. A empresa é sempre a da autenticação. Inclui ramais desativados. Atendentes restritos ao WebPhone não consultam esse histórico administrativo.

Campo da respostaSignificado
ramalid, nome, numero, ativo e criado_em
conexaoMesma situação e dispositivos de /ramais/conexoes; pode ser null se não disponível
consultado_emMomento da consulta, com fuso
chamadas_ativasParticipações deste ramal com chamada_id, origem, destino, tipo_chamada (interna/externa), direcao (realizada/recebida), estado, iniciada_em, atendida_em e encerrada_em
eventosAté 50 acontecimentos, mais recentes primeiro; id, ocorrido_em, tipo, evento, titulo, responsavel e detalhes
pagina / proxima_paginaPágina atual e próxima; null encerra a paginação
primeiro_evento_sipPrimeiro evento SIP efetivamente armazenado para o ramal, ou null

O filtro tipo aceita todos, registros, chamadas ou alteracoes. Paginação começa em 1. A linha do tempo pode ganhar novos eventos durante a leitura; ao consolidar exportações paginadas, elimine duplicidades por id. A paginação é por posição, sem garantia de uma fotografia imutável dos dados.

Eventos SIP: registro (novo contato aceito), renovacao (validade atualizada), removido (retirada antes da expiração), expirado (retirada após o prazo) e observado (contato identificado no início da coleta). A correlação usa contato_hash e endpoint. Os detalhes incluem dispositivo, endereco e expira_em. Registro não prova alcance: consulte também conexao.estado. Um telefone pode ter vários contatos e reconexões; as renovações não substituem o evento anterior. A remoção não distingue, por si só, saída voluntária, substituição de contato ou desativação.

Chamadas geram chamada_iniciada, chamada_atendida e chamada_encerrada por canal SIP do ramal, independentemente de gravar_realizadas/gravar_recebidas. Em ringall ou em vários dispositivos, pode haver mais de uma participação na mesma chamada. Canal atendido é sinalização de conexão; sozinho não comprova conversa humana ou atendimento de uma campanha. Para campanhas, use atendente_atendeu_em e resultado_campanha. Em chamadas internas, os dois ramais têm histórico. Datas de encerramento de participantes podem anteceder o fim da chamada, por transferência.

Nos eventos de chamadas do ramal, detalhes também inclui dial_status, sip_status, hangup_cause e resultado_campanha, com null quando não informados. Esses campos descrevem o resultado atual da chamada relacionada; não são uma fotografia do resultado no instante de cada evento. O painel usa os códigos para distinguir ocupado, não atendida, cancelada, recusada, indisponível e não completada, preservando a mensagem de resultado do servidor.

Os ícones são acompanhados de rótulos. Sentido (recebida, realizada, entre ramais, Click-to-Call ou campanha) e resultado são informações separadas. completed ou atendida_em isoladamente não garantem atendimento do destino: a origem do Click-to-Call e áudios/URAs podem atender primeiro. Sem confirmação adicional, a interface usa Encerrada; BUSY continua Ocupada mesmo que a origem já tenha atendido. ANSWER indica atendimento na sinalização, não prova conversa humana. Para campanhas, prevalece resultado_campanha e somente atendido é mostrado como conexão ao atendente. Os ícones são apresentação; integrações devem usar os campos da API.

Ações administrativas mostram o responsável histórico (pessoa, integração ou sistema), entidade e nomes dos campos de configuração alterados; não revelam senhas. Também aparecem alterações de acesso WebPhone e pausas de fila associadas ao ramal. A criação e ações já auditadas são aproveitadas. Chamadas antigas usam os dados que existirem no banco; não se inventam registros SIP ou participantes anteriores à implantação da coleta.

Desativar usa POST /ramais/{id}/desativar com versao (ou DELETE /ramais/{id}, mantido por compatibilidade) e preserva cadastro, número reservado, histórico e gravações. Recusa chamadas, reservas, gravações em andamento e dependências ativas em filas/destinos. Revoga sessões e desativa os acessos de atendentes vinculados. Para reativar, envie PUT completo com ativo=true e versao atual; reative separadamente os acessos WebPhone. A exclusão definitiva é uma operação separada, descrita em Desativar ou excluir ramais.

Áudios, filas, campanhas e contatos

Áudios podem ser gerados a partir de texto no motor neural local, enviados como arquivo ou gravados no navegador. Todas as opções salvam WAV compatível com o PABX. Consulte os fluxos detalhados abaixo.

Filas precisam de ao menos um ramal ativo. Estratégias: ringall, rrmemory, leastrecent, fewestcalls, random. O tempo por agente é timeout; espera é o máximo desejado de espera, limitado na execução a 300 segundos. Pausa e disponibilidade não alteram a agenda da fila.

Campanhas nascem em rascunho. Cadastre o modo (mensagem com tecla ou transferência direta), operadora, fila, limites e janela de discagem. Áudio é obrigatório apenas no modo com mensagem. Importe contatos antes de iniciar. Pause antes de editar a configuração. Encerrar impede novas chamadas; as já iniciadas podem terminar. Campanhas concluídas ou canceladas não reiniciam pela ação iniciar.

Contatos podem ser JSON ou CSV com cabeçalho exato nome,telefone e separador vírgula. O limite é 10.000 contatos por lote; CSV até 5 MB. Use confirmar=false para validar e confirmar=true para importar. A resposta informa validos, duplicados do lote, erros, importados e amostra. Telefones já importados ou bloqueados não são inseridos novamente; por isso importados pode ser menor que validos.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/contatos" \
  -H "Authorization: Bearer $CHAVE_API" \
  -F 'arquivo=@contatos.csv' -F 'confirmar=0'
# Após revisar a validação, repita com confirmar=1 para efetivar.

Campanhas de URA reversa

Há dois modos, sempre vinculados a uma fila da mesma empresa:

ModoAo cliente atenderCampos específicos
audio_tecla (padrão)Reproduz a mensagem; a tecla de confirmação encaminha à fila.audio_id obrigatório, tecla, tecla_bloqueio, espera_tecla
diretoEncaminha à fila sem mensagem e sem exigir tecla.Não exige áudio; audio_id é ignorado e salvo vazio.

Nos dois modos, tronco_id e fila_id são obrigatórios. espera_atendente aceita 1–120 segundos (padrão 30), contados após encaminhar à fila; vale especificamente para a campanha. O tempo de toque de cada oferta também respeita o menor timeout entre fila, ramal e prazo restante. O cliente ouve tom de encaminhamento durante a espera. Esgotado o prazo, a ligação termina com sem_atendente. O destino alternativo configurado na fila não é executado pela campanha.

espera_tecla aceita 1–30 segundos (padrão 8), após a mensagem, e só se aplica a audio_tecla. As teclas de campanha podem ser 0–9 e devem diferir. A mensagem precisa anunciar a tecla de atendimento e a de bloqueio. O modo direto não oferece bloqueio por tecla; a lista de números já bloqueados continua sendo respeitada.

No painel, abra **Campanhas → Adicionar campanha**, escolha o modo, a fila e a operadora. A disponibilidade da fila aparece na configuração. Use **Operar** para importar contatos, iniciar e acompanhar os resultados. A tela atualiza a cada cinco segundos.

Criar os dois modos por cURL

Defina BASE=https://pabx.atendai.chat/api/v1, CHAVE_API por variável de ambiente e os UUIDs TRONCO_ID, FILA_ID e, quando necessário, AUDIO_ID obtidos nos cadastros do cliente. Os exemplos usam jq para montar JSON sem concatenar valores. Criar uma campanha deixa-a em rascunho e não faz ligações.

# Mensagem seguida de confirmação pela tecla 1; tecla 9 bloqueia o número.
jq -n --arg tronco "$TRONCO_ID" --arg fila "$FILA_ID" --arg audio "$AUDIO_ID" \
  '{nome:"Atendimento com mensagem",configuracao:{modo:"audio_tecla",tronco_id:$tronco,fila_id:$fila,audio_id:$audio,tecla:"1",tecla_bloqueio:"9",espera_tecla:8,espera_atendente:30,simultaneas:2,tentativas:3,intervalo:120,dias:[1,2,3,4,5],inicio:"09:00",fim:"17:30",amd:false}}' \
  > campanha.json
curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @campanha.json
# Transferência ao atender, sem áudio nem tecla.
jq -n --arg tronco "$TRONCO_ID" --arg fila "$FILA_ID" \
  '{nome:"Atendimento direto",configuracao:{modo:"direto",tronco_id:$tronco,fila_id:$fila,espera_atendente:30,simultaneas:2,tentativas:3,intervalo:120,dias:[1,2,3,4,5],inicio:"09:00",fim:"17:30",amd:false}}' \
  > campanha-direta.json
curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data-binary @campanha-direta.json

Guarde dados.id como ID. Importe contatos antes de iniciar:

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/contatos" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data '{"confirmar":true,"contatos":[{"nome":"Contato de exemplo","telefone":"551130000000"}]}'

# Esta ação habilita ligações reais, dentro do horário e da capacidade disponível.
curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/iniciar" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' --data '{}'

curl --fail-with-body --silent --show-error "$BASE/campanhas/$ID/status" \
  -H "Authorization: Bearer $CHAVE_API"
curl --fail-with-body --silent --show-error "$BASE/campanhas/$ID/resultados?pagina=1" \
  -H "Authorization: Bearer $CHAVE_API"

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/pausar" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' --data '{}'
# Use /iniciar para retomar ou /encerrar para encerrar definitivamente.

Escopos: criar/editar/importar exige campanhas:escrever; consultar status, resultados e métricas exige campanhas:ler; iniciar/pausar/encerrar exige operar_campanhas:escrever. Consultar uma fila diretamente exige filas:ler. O status da campanha inclui apenas dados da fila vinculada, da mesma empresa.

Capacidade, pausas e horários

A discagem é progressiva: nunca se liga acima da capacidade livre consultada. O teto é o menor entre simultaneas da campanha (1–100), vagas da fila, limite da empresa e limite do tronco. Um atendente precisa estar conectado, livre, não pausado, fora do descanso após atendimento e sem reserva de outra campanha. O mesmo ramal em várias filas, ou com SIP e WebPhone conectados, continua sendo uma única vaga. Clientes já aguardando na fila reduzem a capacidade de novas discagens.

O servidor reserva essa capacidade antes da ligação, revalida antes de originar e verifica novamente ao oferecer a ligação ao ramal. As reservas são compartilhadas entre campanhas e filas da empresa. Enquanto não houver vaga, a campanha permanece executando e aguarda sem gastar tentativas. Falha de consulta ao Asterisk também suspende novas discagens. A consulta de status é uma fotografia; não autoriza uma integração externa a disparar chamadas ignorando essas reservas.

Ainda é possível o atendente receber outra ligação, desconectar, pausar ou não atender durante a chamada ao cliente. Por isso existe espera_atendente, e uma tecla confirmada não garante atendimento. Trata-se de controle de capacidade com espera limitada, sem promessa de abandono zero ou discagem preditiva.

Novas ligações precisam estar dentro dos dias/datas e horário da campanha e da agenda da fila, no fuso da empresa. A agenda da fila pode ter vários turnos por dia. Chamadas já conectadas ao atendente continuam; ofertas ainda sem conexão revalidam a agenda. Uma campanha fora do prazo de datas aguarda sem discar até ser editada (após pausa) ou encerrada.

Pausar cancela preparações ainda não discadas e libera suas reservas, sem consumir tentativa. Ligações já iniciadas podem completar seu fluxo. Encerrar também cancela contatos pendentes e impede novas tentativas; ligações já iniciadas e atendidas continuam. Campanhas concluídas ou canceladas não reiniciam. Faça GET e preserve a configuração completa e versao ao editar uma campanha pausada. Cada chamada guarda uma cópia da configuração usada na preparação.

Tentativas e resultados

tentativas é o total por contato, incluindo a primeira ligação: 1–10, padrão 3. intervalo é em minutos, mínimo 1, padrão 120. Uma espera por capacidade não incrementa esse contador. Uma tentativa iniciada pelo discador, inclusive uma falha ao originar, incrementa. Uma chamada sem atendimento por agente volta a pendente depois do intervalo, enquanto houver tentativas, exceto bloqueio ou campanha encerrada. Uma conexão com agente conclui o contato.

GET /campanhas/{id}/metricas preserva o formato anterior: array de {estado,quantidade} de contatos. GET /campanhas/{id}/status acrescenta capacidade e resultados:

Campo de dadosSignificado
estado, modoEstado administrativo e modo de execução.
motivo, mensagemCódigo e explicação do que permite ou impede novas chamadas.
vagas, ativasCapacidade disponível para novas chamadas e ligações abertas da campanha.
filanome, aberta, consulta_disponivel, consultado_em, prontos, disponiveis, reservados, capacidade_discagem, aguardando, aguardando_sem_reserva, agentes.
fila.agentes[]ramal_id, numero, nome, estado, pausado, pronto, reservado, reservado_outro, disponivel, candidato_para_fila, ultimo_atendimento (Unix), descanso_ate.
contatos[]Quantidades por estado do contato.
resumoligacoes, clientes_atenderam, confirmacoes_tecla, atendimentos, historicas. São contagens de chamadas, não de pessoas distintas.
resultados[]{resultado,descricao,quantidade} por resultado final da chamada.

prontos considera conexão/estado/pausa/descanso/horário. disponiveis também desconta reservas. capacidade_discagem desconta quem já aguarda sem reserva, evitando descontar duas vezes uma chamada de campanha. candidato_para_fila é diagnóstico da oferta nativa; não deve ser usado como autorização de discagem. reservado_outro é relativo à consulta; no endpoint público não há chamada própria, então toda reserva é de outra chamada.

Códigos de motivo: rascunho, pausada, cancelada, concluida, desativada, fora_do_horario, telefonia_indisponivel, fila_fechada, operadora_desativada, aguardando_atendente, limite_de_chamadas, disponivel. disponivel indica capacidade, não promete contatos elegíveis antes de vencer o intervalo de nova tentativa.

Estados de agente: disponivel, reservado, em_ligacao, pausado, descanso, desconectado, desconhecido, desativado, fora_do_horario. GET /filas/{id}/status mantém também membros, diagnóstico nativo do Asterisk. Use agentes na interface da integração.

GET /campanhas/{id}/resultados?pagina=1 retorna {pagina,por_pagina:100,total,contatos:[...]}. Cada contato informa id, nome, telefone, estado, tentativas, ultimo_resultado, bloqueado, proxima_tentativa_em, chamada_id e os campos da última chamada. Antes da primeira chamada esses campos são nulos. Para todas as tentativas, acompanhe os eventos ou o histórico paginado de chamadas.

Campo da chamadaSignificado
atendida_em (cliente_atendeu_em nos resultados)A operadora informou que o destino atendeu. Pode ser caixa postal.
confirmada_em, confirmadoCliente pressionou a tecla; não significam que um agente atendeu. confirmado permanece disponível nos detalhes da chamada.
enfileirada_emComeçou o encaminhamento e a espera limitada.
atendente_atendeu_em, ramal_atendimento_idConexão com o atendente confirmada pelo Queue; critério de atendimento.
etapa_campanhareservada, discando, cliente_atendeu, confirmado, aguardando_atendente, em_atendimento, finalizada.
resultado_campanhaResultado final descrito abaixo, ou nulo durante o fluxo.
classificacao_amdResultado da detecção, ou nulo quando não usada.

Resultados: atendido, sem_resposta, ocupado, caixa_postal, amd_inconclusivo, falha_amd, sem_confirmacao, tecla_invalida, sem_atendente, cliente_desligou, bloqueado, falha_operadora, falha_fluxo, nao_discada, historico_anterior. nao_discada é uma preparação devolvida sem iniciar tentativa. historico_anterior marca chamadas anteriores à confirmação confiável de conexão; seus antigos estados de contato são preservados e não são usados para inventar atendimento ou novas tentativas.

Estados de contato: pendente, reservado, discando, concluido, falhou, bloqueado, cancelado. Para novas ligações, concluido requer atendido; falhou significa tentativas esgotadas. Um contato que optou pelo bloqueio permanece bloqueado. A tecla de bloqueio inclui o telefone na lista da empresa e impede novas importações/discagens desse mesmo número normalizado. Não afeta outros clientes da plataforma.

Detecção de caixa postal e eventos

amd:false (padrão) encaminha qualquer resposta do destino conforme o modo; não distingue pessoa de caixa postal. amd:true executa a análise do Asterisk antes da mensagem ou da transferência. Acrescenta alguns segundos e pode errar; não identifica uma pessoa com certeza. HUMAN prossegue, MACHINE termina como caixa_postal, HANGUP como cliente_desligou, e ausência de resultado (INDEFINIDO) como falha_amd. Para NOTSURE, amd_inconclusivo:prosseguir (padrão) prossegue; reagendar encerra como amd_inconclusivo, respeitando o limite/intervalo de tentativas. Reagendar não cria tentativas extras.

Eventos próprios: campaign.cliente_atendeu, campaign.amd, campaign.cliente_confirmou, campaign.encaminhada_fila, campaign.atendente_conectado, campaign.sem_capacidade, campaign.opt_out e campaign.contact.result. O último contém contato_id, campanha_id, estado, resultado, tentativas; opt-out usa seu evento específico. A correlação da chamada consta nos eventos armazenados e nos campos id dos eventos de etapa. Ao integrar atendimento, use campaign.atendente_conectado ou atendente_atendeu_em/resultado_campanha=atendido; nunca apenas call.completed, answered ou DTMF. Os estados gerais de chamada continuam descrevendo a telefonia, mesmo quando a campanha não chegou a um agente.

Eventos e webhooks

GET /eventos retorna os últimos 100 eventos da empresa, em ordem decrescente. Não há cursor incremental ou filtro de eventos nessa rota nesta versão. Para integração contínua, cadastre um webhook. Os filtros de webhook são nomes exatos separados por nova linha; vazio recebe todos. Exemplos de eventos: call.created, call.queued, call.dtmf, call.forwarded, call.audio_played, call.audio_failed, call.completed, call.failed, campaign.executando, campaign.pausada, campaign.cancelada, campaign.opt_out e campaign.sem_capacidade.

O cadastro de webhook retorna segredo_unico apenas uma vez. O receptor deve ser HTTPS público na porta 443, sem credenciais ou fragmento na URL. Endereços privados/reservados são recusados; redirecionamentos não são seguidos. A validação atual usa IPv4.

{
  "evento": "call.completed",
  "empresa_id": 123,
  "dados": {"id":"UUID_DA_CHAMADA","estado":"completed"},
  "criado_em": "2026-10-08 12:00:00+00"
}

Cabeçalhos: X-AtendAI-Event, X-AtendAI-Delivery, X-AtendAI-Timestamp e X-AtendAI-Signature. A assinatura é sha256= seguida do HMAC-SHA256 hexadecimal de timestamp + "." + corpo_bruto, usando segredo_unico como chave. Calcule sobre os bytes recebidos; não recodifique o JSON antes de verificar.

<?php
$corpo = file_get_contents('php://input');
$instante = $_SERVER['HTTP_X_ATENDAI_TIMESTAMP'] ?? '';
$recebida = $_SERVER['HTTP_X_ATENDAI_SIGNATURE'] ?? '';
$segredo = getenv('SEGREDO_WEBHOOK');
$esperada = 'sha256=' . hash_hmac('sha256', $instante . '.' . $corpo, $segredo);
if (!ctype_digit($instante) || abs(time() - (int)$instante) > 300 || !hash_equals($esperada, $recebida)) {
    http_response_code(401);
    exit;
}
$entregaId = $_SERVER['HTTP_X_ATENDAI_DELIVERY'] ?? '';
// Persista entregaId com chave única. Se já processado, responda 2xx sem repetir a ação.
// Persista o evento e processe de forma assíncrona antes de responder rapidamente.
http_response_code(204);

2xx confirma a entrega. Há até cinco tentativas; após falhas, os intervalos são 60 s, 300 s, 1.800 s e 7.200 s. O timeout de conexão é 3 s e o total 8 s. O timestamp e assinatura são recalculados em cada tentativa. A integração deve tolerar duplicidade e não depender da ordem de chegada. Os detalhes de entregas são consultados no painel ou pela rota de sessão /entregas-webhook.

Eventos WebSocket são destinados ao painel: uma sessão de administrador/supervisor solicita /websocket-ticket, conecta à URL retornada e envia {"ticket":"..."} como primeira mensagem. O ticket expira em 30 segundos e só pode ser usado uma vez. Contas desativadas, senha inicial pendente ou sessões revogadas perdem esse acesso. Não é a mesma conexão WSS usada pelo SIP do WebPhone.

API de sessão e administração

As rotas marcadas como sessão são usadas pelo próprio painel. Elas não aceitam a chave Bearer como substituta de um usuário autorizado. Use-as em automações administrativas controladas; para integrações de cliente, prefira as rotas Bearer. Não existe endpoint JSON de login ou JWT.

SITE='https://pabx.atendai.chat'
BASE="$SITE/api/v1"
umask 077
curl --fail-with-body --silent --show-error -c sessao.txt "$SITE/entrar" -o entrar.html
CSRF="$(python3 -c 'import re; print(re.search(r"name=\"csrf\" value=\"([^\"]+)\"", open("entrar.html").read()).group(1))')"
read -r -p 'Usuário ou e-mail: ' USUARIO
read -r -s -p 'Senha: ' SENHA
printf '\n'
curl --fail-with-body --silent --show-error -b sessao.txt -c sessao.txt \
  --data-urlencode "csrf=$CSRF" --data-urlencode "email=$USUARIO" \
  --data-urlencode "senha=$SENHA" "$SITE/entrar" -o /dev/null
unset SENHA
# O token CSRF muda no login; leia o novo na página autenticada.
curl --fail-with-body --silent --show-error -L -b sessao.txt -c sessao.txt "$SITE/" -o painel.html
CSRF="$(python3 -c 'import re; print(re.search(r"name=\"csrf-token\" content=\"([^\"]+)\"", open("painel.html").read()).group(1))')"

Contas com troca obrigatória precisam primeiro POST /minha-senha. Uma conta global começa sem cliente selecionado. Consulte GET /administracao/empresas, escolha o ID e selecione o contexto:

EMPRESA_ID='123'
curl --fail-with-body --silent --show-error -b sessao.txt -c sessao.txt \
  --data-urlencode "csrf=$CSRF" --data-urlencode "empresa_id=$EMPRESA_ID" \
  "$SITE/selecionar-empresa" -o /dev/null

Em mutações JSON de sessão, envie X-CSRF-Token. Em operações de cliente, envie também X-Empresa-ID com o cliente selecionado; a API responde CONTEXTO_ALTERADO se outra aba trocar de cliente. Esse cabeçalho valida a seleção existente, não seleciona o cliente. Usuários de cliente ficam sempre na sua própria empresa.

Formulários adicionais fora de /api/v1: POST /encerrar-gestao encerra a seleção global; POST /sair encerra a sessão. Ambos recebem csrf. GET /saude é público e retorna disponibilidade da aplicação/banco, sem atestar telefonia. GET /audios/{id}/ouvir entrega WAV e exige permissão de áudios. GET /autorizar-ws é uma verificação interna de sessão/permite-WebPhone com resposta 204 ou 401/403.

Acesso WebPhone pelo ramal

Em Ramais → Acesso WebPhone, crie nome, usuário e senha. O usuário pode ser empresa.101; é exclusivo na plataforma, tem 3–80 caracteres e aceita letras minúsculas sem acentos, números, ponto, hífen e sublinhado. O acesso criado é sempre de atendente, vinculado ao ramal indicado e com conexão automática. Se necessário, o ramal é habilitado para navegador na mesma operação. O vínculo não concede chamadas externas: essa permissão continua na configuração do ramal.

Senha: 12–1.024 caracteres. trocar_senha:false entrega o telefone pronto ao entrar; true exige uma nova senha antes de conectar. A API de cadastro nunca devolve a senha. O botão de cópia usa a senha que acabou de ser informada no navegador; depois de fechar, é necessário redefini-la para gerar um novo pacote completo. GET de usuários/acessos retorna somente metadados.

A URL é https://pabx.atendai.chat/webphone. A pessoa entra com usuário ou e-mail e senha; não recebe parâmetros de senha na URL. Precisa permitir microfone e ativar áudio no navegador. Alterar ou desativar o acesso revoga suas sessões anteriores; não é uma ordem de hangup de chamada SIP já estabelecida. A senha do usuário é separada da credencial SIP do ramal.

Auditoria e suporte

A auditoria registra o administrador real mesmo quando está gerenciando um cliente. Integrações são identificadas pelo ID e nome da chave, sem armazenar o token. Há snapshots da identidade, cliente, ação, IP/origem, requisição e dados anteriores/posteriores com segredos ocultos. Histórico anterior às melhorias pode ter menos informações.

Filtros: usuario_id (UUID), acao, inicio/fim (YYYY-MM-DD no horário de Brasília), antes_de (cursor). A auditoria global também aceita empresa_id numérico, vazio (todos) ou plataforma. Retorno: {registros:[...],proximo:123}; envie o próximo cursor em antes_de até proximo=null. Detalhes usam o ID numérico da auditoria. O cliente não consegue consultar registros de outros clientes ou da plataforma.

Arquivos para integração e LLM

Guia em Markdown: /documentacao/api.md. Contrato OpenAPI 3.0.3: /documentacao/openapi.json. Documento completo para LLM, com regras de uso e toda a referência: /documentacao/llm.md. Página navegável: /documentacao/api. Esses arquivos são públicos e contêm apenas exemplos fictícios; nenhum segredo ou dado de clientes é incorporado.

Lista de clientes da plataforma

Em **Clientes**, as linhas expansíveis mostram nome, CNPJ, prefixo SIP e situação. Expanda para ver os dados e os botões **Gerenciar cliente** e **Editar cadastro**. O filtro inicia em Ativos; também oferece Desativados e Todos e permanece na URL ao recarregar a página. Clientes desativados mantêm a edição do cadastro, sem o botão de gestão.

GET /administracao/empresas?situacao=ativas aceita ativas, desativadas ou todas; omitido retorna todas para manter compatibilidade. Valor inválido retorna 422. Continua restrito à sessão de superadministrador; chaves de cliente não acessam esta lista.

curl --fail-with-body "$BASE/administracao/empresas?situacao=desativadas" \
  -b cookies.txt

Desativar e reativar uma operadora sem alterar rotas

Em **Operadoras → Desativar**, somente o tronco fica desativado. Não é necessário desativar rotas de entrada, rotas de saída ou campanhas vinculadas. Elas mantêm seus cadastros, destinos, situação e versão. O histórico e as credenciais do tronco são preservados. A alteração é auditada e limitada à empresa autenticada.

O provisionador remove o registro SIP e os objetos do tronco no Asterisk e recarrega o módulo de registros. O efeito é assíncrono; a resposta HTTP confirma o cadastro, não a conclusão do desregistro na operadora. Novas entradas por um tronco desativado são recusadas, mesmo durante o provisionamento; as saídas ignoram esse tronco e podem usar outra operadora ativa já configurada na rota. Campanhas vinculadas aguardam capacidade e não iniciam novas tentativas por esse tronco. A operação não envia hangup às chamadas em andamento.

Para reativar pelo painel, abra **Editar → Cadastro ativo** e salve. O registro SIP volta conforme a opção **Registrar na operadora** já salva, e as rotas existentes voltam a ser usadas sem recriação. Uma rota anteriormente desativada continua desativada.

# Suspender apenas a operadora; exige troncos:escrever.
curl --fail-with-body -X DELETE "$BASE/troncos/$TRONCO_ID" \
  -H "Authorization: Bearer $CHAVE_API"

# Reativar com a configuração e a versão atuais. Requer também troncos:ler.
curl --fail-with-body "$BASE/troncos/$TRONCO_ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  | jq '.dados | {nome, configuracao, versao, ativo: true}' \
  | curl --fail-with-body -X PUT "$BASE/troncos/$TRONCO_ID" \
      -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
      --data-binary @-

DELETE /troncos/{id} retorna {sucesso:true,dados:{desativado:true}}. PUT /troncos/{id} com ativo:false, nome, configuração completa e versão atual tem o mesmo efeito. Vínculos não produzem EM_USO para esta desativação; proteções de dependência dos demais cadastros continuam aplicáveis. Ao simular uma entrada por tronco desativado, o servidor retorna 403 OPERADORA_DESATIVADA.

A opção configuracao.registrar:false é diferente de desativar o cadastro: ela mantém o tronco ativo, para operadoras que permitem chamadas sem REGISTER. Não a use como confirmação de que um tronco deixou de aceitar chamadas.

Campanha executando sem ligar: diagnóstico da discagem

estado: executando significa que a campanha está habilitada. Não comprova que houve uma tentativa. Na lista do painel, as campanhas em execução mostram a situação operacional atual; em **Operar**, o aviso explica o motivo, a operadora e a ação necessária. As consultas não originam chamadas.

CAMPANHA_ID="UUID_DA_CAMPANHA"
curl --fail-with-body "$BASE/campanhas/$CAMPANHA_ID/status" \
  -H "Authorization: Bearer $CHAVE_API" | jq '.dados | {estado,rotulo,motivo,mensagem,orientacao,operadora,discagem,pendencias,processamento,vagas,ativas}'

curl --fail-with-body "$BASE/campanhas/$CAMPANHA_ID/resultados?pagina=1" \
  -H "Authorization: Bearer $CHAVE_API" | jq '.dados.contatos[] | {telefone,estado,tentativas,ultimo_resultado,situacao_discagem}'

Use os mesmos BASE, CHAVE_API e UUID da campanha dos exemplos anteriores. As duas consultas exigem campanhas:ler da própria empresa. Os contatos são paginados em grupos de 100.

MotivoSignificado e ação
sem_rotaHá contatos sem uma rota ativa que aceite o número e inclua a operadora selecionada. Confira prefixo, comprimento, operadoras e transformação de dígitos em **Rotas de saída**.
numero_invalidoO telefone ou a transformação de dígitos produz um número inválido. Confira os dados e a rota.
aguardando_retentativaO intervalo ainda não venceu. discagem.proxima_tentativa_em informa a primeira data futura elegível; horários e capacidade ainda se aplicam.
aguardando_atendenteConfira fila.agentes: desconectado, pausado, em ligação, descanso ou reservado para outra campanha.
fora_do_horario / fila_fechadaConfira a agenda da campanha e a ativação/agenda da fila no fuso da empresa.
limite_de_chamadasAguarde liberação do limite da campanha, empresa ou operadora.
processamento_indisponivelO heartbeat de discador ou chamadas está ausente ou tem mais de 30 segundos. Peça ao administrador para verificar Diagnósticos.
telefonia_indisponivel / operadora_desativadaA consulta da telefonia falhou ou a operadora está desativada.
sem_contatos / contatos_bloqueados / tentativas_esgotadasNão há contato apto para novas tentativas. Confira os resultados e a lista de bloqueio.
disponivel / em_ligacaoHá contatos elegíveis para o próximo ciclo ou chamadas em andamento. Não garantem que o cliente ou atendente atendeu.

Exemplo: +55 (11) 4000-9990 é armazenado como 551140009990, com 12 dígitos. Uma rota que só aceita 10–11 dígitos não corresponde a esse formato. Se a operadora recebe 0 + DDD + número, uma rota brasileira pode aceitar prefixo 55, tamanho 12–13, remover 2 e adicionar 0, vinculada à operadora da campanha. Isso é um exemplo; confirme o formato exigido pela operadora antes de salvar. O sistema não remove o país nem ativa rotas por conta própria.

A partir da versão 0.16.0, contatos sem rota permanecem pendentes, não consomem tentativas e não impedem os demais contatos válidos de discar. pendencias aparece mesmo quando outro motivo principal, como horário ou fila, impede a execução. Corrigir a rota atualiza a prévia automaticamente, sem reimportar o contato. **Se a campanha estiver executando, ela poderá discar assim que houver rota, horário e atendente; pause antes da alteração se quiser controlar a retomada.**

discagem.prontos conta contatos com rota válida, intervalo vencido, tentativas restantes e sem bloqueio. vagas agora também é limitado a essa quantidade; a capacidade independente da fila continua em fila.capacidade_discagem. Nos resultados, situacao_discagem contém motivo, mensagem e eventual próxima tentativa para contatos pendentes; é null nos demais estados. O histórico da chamada anterior continua em ultimo_resultado e resultado_campanha. Horários são retornados com timezone; a interface os apresenta em fuso_horario da empresa.

Registro, histórico e recuperação das operadoras (0.21.0)

Em **Operadoras → Status e histórico**, consulte o estado atual, a política de recuperação aplicada, a última falha e a linha do tempo. A lista de operadoras atualiza o estado a cada 30 segundos; a tela de histórico, a cada 15 segundos. Filtre por registros SIP, alterações de cadastro e período. Os horários usam o fuso da empresa. A auditoria identifica quem criou, alterou, desativou ou reativou a operadora.

configuracao.recuperar_registro é booleano, padrão true. Salvar o cadastro aplica novas tentativas a cada 60 segundos para falhas temporárias (como falta de resposta e SIP 503) e intervalo_recuperacao segundos para rejeições (padrão 300; entre 60 e 3600, incluindo falha de autenticação 401/407 e SIP 403). O Asterisk respeita Retry-After informado pela operadora. O limite técnico é 1.000.000 de tentativas consecutivas e é zerado após um registro bem-sucedido; não se trata de tentativas ilimitadas. Desmarcar a opção volta à política anterior: 10 tentativas para falhas temporárias e nenhuma nova tentativa após rejeições permanentes. Desativar a operadora ou desmarcar registrar interrompe o registro, independentemente desta opção. Uma senha incorreta, bloqueio de conta ou IP não autorizado precisa de correção; tentar novamente não elimina essa causa.

Na atualização, a migração 025 solicita o reprovisionamento dos cadastros ativos. O monitor verifica divergências periodicamente e reaplica a política automaticamente: recuperacao.habilitada informa a preferência do cadastro; recuperacao.aplicada confirma se a configuração consultada no Asterisk corresponde à preferência atual, inclusive quando a recuperação está desligada. Não confunda ambos. O estado indisponivel significa que não foi possível consultar a telefonia, não que a operadora esteja desregistrada. sem_registro é a configuração deliberada de uma operadora que não usa REGISTER.

Todas as consultas abaixo exigem troncos:ler e ficam limitadas à empresa da autenticação. O endpoint legado /troncos/{id}/diagnostico mantém seu formato de lista de etapas.

# Lista com estados atuais, sem senhas ou pacotes SIP.
curl --fail-with-body "$BASE/troncos/status" -H "Authorization: Bearer $CHAVE"

# Mesmo formato, com um único item em dados.troncos.
curl --fail-with-body "$BASE/troncos/$TRONCO_ID/status" -H "Authorization: Bearer $CHAVE"

# Datas inclusivas, no fuso da empresa; 50 eventos por página.
curl --fail-with-body --get "$BASE/troncos/$TRONCO_ID/historico" \
  -H "Authorization: Bearer $CHAVE" \
  --data-urlencode 'tipo=todos' --data-urlencode 'pagina=1' \
  --data-urlencode 'inicio=2026-10-17' --data-urlencode 'fim=2026-10-17'

A consulta de status retorna troncos, consultado_em, fuso_horario e monitoramento. Cada tronco contém estado, rotulo, consulta_disponivel, observacao, ultima_falha, proxima_tentativa_estimada_em e recuperacao. Estados: registrado, rejeitado, pausado, desativado, sem_registro, indisponivel, nao_configurado e nao_registrado. observacao é a última coleta persistida, com estado e datas; a situação atual vem da consulta ao Asterisk. ultima_falha continua disponível após a recuperação e não deve ser apresentada como falha atual quando o estado for registrado.

proxima_tentativa_estimada_em informa a previsão do último aviso nativo ainda futuro ou o prazo persistido do monitor. É uma estimativa, não garantia: comandos e consultas dependem dos serviços e da resposta da operadora. A previsão pode ser nula, atrasada ou substituída por novo aviso. monitoramento informa a saúde da coleta de estados (registros_troncos), logs (logs_troncos) e recuperação (recuperacao_troncos). O monitor verifica aproximadamente a cada 15 segundos no processo de provisionamento; intervalos podem aumentar durante operações lentas.

A aplicação deixa o Asterisk fazer as tentativas nativas. Se elas pararem de avançar, o monitor solicita um novo REGISTER após o intervalo configurado, com margem de 30 segundos e considerando a última falha/tentativa conhecida. Configuração divergente ou registro ausente pode exigir reprovisionamento. Um tronco registrado e com política correta não é reiniciado pelo monitor nem pelo botão Tentar agora.

configuracao.recuperar_ao_registrar_ramal é booleano, padrão true, independente de recuperar_registro. Um novo registro SIP autenticado de qualquer ramal da **mesma empresa** pode antecipar a recuperação dos troncos não registrados. O monitor considera eventos registro dos últimos dois minutos, uma única vez por tronco; renovações periódicas e OPTIONS não disparam a ação. O gatilho respeita o prazo nativo informado no último aviso. Há intervalo mínimo de 60 segundos desde a última intervenção/falha conhecida; eventos durante esse período são consumidos, sem fila acumulada. Operadoras desativadas, sem REGISTER ou pausadas são ignoradas. Para desligar as duas formas de recuperação, desmarque as duas opções; para interromper registro e renovações use Pausar registro.

Em **Operadoras → Status e histórico**, administradores têm **Tentar agora**, **Pausar registro** e **Retomar registro**. Pausar remove a configuração de REGISTER e suspende renovações, podendo impedir novas chamadas recebidas. As rotas e credenciais permanecem; chamadas em curso não são encerradas pela aplicação. A pausa sobrevive a reinícios, reprovisionamento e novos registros de ramais. Só Retomar a remove. O estado pausado indica a intenção persistida; controle_registro.solicitacao não nula indica que a aplicação ao Asterisk ainda está pendente.

# Solicitar tentativa, sem alterar senha nem desligar rotas.
curl --fail-with-body -X POST "$BASE/troncos/$TRONCO_ID/registro" \
  -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"acao":"tentar"}'

# Suspender registro e todas as recuperações até retomada explícita.
curl --fail-with-body -X POST "$BASE/troncos/$TRONCO_ID/registro" \
  -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"acao":"pausar"}'

# Retomar (respeita o limite de frequência).
curl --fail-with-body -X POST "$BASE/troncos/$TRONCO_ID/registro" \
  -H "Authorization: Bearer $CHAVE" -H 'Content-Type: application/json' \
  -d '{"acao":"retomar"}'

POST exige troncos:escrever ou sessão de administrador da empresa/master com CSRF. Corpo exclusivo acao, valores tentar, pausar, retomar. Retorna **202** com tronco_id, acao, estado e mensagem; não significa registro confirmado. Consulte o status até estado=registrado, pausa aplicada ou falha explícita. 403: sem permissão; 404: tronco fora da empresa; 409: operadora desativada/sem REGISTER ou tentar durante pausa; 422: campos inválidos; 429: menos de 60 segundos entre solicitações de tentativa/retomada ou desde a última intervenção. Pausa pode cancelar uma solicitação pendente imediatamente; pausas repetidas são idempotentes. Não faça polling de POST.

Campos adicionais no status: mensagem_operacional, monitor_recuperacao_saudavel, controle_registro (pausado, solicitacao, solicitada_em, ultima_tentativa_em, proxima_tentativa_em, resultado) e, em recuperacao, ao_registrar_ramal e intervalo_configurado_segundos. ultima_tentativa_em é a intervenção da aplicação, não cada renovação SIP nativa. resultado pode ser aguardando, solicitado, pausado, configuracao_aplicada, registrado, aguardando_recuperacao, recuperacao_desligada, tentativa_enviada, falha_comunicacao ou desativado. Um comando aceito pelo Asterisk ainda aguarda a resposta da operadora. As solicitações são auditadas com o responsável; a execução aparece no histórico com origem usuario, ramal ou monitor.

O histórico retorna eventos, pagina, proxima_pagina, primeiro_evento_registro e fuso_horario. tipo do filtro aceita todos, registros e alteracoes; página de 1 a 100.000. Eventos incluem ocorrido_em, grupo, tipo, estado, codigo_sip, motivo, nova_tentativa_segundos, origem, responsavel, titulo, mensagem e nivel. codigo_sip fica nulo quando não há resposta; não invente SIP 403 ou senha incorreta a partir de Rejected. Os eventos observado registram o estado encontrado pelo monitor, não o instante exato em que a falha começou. renovado indica renovação confirmada; registrado, recuperação observada após outro estado.

A coleta combina eventos AMI Registry, consulta periódica e avisos específicos de registro do log Asterisk. Não grava mensagens SIP brutas, autenticação Digest nem segredos. A vinculação de avisos exige a correspondência única de conta, servidor e porta: contas ambíguas são ignoradas para evitar associação incorreta entre clientes. Ao iniciar, o coletor lê até os últimos 2 MiB do log atual e do rotacionado .1, deduplicando eventos. Logs antigos comprimidos não são importados automaticamente. Histórico anterior à implantação ou a uma interrupção do coletor pode estar incompleto; datas de falha não devem ser reconstruídas por suposição. O banco de histórico entra no backup normal da aplicação.

Segurança e acessos da plataforma

Disponível em **Plataforma → Segurança e acessos** (/seguranca-rede). Somente usuários ativos com perfil superadministrador, após a troca da senha inicial, podem consultar ou alterar a segurança. A página é global mesmo quando há um cliente selecionado: um IP público pode ser compartilhado por vários clientes e aparelhos. Administradores de clientes, supervisores, atendentes e chaves Bearer não têm acesso.

O painel mostra o Fail2Ban da proteção atendai-sip, os bloqueios e respectivos prazos, as regras atuais do UFW e eventos sanitizados de autenticação SIP, falhas de registro Asterisk, bloqueios/liberações e pacotes registrados pelo UFW. Ao consultar um IP, mostra também contatos SIP ativos naquele endereço, com cliente, ramal, porta, situação e validade do registro. Os horários da interface são de Brasília; a API entrega ISO 8601 com fuso.

**Como investigar um ramal que não registra:**

1. Consulte o IP público do cliente. Confira se há bloqueio no Fail2Ban ou na lista manual do painel.

2. Expanda os eventos recentes. ChallengeSent é uma etapa normal da autenticação. ChallengeResponseFailed, InvalidPassword e autenticacao_recusada indicam recusa. O usuário informado em uma requisição recusada não é uma identidade autenticada; ele ajuda a localizar um aparelho configurado incorretamente.

3. Confira a porta de origem e os dispositivos registrados. Uma autenticação aceita isolada não garante registro ativo; a lista de contatos é consultada separadamente.

4. Corrija a configuração no aparelho. Uma tentativa errada de outro telefone no mesmo IP pode causar bloqueio e afetar todos os ramais dessa conexão.

5. Se ainda houver bloqueio, libere o nível correspondente, informe o motivo e confirme. Consulte novamente o IP. Novas falhas podem provocar outro bloqueio automático.

Ações disponíveis:

acaoEfeito
desbloquear_fail2banRemove o bloqueio atual daquele IP somente na proteção atendai-sip. Não cria uma exceção permanente e não remove regras UFW.
bloquear_sipCria uma regra UFW persistente, restrita à entrada UDP 5060 daquele IP, e aciona o Fail2Ban para bloquear imediatamente também fluxos SIP já existentes.
remover_bloqueio_sipRemove somente a regra SIP criada pelo painel. Se o Fail2Ban também estiver bloqueando, libere-o separadamente.

As ações não alteram SSH, HTTPS, RTP, regras de outros serviços, política geral do firewall ou parâmetros do Fail2Ban. Redes/CIDRs, portas arbitrárias e comandos livres não são aceitos. Endereços de loopback, multicast, não especificados e link-local são protegidos; a criação de bloqueio também recusa endereços locais do próprio servidor. Regras criadas fora do painel são exibidas para consulta e não são removidas por essas ações.

Toda alteração exige motivo com 10 a 500 caracteres e confirmar:true. A auditoria global registra solicitação, administrador, IP, motivo e conclusão ou falha, com o mesmo operacao_id. Um registro adicional do adaptador, protegido pelo root, permite verificar a execução no servidor. Não escreva senhas no motivo. A consulta não retorna senhas, respostas de autenticação, desafios, Call-ID, SessionID nem pacotes SIP completos.

API administrativa

São rotas adicionais, sem alteração dos contratos anteriores. **Usam exclusivamente cookie de sessão de superadministrador**; não envie Authorization/Bearer. POST exige X-CSRF-Token. O limite é de 40 requisições por minuto por administrador, compartilhado entre consulta e ações.

# BASE inclui /api/v1. Use a sessão autenticada do administrador master.
curl --fail-with-body -b sessao.txt --get \
  "$BASE/administracao/seguranca-rede" \
  --data-urlencode 'ip=198.51.100.24' \
  --data-urlencode 'fonte=todas' \
  --data-urlencode 'nivel=problemas'

curl --fail-with-body -b sessao.txt -X POST \
  "$BASE/administracao/seguranca-rede/acoes" \
  -H "X-CSRF-Token: $CSRF" -H 'Content-Type: application/json' \
  -d '{"acao":"desbloquear_fail2ban","ip":"198.51.100.24","motivo":"Configuração SIP corrigida pelo responsável.","confirmar":true}'

GET aceita somente ip opcional, fonte (todas, sip, asterisk, fail2ban, firewall) e nivel (problemas, padrão; ou todos). O filtro problemas também inclui as liberações para mostrar o ciclo do bloqueio. Sem IP, a listagem apresenta eventos globais. POST aceita somente acao, ip, motivo e confirmar. IP deve ser um IPv4 ou IPv6 individual, sem porta, máscara ou zona.

A consulta retorna dados.consultado_em, fail2ban, firewall, falhas, logs, contatos e telefonia_disponivel. Com IP, inclui diagnostico.bloqueado_fail2ban e diagnostico.bloqueado_painel. Valores null significam consulta inconclusiva. Serviço indisponível não deve ser mostrado como ausência de bloqueios. telefonia_disponivel:null significa que os contatos não foram consultados porque o IP não foi informado. Os indicadores por IP verificam somente a proteção SIP e as regras do painel; regras UFW externas aparecem na tabela, mas não são interpretadas como um parecer completo de conectividade.

O resultado confirmado da ação contém aplicada:true, acao, ip e operacao_id. Em 503, a ação pode ter sido aplicada parcialmente antes de falhar a verificação; consulte novamente o IP e a auditoria. Não repita alterações em massa. A requisição retorna 401 sem sessão, 403 sem perfil/CSRF adequado ou com Bearer, 422 para campos inválidos e 429 ao ultrapassar o limite.

Cobertura e limitações dos logs

A consulta exibe até 200 eventos mais recentes encontrados nos trechos lidos. logs.cobertura identifica a fonte, o arquivo e se a leitura foi parcial; mais_registros indica mais ocorrências no trecho consultado. São lidos o arquivo atual e .1: até 12 MiB por arquivo de segurança SIP, 4 MiB por arquivo operacional Asterisk e 2 MiB por arquivo Fail2Ban/UFW. Arquivos compactados não são consultados. Refine IP e origem para investigar. Ausência de eventos não comprova ausência de tentativas.

Se /var/log/ufw.log não existir ou o firewall não registrar determinado tráfego, não haverá eventos UFW; suas regras ainda podem estar ativas. O painel não habilita logging de pacotes SIP, não altera a política de logs, não consulta firewalls do provedor e não interpreta regras nftables/iptables criadas manualmente fora do UFW/Fail2Ban.

Validade do registro e conexão dos ramais (0.21.1)

expira_em é o prazo de validade daquele contato SIP observado, renovado automaticamente pelo aparelho enquanto conectado. Não é um desligamento agendado e não é o tempo máximo de chamada. O telefone negocia esse prazo no REGISTER; a configuração SIP sugere 300 segundos, e o Asterisk aceita prazos entre 60 e 7200 segundos. Telefones que solicitam 60 ou 90 segundos precisam renovar antes do vencimento. Não simule um registro permanente nem marque um aparelho sem resposta como conectado.

No histórico, renovacao aparece como **Renovação automática (normal)**; expirado, como **Contato expirou sem renovação**. Eventos SIP acrescentam mensagem, explicando o significado sem alterar evento ou tipo. A validade em eventos antigos é a daquele instante, não a validade atual. O vencimento de um contato não significa necessariamente que todos os dispositivos do ramal desconectaram: consulte conexao.estado e cada dispositivo de GET /ramais/conexoes.

- conectado: contato válido com resposta à verificação de disponibilidade.

- indisponivel: contato ainda válido, mas sem resposta à verificação.

- desconectado: nenhum contato válido observado.

- verificando: ainda aguardando confirmação de resposta.

- desconhecido: consulta indisponível; não conclua que houve queda.

A partir da migração 027, o histórico reconhece o separador ^3B usado pelo Asterisk Realtime nas URIs e conserva o IP/porta do Contact público. Eventos anteriores que exibiam endereço privado de Via são preservados e identificados por fonte_ip=via_sip; não são reescritos com o endereço atual.

O provisionamento de troncos com servidor/porta explícitos usa srv_lookups=no nos objetos identify. Domínios continuam resolvidos por A/AAAA; apenas a descoberta de serviços SRV é dispensada nesse caminho. Isso evita repetição de consultas de serviços UDP/TCP/TLS durante a identificação dos pacotes SIP. Não altera usuário, senha, destino de chamadas, codecs ou tempo de validade de ramais.

Diagnóstico das tentativas de chamada (0.21.2)

O histórico geral e o histórico de cada ramal mostram **Entender esta tentativa**, com orientação, número digitado, número enviado à operadora, resposta SIP, resultado da discagem e causa de encerramento. Os horários do painel são de Brasília.

As consultas GET /chamadas, GET /chamadas/{id} e os detalhes dos eventos de chamada em GET /ramais/{id}/historico acrescentam diagnostico, sem remover campos ou mudar rotas. Eventos futuros call.failed e call.completed também podem incluir o diagnóstico. Consultas exigem as permissões existentes e respeitam a empresa autenticada. Não há exposição de credenciais ou da solicitação interna.

curl "$BASE/chamadas/$CHAMADA_ID" \
  -H "Authorization: Bearer $CHAVE_API"

diagnostico é null quando não há interpretação aplicável (inclusive chamada em andamento, atendida ou com resultado específico de campanha); nos demais casos contém:

CampoSignificado
codigosem_rota, linhas_ocupadas, cancelada, destino_nao_localizado, formato_invalido, ocupado, sem_resposta, recusada ou indisponivel
origempabx para bloqueio local comprovado; operadora_ou_destino para SIP 404 em discagem externa; indeterminada nos demais casos
mensagemExplicação do resultado observado
orientacaoPróximo passo, sem presumir uma causa não demonstrada

Exemplo fictício: destino="40001234", numero_enviado="01140001234", dial_status="CHANUNAVAIL", sip_status=404 resultam em codigo="destino_nao_localizado". O PABX acrescenta o DDD da empresa a números locais de 8/9 dígitos, antes de aplicar a transformação da rota. Confirme o DDD real do destino: o cadastro da empresa não prova que o destino seja local.

SIP 404 significa que o endereço solicitado não foi localizado pelo servidor que respondeu; não comprova que o telefone inexiste em todas as redes. Verifique o formato exigido e, se estiver correto, encaminhe à operadora o número enviado, horário e código. Referência: RFC 3261, seção 21.4.5.

SIP 180/183 são respostas provisórias e não comprovam atendimento. CANCEL permanece cancelamento mesmo se houve 183. hangup_cause=21 sem motivo local persistido não prova recusa pela operadora. Novas falhas ROTA_NAO_ENCONTRADA no dialplan são registradas como falha local antes do encerramento; o motivo não é substituído por uma mensagem genérica no hangup. Históricos antigos não são reescritos nem reclassificados a partir das rotas atuais. numero_enviado=null isoladamente significa ausência de informação, não prova que não houve discagem.

Se a operadora confirmar que um destino específico exige somente os 8 dígitos locais, crie uma exceção exata em POST /rotas_saida antes da rota geral. Exemplo fictício para empresa com DDD 11 e destino 40001234: prefixo="1140001234", tamanho_minimo=10, tamanho_maximo=10, remover=2, adicionar="", prioridade numericamente menor que a rota geral e os mesmos troncos autorizados. O prefixo é comparado **após** a normalização do DDD. Assim, 40001234, 1140001234 e 01140001234 enviam 40001234; outros números mantêm suas rotas. Valide na simulação antes de discar. Não remova o DDD de todas as chamadas para resolver uma exceção de destino.

Interfone por QR Code fixo (0.23.0)

No cliente selecionado, abra **Telefonia → Interfones → Criar Interfone**. Informe o nome que o visitante verá e escolha um ramal, fila, URA ou regra de horário **ativo da mesma empresa**. Salve e abra **QR Code e link** para baixar o PNG e imprimir na entrada. O QR é gerado no navegador, sem enviar o link para serviços externos. O destino e os limites podem ser alterados mantendo o mesmo QR. **Substituir QR Code** invalida o anterior e encerra as visitas abertas. Desativar o interfone também encerra visitas; ativá-lo novamente mantém seu QR atual.

O visitante não precisa de login. Deve abrir o link em HTTPS, tocar em **Chamar** e autorizar o microfone. Não há chamada automática ao abrir a página. A tela mostra conexão, toque, atendimento e término, com microfone, saída de áudio e teclado para URAs. A identidade exibida ao destino é Interfone · Nome. A chamada segue os fluxos existentes, inclusive Siga-me, agenda, fila, URA e gravação recebida configurada no ramal. O visitante não escolhe um número livre nem recebe acesso ao painel. A página deve permanecer aberta durante a conversa; o sistema não promete manter áudio com o celular bloqueado ou o navegador suspenso.

ConfiguraçãoPadrãoFaixa e comportamento
duracao_maxima300 segundos30–1800; começa no INVITE aceito pelo servidor, inclui espera, menus e conversa
intervalo60 segundos10–3600; mesmo interfone e mesmo IP **ou** cookie; contado da abertura ou encerramento, o mais recente
simultaneas11–10 visitas abertas, incluindo páginas aguardando; respeita também o limite de chamadas da empresa
Prazo para iniciar120 segundosFixo; a visita expira mesmo sem clicar em Chamar

Pessoas na mesma rede podem compartilhar o limite por IP. Um QR fixo pode ser fotografado ou compartilhado: quem possuir o link poderá iniciar outra visita **após os limites**, mesmo fora do local. O QR não comprova presença física. Para invalidar um link divulgado, use Substituir QR Code. Há limites adicionais de 60 aberturas/hora/IP, 30 aberturas/minuto/QR e 600 requisições públicas/minuto/IP.

API de administração

As novas rotas são aditivas; os contratos existentes de ramais, WebPhone, chamadas e gravações permanecem. Use uma chave da empresa com interfones:ler e/ou interfones:escrever. No painel, administrador da empresa ou da plataforma gerencia os interfones; atendentes e supervisores não recebem os links administrativos. Para montar um seletor de destinos pela API, conceda separadamente leitura dos recursos desejados.

BASE='https://pabx.atendai.chat/api/v1'
# CHAVE_API e RAMAL_ID pertencem ao cliente selecionado.
curl --fail-with-body --silent --show-error "$BASE/interfones" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data "{\"nome\":\"Portaria principal\",\"destino\":{\"tipo\":\"ramal\",\"id\":\"$RAMAL_ID\"},\"duracao_maxima\":300,\"intervalo\":60,\"simultaneas\":1,\"ativo\":true}"

A resposta dados contém id, empresa_id, os campos configuráveis, versao, datas e url. A URL tem o formato /interfone#CHAVE_ALEATORIA: o fragmento não é enviado em logs HTTP nem em Referer. Não registre essa URL em logs da integração. A chave é guardada cifrada no servidor. GET /interfones lista até 500; GET /interfones/{id} consulta um. PUT /interfones/{id} substitui a configuração e exige a versao atual; para desativar, envie todos os campos e ativo:false. Não há exclusão física de interfone; o histórico é preservado.

curl --fail-with-body --silent --show-error "$BASE/interfones/$ID/sessoes" \
  -H "Authorization: Bearer $CHAVE_API"
curl --fail-with-body --silent --show-error -X POST "$BASE/interfones/$ID/renovar-link" \
  -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
  --data '{"versao":1}'

O histórico retorna as últimas 50 visitas, mais recentes primeiro, com id, estado, ip, criada_em, expira_em, iniciada_em, encerrada_em, motivo_fim, chamada_id e mensagem_resultado. Valores de término: visitante_encerrou, chamada_finalizada ou prazo_ou_desativacao. O UUID chamada_id permite consultar os endpoints habituais de chamadas/gravações, com seus escopos próprios. Sessões sem ligação têm chamada_id:null. A disponibilidade do WAV continua assíncrona, conforme o contrato de gravações. Criação, edição, renovação, abertura e encerramento têm auditoria. Não é permitido desativar um destino usado por interfone ativo; exclusão de ramal também verifica vínculos preservados.

Contrato público da visita

A página /interfone usa **JsSIP já incluído no projeto**. Não use /webphone/preparar, contas de funcionários nem chaves administrativas no navegador do visitante. As quatro rotas abaixo são POST em /api/v1/publico/interfone, exigem Content-Type: application/json e Origin exata de URL_APLICACAO. São destinadas à página na mesma origem, sem CORS externo. Um backend pode usar cURL para homologação com cookie próprio, mas isso não inicia áudio.

1. abrir, corpo {"chave":"64 caracteres hexadecimais do fragmento"}: cria atendai_visitante, cookie Secure/HttpOnly/SameSite=Strict, e retorna sessao_id, segredo, nome, estado:"aguardando", expira_em ISO 8601 e duracao_maxima. Cada abertura cria uma nova sessão sujeita aos limites. Manter UUID/segredo **somente em memória**, não em localStorage ou logs.

2. Depois do gesto do usuário e permissão de microfone, preparar, corpo {"sessao_id":"UUID","segredo":"SEGREDO_DA_VISITA"} e o mesmo cookie. Retorna usuario, senha, dominio, wss, destino:"chamar", expira_em **uma única vez**. São credenciais efêmeras de INVITE, não de registro de ramal. Instanciar JsSIP.UA com register:false, session_timers:false, URI sip:USUARIO@DOMINIO e WSS retornado; ao conectar, executar uma única ua.call('sip:chamar@DOMINIO', {mediaStream,...}). Não enviar REGISTER, outro destino ou REFER. O browser não recebe empresa/destino administrativo para controlar o roteamento.

3. estado, mesmo corpo e cookie: retorna estado, expira_em, motivo_fim e chamada nula ou com estado, mensagem_resultado, atendida_em. Consultar a cada 5 segundos; atualizar o prazo após o INVITE, pois passa do limite de início para o limite de duração. Estados: aguardando → pronta → em_chamada → encerrada; qualquer estado não terminal pode expirar/ser cancelado.

4. encerrar, mesmo corpo e cookie: resposta {"encerrada":true}. Idempotente para a própria sessão, revoga SIP e solicita hangup. No navegador, também finalizar RTCSession, UA, tracks de microfone e áudio. Executar ao sair/encerrar; o servidor mantém proteção independente desses avisos.

ORIGEM='https://pabx.atendai.chat'
BASE="$ORIGEM/api/v1"
# QR_CHAVE é a parte após #. Não imprimir segredos em logs.
umask 077
curl --fail-with-body --silent --show-error -b visitante.txt -c visitante.txt \
  -H "Origin: $ORIGEM" -H 'Content-Type: application/json' \
  --data "{\"chave\":\"$QR_CHAVE\"}" "$BASE/publico/interfone/abrir" > visita.json
# Criar corpo sem expor o segredo no histórico do shell.
jq '.dados | {sessao_id,segredo}' visita.json > sessao-visita.json
curl --fail-with-body --silent --show-error -b visitante.txt \
  -H "Origin: $ORIGEM" -H 'Content-Type: application/json' \
  --data-binary @sessao-visita.json "$BASE/publico/interfone/estado"
curl --fail-with-body --silent --show-error -b visitante.txt \
  -H "Origin: $ORIGEM" -H 'Content-Type: application/json' \
  --data-binary @sessao-visita.json "$BASE/publico/interfone/encerrar"
rm -f visitante.txt visita.json sessao-visita.json

Não reutilizar preparar após perder sua resposta: a credencial não é retornada novamente. Encerrar a sessão e abrir outra após o intervalo. HTTP 401 indica cookie/segredo inválido; 403, origem ou operação não autorizada; 404, QR/destino indisponível; 409, capacidade ou versão conflitante; 410, sessão já utilizada/expirada/desativada; 429, intervalo ou limite de requisições. O motivo detalhado está em erro.mensagem/erro.codigo.

A identidade PJSIP temporária não possui AOR, REGISTER ou assinaturas, recebe somente o contexto atendai-interfone e não permite REFER. O AGI consome a sessão atomicamente e resolve o destino no servidor; um novo INVITE com as mesmas credenciais é recusado, mesmo durante a primeira chamada. A expiração absoluta é aplicada no Asterisk, há timeout RTP de 45 segundos sem áudio e o worker atendai-chamadas encerra sessões expiradas/desativadas. O encerramento do CDR remove endpoint e autenticação. Esses controles limitam cada sessão a uma ligação; não dependem de timers JavaScript. O visitante usa DTMF apenas nos menus e não recebe o atalho de transferência DTMF do chamador.

Chefe / Secretária (Boss / Secretary)

No painel, abra **Ramais → ramal do chefe → Chefe / Secretária**, ative a triagem e selecione o ramal da secretária. Exemplo: chefe 2000 e secretária 2001. O chefe continua podendo realizar chamadas normalmente. Chamadas destinadas a ele por ramais, operadoras, URAs, encaminhamentos e membros de filas passam pela secretária. Em filas, a regra só é executada quando a fila seleciona o chefe como membro; a disponibilidade da fila continua valendo.

A secretária atende, decide se deve encaminhar e usa **Transferir → 2000** no telefone SIP ou WebPhone. Pode ligar diretamente para o chefe para consultá-lo; aparelhos com transferência assistida podem concluir a consulta antes de unir as partes. Recusar significa encerrar a chamada ou transferir para outro destino. Outros ramais que transfiram para o chefe também passam pela triagem. A identidade é autenticada pelo PABX; alterar o número apresentado não concede permissão.

A triagem precede o Siga-me do chefe. Se liberada pela secretária, as regras normais do chefe (incluindo Siga-me) continuam valendo. Os desvios da secretária também são respeitados, mas não dão autorização aos respectivos destinos para liberar o chefe. Se ela estiver indisponível, não há liberação automática. Ciclos e referências entre empresas são recusados. Desative a triagem para voltar ao comportamento normal. Não exclua a secretária enquanto estiver vinculada.

As rotas novas são aditivas, sem mudança nos contratos existentes:

curl "$BASE/ramais/$CHEFE_ID/chefe-secretaria" \
  -H "Authorization: Bearer $CHAVE_API"

# Use a versão retornada no GET e os UUIDs da empresa autenticada.
curl -X PUT "$BASE/ramais/$CHEFE_ID/chefe-secretaria" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"versao":1,"chefe_secretaria":{"habilitado":true,"secretaria_id":"22222222-2222-4222-8222-222222222222"}}'

BASE termina em /api/v1. Escopos: ramais:ler e ramais:escrever. Resposta em dados: ramal_id, numero, nome, versao, chefe_secretaria. Para desativar, envie habilitado:false com a versão atual; pode conservar secretaria_id ou removê-lo com null. Um PUT /ramais/{id} antigo que omita configuracao.chefe_secretaria preserva a configuração. Alterações são auditadas. Cada triagem emite call.forwarded com motivo:"chefe_secretaria", origem e destino, além da auditoria encaminhar_secretaria. A triagem conserva o UUID da chamada; transferências SIP seguem a cadeia de correlação documentada.

A transferência REST genérica POST /chamadas/{id}/transfer continua sujeita à triagem e não representa a autorização da secretária. Para liberar o chefe, use a sessão SIP autenticada da secretária (REFER do WebPhone/telefone ou consulta e transferência assistida). Na ausência de identificação segura do transferidor, o PABX mantém a triagem.

Registro de um ramal recém-criado ou editado

O cadastro e o provisionamento no Asterisk são etapas distintas. GET /api/v1/webphone continua retornando os mesmos campos quando pronto, com sessão de usuário e isolamento por empresa. Antes de criar JsSIP.UA, confira a resposta:

- 200: use as credenciais retornadas e aguarde o evento registered; o HTTP 200 sozinho não comprova registro SIP.

- 503, erro.codigo=RAMAL_EM_CONFIGURACAO: o endpoint, auth, AOR ou a senha atual ainda não estão disponíveis. Repita esse GET a cada 2 segundos por até 30 segundos; não envie REGISTER enquanto aguarda. O painel faz essa espera automaticamente e mostra “Configurando ramal”. Se persistir, informa que a conexão não foi concluída e permite nova tentativa manual.

- 409, erro.codigo=RAMAL_CONFIGURACAO_FALHOU: as tentativas de provisionamento se esgotaram. O administrador deve corrigir a causa e reprocessar a configuração. Não repetir indefinidamente nem excluir/recriar o ramal ou trocar a senha como solução.

Erros de autenticação/permissão não fazem parte dessa repetição. Trocar o ramal selecionado ou sair da página cancela a espera anterior. Após atualizar o painel, recarregue a página para carregar essa proteção.

Campos dos cadastros

Os corpos JSON usam nome, configuracao e, na edição, versao. ativo é opcional (padrão true). PUT substitui os campos configuráveis; envie o cadastro completo obtido no GET. Campos desconhecidos são descartados. As tabelas abaixo descrevem configuracao; não envie os campos internos endpoint, senha_cifrada, segredo_cifrado ou estado.

Campos: dominios

Organize os endereços SIP da sua empresa.

CampoFormatoUsoPadrão
dominiotextDomínio SIP"empresa.pabx.atendai.chat"
principalbooleanUsar como domínio principalfalse

Campos: ramais

Conecte telefones e organize sua equipe.

CampoFormatoUsoPadrão
numerotextNúmero do ramal"101"
nome_identificacaotextNome exibido nas chamadas (vazio usa o nome do ramal)""
webphonebooleanUsar no navegadortrue
sufixo_siptextUsuário SIP após o prefixo da empresa""
sip_sem_simbolosbooleanHabilitar também usuário SIP sem símbolosfalse
senhapasswordSenha SIP""
externasbooleanPermitir chamadas externasfalse
internacionalbooleanPermitir chamadas internacionaisfalse
timeoutinteiroTempo para atender (segundos)30
destino_nao_atendidoobjeto DestinoSe este ramal não atender{"tipo":"encerrar"}
gravar_realizadasbooleanGravar chamadas feitas por este ramalfalse
gravar_recebidasbooleanGravar chamadas recebidas por este ramalfalse

Campos: troncos

Cadastre o tronco SIP da operadora. Desativar interrompe o registro SIP e preserva as rotas para reativação.

CampoFormatoUsoPadrão
servidortextServidor SIP"sip.operadora.com.br"
portainteiroPorta SIP5060
autenticacaoselectAutenticação; valores: senha, ip"senha"
usuariotextUsuário SIP""
senhapasswordSenha SIP""
ip_autorizadotextIP autorizado pela operadora""
caller_idtextNúmero principal""
transporteselectTransporte; valores: udp, tcp"udp"
registrarbooleanRegistrar na operadoratrue
limiteinteiroLimite de chamadas simultâneas5
recuperar_registrobooleanTentar recuperar o registro automaticamente após falhastrue
intervalo_recuperacaointeiroIntervalo após rejeição, em segundos (60 a 3600)300
recuperar_ao_registrar_ramalbooleanTentar recuperar o tronco quando um ramal desta empresa conectartrue

Campos: rotas_saida

Defina como sua equipe faz chamadas externas.

CampoFormatoUsoPadrão
prefixotextPrefixo permitido (vazio aceita todos)""
tamanho_minimointeiroQuantidade mínima de dígitos8
tamanho_maximointeiroQuantidade máxima de dígitos15
removerinteiroDígitos a remover do início0
adicionartextPrefixo a adicionar""
prioridadeinteiroPrioridade (menor primeiro)10
troncosarray de UUIDs: troncosOperadoras, na ordem de preferência[]

Campos: rotas_entrada

Escolha para onde enviar cada número recebido.

CampoFormatoUsoPadrão
didtextNúmero recebido (DID)""
tronco_idUUID de troncosOperadora""
destinoobjeto DestinoPara onde enviar a ligação?null

Campos: uras

Toque uma mensagem e encaminhe automaticamente ou ofereça um menu de teclas.

CampoFormatoUsoPadrão
modoselectTipo de URA; valores: teclas, simples"teclas"
audio_idUUID de audiosMensagem inicial""
timeoutinteiroEspera pela tecla (segundos)5
repeticoesinteiroRepetições da mensagem1
opcoesobjeto tecla → DestinoOpções do teclado[]
destinoobjeto DestinoSe não houver uma opção válida{"tipo":"encerrar"}
destino_nao_atendidoobjeto DestinoSe o destino escolhido não atender{"tipo":"encerrar"}

Campos: horarios

Direcione ligações conforme expediente e feriados.

CampoFormatoUsoPadrão
periodosarray de faixas {dias,inicio,fim}Dias e faixas de atendimento[]
diasarray de dias 1–7Dias da semana[1,2,3,4,5]
iniciotimeInício do expediente"08:00"
fimtimeFim do expediente"18:00"
intervalostextareaOutros períodos (um HH:MM-HH:MM por linha)""
feriadostextareaFeriados (uma data AAAA-MM-DD por linha)""
destino_abertoobjeto DestinoDurante o expediente (quando usada como destino){"tipo":"encerrar"}
destino_fechadoobjeto DestinoFora do expediente{"tipo":"encerrar"}

Campos: filas

Distribua chamadas entre os atendentes disponíveis.

CampoFormatoUsoPadrão
horario_idUUID de horariosHorário de atendimento; vazio remove a regra""
destino_fechadoobjeto DestinoFora do horário da fila{"tipo":"encerrar"}
ramaisarray de UUIDs: ramaisAtendentes[]
estrategiaselectComo distribuir as chamadas?; valores: ringall, rrmemory, leastrecent, fewestcalls, random"rrmemory"
timeoutinteiroTempo para cada atendente (segundos)20
esperainteiroEspera máxima (segundos)60
descansointeiroDescanso após a chamada (segundos)5
destinoobjeto DestinoSe ninguém atender nesta fila{"tipo":"encerrar"}

Campos: audios

Mensagens de boas-vindas, atendimento e campanhas.

CampoFormatoUsoPadrão
arquivomultipart binárioEnvio somente no POST; PUT altera nome/ativo, mantendo o arquivo—

Campos: campanhas

Ligue com confirmação por tecla ou encaminhe ao atendente assim que o cliente atender.

CampoFormatoUsoPadrão
modoselectComo encaminhar o cliente?; valores: audio_tecla, direto"audio_tecla"
tronco_idUUID de troncosOperadora""
audio_idUUID de audiosMensagem; obrigatório em audio_tecla, ignorado em direto""
fila_idUUID de filasFila de atendimento""
teclaselectTecla para confirmar; valores: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9"1"
tecla_bloqueioselectTecla para não receber novas ligações; valores: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9"9"
espera_teclainteiroEspera pela tecla após a mensagem (segundos)8
espera_atendenteinteiroEspera máxima para conectar um atendente (segundos)30
simultaneasinteiroMáximo de chamadas simultâneas1
tentativasinteiroMáximo de tentativas por contato3
intervalointeiroIntervalo entre tentativas (minutos)120
diasarray de dias 1–7Dias permitidos[1,2,3,4,5]
iniciotimeHorário inicial"09:00"
fimtimeHorário final"17:30"
data_iniciodateData de início (opcional)""
data_fimdateData de término (opcional)""
amdbooleanIdentificar caixa postal (AMD)false
amd_inconclusivoselectSe a detecção de caixa postal for inconclusiva; valores: prosseguir, reagendar"prosseguir"

Campos: webhooks

Envie eventos assinados às suas integrações.

CampoFormatoUsoPadrão
versao_payloadselectFormato do webhook; valores: 1, 2"1"
urlurlEndereço HTTPS de destino"https://"
eventostextareaEventos (um por linha; vazio recebe todos)""

Referência de todas as operações HTTP

As permissões abaixo se referem a chaves Bearer quando indicado. Nos exemplos com sessão, use o procedimento de autenticação de sessão. Os UUIDs 00000000-0000-4000-8000-000000000001 são ilustrativos: substitua cada referência pelo UUID real do recurso correspondente, sempre do mesmo cliente. As variáveis ID, USUARIO_ID, EMPRESA_ID e REGISTRO_ID correspondem aos identificadores presentes na URL.

GET /dominios

Listar Domínios SIP (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: dominios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/dominios" \
  -H "Authorization: Bearer $CHAVE_API"
POST /dominios

Criar domínio SIP.

Autenticação: Bearer ou sessão autorizada. Permissão: dominios:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/dominios" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de domínio SIP",
    "configuracao": {
        "dominio": "empresa.exemplo.com",
        "principal": false
    }
}'
GET /dominios/{id}

Consultar domínio SIP pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: dominios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/dominios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /dominios/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: dominios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/dominios/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de domínio SIP",
    "configuracao": {
        "dominio": "empresa.exemplo.com",
        "principal": false
    },
    "versao": 1,
    "ativo": true
}'
DELETE /dominios/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: dominios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/dominios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /ramais

Listar Ramais (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais" \
  -H "Authorization: Bearer $CHAVE_API"
POST /ramais

Criar ramal.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de ramal",
    "configuracao": {
        "numero": "101",
        "sufixo_sip": "101",
        "sip_sem_simbolos": false,
        "senha": "",
        "webphone": true,
        "externas": false,
        "internacional": false,
        "timeout": 30,
        "destino_nao_atendido": {
            "tipo": "encerrar"
        },
        "gravar_realizadas": false,
        "gravar_recebidas": false
    }
}'
GET /ramais/{id}

Consultar ramal pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /ramais/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de ramal",
    "configuracao": {
        "numero": "101",
        "sufixo_sip": "101",
        "sip_sem_simbolos": false,
        "senha": "",
        "webphone": true,
        "externas": false,
        "internacional": false,
        "timeout": 30,
        "destino_nao_atendido": {
            "tipo": "encerrar"
        },
        "gravar_realizadas": false,
        "gravar_recebidas": false
    },
    "versao": 1,
    "ativo": true
}'
DELETE /ramais/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/ramais/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /troncos

Listar Operadoras (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos" \
  -H "Authorization: Bearer $CHAVE_API"
POST /troncos

Criar operadora.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/troncos" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de operadora",
    "configuracao": {
        "servidor": "sip.operadora.exemplo.com",
        "porta": 5060,
        "autenticacao": "senha",
        "usuario": "USUARIO_DA_OPERADORA",
        "senha": "SUBSTITUA_PELA_SENHA_SIP",
        "ip_autorizado": "",
        "caller_id": "551130000000",
        "transporte": "udp",
        "registrar": true,
        "recuperar_registro": true,
        "limite": 5
    }
}'
GET /troncos/{id}

Consultar operadora pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /troncos/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/troncos/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de operadora",
    "configuracao": {
        "servidor": "sip.operadora.exemplo.com",
        "porta": 5060,
        "autenticacao": "senha",
        "usuario": "USUARIO_DA_OPERADORA",
        "senha": "",
        "ip_autorizado": "",
        "caller_id": "551130000000",
        "transporte": "udp",
        "registrar": true,
        "recuperar_registro": true,
        "limite": 5
    },
    "versao": 1,
    "ativo": true
}'
DELETE /troncos/{id}

Desativar operadora e interromper registro SIP, preservando rotas e vínculos.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/troncos/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /rotas_saida

Listar Rotas de saída (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/rotas_saida" \
  -H "Authorization: Bearer $CHAVE_API"
POST /rotas_saida

Criar rota de saída.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/rotas_saida" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de rota de saída",
    "configuracao": {
        "prefixo": "",
        "tamanho_minimo": 10,
        "tamanho_maximo": 11,
        "remover": 0,
        "adicionar": "0",
        "prioridade": 10,
        "troncos": [
            "00000000-0000-4000-8000-000000000001"
        ]
    }
}'
GET /rotas_saida/{id}

Consultar rota de saída pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/rotas_saida/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /rotas_saida/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/rotas_saida/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de rota de saída",
    "configuracao": {
        "prefixo": "",
        "tamanho_minimo": 10,
        "tamanho_maximo": 11,
        "remover": 0,
        "adicionar": "0",
        "prioridade": 10,
        "troncos": [
            "00000000-0000-4000-8000-000000000001"
        ]
    },
    "versao": 1,
    "ativo": true
}'
DELETE /rotas_saida/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/rotas_saida/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /rotas_entrada

Listar Rotas de entrada (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_entrada:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/rotas_entrada" \
  -H "Authorization: Bearer $CHAVE_API"
POST /rotas_entrada

Criar rota de entrada.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_entrada:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/rotas_entrada" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de rota de entrada",
    "configuracao": {
        "did": "551130000000",
        "tronco_id": "00000000-0000-4000-8000-000000000001",
        "destino": {
            "tipo": "ura",
            "id": "00000000-0000-4000-8000-000000000001"
        }
    }
}'
GET /rotas_entrada/{id}

Consultar rota de entrada pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_entrada:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/rotas_entrada/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /rotas_entrada/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_entrada:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/rotas_entrada/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de rota de entrada",
    "configuracao": {
        "did": "551130000000",
        "tronco_id": "00000000-0000-4000-8000-000000000001",
        "destino": {
            "tipo": "ura",
            "id": "00000000-0000-4000-8000-000000000001"
        }
    },
    "versao": 1,
    "ativo": true
}'
DELETE /rotas_entrada/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_entrada:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/rotas_entrada/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /uras

Listar URAs (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: uras:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/uras" \
  -H "Authorization: Bearer $CHAVE_API"
POST /uras

Criar URA.

Autenticação: Bearer ou sessão autorizada. Permissão: uras:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/uras" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de URA",
    "configuracao": {
        "modo": "teclas",
        "audio_id": "00000000-0000-4000-8000-000000000001",
        "timeout": 5,
        "repeticoes": 1,
        "opcoes": {
            "1": {
                "tipo": "fila",
                "id": "00000000-0000-4000-8000-000000000001"
            },
            "2": {
                "tipo": "ramal",
                "id": "00000000-0000-4000-8000-000000000001",
                "horario_id": "00000000-0000-4000-8000-000000000001",
                "destino_fechado": {
                    "tipo": "encerrar"
                },
                "destino_nao_atendido": {
                    "tipo": "fila",
                    "id": "00000000-0000-4000-8000-000000000001"
                }
            }
        },
        "destino": {
            "tipo": "encerrar"
        },
        "destino_nao_atendido": {
            "tipo": "encerrar"
        }
    }
}'
GET /uras/{id}

Consultar URA pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: uras:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/uras/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /uras/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: uras:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/uras/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de URA",
    "configuracao": {
        "modo": "teclas",
        "audio_id": "00000000-0000-4000-8000-000000000001",
        "timeout": 5,
        "repeticoes": 1,
        "opcoes": {
            "1": {
                "tipo": "fila",
                "id": "00000000-0000-4000-8000-000000000001"
            },
            "2": {
                "tipo": "ramal",
                "id": "00000000-0000-4000-8000-000000000001",
                "horario_id": "00000000-0000-4000-8000-000000000001",
                "destino_fechado": {
                    "tipo": "encerrar"
                },
                "destino_nao_atendido": {
                    "tipo": "fila",
                    "id": "00000000-0000-4000-8000-000000000001"
                }
            }
        },
        "destino": {
            "tipo": "encerrar"
        },
        "destino_nao_atendido": {
            "tipo": "encerrar"
        }
    },
    "versao": 1,
    "ativo": true
}'
DELETE /uras/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: uras:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/uras/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /horarios

Listar Horários (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: horarios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/horarios" \
  -H "Authorization: Bearer $CHAVE_API"
POST /horarios

Criar regra de horário.

Autenticação: Bearer ou sessão autorizada. Permissão: horarios:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/horarios" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de regra de horário",
    "configuracao": {
        "periodos": [
            {
                "dias": [
                    1
                ],
                "inicio": "08:00",
                "fim": "12:00"
            },
            {
                "dias": [
                    1
                ],
                "inicio": "13:00",
                "fim": "22:00"
            },
            {
                "dias": [
                    2,
                    3,
                    4,
                    5
                ],
                "inicio": "09:00",
                "fim": "18:00"
            }
        ],
        "feriados": "2026-12-25",
        "destino_aberto": {
            "tipo": "encerrar"
        },
        "destino_fechado": {
            "tipo": "audio",
            "id": "00000000-0000-4000-8000-000000000001"
        }
    }
}'
GET /horarios/{id}

Consultar regra de horário pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: horarios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/horarios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /horarios/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: horarios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/horarios/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de regra de horário",
    "configuracao": {
        "periodos": [
            {
                "dias": [
                    1
                ],
                "inicio": "08:00",
                "fim": "12:00"
            },
            {
                "dias": [
                    1
                ],
                "inicio": "13:00",
                "fim": "22:00"
            },
            {
                "dias": [
                    2,
                    3,
                    4,
                    5
                ],
                "inicio": "09:00",
                "fim": "18:00"
            }
        ],
        "feriados": "2026-12-25",
        "destino_aberto": {
            "tipo": "encerrar"
        },
        "destino_fechado": {
            "tipo": "audio",
            "id": "00000000-0000-4000-8000-000000000001"
        }
    },
    "versao": 1,
    "ativo": true
}'
DELETE /horarios/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: horarios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/horarios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /filas

Listar Filas (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: filas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/filas" \
  -H "Authorization: Bearer $CHAVE_API"
POST /filas

Criar fila.

Autenticação: Bearer ou sessão autorizada. Permissão: filas:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/filas" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de fila",
    "configuracao": {
        "ramais": [
            "00000000-0000-4000-8000-000000000001"
        ],
        "estrategia": "rrmemory",
        "timeout": 20,
        "espera": 60,
        "descanso": 5,
        "destino": {
            "tipo": "encerrar"
        },
        "horario_id": "00000000-0000-4000-8000-000000000001",
        "destino_fechado": {
            "tipo": "encerrar"
        }
    }
}'
GET /filas/{id}

Consultar fila pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: filas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/filas/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /filas/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: filas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/filas/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de fila",
    "configuracao": {
        "ramais": [
            "00000000-0000-4000-8000-000000000001"
        ],
        "estrategia": "rrmemory",
        "timeout": 20,
        "espera": 60,
        "descanso": 5,
        "destino": {
            "tipo": "encerrar"
        },
        "horario_id": "00000000-0000-4000-8000-000000000001",
        "destino_fechado": {
            "tipo": "encerrar"
        }
    },
    "versao": 1,
    "ativo": true
}'
DELETE /filas/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: filas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/filas/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /audios

Listar Áudios (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: audios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/audios" \
  -H "Authorization: Bearer $CHAVE_API"
POST /audios

Criar áudio.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/audios" \
  -H "Authorization: Bearer $CHAVE_API" \
  -F 'nome=Mensagem inicial' \
  -F 'arquivo=@mensagem.wav'
GET /audios/{id}

Consultar áudio pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/audios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /audios/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/audios/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de áudio",
    "configuracao": [],
    "versao": 1,
    "ativo": true
}'
DELETE /audios/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/audios/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /campanhas

Listar Campanhas (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/campanhas" \
  -H "Authorization: Bearer $CHAVE_API"
POST /campanhas

Criar campanha.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de campanha",
    "configuracao": {
        "modo": "audio_tecla",
        "espera_tecla": 8,
        "espera_atendente": 30,
        "amd_inconclusivo": "prosseguir",
        "tronco_id": "00000000-0000-4000-8000-000000000001",
        "audio_id": "00000000-0000-4000-8000-000000000001",
        "fila_id": "00000000-0000-4000-8000-000000000001",
        "tecla": "1",
        "tecla_bloqueio": "9",
        "simultaneas": 1,
        "tentativas": 3,
        "intervalo": 120,
        "dias": [
            1,
            2,
            3,
            4,
            5
        ],
        "inicio": "09:00",
        "fim": "17:30",
        "data_inicio": "",
        "data_fim": "",
        "amd": false
    }
}'
GET /campanhas/{id}

Consultar campanha pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/campanhas/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /campanhas/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/campanhas/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de campanha",
    "configuracao": {
        "modo": "audio_tecla",
        "espera_tecla": 8,
        "espera_atendente": 30,
        "amd_inconclusivo": "prosseguir",
        "tronco_id": "00000000-0000-4000-8000-000000000001",
        "audio_id": "00000000-0000-4000-8000-000000000001",
        "fila_id": "00000000-0000-4000-8000-000000000001",
        "tecla": "1",
        "tecla_bloqueio": "9",
        "simultaneas": 1,
        "tentativas": 3,
        "intervalo": 120,
        "dias": [
            1,
            2,
            3,
            4,
            5
        ],
        "inicio": "09:00",
        "fim": "17:30",
        "data_inicio": "",
        "data_fim": "",
        "amd": false
    },
    "versao": 1,
    "ativo": true
}'
DELETE /campanhas/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/campanhas/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /webhooks

Listar Webhooks (até 500, mais recentes primeiro).

Autenticação: Bearer ou sessão autorizada. Permissão: webhooks:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/webhooks" \
  -H "Authorization: Bearer $CHAVE_API"
POST /webhooks

Criar webhook.

Autenticação: Bearer ou sessão autorizada. Permissão: webhooks:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/webhooks" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de webhook",
    "configuracao": {
        "versao_payload": "1",
        "url": "https://integracao.exemplo.com/eventos",
        "eventos": "call.created\ncall.completed\ncall.failed"
    }
}'
GET /webhooks/{id}

Consultar webhook pelo UUID.

Autenticação: Bearer ou sessão autorizada. Permissão: webhooks:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/webhooks/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /webhooks/{id}

Substituir configuração; enviar versão obtida no GET.

Autenticação: Bearer ou sessão autorizada. Permissão: webhooks:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/webhooks/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Exemplo de webhook",
    "configuracao": {
        "versao_payload": "1",
        "url": "https://integracao.exemplo.com/eventos",
        "eventos": "call.created\ncall.completed\ncall.failed"
    },
    "versao": 1,
    "ativo": true
}'
DELETE /webhooks/{id}

Desativar; recusa dependências ativas e preserva histórico.

Autenticação: Bearer ou sessão autorizada. Permissão: webhooks:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/webhooks/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
GET /interfones

Listar interfones desta empresa (até 500).

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/interfones" \
  -H "Authorization: Bearer $CHAVE_API"
POST /interfones

Criar interfone com QR fixo e destino restrito.

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/interfones" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Portaria principal",
    "destino": {
        "tipo": "ramal",
        "id": "00000000-0000-4000-8000-000000000001"
    },
    "duracao_maxima": 300,
    "intervalo": 60,
    "simultaneas": 1,
    "ativo": true
}'
GET /interfones/{id}

Consultar configuração e URL do QR Code.

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/interfones/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /interfones/{id}

Substituir configuração; desativar encerra as visitas abertas.

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/interfones/$ID" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Portaria principal",
    "destino": {
        "tipo": "ramal",
        "id": "00000000-0000-4000-8000-000000000001"
    },
    "duracao_maxima": 300,
    "intervalo": 60,
    "simultaneas": 1,
    "ativo": true,
    "versao": 1
}'
GET /interfones/{id}/sessoes

Últimas 50 visitas com IP, resultado e UUID da chamada.

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/interfones/$ID/sessoes" \
  -H "Authorization: Bearer $CHAVE_API"
POST /interfones/{id}/renovar-link

Invalidar QR anterior e visitas abertas; retorna nova URL.

Autenticação: Bearer ou sessão autorizada. Permissão: interfones:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/interfones/$ID/renovar-link" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "versao": 1
}'
POST /publico/interfone/abrir

Abrir visita única de até 2 minutos; define cookie HttpOnly.

Autenticação: visita pública com Origin e credenciais próprias (sem chave administrativa). Permissão: Chave do QR e Origin da aplicação. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/publico/interfone/abrir" \
  -b visitante.txt -c visitante.txt \
  -H "Origin: $ORIGEM" \
  -H 'Content-Type: application/json' \
  --data '{
    "chave": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
POST /publico/interfone/preparar

Emitir credenciais SIP efêmeras uma única vez, após permissão do microfone.

Autenticação: visita pública com Origin e credenciais próprias (sem chave administrativa). Permissão: Cookie do visitante, sessao_id, segredo e Origin da aplicação. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/publico/interfone/preparar" \
  -b visitante.txt -c visitante.txt \
  -H "Origin: $ORIGEM" \
  -H 'Content-Type: application/json' \
  --data '{
    "sessao_id": "00000000-0000-4000-8000-000000000001",
    "segredo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}'
POST /publico/interfone/estado

Consultar apenas o estado da própria visita.

Autenticação: visita pública com Origin e credenciais próprias (sem chave administrativa). Permissão: Cookie do visitante, sessao_id, segredo e Origin da aplicação. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/publico/interfone/estado" \
  -b visitante.txt -c visitante.txt \
  -H "Origin: $ORIGEM" \
  -H 'Content-Type: application/json' \
  --data '{
    "sessao_id": "00000000-0000-4000-8000-000000000001",
    "segredo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}'
POST /publico/interfone/encerrar

Revogar visita e desligar sua chamada.

Autenticação: visita pública com Origin e credenciais próprias (sem chave administrativa). Permissão: Cookie do visitante, sessao_id, segredo e Origin da aplicação. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/publico/interfone/encerrar" \
  -b visitante.txt -c visitante.txt \
  -H "Origin: $ORIGEM" \
  -H 'Content-Type: application/json' \
  --data '{
    "sessao_id": "00000000-0000-4000-8000-000000000001",
    "segredo": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}'
GET /audios/vozes

Vozes neurais locais disponíveis em português do Brasil e limites.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/audios/vozes" \
  -H "Authorization: Bearer $CHAVE_API"
POST /audios/previa-voz

Gerar prévia WAV temporária sem cadastrar mensagem.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/audios/previa-voz" \
  -H "Authorization: Bearer $CHAVE_API" \
  --output mensagem.wav \
  -H 'Content-Type: application/json' \
  --data '{
    "texto": "Olá! Você ligou para nossa empresa. Para atendimento, digite um.",
    "voz": "faber",
    "velocidade": 1
}'
POST /audios/gerar-voz

Gerar voz local e cadastrar mensagem WAV reutilizável.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/audios/gerar-voz" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Boas-vindas",
    "texto": "Olá! Você ligou para nossa empresa. Para atendimento, digite um.",
    "voz": "faber",
    "velocidade": 1
}'
GET /audios/{id}/arquivo

Ouvir ou baixar WAV autenticado; baixar=1 força download.

Autenticação: Bearer ou sessão autorizada. Permissão: audios:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/audios/$ID/arquivo?baixar=1" \
  -H "Authorization: Bearer $CHAVE_API" \
  --output mensagem.wav
POST /ramais/lote/previa

Conferir sequência, modelo e conflitos; não cria ramais.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/lote/previa" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "numero_inicial": "1002",
    "quantidade": 83,
    "sufixo_inicial": "1002",
    "nome_padrao": "Ramal {numero}"
}'
POST /ramais/lote

Criar de 1 a 100 ramais atomicamente; requer Idempotency-Key.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/lote" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data '{
    "numero_inicial": "1002",
    "quantidade": 83,
    "sufixo_inicial": "1002",
    "nome_padrao": "Ramal {numero}"
}'
GET /ramais/{id}/exclusao

Conferir gravações, chamadas e vínculos antes de desativar ou excluir.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/exclusao" \
  -H "Authorization: Bearer $CHAVE_API"
POST /ramais/{id}/desativar

Desativar preservando gravações; revoga acessos de atendentes.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/$ID/desativar" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "versao": 1
}'
POST /ramais/{id}/excluir

Excluir definitivamente; gravações exigem confirmação e escopo adicional.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever; gravacoes:escrever quando houver gravações. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/$ID/excluir" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "versao": 1,
    "confirmar": true,
    "excluir_gravacoes": false
}'
POST /ramais/documentacao

Gerar PDF dos ramais do cliente (TXT opcional); credenciais somente se solicitadas.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler; também ramais:escrever ao incluir senhas. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/documentacao" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "situacao": "ativos",
    "incluir_senhas": false,
    "formato": "pdf"
}'
POST /ramais/{id}/credencial

Renovar senha SIP; invalida a senha anterior.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/$ID/credencial" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
GET /empresa/documentacao

Consultar logo e marca-d’água da empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/empresa/documentacao" \
  -H "Authorization: Bearer $CHAVE_API"
GET /empresa/documentacao/logo

Consultar imagem privada do PDF.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/empresa/documentacao/logo" \
  -H "Authorization: Bearer $CHAVE_API" \
  --output imagem.png
POST /empresa/documentacao/logo

Enviar PNG ou JPEG de até 3 MB para o PDF.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/empresa/documentacao/logo" \
  -H "Authorization: Bearer $CHAVE_API" \
  -F 'arquivo=@logo.png'
DELETE /empresa/documentacao/logo

Remover imagem do PDF desta empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/empresa/documentacao/logo" \
  -H "Authorization: Bearer $CHAVE_API"
GET /empresa/documentacao/marca_dagua

Consultar imagem privada do PDF.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/empresa/documentacao/marca_dagua" \
  -H "Authorization: Bearer $CHAVE_API" \
  --output imagem.png
POST /empresa/documentacao/marca_dagua

Enviar PNG ou JPEG de até 3 MB para o PDF.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/empresa/documentacao/marca_dagua" \
  -H "Authorization: Bearer $CHAVE_API" \
  -F 'arquivo=@logo.png'
DELETE /empresa/documentacao/marca_dagua

Remover imagem do PDF desta empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/empresa/documentacao/marca_dagua" \
  -H "Authorization: Bearer $CHAVE_API"
GET /empresa/telefonia

Prefixo SIP fixo e preferência de captura da empresa autenticada.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/empresa/telefonia" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /empresa/telefonia

Configurar ativação e códigos de captura desta empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/empresa/telefonia" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "captura_chamadas": true,
    "codigo_captura_geral": "#0",
    "prefixo_captura_direta": "#1"
}'
GET /ramais/{id}/historico

Histórico do ramal, conexão e chamadas ativas; preservado após desativação.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler e chamadas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/historico?tipo=todos&pagina=1" \
  -H "Authorization: Bearer $CHAVE_API"
GET /ramais/conexoes

Conexões reais SIP/WebPhone com dispositivos, alcance e horário da consulta.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/conexoes" \
  -H "Authorization: Bearer $CHAVE_API"
GET /ramais/{id}/chefe-secretaria

Consultar triagem Chefe / Secretária e versão do ramal.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/chefe-secretaria" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /ramais/{id}/chefe-secretaria

Configurar triagem do chefe; secretária deve ser outro ramal ativo da mesma empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$ID/chefe-secretaria" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "versao": 1,
    "chefe_secretaria": {
        "habilitado": true,
        "secretaria_id": "00000000-0000-4000-8000-000000000001"
    }
}'
GET /ramais/{id}/siga-me

Consultar regras e versão do Siga-me deste ramal.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/siga-me" \
  -H "Authorization: Bearer $CHAVE_API"
PUT /ramais/{id}/siga-me

Substituir somente as regras do Siga-me; exige versão atual.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$ID/siga-me" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "versao": 1,
    "siga_me": {
        "habilitado": true,
        "permitir_telefone": true,
        "codigo_ativar": "#21",
        "codigo_desativar": "#22",
        "tempo_toque": 20,
        "tempo_externo": 45,
        "sempre": null,
        "nao_atende": {
            "tipo": "ramal",
            "id": "00000000-0000-4000-8000-000000000001"
        },
        "ocupado": null,
        "indisponivel": null
    }
}'
GET /ramais/{id}/configuracao-sip

Dados de configuração do telefone SIP, sem senha.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/configuracao-sip" \
  -H "Authorization: Bearer $CHAVE_API"
POST /ramais/{id}/revelar-credencial

Consultar senha SIP existente; registra auditoria e não renova.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/$ID/revelar-credencial" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
GET /chamadas/{id}/gravacoes

Gravações por ramal e sentido; somente metadados.

Autenticação: Bearer ou sessão autorizada. Permissão: gravacoes:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/chamadas/$ID/gravacoes" \
  -H "Authorization: Bearer $CHAVE_API"
GET /ramais/{id}/gravacoes

Gravações do ramal, inclusive desativado; 50 por página, mais recentes primeiro.

Autenticação: Bearer ou sessão autorizada. Permissão: ramais:ler e gravacoes:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/gravacoes?direcao=todas&pagina=1" \
  -H "Authorization: Bearer $CHAVE_API"
GET /gravacoes/{id}/arquivo

Áudio WAV autenticado; baixar=1 força download; suporta Range.

Autenticação: Bearer ou sessão autorizada. Permissão: gravacoes:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/gravacoes/$ID/arquivo?baixar=1" \
  -H "Authorization: Bearer $CHAVE_API" \
  --output gravacao.wav
GET /troncos/{id}/diagnostico

Verificar DNS, endpoint e registro SIP.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos/$ID/diagnostico" \
  -H "Authorization: Bearer $CHAVE_API"
POST /troncos/{id}/registro

Solicitar tentativa, pausar ou retomar registro SIP; processamento assíncrono.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/troncos/$ID/registro" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "acao": "tentar"
}'
GET /troncos/status

Estado atual de registro dos troncos da empresa e saúde do monitoramento.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos/status" \
  -H "Authorization: Bearer $CHAVE_API"
GET /troncos/{id}/status

Registro atual, última falha e política de recuperação aplicada no Asterisk.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos/$ID/status" \
  -H "Authorization: Bearer $CHAVE_API"
GET /troncos/{id}/historico

Registro, renovações, falhas e alterações com responsáveis; 50 eventos por página.

Autenticação: Bearer ou sessão autorizada. Permissão: troncos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/troncos/$ID/historico?tipo=todos&pagina=1&inicio=2026-10-17&fim=2026-10-17" \
  -H "Authorization: Bearer $CHAVE_API"
GET /filas/{id}/status

Agentes, quantidade de prontos, aguardando e indicador aberta.

Autenticação: Bearer ou sessão autorizada. Permissão: filas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/filas/$ID/status" \
  -H "Authorization: Bearer $CHAVE_API"
POST /filas/{id}/disponibilidade

Pausar ou disponibilizar um atendente.

Autenticação: Bearer ou sessão autorizada. Permissão: operar_filas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/filas/$ID/disponibilidade" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "pausado": true,
    "motivo": "Intervalo"
}'
GET /painel

Indicadores da empresa e disponibilidade dos serviços.

Autenticação: Bearer ou sessão autorizada. Permissão: painel:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/painel" \
  -H "Authorization: Bearer $CHAVE_API"
GET /chamadas

Histórico: até 100 por página; ativas=1 filtra chamadas abertas.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/chamadas?pagina=1&ativas=0" \
  -H "Authorization: Bearer $CHAVE_API"
POST /chamadas/correlacionar-sip

Resolver Call-ID SIP e ramal em UUIDs REST; 200 correlacionada ou 202 pendente.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:ler; sessão atendente somente no próprio ramal. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/correlacionar-sip" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "sip_call_id": "exemplo-call-id@crm.example.invalid",
    "ramal_id": "00000000-0000-4000-8000-000000000001"
}'
GET /chamadas/{id}

Detalhes e correlação de uma chamada.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/chamadas/$ID" \
  -H "Authorization: Bearer $CHAVE_API"
POST /chamadas/originate

Tocar o ramal e, após atendimento, ligar para o destino; requer Idempotency-Key.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:escrever. HTTP de sucesso: 202.

curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/originate" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data '{
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "destino": "102"
}'
POST /chamadas/{id}/hangup

Encerrar uma ligação com canal ativo.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/$ID/hangup" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
POST /chamadas/{id}/transfer

Transferir para o número de um ramal ativo da mesma empresa.

Autenticação: Bearer ou sessão autorizada. Permissão: chamadas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/$ID/transfer" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "destino": "102"
}'
POST /simular

Simular sem ligar: tipo saida, entrada, horario ou destino.

Autenticação: Bearer ou sessão autorizada. Permissão: rotas_saida:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/simular" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "tipo": "destino",
    "destino": {
        "tipo": "fila",
        "id": "00000000-0000-4000-8000-000000000001"
    },
    "data": "2026-10-12T12:30:00-03:00"
}'
POST /campanhas/{id}/contatos

Validar contatos; confirmar=true importa o lote.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/contatos" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{
    "confirmar": false,
    "contatos": [
        {
            "nome": "Pessoa de exemplo",
            "telefone": "551130000000"
        }
    ]
}'
POST /campanhas/{id}/iniciar

Iniciar campanha.

Autenticação: Bearer ou sessão autorizada. Permissão: operar_campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/iniciar" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
POST /campanhas/{id}/pausar

Pausar campanha.

Autenticação: Bearer ou sessão autorizada. Permissão: operar_campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/pausar" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
POST /campanhas/{id}/encerrar

Encerrar campanha.

Autenticação: Bearer ou sessão autorizada. Permissão: operar_campanhas:escrever. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/campanhas/$ID/encerrar" \
  -H "Authorization: Bearer $CHAVE_API" \
  -H 'Content-Type: application/json' \
  --data '{}'
GET /campanhas/{id}/status

Diagnóstico de discagem, rotas, próxima tentativa, fila e indicadores de atendimento.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/campanhas/$ID/status" \
  -H "Authorization: Bearer $CHAVE_API"
GET /campanhas/{id}/resultados

Última tentativa de cada contato, 100 por página.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/campanhas/$ID/resultados?pagina=1" \
  -H "Authorization: Bearer $CHAVE_API"
GET /campanhas/{id}/metricas

Quantidades de contatos por estado.

Autenticação: Bearer ou sessão autorizada. Permissão: campanhas:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/campanhas/$ID/metricas" \
  -H "Authorization: Bearer $CHAVE_API"
GET /eventos

Últimos 100 eventos da empresa; sem paginação.

Autenticação: Bearer ou sessão autorizada. Permissão: eventos:ler. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/eventos" \
  -H "Authorization: Bearer $CHAVE_API"
GET /catalogo

Catálogo de campos usados no painel.

Autenticação: sessão de usuário. Permissão: Administrador do cliente ou da plataforma. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/catalogo" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /usuarios

Usuários do cliente selecionado, sem senhas.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/usuarios" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
POST /usuarios

Criar usuário; exige troca da senha inicial.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/usuarios" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Maria",
    "email": "maria@exemplo.com",
    "perfil": "atendente",
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "senha": "SUBSTITUA_POR_12_OU_MAIS_CARACTERES",
    "conectar_automaticamente": true,
    "ativo": true
}'
PUT /usuarios/{id}

Editar usuário; senha vazia mantém a atual.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/usuarios/$ID" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Maria",
    "email": "maria@exemplo.com",
    "perfil": "atendente",
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "senha": "",
    "conectar_automaticamente": true,
    "ativo": true
}'
GET /ramais/{id}/acessos-webphone

Listar atendentes vinculados a este ramal.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/ramais/$ID/acessos-webphone" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
POST /ramais/{id}/acessos-webphone

Criar acesso direto e habilitar o ramal para navegador.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/ramais/$ID/acessos-webphone" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Maria",
    "login": "empresa.101",
    "senha": "SUBSTITUA_POR_12_OU_MAIS_CARACTERES",
    "trocar_senha": false,
    "ativo": true
}'
PUT /ramais/{id}/acessos-webphone/{usuario_id}

Editar acesso do ramal; encerra sessões anteriores.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/ramais/$ID/acessos-webphone/$USUARIO_ID" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Maria",
    "login": "empresa.101",
    "senha": "",
    "trocar_senha": false,
    "ativo": true
}'
POST /minha-senha

Alterar a própria senha; invalida outras sessões.

Autenticação: sessão de usuário. Permissão: Usuário autenticado. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/minha-senha" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "atual": "SENHA_ATUAL",
    "nova": "NOVA_SENHA_COM_12_CARACTERES"
}'
GET /chaves-api

Listar metadados e escopos das chaves; não retorna tokens.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/chaves-api" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
POST /chaves-api

Criar chave da empresa atual; token só nesta resposta.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/chaves-api" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "CRM",
    "escopos": [
        "ramais:ler",
        "chamadas:ler",
        "chamadas:escrever"
    ]
}'
DELETE /chaves-api/{id}

Revogar chave de integração.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X DELETE "$BASE/chaves-api/$ID" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /entregas-webhook

Últimas 100 entregas, tentativas, estado e HTTP.

Autenticação: sessão de usuário. Permissão: Administrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/entregas-webhook" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /webphone

Credencial SIP do próprio ramal; administrador pode selecionar ramal_id.

Autenticação: sessão de usuário. Permissão: Sessão com permissão de WebPhone. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/webphone?ramal_id=00000000-0000-4000-8000-000000000001" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
POST /webphone/preparar

Validar número, captura ou Siga-me antes da chamada WebRTC.

Autenticação: sessão de usuário. Permissão: Sessão com permissão de WebPhone. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/webphone/preparar" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{
    "numero": "102",
    "ramal_id": "00000000-0000-4000-8000-000000000001"
}'
GET /webphone/filas

Consultar filas e pausa do ramal.

Autenticação: sessão de usuário. Permissão: Sessão com permissão de WebPhone. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/webphone/filas?ramal_id=00000000-0000-4000-8000-000000000001" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
POST /websocket-ticket

Ticket de eventos com uso único, válido por 30 segundos.

Autenticação: sessão de usuário. Permissão: Administrador ou supervisor. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/websocket-ticket" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' \
  --data '{}'
GET /auditoria

Auditoria paginada: 50 registros, cursor antes_de.

Autenticação: sessão de usuário. Permissão: Administrador do cliente. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/auditoria?acao=alterar&inicio=2026-10-01&fim=2026-10-31" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /auditoria/filtros

Responsáveis e ações disponíveis nos filtros.

Autenticação: sessão de usuário. Permissão: Administrador do cliente. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/auditoria/filtros" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /auditoria/{registro_id}

Detalhes, identidade histórica e antes/depois protegidos.

Autenticação: sessão de usuário. Permissão: Administrador do cliente. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/auditoria/$REGISTRO_ID" \
  -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID"
GET /administracao/auditoria

Auditoria paginada: 50 registros, cursor antes_de.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/auditoria?acao=alterar&inicio=2026-10-01&fim=2026-10-31" \
  -b sessao.txt
GET /administracao/auditoria/filtros

Responsáveis e ações disponíveis nos filtros.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/auditoria/filtros" \
  -b sessao.txt
GET /administracao/auditoria/{registro_id}

Detalhes, identidade histórica e antes/depois protegidos.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/auditoria/$REGISTRO_ID" \
  -b sessao.txt
GET /administracao/empresas

Listar clientes da plataforma por situação.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/empresas?situacao=ativas" \
  -b sessao.txt
POST /administracao/empresas

Criar cliente isolado.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/administracao/empresas" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Empresa exemplo",
    "slug": "empresa-exemplo",
    "razao_social": "Empresa Exemplo Ltda",
    "cnpj": "",
    "ddd": "11",
    "dominio_sip": "empresa.pabx.atendai.chat",
    "fuso_horario": "America/Sao_Paulo"
}'
PUT /administracao/empresas/{empresa_id}

Editar cliente; suspensão bloqueia sua operação.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/administracao/empresas/$EMPRESA_ID" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Empresa exemplo",
    "razao_social": "Empresa Exemplo Ltda",
    "cnpj": "",
    "ddd": "11",
    "ativo": true,
    "limite_chamadas": 10
}'
GET /administracao/seguranca-rede

Consultar Fail2Ban SIP, regras UFW, contatos e logs sanitizados.

Autenticação: sessão de usuário. Permissão: Superadministrador; somente sessão. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/seguranca-rede?ip=198.51.100.24&fonte=todas&nivel=problemas" \
  -b sessao.txt
POST /administracao/seguranca-rede/acoes

Bloquear ou liberar SIP por IP, com motivo e auditoria.

Autenticação: sessão de usuário. Permissão: Superadministrador; somente sessão. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X POST "$BASE/administracao/seguranca-rede/acoes" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "acao": "desbloquear_fail2ban",
    "ip": "198.51.100.24",
    "motivo": "Configuração do aparelho corrigida e validada.",
    "confirmar": true
}'
GET /administracao/administradores

Listar administradores globais.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X GET "$BASE/administracao/administradores" \
  -b sessao.txt
POST /administracao/administradores

Criar administrador global com troca obrigatória de senha.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 201.

curl --fail-with-body --silent --show-error -X POST "$BASE/administracao/administradores" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Administrador exemplo",
    "email": "admin@exemplo.com",
    "senha": "SUBSTITUA_POR_12_OU_MAIS_CARACTERES"
}'
PUT /administracao/administradores/{id}

Editar ou desativar administrador; senha vazia mantém a atual.

Autenticação: sessão de usuário. Permissão: Superadministrador. HTTP de sucesso: 200.

curl --fail-with-body --silent --show-error -X PUT "$BASE/administracao/administradores/$ID" \
  -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" \
  -H 'Content-Type: application/json' \
  --data '{
    "nome": "Administrador exemplo",
    "email": "admin@exemplo.com",
    "senha": "",
    "ativo": true
}'