Integrações e API
Documentacao da API pública do Contact Desk
Guia da API pública do Contact Desk: autenticação, casos de uso, segurança, integrações, webhooks e boas práticas.
Resposta rápida
A API pública do Contact Desk permite conectar sistemas externos a fluxos de atendimento, tickets, usuários, conversas e automações. Ela deve ser usada com tokens seguros, escopos controlados e logs de integração. O objetivo e integrar processos sem expor credenciais nem criar dependencias frageis.
Quando usar a API
Use a API quando outro sistema precisa criar, consultar ou atualizar informacoes do Contact Desk de forma controlada. Em muitos casos, a API substitui importacoes manuais, planilhas e envio de e-mails operacionais.
- Criar ticket a partir de formulario externo.
- Consultar status de ticket.
- Sincronizar solicitantes.
- Registrar eventos de outro sistema.
- Acionar automacoes externas.
- Integrar portais e sistemas legados.
API versus webhook
API e chamada ativa: um sistema externo chama o Contact Desk. Webhook e notificacao de evento: o Contact Desk avisa outro sistema quando algo acontece. Fluxos maduros podem usar os dois.
- API: sistema externo pergunta ou envia dados.
- Webhook: Contact Desk envia evento.
- API e webhook juntos: sincronizacao mais completa.
- Evite polling excessivo quando webhook resolve.
Seguranca de tokens
Tokens de API devem ser tratados como senha. Eles nunca devem ser colocados em HTML, JavaScript publico, prints, documentos compartilhados ou repositorios. Sempre use menor privilegio possivel.
- Guardar token em variavel segura.
- Rotacionar periodicamente.
- Revogar token nao usado.
- Separar token por integracao.
- Nao registrar token em log.
- Aplicar permissao minima necessaria.
Boas praticas de integracao
Uma integracao confiavel precisa lidar com erro, repeticao e idempotencia. Se um sistema externo enviar o mesmo evento duas vezes, o Contact Desk ou a camada integradora deve evitar duplicidade indesejada.
- Tratar timeout e retry.
- Registrar correlation id.
- Evitar duplicar tickets.
- Validar payload antes de enviar.
- Monitorar falhas por horario.
- Documentar dono da integracao.
Ferramentas no-code e low-code
n8n, Power Automate, Make e Zapier podem chamar a API ou receber webhooks. Elas aceleram integracoes, mas exigem o mesmo cuidado com credenciais, erros e logs.
- Usar secrets da ferramenta.
- Testar ambiente controlado.
- Limitar permissao do token.
- Registrar falhas.
- Evitar fluxos que criam loop entre sistemas.
Exemplo de criacao de ticket via API
Um formulario externo pode enviar nome, e-mail, assunto, descricao, fila e prioridade para criar um ticket no Contact Desk. A integracao deve validar campos obrigatorios antes de chamar a API e guardar o identificador externo para evitar duplicidade.
- Formulario recebe dados.
- Backend valida campos.
- Backend chama API com token seguro.
- Contact Desk cria ticket.
- Sistema externo guarda numero do ticket.
- Usuario recebe protocolo.
Exemplo de portal consultando status
Um portal de cliente pode consultar status de um ticket usando protocolo, documento ou identificador externo. Esse fluxo precisa respeitar permissao e privacidade: o usuario deve ver apenas tickets aos quais tem direito.
- Validar identidade do usuario.
- Consultar ticket pelo identificador correto.
- Exibir status e ultima atualizacao.
- Nao expor comentario interno.
- Registrar tentativa de consulta quando necessario.
Monitoramento da integracao
Integracao sem monitoramento vira ponto cego. A equipe precisa saber quando a API falha, quando um token expira, quando um endpoint externo fica fora do ar ou quando o volume aumenta de forma anormal.
- Logs de sucesso e falha.
- Alertas para erro repetido.
- Metricas de tempo de resposta.
- Contagem de chamadas por periodo.
- Fila de retry.
- Plano de rollback.
Boas práticas
- Revise permissões antes de liberar recursos para novos usuários.
- Teste mudanças em um fluxo controlado antes de aplicar em toda a operação.
- Use nomes claros para filas, categorias, automações e respostas prontas.
- Consulte logs e auditoria quando uma ação precisar de rastreabilidade.
Perguntas frequentes
Posso chamar a API direto do navegador?
Nao para fluxos privados com token sensivel. Use backend ou ferramenta segura para proteger credenciais.
API cria tickets automaticamente?
Pode criar, se o endpoint e o token tiverem permissao. O desenho deve evitar duplicidade e validar dados obrigatorios.
Webhook substitui API?
Nao. Webhook avisa eventos. API consulta ou envia dados sob demanda.
Quando acionar o administrador?
Acione um administrador quando a configuração envolver credenciais, permissões, integrações, filas compartilhadas, políticas de SLA, automações globais ou dados sensíveis.