Central de ajudaIntegrações

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

ChamarO que faz
GET /casesLista os casos abertos ou fechados do seu centro de atendimento.
GET /cases/searchPesquisa casos com base no ID da etiqueta ou no título do caso.
GET /whoamiLê as configurações do seu hub, como os tipos de casos e as páginas relacionadas a esses casos.
GET /rolesLista dos papéis do seu hub
GET /stagesLista as etapas do seu hub.
GET /schemasLê 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âmetroO que fazObrigatórioPadrão
status1 para casos abertos; 0 para casos fechados.Não1
limitQuantos casos uma página pode conter, até 1000.Não20
start_keyO startKey da página anteriorNãoPrimeira 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.
  • team Associa 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, e startKey. Chame nextLink, ou envie startKey como start_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 limit casos, enquanto ainda haja casos disponíveis. Use o valor nextLink como 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âmetroO que fazObrigatórioPadrão
queryAs palavras que precisam ser procuradas. Envie * para cada caso.Sim—
status1 para casos abertos; 0 para casos fechados.Não1
limitQuantos resultados uma página pode conter, até 250.Não20
pageQual página dos resultados, número 1?Não1
sort_byUm 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ãoA 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… document Conté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?
  • found indica quantos casos correspondem ao critério de seleção. Passe pelas páginas com page; não há nenhum valor para nextLink.
  • 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

ChamarO que isso responde
GET /whoamiO 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 /rolesCada 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 /stagesCada etapa, desde a primeira até a última, com stage_id, name, description e order.
GET /schemasdefault_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

StatusmessagePor que
400SchemaFieldsExceptionO 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.
400InvalidStartKeyExceptionO start_key veio de outra lista.
400SearchParameterExceptionA busca rejeitou um parâmetro, como: sort_by Em um campo de texto ou algo do tipo. limit Mais de 250; reason Diz qual…
403HostCreateCaseNotEnabledExceptionO 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.

Artigos relacionados

Entenda o que a API pode fazer.Saiba o que uma chave de gerenciamento e uma chave central podem fazer, por que cada chave funciona como um Assistente Virtual e onde encontrar a lista completa de especificações técnicas.IntegraçõesLeia e atualize os detalhes do caso com uma chave central.Leia os detalhes e a equipe de um caso e altere os detalhes que um administrador permite que altere a função do Assistente Virtual, como a etapa ou um campo personalizado.IntegraçõesCrie e atualize casos com uma chave de gerenciamento.Liste, crie, leia, atualize e exclua os casos do seu hub a partir do seu próprio software, incluindo o estágio e os campos personalizados.IntegraçõesLidar com erros e códigos de status da APILeia o corpo da mensagem de erro, o que significam os códigos 400, 401, 403, 404, 500 e 503 e por que um item que sua chave não consegue ver responde ao erro 404.Integrações