Para: Administradores
Encontre casos com uma chave central
Liste os casos em seu hub, abertos ou fechados, pesquise-os por ID da tag ou título e encontre o ID de um caso a partir do seu próprio software.
Neste artigo7 seções
Antes de começar
Esta página aborda as chamadas que a chave de hub utiliza para encontrar os casos relacionados. Os caminhos estão indicados em https://prd-api-app.caseactive.com/v1/<hub id>.
Chamadas
| Chamar | O que faz |
|---|---|
GET /cases | Lista os casos abertos ou fechados do seu centro de atendimento. |
GET /cases/search | Pesquisa casos com base no ID da etiqueta ou no título do caso. |
GET /whoami | Lê as configurações do seu hub, como os tipos de casos e as páginas relacionadas a esses casos. |
GET /roles | Lista dos papéis do seu hub |
GET /stages | Lista as etapas do seu hub. |
GET /schemas | Lê o caso do seu hub e os campos personalizados do usuário. |
A chave “hub” funciona como o Assistente VirtualAssistente Virtual Um membro de equipe automatizado que publica mensagens de boas-vindas, atualizações e posts de apresentação para a empresa; suas publicações exibem um selo de Assistente Virtual. do seu hub. Essa função está presente em todos os casos, então essas chamadas chegam a todos os casos do seu hub. Os dois exemplos incluídos são apenas para ilustrar esse funcionamento.
A chave “hub” não pode criar casos: POST /cases responde com o código 403 para HostCreateCaseNotEnabledException. Para criar casos com o seu software, utilize uma chave de gerenciamento; veja Como criar e atualizar casos usando uma chave de gerenciamento.
Listagem de casos
| Parâmetro | O que faz | Obrigatório | Padrão |
|---|---|---|---|
status | 1 para casos abertos; 0 para casos fechados. | Não | 1 |
limit | Quantos casos uma página pode conter, até 1000. | Não | 20 |
start_key | O startKey da página anterior | Não | Primeira página |
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"items": [
{
"case_id": "cc-1a2b3c4d5e6f70",
"case_ref_id": "ca-7e6d5c4b3a2f10::rear-end-2026",
"title": "Jane Sample auto accident",
"team": {
"cu-7e6d5c4b3a2f10": "role::bots",
"cu-4f1c2a9e8b7d60": "role::clients",
"cu-9d8c7b6a5f4e30": "role::staff"
}
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1"
}
}
- Os casos são organizados em ordem de ID do TagID da etiqueta Uma etiqueta permanente que você atribui a um caso, como rear-end-2026, também exibida como ID de referência e usada em importações., da Z para a A, e não por data.
case_ref_idé o ID do seu hub. São dois hífenos, seguidos pelo ID da etiqueta da arma.teamAssocia cada pessoa no caso ao seu rolamentoFunção Um conjunto de permissões que define o que alguém pode ver e fazer em um caso, como funcionários ou clientes., sem que haja nomes indicados. Para obter informações sobre os nomes das pessoas envolvidas, consulte o grupo responsável pelo caso; veja Leia e atualize as informações do caso usando uma chave de hub.- Embora ainda haja mais casos como esse, a página também contém os valores
nextLink, que representam o endereço completo da próxima página, estartKey. ChamenextLink, ou enviestartKeycomostart_key, até que uma página retorne sem esses valores. - Os casos que são excluídos não são considerados. Portanto, uma página pode conter menos de
limitcasos, enquanto ainda haja casos disponíveis. Use o valornextLinkcomo referência, e não o número de casos existentes. - O título e o status do caso podem sofrer uma alteração em alguns segundos.
Pesquisando casos
GET /cases/search corresponde às suas palavras em qualquer lugar da ID de tag de um caso. Também funciona desde o início da palavra no título do caso. Permite pequenos erros de digitação. Não realiza buscas nas descrições dos casos.
| Parâmetro | O que faz | Obrigatório | Padrão |
|---|---|---|---|
query | As palavras que precisam ser procuradas. Envie * para cada caso. | Sim | — |
status | 1 para casos abertos; 0 para casos fechados. | Não | 1 |
limit | Quantos resultados uma página pode conter, até 250. | Não | 20 |
page | Qual página dos resultados, número 1? | Não | 1 |
sort_by | Um campo numérico e uma direção, como por exemplo created_on:desc. Ele aceita valores como created_on, date_opened, last_activity, updated_on, users_ct e case_status. | Não | A melhor combinação primeiro |
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"found": 1,
"page": 1,
"hits": [
{
"document": {
"case_id": "cc-1a2b3c4d5e6f70",
"ref_id": "rear-end-2026",
"title": "Jane Sample auto accident",
"case_status": 1,
"case_type": "general",
"case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
"date_opened": 1772668800,
"created_on": 1791043509,
"last_activity": 1791050112,
"users_ct": 3
}
}
],
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026"
}
}
- Cada golpe que é dado…
documentContém o ID do caso, o ID da etiqueta, o título, o status. Tipo de casoTipo de caso Uma categoria para casos, como "geral", usada para direcionar automações aos casos corretos., Etapa/EstágioEstágio Uma etapa pela qual um caso passa, como Entrada ou Envio de Demanda, que a empresa nomeia e descreve e que aparece na página do caso., Quantas pessoas estão nisso? E quais são as datas, em segundos do Unix, no fuso horário UTC? foundindica quantos casos correspondem ao critério de seleção. Passe pelas páginas compage; não há nenhum valor paranextLink.- O caso pode ser pesquisado em questão de segundos, após qualquer alteração ocorrer.
Localizando um caso pelo seu ID de etiqueta
Não existe uma maneira precisa de buscar por ID de Tag. É necessário realizar uma busca, e então selecionar o resultado cujo document.ref_id seja exatamente o ID do Tag. Isso porque a busca também encontrará correspondências próximas, como rear-end-2025. Para cobrir todos os casos possíveis, é preciso realizar buscas com status=1, e depois com status=0.
Assim que você obtiver o ID do caso, todas as chamadas relacionadas ao caso utilizarão esse ID. Veja Leia e atualize os detalhes do caso com a chave do hub.
Configurações do seu hub
| Chamar | O que isso responde |
|---|---|
GET /whoami | O ID do usuário da chave, o nome do seu hub, os tipos de casos que ele suporta, e quais seções ele está habilitado a acessar. host_default_schemas, As páginas de caso e de campo do usuário |
GET /roles | Cada papel que o Assistente Virtual desempenha inclui os valores role::bots, role_id, name, description, color e reads_notes. Além disso, verifica-se se o papel pode ler as notas relacionadas a ele. |
GET /stages | Cada etapa, desde a primeira até a última, com stage_id, name, description e order. |
GET /schemas | default_schemas, as páginas relacionadas ao caso do seu hub e aos campos personalizados pelo usuário. Cada uma dessas páginas contém as chaves, rótulos e tipos dos respectivos campos. |
Nenhuma das páginas responde a tudo de uma só vez.
Se uma chamada for recusada
| Status | message | Por que |
|---|---|---|
| 400 | SchemaFieldsException | O parâmetro está faltando ou é inválido. Por exemplo, um query vazio, ou um status que não seja 0 ou 1. O errors também está inválido. |
| 400 | InvalidStartKeyException | O start_key veio de outra lista. |
| 400 | SearchParameterException | A busca rejeitou um parâmetro, como: sort_by Em um campo de texto ou algo do tipo. limit Mais de 250; reason Diz qual… |
| 403 | HostCreateCaseNotEnabledException | O hub key tentou criar um caso. |
Para informações sobre o corpo do erro e os demais códigos de erro, consulte Como lidar com erros da API e códigos de status.