Integrações e API
Como integrar sistemas via API
Aprenda como planejar integrações via API com segurança, tokens, webhooks, erros, retries e exemplos de uso no Contact Desk.
Resposta rápida
Integrar sistemas via API significa permitir que plataformas troquem dados de forma controlada. No atendimento, isso pode criar tickets a partir de formularios, consultar status em portais, enviar eventos para BI ou conectar fluxos de n8n, Power Automate, Make e Zapier. A integração deve ser planejada com segurança, escopo claro e tratamento de falhas.
Passo a passo
- Defina o objetivo da integração.
- Escolha API, webhook ou ambos.
- Crie token com permissão minima.
- Mapeie campos obrigatorios.
- Implemente tratamento de erro e retry.
- Teste em ambiente controlado.
- Monitore logs após públicar.
Comece pelo caso de uso
Nao comece pela tecnologia. Comece pelo problema. Uma integracao boa tem objetivo claro, dono, sistema de origem, sistema de destino e criterio de sucesso.
- Criar ticket automaticamente.
- Consultar status por protocolo.
- Sincronizar usuario ou solicitante.
- Enviar alerta para canal externo.
- Alimentar BI com eventos de atendimento.
API ou webhook
Use API quando um sistema externo precisa chamar o Contact Desk. Use webhook quando o Contact Desk precisa avisar outro sistema sobre um evento. Muitas integracoes usam os dois para reduzir consultas repetitivas.
- API: chamada sob demanda.
- Webhook: notificacao de evento.
- API + webhook: sincronizacao mais eficiente.
- Evite polling quando evento resolve.
Seguranca
Tokens e segredos devem ficar fora do navegador. Tambem e importante limitar permissao, registrar logs sem dados sensiveis e rotacionar credenciais quando houver troca de fornecedor ou colaborador.
- Token em cofre ou variavel segura.
- Menor privilegio possivel.
- HTTPS obrigatorio.
- Validacao de payload.
- Logs sem segredo.
- Revogacao de tokens antigos.
Falhas e duplicidade
Integracoes falham. O desenho precisa prever timeout, tentativa repetida, dados invalidos e duplicidade. Sem isso, um mesmo formulario pode criar varios tickets ou um erro temporario pode interromper o atendimento.
- Usar identificador externo.
- Validar campos antes de enviar.
- Controlar retry.
- Registrar correlation id.
- Monitorar erros por periodo.
- Criar alerta para falhas recorrentes.
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
Preciso de desenvolvedor para integrar via API?
Para integracoes complexas, sim. Para fluxos simples, ferramentas como n8n, Make, Zapier ou Power Automate podem ajudar.
Posso colocar token no JavaScript do site?
Nao. Tokens privados devem ficar em backend ou ferramenta segura.
Webhook e mais seguro que API?
Nao por si so. Ambos precisam de HTTPS, validacao, autentificacao e controle de dados.
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.