Central de ajudaIntegrações

Para: Administradores

Pesquise casos e usuários com uma chave de gerenciamento.

Encontre casos, pessoas, membros do caso, funções e importe linhas por texto, com filtros, a partir do seu próprio software.

Neste artigo6 seções

Antes de começar

Esta página aborda o recurso GET https://prd-api-manage.caseactive.com/v1/<hub id>/search, que permite encontrar registros no seu hub, com base em texto. Ele realiza buscas apenas no próprio hub do usuário.

Parâmetros

ParâmetroO que fazObrigatórioPadrão
tableO que deve ser pesquisado: cases, host_users, case_users, host_roles, case_invoices, host_imports ou import_itemsSim—
queryO texto a ser encontrado: * corresponde a tudo, para uma busca feita apenas com filtros.Sim—
query_byOs campos de texto a serem analisados, separados por vírgulas, como given_name,family_name,emailSim—
filter_byUma condição, como case_status:=1. Repita o parâmetro para adicionar mais condições; todas devem ser satisfeitas.NãoNenhum
sort_byUm campo numérico e uma direção, como created_on:descNãoMelhor combinação
pageQual página?Não1
limitOs resultados que uma página pode apresentar são, no máximo, 250.Não10
  • Uma palavra em query corresponde ao seu início, e permite que haja alguns erros de digitação. Portanto, jan consegue encontrar “Jane”. Nos IDs de tags, nomes, endereços de e-mail, números de telefone e IDs de referência, a correspondência pode ocorrer em qualquer lugar do texto. Assim, end-2026 consegue encontrar rear-end-2026.
  • Um filtro é um campo, um operador e um valor: := significa “exato”, :!= significa “não”, e :>, :<, :>= e :<= referem-se a números. Uma condição não pode conter &&, ||, parênteses ou vírgulas. Em vez disso, deve-se enviar vários parâmetros filter_by. Um valor pode conter / e +, como ref_id:=2026/rear-end ou phone:=+15551234567. Em um endereço, + deve ser enviado como %2B; caso contrário, ele será interpretado como um espaço.
  • Apenas campos numéricos podem ser ordenados. As datas apresentadas nos resultados são expressas em segundos do formato Unix.
  • Um registro pode levar alguns minutos para ser exibido, após ser criado ou alterado.
  • As consultas não podem ser pesquisadas usando uma chave.

Tabelas

tableCampos de texto para pesquisar e filtrar.Campos numéricos para filtrar e classificar.
casescase_id, ref_id (…) 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.), title, description, case_type, case_stage, users (IDs de usuário dos membros)case_status (1 aberto, 0 fechado), users_ct, date_opened, created_on, last_activity, updated_on
host_usersuser_id, given_name, family_name, email, phone, host_ref_id, title, company, address1, address2, locality, region, postal_code, country, gender, birthdate_md (mês e dia, como 04-12), locale, zoneinfo, host_user_type, host_granted_status, host_default_role, host_staff_designationhost_user_status (1 ativo, 0 desativado), host_cases_ct, email_verified, phone_verified, created_on, updated_on
case_userscase_id, user_id, case_ref_id, case_role_id, e também os valores de title e description do caso em questão.case_status, created_on, updated_on
host_rolesrole_id, name, role_type, permissions, case_read_fields, case_write_fieldsusers_ct, created_on, updated_on
case_invoicesinvoice_id, name, invoice_number, po_number, host_ref_id, description, notes, status (open, paid, void, uncollectible ou processing), status_reason, payment_gateway, case_id, user_id, participants_ids, refund_status (pending, succeeded, failed ou canceled), refund_reason, completed_on_daytotal, subtotal, discount, tax, refund_amount, payment_attempts_ct, due_date, completed_on, created_on, updated_on
host_importsimport_id, name, source, type, user_id, statustotal, passed, failed, created_on, updated_on
import_itemsimport_id, unique_id, type, status, error_msg, error_recordcreated_on, updated_on

host_users Inclui o seu hub. 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., de quem host_user_type É bot. case_users Não possui nomes: encontre a pessoa em questão. host_users, Em seguida, filtre. case_users Por… user_id. case_invoices A empresa detém apenas faturas publicadas. Os valores estão expressos em centavos. tax E… discount São frações. Uma fatura reembolsada mantém… status paid; O reembolso ocorre… refund_status.

Exemplos

Um caso, com base no seu ID de etiqueta:

curl -G https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "table=cases" \
  --data-urlencode "query=*" \
  --data-urlencode "query_by=ref_id" \
  --data-urlencode "filter_by=ref_id:=rear-end-2026"

Pessoas ativas cujos nomes ou e-mails começam com jane. Os mais recentes primeiro:

curl -G https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "table=host_users" \
  --data-urlencode "query=jane" \
  --data-urlencode "query_by=given_name,family_name,email" \
  --data-urlencode "filter_by=host_user_status:=1" \
  --data-urlencode "sort_by=created_on:desc"

Abra os casos em apenas uma etapaEstá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., utilizando um stage_id proveniente de GET /stages: table=cases&query=*&query_by=title&filter_by=case_status:=1&filter_by=case_stage:=stage::20260927120000_8c1f0e2d3b4a59.

As faturas foram alteradas a partir da meia-noite do dia 8 de outubro de 2026, no fuso horário UTC. As alterações mais antigas são apresentadas primeiro: table=case_invoices&query=*&query_by=name&filter_by=updated_on:>1791417600&sort_by=updated_on:asc.

Resultados

{
  "data": {
    "found": 1,
    "page": 1,
    "hits": [
      {
        "document": {
          "case_id": "cc-1a2b3c4d5e6f70",
          "host_id": "ca-7e6d5c4b3a2f10",
          "ref_id": "rear-end-2026",
          "title": "Jane Sample auto accident",
          "case_type": "general",
          "case_status": 1,
          "users": ["cu-4f1c2a9e8b7d60", "cu-9d8c7b6a5f4e30"],
          "users_ct": 2,
          "date_opened": 1790899200,
          "created_on": 1790949909,
          "updated_on": 1790949909
        }
      }
    ]
  }
}

found indica quantos registros correspondem à busca realizada. O document de cada resultado representa o próprio registro da busca. Os resultados também contêm os campos de pontuação fornecidos pelo mecanismo de busca; esses campos podem ser ignorados. Não existe um nextLink: continue procurando pelo próximo page até obter todos os found resultados.

A busca por palavras também pode encontrar valores semelhantes. Portanto, quando você procura por um registro com base em um ID, verifique o resultado que obtém, ou seja, o valor document.

Se uma chamada for recusada

StatusmessagePor que
400SchemaFieldsExceptiontable, query ou query_by estão ausentes ou desconhecidos. Além disso, um filter_by contém caracteres que não podem ser processados (FieldSearchFilterTypeException, em filter_by.0 para o primeiro).
400SearchParameterExceptionO mecanismo de busca se recusou a aceitar esse arquivo: era um campo desconhecido, um filtro que não podia ser lido, além de ser um campo de texto. sort_by, ou limit Mais de 250. reason Contém as próprias palavras do motor.
403BotSearchTableNotAllowedExceptionVocê pediu host_inquiries, mas uma chave não pode ser usada para pesquisar esse valor.
500InternalErrorO mecanismo de busca está indisponível. Tente novamente mais tarde.

Artigos relacionados

Crie 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çõesAdicione e atualize usuários com uma chave de gerenciamento.Liste as pessoas da sua central, adicione clientes, leia os detalhes e casos de alguém e desative ou reative o acesso dessa pessoa.Integrações