Este é o ponto de partida da documentação da API cVortex. Ela foi dividida em vários documentos, um por assunto, para ser mais fácil de consultar do que uma página única e gigante. Esta primeira página explica, em linguagem simples, o que essa API faz e como ela é organizada mesmo que você nunca tenha trabalhado com uma API antes.
O que é uma API, em termos simples
Uma API é uma forma de dois sistemas de computador "conversarem" entre si automaticamente, sem precisar de uma pessoa clicando em telas. Pense nela como um garçom: você (o seu sistema) faz um pedido, o garçom (a API) leva esse pedido até a cozinha (a plataforma cVortex), e depois traz de volta o que você pediu.
Alguns termos técnicos que aparecem em toda a documentação, explicados de forma direta:
-
Endpoint: um "endereço" específico que você chama para fazer uma coisa por exemplo, "criar uma pessoa" ou "buscar um caso". É como um ramal de telefone: cada ramal atende para um assunto diferente.
-
Request (requisição): a mensagem que você envia perguntando ou pedindo algo.
-
Response (resposta): o que a API devolve depois da sua requisição.
-
JSON: o formato de texto usado para organizar os dados enviados e recebidos parecido com uma ficha com campos preenchidos, mas escrito de um jeito que o computador entende.
-
Token de acesso / Bearer: uma espécie de "crachá" digital que você recebe depois de se identificar, e que precisa mostrar em toda chamada para provar que tem permissão de usar a API.
-
Payload: o conteúdo que você envia dentro de uma requisição os dados propriamente ditos.
Para que serve esta API
Esta API permite buscar dados atuais e históricos sobre o atendimento de um caso (o que costuma ser chamado de "chamado" ou "ticket" em outras plataformas), com o objetivo principal de:
-
montar relatórios e dashboards;
-
automatizar rotinas do dia a dia do seu negócio (por exemplo, criar casos automaticamente, enviar mensagens, atualizar status).
Como os dados são organizados
Os dados desta API giram em torno de algumas "peças" principais:
|
O que é |
Explicação simples |
|---|---|
|
Histórico de interações de chat |
O registro das conversas trocadas com o cliente pelos canais de mensagem (WhatsApp, Webchat, Telegram, Instagram, Messenger) |
|
Dados padrão do caso |
As informações que já vêm prontas na plataforma para qualquer caso (assunto, prioridade, status, etc.) |
|
Dados personalizados do caso |
Campos extras que o seu negócio configurou, além dos campos padrão |
|
Histórico de eventos do caso |
Um registro de tudo que aconteceu com aquele caso ao longo do tempo |
|
Informações de SLA |
O acompanhamento de prazos: se o caso está dentro ou fora do tempo combinado de atendimento |
Atenção com as credenciais de acesso
-
As credenciais (usuário e senha usados para gerar o token) devem ser pedidas ao suporte cVortex.
-
Essas credenciais servem só para a API não use a mesma senha que você usa para entrar na plataforma pelo navegador.
O que dá para fazer com esta API (resumo)
-
Criar, consultar e atualizar dados de casos (o "atendimento" em si).
-
Executar ações de um fluxo de atendimento (workflow) sobre um caso.
-
Consultar respostas de questionários.
-
Consultar interações por e-mail, chat e voz.
-
Enviar mensagens ativamente para o cliente (WhatsApp, e-mail, SMS).
-
Administrar usuários (ativar, inativar, listar).
Todos os documentos, por assunto
|
# |
Documento |
O que você encontra lá |
|---|---|---|
|
1 |
Como conseguir o token de acesso, como usá-lo, formato de data e limite de chamadas por segundo |
|
|
2 |
Criar, atualizar, buscar (de duas formas) e contar pessoas; e como unificar duas pessoas duplicadas |
|
|
3 |
Tudo sobre o ciclo de vida de um caso: trocar a pessoa ou a unidade de negócio, trocar o responsável, mudar o status, reabrir, unificar casos, buscar e contar casos, anexar arquivos |
|
|
4 |
Consultar um formulário de abertura de caso e criar um caso novo a partir dele |
|
|
5 |
Consultar e executar ações de um fluxo de atendimento, transferir o caso para um bot, consultar respostas de questionário |
|
|
6 |
Consultar o histórico de conversas de um caso, o conteúdo e anexos de e-mails e mensagens, e as gravações de ligações |
|
|
7 |
Buscar, contar, ativar e inativar usuários |
|
|
8 |
Enviar mensagens ativamente para o cliente: texto, WhatsApp com template, botões, e-mail, SMS inclui também como cadastrar e consultar os templates de WhatsApp usados no envio |
|
|
9 |
Criar, atualizar e buscar registros em cadastros personalizados que o seu negócio criou na plataforma |
|
|
10 |
Avisar Meta e TikTok sobre a evolução de um lead que veio de um anúncio |
|
|
11 |
Ver em tempo real quantos agentes estão disponíveis e quantos atendimentos estão esperando na fila |
Por onde começar
-
Leia esta página até o fim ela dá a base para entender o resto.
-
Vá para Autenticação e Segurança: sem o token de acesso, nenhum outro endpoint funciona.
-
Depois, use os demais documentos como referência, um de cada vez, conforme o que você estiver construindo.
Nota sobre dados de exemplo
Todos os payloads de exemplo desta documentação usam os dados fictícios padronizados. Se algum endpoint novo for adicionado no futuro, siga o mesmo padrão para não expor dados reais em uma documentação pública.