Para: Administradores
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.
Neste artigo10 seções
Antes de começar
Esta página aborda sobre as chamadas de caso que podem ser gerenciadas por uma chave específica. Os caminhos estão localizados abaixo de https://prd-api-manage.caseactive.com/v1/<hub id>.
Chamadas
| Chamar | O que faz |
|---|---|
GET /cases | Lista os casos do seu hub, com os mais recentes em primeiro lugar. |
POST /cases | Cria um caso/problema |
GET /cases/<case_id> | Lê um caso específico. |
PUT /cases/<case_id> | Modifica o caso de alguma palavra. |
DELETE /cases/<case_id> | Apaga um caso de uma vez por todas. |
GET /stages | Lista as etapas do seu hub, para encontrar seus IDs. |
GET /schemas?schema_type=cases | Lê os campos personalizados do seu hub. |
Listagem de casos
| Parâmetro | O que faz | Obrigatório | Padrão |
|---|---|---|---|
type | 1 refere-se apenas aos casos abertos; 0 refere-se aos casos fechados. Apesar do nome, o filtro é baseado no status do caso, e não no tipo de caso. | Não | Ambos |
limit | Quantos casos uma página pode conter, até 1000. | Não | 20 |
start_key | O startKey da página anterior | Não | Primeira página |
curl "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?type=1" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"items": [
{
"case_id": "cc-1a2b3c4d5e6f70",
"host_id": "ca-7e6d5c4b3a2f10",
"ref_id": "rear-end-2026",
"title": "Jane Sample auto accident",
"case_type": "general",
"case_status": 1,
"case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
"users": {
"cu-7e6d5c4b3a2f10": "role::bots",
"cu-4f1c2a9e8b7d60": "role::clients",
"cu-9d8c7b6a5f4e30": "role::staff"
},
"created_on": "2026-10-02T14:05:09+00:00"
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?type=1"
}
}
usersassocia cada pessoa no caso ao seu rolamentoFunção Um conjunto de permissões que define o que alguém pode ver e fazer em um caso, como funcionários ou clientes.. Isso inclui o 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. do seu hub, comorole::bots.- Embora ainda haja mais casos como esse, a página também contém os valores
nextLink, que representam o endereço completo da próxima página, estartKey. ChamenextLink, ou enviestartKeycomostart_key, até que uma página retorne sem esses valores. - Os casos que são excluídos não são incluídos na lista. Para encontrar um caso com base no seu ID de 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., consulte Buscar casos e usuários com chave de gerenciamento.
Campos do caso
POST /cases e PUT /cases/<case_id> consideram esses campos como dados em formato JSON. Os campos que não estão listados são ignorados.
| Campo | O que faz | Obrigatório | Padrão |
|---|---|---|---|
ref_id | O ID da tag do caso é composto por letras, números, traços e barras, todos escritos em minúsculas. Nenhum dos casos no seu hub pode compartilhar o mesmo ID. Esse ID é definido apenas durante a criação do caso; não pode ser alterado posteriormente. | Sim, ao criar. | — |
title | O nome do caso, mostrado para todos. | Sim, ao criar. | — |
description | Uma descrição para o pessoal. Os clientes não veem isso. Em uma mudança, "" apaga essa informação. | Não | Nenhum |
case_type | general, ou um dos tipos de caso do seu hub, case typesTipo de caso Uma categoria para casos, como "geral", usada para direcionar automações aos casos corretos.. Esses tipos são indicados abaixo de Configurações › Campos. Em caso de alteração, o próprio tipo do caso também é aceito, mesmo depois de você tê-lo removido das suas configurações. | Não | general |
case_status | 1 para aberto, 0 para fechado. | Não | 1 |
case_stage | O ID da sua 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. é GET /stages. Quando ocorre alguma mudança, "" retira a etapa do seu local de destino. | Não | Nenhuma fase |
date_opened | A data em que o caso foi iniciado, como 2026-03-15 | Não | Hoje, no fuso horário UTC |
hidden_modules | Seções a serem ocultadas neste caso: qualquer uma dos case, convos, events, forms, signs, invoices, notes, tasks e team. Envie [] para exibir todas elas novamente. | Não | Nenhum escondido. |
meta_data | Seus campos personalizados… Veja abaixo. | Não | Nenhum |
Você não pode adicionar pessoas durante o processo de criação de um novo caso. Apenas o Assistente Virtual pode ser adicionado a um novo caso. Adicione-as posteriormente, usando POST /cases/permissions. Veja Como adicionar e remover membros de um caso, utilizando a chave “manage”.
Criando um caso
curl -X POST https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ref_id": "rear-end-2026", "title": "Jane Sample auto accident", "case_type": "general", "date_opened": "2026-10-02"}'
Isso responde a 201 com o ID do novo caso.
{"data": {"case_id": "cc-1a2b3c4d5e6f70", "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases"}}
Ninguém recebe e-mails. As regras de “Assign Cases” determinam quem deve estar responsável por cada caso, e para cada tipo de caso, é definido quem será o responsável por ele. Portanto, qualquer pessoa que adicione um novo membro à equipe do caso será rejeitada, pois trata-se de uma duplicação. Um caso criado em uma determinada fase não recebe nenhum aviso ou notificação relacionado a esse estágio.
Lendo um caso
GET /cases/<case_id> Responde ao caso em questão. case_id, host_id, ref_id, title, description, case_type, case_status, case_stage, date_opened, hidden_modules, meta_data, users_ct Quantas pessoas estão envolvidas nisso? Incluindo o Assistente Virtual. created_on E… updated_on. Para saber quem está envolvido nisso, use… GET /cases/permissions?case_id=<case_id>.
Alterar um caso
PUT /cases/<case_id> aceita qualquer um dos campos de caso, exceto ref_id. Ele altera apenas aqueles que você fornece. Ele responde a 204, sem nenhum corpo de resposta.
- Mover um caso aberto para uma fase adiciona um marco nessa fase. O Assistente Virtual, se o seu hub tiver essa função, fará isso automaticamente. Veja “Adicionar uma publicação automaticamente quando um caso atinge uma fase”. Nada mais é publicado ou enviado: fechar um caso ou alterar seu tipo não afeta ninguém.
meta_datasubstitui todos os campos personalizados que existem no caso em questão.- Um caso fechado ainda pode ser alterado. Portanto, uma sincronização pode reabrir esse caso com
"case_status": 1.
Etapas e campos personalizados
GET /stages lista as etapas do seu hub. Essas etapas são definidas pelo administrador sob Configurações › Etapas. Cada etapa possui os campos stage_id, name, description e order, todos ao mesmo tempo. Um usuário com permissão pode ler as informações sobre as etapas, mas não pode alterá-las.
GET /schemas?schema_type=cases utiliza os campos personalizados do seu hub, definidos em Configurações › Campos, como uma lista de páginas. Cada página contém as chaves, rótulos e tipos dos campos correspondentes. Envie meta_data como uma lista, com um objeto por página, na mesma ordem indicada. Cada objeto contém os valores correspondentes às chaves dos campos.
{"meta_data": [{"policy_number": "PN-5521", "insurer": "Northwind Mutual"}]}
Um valor deve se adequar ao tipo do campo em questão; caso contrário, o pedido será rejeitado. Requeridos é verificado apenas pelas formas de preenchimento presentes no Painel de Administração e no Lobby. Portanto, qualquer campo que você crie ou atualize aqui pode ficar vazio, sem que isso cause problemas.
Excluindo um caso
A resposta de DELETE /cases/<case_id> é 204. Esse caso de exclusão deixa as suas listas imediatamente desativadas e, posteriormente, as listas são apagadas permanentemente, incluindo os posts, arquivos, formulários, documentos eletrônicos, faturas, eventos, tarefas e notas relacionados. Não é possível reverter essa exclusão, e ninguém é informado sobre o ocorrido. A identificação da tag utilizada para a exclusão fica livre novamente, após a conclusão do processo de exclusão.
Se uma chamada for recusada
| Status | message | Por que |
|---|---|---|
| 400 | SchemaFieldsException | O campo está ausente ou inválido; o nome do campo é errors. Um tipo de caso ou estágio desconhecido está associado ao campo FieldValidatorFailedException. |
| 400 | CaseReferenceIdExistsException | Há outro caso que já possui esse ID de tag, mesmo sendo esse caso ainda em processo de exclusão. reason detém o valor case_id desse caso. |
| 404 | ItemNotFoundException | O caso não existe. Ele pertence a outro hub ou está sendo apagado. |
| 403 | ManageBillingInactiveException | O painel de administração do seu hub foi bloqueado após um pagamento falhado. |
Para informações sobre o corpo do erro e os demais códigos de erro, consulte Como lidar com erros da API e códigos de status.