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âmetro | O que faz | Obrigatório | Padrão |
|---|---|---|---|
table | O que deve ser pesquisado: cases, host_users, case_users, host_roles, case_invoices, host_imports ou import_items | Sim | — |
query | O texto a ser encontrado: * corresponde a tudo, para uma busca feita apenas com filtros. | Sim | — |
query_by | Os campos de texto a serem analisados, separados por vírgulas, como given_name,family_name,email | Sim | — |
filter_by | Uma condição, como case_status:=1. Repita o parâmetro para adicionar mais condições; todas devem ser satisfeitas. | Não | Nenhum |
sort_by | Um campo numérico e uma direção, como created_on:desc | Não | Melhor combinação |
page | Qual página? | Não | 1 |
limit | Os resultados que uma página pode apresentar são, no máximo, 250. | Não | 10 |
- Uma palavra em
querycorresponde ao seu início, e permite que haja alguns erros de digitação. Portanto,janconsegue 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-2026consegue encontrarrear-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âmetrosfilter_by. Um valor pode conter/e+, comoref_id:=2026/rear-endouphone:=+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
table | Campos de texto para pesquisar e filtrar. | Campos numéricos para filtrar e classificar. |
|---|---|---|
cases | case_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_users | user_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_designation | host_user_status (1 ativo, 0 desativado), host_cases_ct, email_verified, phone_verified, created_on, updated_on |
case_users | case_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_roles | role_id, name, role_type, permissions, case_read_fields, case_write_fields | users_ct, created_on, updated_on |
case_invoices | invoice_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_day | total, subtotal, discount, tax, refund_amount, payment_attempts_ct, due_date, completed_on, created_on, updated_on |
host_imports | import_id, name, source, type, user_id, status | total, passed, failed, created_on, updated_on |
import_items | import_id, unique_id, type, status, error_msg, error_record | created_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
| Status | message | Por que |
|---|---|---|
| 400 | SchemaFieldsException | table, 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). |
| 400 | SearchParameterException | O 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. |
| 403 | BotSearchTableNotAllowedException | Você pediu host_inquiries, mas uma chave não pode ser usada para pesquisar esse valor. |
| 500 | InternalError | O mecanismo de busca está indisponível. Tente novamente mais tarde. |