Este guia existe para responder uma única pergunta:
👉 “Qual API do CloudChat eu devo usar para o que eu quero fazer?”
Antes de copiar qualquer endpoint ou escrever código, leia esta página. Ela evita confusão, uso incorreto de APIs e impactos não desejados em produção.
🧠 Visão geral: existem 3 tipos de APIs no CloudChat
As APIs do CloudChat não são todas iguais.
Elas se dividem em três categorias, cada uma com um objetivo claro.
📦 APIs de Extração de Dados
Servem para análise histórica e relatórios.
-
Exportação em lote (batch)
-
Uso típico: BI, auditoria, dashboards
-
Não alteram dados
-
Ideais para jobs agendados
🔍 APIs de Consulta em Tempo Real
Servem para ler dados atuais do sistema.
-
Buscar contatos
-
Listar tickets
-
Ler mensagens
-
Não alteram dados
-
Usadas em integrações e automações em tempo real
✏️ APIs de Atualização e Ação
⚠️ Essas APIs alteram dados reais em produção.
-
Resolver tickets
-
Alterar status, prioridade ou time
-
Criar mensagens em tickets
-
Podem impactar operação, SLA e métricas
-
Algumas rotas são experimentais ou exigem flag ativa
📦 Quando usar APIs de Extração de Dados
Use APIs de extração quando você quer:
-
Criar relatórios
-
Alimentar ferramentas de BI
-
Fazer auditorias
-
Analisar grandes períodos de tempo
-
Exportar muitos tickets de uma vez
Essas APIs:
-
Funcionam em lote
-
Têm limite de intervalo por requisição
-
Não devem ser usadas para lógica de aplicação em tempo real
👉 Documentação específica:
📦 API de Extração de Dados (Data Extract API)
🔍 Quando usar APIs de Consulta em Tempo Real
Use APIs de consulta quando você precisa responder perguntas agora, como:
-
“Esse contato já existe?”
-
“Quais tickets esse cliente tem?”
-
“Qual é o status atual desse ticket?”
-
“Quais mensagens foram trocadas nessa conversa?”
Essas APIs:
-
São somente leitura (GET)
-
Operam diretamente na base de produção
-
Não substituem a API de extração
👉 Documentação específica:
🔍 APIs de Consulta em Tempo Real (Contacts, Tickets e Messages)
✏️ Quando usar APIs de Atualização e Ação
⚠️ Atenção: essas APIs modificam dados reais no CloudChat.
Use APIs de ação quando você quer:
-
Resolver um ticket via integração
-
Atualizar prioridade ou time responsável
-
Criar mensagens automaticamente
-
Sincronizar ações de outro sistema com o CloudChat
Essas APIs:
-
Executam ações em produção
-
Podem afetar operação e métricas
-
Devem ser usadas com cuidado e validação
👉 Documentação específica:
✏️ APIs de Atualização e Ação em Tickets
🧩 Regra prática para escolher a API certa
Pergunte sempre:
-
Quero analisar dados históricos?
→ Use API de Extração de Dados -
Quero apenas ler dados atuais?
→ Use APIs de Consulta em Tempo Real -
Quero mudar algo no sistema?
→ Use APIs de Atualização e Ação
Se ainda estiver em dúvida, não avance. Usar a API errada pode gerar efeitos colaterais inesperados.
🚦 Níveis de cuidado (importante)
-
Extração de dados → risco baixo
-
Consulta em tempo real → risco médio
-
Atualização / ação → risco alto
Quanto mais você se aproxima de ações de escrita, mais atenção e testes são necessários.
❌ Erros comuns que este guia ajuda a evitar
-
Usar API de extração para algo que precisa ser em tempo real
-
Usar API de escrita achando que é apenas consulta
-
Misturar lógica de aplicação com exportação de dados
-
Alterar tickets sem entender o impacto operacional
📌 Próximos passos
Agora escolha a documentação certa para o seu caso:
Esse guia deve sempre ser lido antes das FAQs técnicas acima.