Centro de ayudaIntegraciones

Para: Administradores

Encuentra casos con una clave central

Enumere los casos en su plataforma, abiertos o cerrados, búsquelos por ID de etiqueta o título, y encuentre el ID de un caso desde su propio software.

En este artículo7 secciones

Antes de empezar

Esta página describe las llamadas que utiliza la clave de hub para encontrar los casos correspondientes. Los caminos se encuentran debajo de https://prd-api-app.caseactive.com/v1/<hub id>.

Llamadas

LlamarLo que hace
GET /casesLista los casos abiertos o cerrados en su centro de control.
GET /cases/searchBúsqueda de casos según la identificación del tag o el título del caso.
GET /whoamiLee la configuración de su dispositivo, como los tipos de casos y las páginas relacionadas con cada campo.
GET /rolesLista de las funciones de su centro de datos.
GET /stagesLista de las etapas de tu centro de operaciones.
GET /schemasLee los campos de caso y de datos personalizados del usuario de tu dispositivo.

La llave “hub” funciona como el Asistente VirtualAsistente virtual Un miembro del equipo automatizado que publica mensajes de bienvenida, registros de asistencia y actualizaciones de la empresa; sus publicaciones llevan una insignia de Asistente Virtual. de tu centro de control. Está presente en cada caso, por lo que todas las llamadas llegan a todos los casos que se encuentran en tu centro de control. Se incluyen dos ejemplos de casos para ilustrar este proceso.

Una clave de hub no puede crear casos: POST /cases devuelve el código 403 para HostCreateCaseNotEnabledException. Para crear casos desde su software, utilice una clave de gestión; vea Crear y actualizar casos con una clave de gestión.

Listado de casos

ParámetroLo que haceRequeridoPor defecto
status1 para casos abiertos; 0 para casos cerrados.No.1
limit¿Cuántos casos puede almacenar una página, hasta 1000 en total?No.20
start_keyEl startKey de la página anteriorNo.Primera 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"
  }
}
  • Los casos se presentan en orden de ID del tagID de etiqueta Una etiqueta permanente que se le asigna a una caja, como por ejemplo rear-end-2026, que también se muestra como ID de referencia y se utiliza en las importaciones., desde Z hasta A, y no según la fecha.
  • case_ref_id es la ID del centro de operaciones; consta de dos comas y la ID de la etiqueta del caso.
  • team Asigna a cada persona que forma parte del caso su rolPapel Un conjunto de permisos que determina qué puede ver y hacer una persona en un caso, como por ejemplo, el personal o los clientes., sin indicar nombres. Para obtener los nombres de las personas involucradas, consulte el equipo del caso; véase Leer y actualizar los detalles del caso utilizando una clave de hub.
  • Aunque todavía hay más casos que se deben resolver, la página también contiene los valores nextLink, que representan la dirección completa de la página siguiente, y startKey. Llamar a nextLink, o enviar startKey como start_key, hasta que se encuentre una página que no contenga estos valores.
  • Los casos que se eliminan no se tienen en cuenta; por lo tanto, una página puede contener menos de limit casos, mientras que todavía quedan más casos disponibles. Se debe referir a nextLink, no al número total de casos.
  • El título y el estado de un caso pueden cambiar en unos segundos.

Búsqueda de casos

GET /cases/search coincide con las palabras que aparecen en cualquier lugar de la ID de etiqueta de un caso. También puede detectar errores pequeños en las palabras, pero no busca descripciones.

ParámetroLo que haceRequeridoPor defecto
queryLas palabras que deben buscarse. Envíe * para cada caso.Sí.—
status1 para casos abiertos; 0 para casos cerrados.No.1
limit¿Cuántos resultados puede contener una página, hasta un máximo de 250.No.20
page¿Qué página de los resultados, número 1?No.1
sort_byUn campo numérico y una dirección, como por ejemplo created_on:desc. Se necesitan los valores de created_on, date_opened, last_activity, updated_on, users_ct y case_status.No.La mejor coincidencia primero
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 se da… document Contiene la identificación del caso, el ID de la etiqueta, el título, el estado. Tipo de casoTipo de caso Una categoría para casos, como por ejemplo "general", que se utiliza para dirigir las automatizaciones a los casos adecuados., Etapa/ProcesoEscenario Una etapa por la que pasa un caso, como la recepción o el envío de la solicitud, que la firma nombra y describe y que se muestra en la página del caso., ¿Cuántas personas están conectadas a él? Además, se indican las fechas en segundos de Unix, según el formato UTC.
  • found indica cuántos casos coinciden. Puedes verlos uno por uno, utilizando page. No hay ningún valor para nextLink.
  • Un caso puede ser buscado en cuestión de segundos, tan pronto como se produzca un cambio.

Búsqueda de un caso por su ID de etiqueta

No existe una forma precisa de buscar por el ID de la etiqueta. Búscala, y luego selecciona el resultado cuyo document.ref_id sea exactamente igual al ID de la etiqueta. De esta manera, se evitan las coincidencias cercanas como rear-end-2025. Puedes buscar también con status=1 y luego con status=0, para abarcar tanto los casos abiertos como los cerrados.

Una vez que tenga la identificación del caso, toda llamada relacionada con ese caso utilizará esa identificación. Consulte Leer y actualizar los detalles del caso utilizando una clave de hub.

Configuración de tu hub

LlamarLo que responde
GET /whoamiEl ID del usuario que utiliza la llave, el nombre de su centro de control, los tipos de casos que puede manejar, las secciones en las que está disponible, y host_default_schemas, las páginas relacionadas con los campos de caso y de usuario.
GET /rolesCada rol, incluido el de Asistente Virtual, cuenta con las funciones role::bots, role_id, name, description, color y reads_notes. Independientemente de si el rol puede leer notas o no.
GET /stagesCada etapa, desde la primera hasta la última, con stage_id, name, description y order.
GET /schemasdefault_schemas, las páginas relacionadas con el caso de tu centro de distribución y los campos personalizados por el usuario. Cada una de estas páginas contiene las claves, etiquetas y tipos de los campos correspondientes.

Ninguna de esas páginas responde a todo al mismo tiempo.

Si se rechaza una llamada

EstadomessagePor qué
400SchemaFieldsExceptionFaltan o los parámetros son inválidos. Por ejemplo, puede haber un query vacío, o un status que no sea 0 ni 1. El errors también puede estar vacío.
400InvalidStartKeyExceptionEl start_key proviene de otra lista.
400SearchParameterExceptionLa búsqueda rechazó un parámetro, como sort_by en un campo de texto, o un valor de limit que excediera los 250. El parámetro reason indica cuál es el valor a buscar.
403HostCreateCaseNotEnabledExceptionUn “hub key” intentó crear un caso.

Para información sobre el cuerpo de error y los demás códigos, vea Como manejar los errores de la API y los códigos de estado.

Artículos relacionados

Entienda lo que la API puede hacerDescubre qué funciones pueden alcanzar una clave de administración y una clave de concentrador, por qué cada clave actúa como asistente virtual y dónde encontrar la lista técnica completa.IntegracionesLea y actualice los detalles del caso con una clave central.Lee los detalles del caso y del equipo, y cambia los detalles que un administrador permite que cambie el rol del asistente virtual, como la etapa o un campo personalizado.IntegracionesCree y actualice casos con una clave de administración.Lista, crea, lee, actualiza y elimina los casos de tu plataforma desde tu propio software, incluyendo su etapa y campos personalizados.IntegracionesGestionar errores de API y códigos de estadoLea el cuerpo del error, qué significan los códigos 400, 401, 403, 404, 500 y 503, y por qué un elemento que su clave no puede ver responde con el código 404.Integraciones