Centro assistenzaIntegrazioni

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

ChiamataCosa fa
GET /casesElenca i casi aperti o chiusi del proprio hub.
GET /cases/searchCerca i casi in base all’ID della tag o al titolo del documento.
GET /whoamiLegge le impostazioni del tuo hub, come i tipi di casse e le pagine relative ai campi di dati.
GET /rolesElenca i ruoli del proprio hub.
GET /stagesElenca le fasi che compongono il proprio hub.
GET /schemasLegge 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

ParametroCosa faNecessarioPredefinito
status1 per i casi aperti, 0 per i casi chiusi.No.1
limitQuanti elementi possono essere presenti su una pagina, fino a 1000.No.20
start_keyIl startKey della pagina precedenteNo.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.
  • team assegnano 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, e startKey. È possibile chiamare nextLink, oppure inviare startKey come start_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 limit casi, mentre altri casi rimangono ancora presenti. Bisogna considerare il valore indicato da nextLink, 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.

ParametroCosa faNecessarioPredefinito
queryLe parole da cercare… Inviare * per ogni caso.Sì.–
status1 per i casi aperti, 0 per i casi chiusi.No.1
limitQuanti risultati può contenere una pagina, fino a 250.No.20
pageQuale pagina dei risultati, partendo da la pagina numero 1?No.1
sort_byUn 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… document Contiene 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.
  • found indica quante delle caselle corrispondono tra loro. Puoi scorrerle con page; non c’è alcun valore per nextLink.
  • 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

ChiamataA cosa risponde
GET /whoamiL’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 /rolesOgni 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 /stagesOgni fase, dalla prima all’ultima, utilizzando i valori stage_id, name, description e order.
GET /schemasdefault_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

StatomessagePerché
400SchemaFieldsExceptionÈ 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.
400InvalidStartKeyExceptionIl start_key proveniva da un’altra lista.
400SearchParameterExceptionLa 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.
403HostCreateCaseNotEnabledExceptionUna 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.

Articoli correlati

Comprendere cosa può fare l'APIScopri quali funzioni possono svolgere un tasto di gestione e un tasto hub, perché ogni tasto funge da Assistente Virtuale e dove trovare l'elenco tecnico completo.IntegrazioniLeggi e aggiorna i dettagli del caso con una chiave hubLeggi i dettagli di un caso e il team, e modifica i dettagli che un amministratore consente di modificare per il ruolo dell'assistente virtuale, come la fase o un campo personalizzato.IntegrazioniCrea e aggiorna i casi con una chiave di gestioneElenca, crea, leggi, aggiorna ed elimina i casi del tuo hub dal tuo software, inclusi i relativi campi di fase e personalizzati.IntegrazioniGestire gli errori e i codici di stato delle APILeggi il corpo dell'errore, cosa significano i codici 400, 401, 403, 404, 500 e 503 e perché un elemento che la tua chiave non riesce a vedere risponde al codice 404.Integrazioni