Per: Amministratori
Trova custodie con chiave hub
Elenca i casi presenti nel tuo hub, aperti o chiusi, cercali tramite ID tag o titolo e trova l'ID di un caso dal tuo software.
In questo articolo7 sezioni
Prima di iniziare
Questa pagina descrive le operazioni che il “hub key” effettua per trovare i casi specifici. I percorsi utilizzati sono indicati sotto https://prd-api-app.caseactive.com/v1/<hub id>.
Chiamate
| Chiamata | Cosa fa |
|---|---|
GET /cases | Elenca i casi aperti o chiusi del proprio hub. |
GET /cases/search | Cerca i casi in base all’ID della tag o al titolo del documento. |
GET /whoami | Legge le impostazioni del tuo hub, come i tipi di casse e le pagine relative ai campi di dati. |
GET /roles | Elenca i ruoli del proprio hub. |
GET /stages | Elenca le fasi che compongono il proprio hub. |
GET /schemas | Legge il caso del tuo utente e i campi personalizzati utilizzati dall’utente stesso. |
La chiave “hub” funge da punto di riferimento per il sistema. Assistente virtualAssistente virtuale Un membro automatizzato del team che pubblica messaggi di benvenuto, check-in e post di aggiornamento per l'azienda; i suoi post sono contrassegnati da un badge di Assistente Virtuale., In ogni caso, queste chiamate raggiungono tutti i casi presenti nel proprio hub di controllo. Sono stati inclusi due esempi per illustrare questo fenomeno.
Una chiave di hub non può creare dei casi: POST /cases restituisce il codice 403 per HostCreateCaseNotEnabledException. Per creare dei casi tramite il proprio software, è necessario utilizzare una chiave di gestione; vedi Creazione e aggiornamento dei casi con una chiave di gestione.
Elenco dei casi
| Parametro | Cosa fa | Necessario | Predefinito |
|---|---|---|---|
status | 1 per i casi aperti, 0 per i casi chiusi. | No. | 1 |
limit | Quanti elementi possono essere presenti su una pagina, fino a 1000. | No. | 20 |
start_key | Il startKey della pagina precedente | No. | Prima pagina |
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"
}
}
- I casi vengono presentati in ordine ID del tagID tag Un'etichetta permanente che si assegna a un caso, come ad esempio rear-end-2026, visualizzata anche come ID di riferimento e utilizzata nelle importazioni., da Z a A, e non in base alla data di creazione.
case_ref_idè l’ID del proprio hub; inoltre, contiene due punti e l’ID della “Tag” relativa alla situazione attuale.teamassegnano a ciascuna persona coinvolta nel caso il proprio ruoloRuolo Un insieme di autorizzazioni che determina cosa una persona può vedere e fare su un caso, ad esempio il personale o i clienti., senza fornire dei nomi. Per quanto riguarda i nomi, si veda il team che gestisce il caso; per ulteriori informazioni, si veda Leggi e aggiorna i dettagli del caso utilizzando una chiave di accesso.- Anche se ci sono ancora molti casi da gestire, la pagina contiene anche i valori
nextLink, che rappresentano l’indirizzo completo della pagina successiva, estartKey. È possibile chiamarenextLink, oppure inviarestartKeycomestart_key, fino a quando non viene restituita una pagina senza questi valori. - I casi che vengono eliminati vengono esclusi dalla lista; quindi, una pagina può contenere meno di
limitcasi, mentre altri casi rimangono ancora presenti. Bisogna considerare il valore indicato danextLink, non il numero effettivo dei casi. - Il titolo e lo stato di un caso possono cambiare di qualche secondo.
Casi di ricerca
GET /cases/search può corrispondere alle parole presenti in qualsiasi punto dell’ID delle etichette di un caso. Inoltre, può riconoscere anche le parole che iniziano con una lettera minuscola. Non effettua però ricerche sulle descrizioni dei contenuti.
| Parametro | Cosa fa | Necessario | Predefinito |
|---|---|---|---|
query | Le parole da cercare… Inviare * per ogni caso. | Sì. | – |
status | 1 per i casi aperti, 0 per i casi chiusi. | No. | 1 |
limit | Quanti risultati può contenere una pagina, fino a 250. | No. | 20 |
page | Quale pagina dei risultati, partendo da la pagina numero 1? | No. | 1 |
sort_by | Un campo numerico e una direzione, ad esempio created_on:desc. Viene utilizzato per indicare i valori di created_on, date_opened, last_activity, updated_on, users_ct e case_status. | No. | La migliore combinazione per prima. |
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"
}
}
- Ogni colpo che viene sferzato…
documentContiene l’ID del caso, l’ID della tag, il titolo, lo stato del caso. Tipo di casoTipo di caso Una categoria per i casi, come ad esempio "generale", utilizzata per indirizzare le automazioni verso i casi appropriati., Stagione/PeriodoPalcoscenico Una fase del percorso di una pratica, come ad esempio l'acquisizione dei dati o l'invio della richiesta, che lo studio legale nomina e descrive e che viene visualizzata nella pagina della pratica., Quanti persone sono presenti su di esso, e quali sono le date, espressa in secondi Unix secondo l’ora UTC. foundindica quante delle caselle corrispondono tra loro. Puoi scorrerle conpage; non c’è alcun valore pernextLink.- Un caso può essere esaminato in pochi secondi, non appena si verifica un cambiamento.
Individuazione di un caso tramite il suo ID tag
Non esiste un modo preciso per cercare utilizzando l’ID della tag. È necessario effettuare una ricerca, e poi selezionare il risultato che corrisponde all’indicazione richiesta. document.ref_id È esattamente il proprio ID di tag. Inoltre, una ricerca può trovare anche corrispondenze simili, come… rear-end-2025. Cerca con… status=1, Poi status=0, Per coprire i casi aperti e chiusi.
Una volta ottenuta l’ID del caso, ogni chiamata relativa a quel caso utilizza tale ID. Per ulteriori informazioni, vedere Lezione 2: Lettura e aggiornamento dei dettagli del caso con una chiave di hub.
Le impostazioni del tuo hub
| Chiamata | A cosa risponde |
|---|---|
GET /whoami | L’ID dell’utente che utilizza la chiave, il nome del proprio hub, i tipi di casse a cui è abilitato l’accesso, e le sezioni su cui può accedere. host_default_schemas, Le pagine relative al caso specifico e ai dati dell’utente. |
GET /roles | Ogni ruolo, compreso quello del “Assistente Virtuale”, include le funzioni role::bots, role_id, name, description, color e reads_notes. Inoltre, il ruolo è in grado di leggere le note presenti nel sistema. |
GET /stages | Ogni fase, dalla prima all’ultima, utilizzando i valori stage_id, name, description e order. |
GET /schemas | default_schemas, le pagine relative al caso del tuo hub e ai campi personalizzati degli utenti; ognuna di queste pagine contiene i nomi dei campi, i loro label e i tipi di dati che possono essere memorizzati in quei campi. |
Nessuna di quelle pagine risponde a tutte le domande contemporaneamente.
Se una chiamata viene rifiutata
| Stato | message | Perché |
|---|---|---|
| 400 | SchemaFieldsException | È mancante o non valido un parametro. Ad esempio, potrebbe esserci uno spazio vuoto tra i parametri query, oppure il valore di status potrebbe essere diverso da 0 o 1. Inoltre, il valore di errors non è definito. |
| 400 | InvalidStartKeyException | Il start_key proveniva da un’altra lista. |
| 400 | SearchParameterException | La ricerca ha rifiutato l’uso di alcuni parametri, come sort_by per i campi di testo, oppure limit quando il valore supera i 250. Inoltre, il parametro reason indica quale sia il valore da utilizzare. |
| 403 | HostCreateCaseNotEnabledException | Una chiave di hub ha cercato di creare una situazione particolare. |
Per informazioni sul corpo dell’errore e sugli altri codici, si veda Comunicare gli errori dell’API e i codici di stato.