Desenvolvedores
API REST, webhooks assinados e eventos ao vivo.
A barra entra na página do CRM e fala só por REST; o desfecho de cada ligação volta ao servidor do CRM por webhook assinado (aviso automático de sistema para sistema).
Escopo da API
Da conta do cliente ao desfecho de cada tentativa.
O que a API recebe
- Ramais e a conta inteira da operação provisionados por API, de forma idempotente.
- Operadoras, troncos e números cadastrados por API, com trilha.
- Perfis de roteiro e checklist por campanha enviados pelo backend do CRM.
- Pausas e ocorrências vindas do CRM.
O que a API devolve
- Desfecho técnico de cada tentativa do discador (BUSY, NO_ANSWER), com de-para por operação.
Autenticação
Duas identidades, cada uma com um papel.
A sessão do operador identifica a pessoa que está na ligação e é revogável no ato: encerrada a sessão, a barra perde o acesso na hora. A chave de API identifica o sistema do cliente, serve à integração de servidor para servidor e não disca. Assim, uma chave exposta numa integração não origina ligação.
- Nenhuma credencial aceita parâmetro de cliente (tenant): o cliente vem da credencial.
- Permissões em catálogo versionado; a barra esconde o que o operador não pode fazer.
- Para o operador, os eventos ao vivo; para o servidor do CRM, o webhook.
| Credencial | Quem identifica | Para que serve | Limite |
|---|---|---|---|
| Sessão do operador | A pessoa na ligação | Barra e eventos ao vivo | Revogável no ato |
| Chave de API | O sistema do cliente | Integração entre servidores | Não disca |
O limite de cada credencial
Chave exposta
A situação: Uma chave de API exposta numa integração.
O que acontece: Não origina ligação: a chave serve à integração de servidor para servidor e não disca.
Sessão encerrada
A situação: A sessão do operador é encerrada.
O que acontece: A barra perde o acesso na hora: a sessão é revogável no ato.
Cliente (tenant)
A situação: Um parâmetro de cliente (tenant) junto da credencial.
O que acontece: Nenhuma credencial aceita: o cliente vem da credencial.
Erros
Erro em JSON, com código que não muda.
- Todo erro volta em JSON, com código estável para o seu sistema tratar.
- Respostas 429 e 503 trazem o cabeçalho Retry-After, que diz quando tentar de novo.
- Números em E.164 (formato internacional, com código do país) e país sempre explícito.
- API em inglês; toda resposta informa a versão do serviço.
| Resposta | O que o seu sistema faz |
|---|---|
| Erro em JSON | Trata pelo código estável. |
| 429 | Espera o tempo do Retry-After e tenta de novo. |
| 503 | Espera o tempo do Retry-After e tenta de novo. |
Eventos ao vivo
A ligação acompanhada na sessão do operador.
Os eventos da ligação chegam por SSE (eventos enviados pelo servidor), na sessão do operador, sem consulta repetida. Quando o telefone toca, a barra mostra o cartão de quem liga (screen pop). Ao fim da ligação, a transcrição separada por falante, o resumo e a nota de qualidade chegam pela barra, sob demanda.
O supervisor tem o próprio fluxo. GET /v1/supervisor/events entrega a foto da operação e, depois, cada mudança de operador, softphone, fila e campanha, com retomada pelo último evento, pela chave de API do cliente. O fluxo só lê a memória do motor de chamadas, sem consulta ao banco por tela aberta. Os painéis prontos estão no ekovox Analytics.
Webhooks
Webhook assinado, com fila de entrega durável.
No fim da ligação, o servidor do CRM recebe por webhook o desfecho e o link da gravação. Cada operação tem o próprio webhook. O corpo é assinado em HMAC-SHA256, com chave gerada pela plataforma, mostrada uma única vez e trocável.
- Cada evento tem identificador próprio: o seu sistema descarta o repetido (idempotência).
- Nova tentativa com espera que dobra a cada falha, até 1 hora entre tentativas.
- Sem entrega em 24 horas, a fila desiste; o administrador pode reenviar.
- Resposta 3xx ou 4xx, exceto 408 e 429, encerra a entrega como recusada.
Gravações
O link da gravação é assinado e expira.
- O webhook leva o link da gravação, assinado e de curta duração.
- Gravação ouvida no CRM pela sessão do usuário; cada escuta fica registrada.
- Opção: gravação no armazenamento (bucket) do próprio cliente, com prova de escrita.
- Transcrição só por tempo curto no serviço, fora do webhook; o CRM a guarda.
Política de gravação, retenção e transcrição, em Gravação & Transcrição
Barra
Um componente web na página do CRM.
A barra é um Web Component (componente padrão do navegador) que entra na página do CRM e fala com a plataforma só por REST. Ela nunca escreve no banco do CRM: o que o CRM guarda chega pela API e pelo webhook.
Como a barra aparece dentro do CRM, em Barra para qualquer CRM
- Tema herdado do CRM, com contraste WCAG (padrão de acessibilidade).
- Atalhos configuráveis, janela flutuante e modo controlador do telefone de mesa.
- Número do cliente em atraso mascarado na tela do operador.
- Interface em inglês, português do Brasil ou espanhol, gravada na sessão.
Documentação
Especificação OpenAPI 3.1, em quatro variantes de idioma.
A especificação segue o OpenAPI 3.1 e a documentação está em inglês, português do Brasil e espanhol, em duas variantes: América Latina e Espanha. A documentação não é pública: o acesso é combinado com o time técnico de cada projeto. Peça a especificação, e um engenheiro de telefonia responde.
- English
- Português (Brasil)
- Español (Latinoamérica)
- Español (España)
Exemplos por CRM
A mesma receita, em qualquer CRM.
Colocar a barra na página do CRM onde o operador trabalha.
Enviar, do backend do CRM, roteiros e checklists por campanha, pausas e ocorrências.
Receber o webhook assinado, conferir a assinatura e gravar desfecho e link.
Mapear os desfechos técnicos do discador para a tabulação do CRM.
Guardar no CRM a transcrição e o resumo que chegam pela barra.
CRMs com integração
Celcoin
CobranSaaS
Cyber Financial Solutions
Recupera Créditorevo360
SisCobra
Perguntas frequentes
Como meu sistema sabe que o webhook é da plataforma?
O corpo de cada webhook é assinado em HMAC-SHA256, com uma chave gerada pela plataforma, mostrada uma única vez e trocável. O seu servidor recalcula a assinatura e descarta o que não confere.
O que acontece se o meu servidor estiver fora do ar?
O evento fica na fila de entrega. A espera entre tentativas dobra a cada falha, até 1 hora. Sem entrega em 24 horas, a fila desiste, e o administrador pode reenviar. Uma resposta 3xx ou 4xx, exceto 408 e 429, encerra a entrega como recusada.
A chave de API consegue fazer ligações?
Não. A chave de API identifica o sistema do cliente e serve à integração entre servidores; ela não disca. A ligação parte da sessão do operador na barra, revogável no ato, ou da campanha do discador.
A transcrição chega pelo webhook?
Não. O webhook leva o desfecho e o link da gravação. A transcrição, o resumo e a nota chegam pela barra, sob demanda. A transcrição fica só na memória do serviço, por tempo curto, e quem guarda o texto é o CRM.
A barra precisa de acesso ao banco do meu CRM?
Não. A barra é um componente web que fala com a plataforma só por REST e nunca escreve no banco do CRM. O que o CRM guarda chega pela API e pelo webhook.
Para o comitê
| Cadeira | O que conferir | Onde conferir |
|---|---|---|
| Operações (COO) | Discador ativo, preditivo e progressivo, e supervisão em tempo real por campanha. | |
| Financeiro (CFO) | Contratação por posição de atendimento, sem preço publicado, dimensionada com a operação. | |
| TI e segurança (CTO) | A barra fala só por REST. O webhook é assinado, e há duas identidades: a sessão do operador e a chave de API, que não disca. Ambiente dedicado, implantado por cliente, para quem exige isolamento. | |
| Jurídico e DPO | Gravação ouvida por link assinado, trilha de quem ouviu e retenção no prazo de cada cliente. A IA só entra com as guardas da plataforma. | |
| Supervisão | O Copilot sugere e preenche a tabulação; quem grava é o operador. | |
| Compras | Implantação com escopo próprio; contratação sem preço publicado. |
Próximo passo
Desenhe a integração com um engenheiro.
Conte qual CRM a operação usa, quantas posições de atendimento (PAs) tem e quantos minutos fala por mês. Um engenheiro de telefonia responde com as perguntas de rede e de operadora e envia a especificação da API.