Para: Administradores
Leia e atualize os detalhes do caso com uma chave central.
Leia os detalhes e a equipe de um caso e altere os detalhes que um administrador permite que altere a função do Assistente Virtual, como a etapa ou um campo personalizado.
Neste artigo8 seções
Antes de começar
Esta página aborda como ler e alterar os detalhes de um caso, utilizando uma chave de hub. Os caminhos estão indicados por https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Chamadas
| Chamar | O que faz |
|---|---|
GET /case | Lê os detalhes do caso. |
PUT /case | Isso altera os detalhes relacionados à chave. A chave pode mudar. |
GET /whoami | Indica quais detalhes o código pode ler e alterar neste caso, além das seções que ele aponta. |
GET /team | Lista as pessoas envolvidas no caso. |
GET /placeholders | Lê os valores que os códigos dos seus modelos preenchem nesse caso. |
Que coisas um hub pode ler e alterar, depende do papel desempenhado pelo 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., bots. Por padrão, o sistema lê os detalhes padrão do caso. Nenhum desses detalhes pode ser alterado até que um administrador permita isso.
Permitir que a chave altere os detalhes
Em Configurações › Papéis, edite o papel do bot. Em Caso, marque a opção Atualizar todos os campos de caso especificados no papel. Os detalhes dos campos podem ser Título, Descrição, Data de abertura, Status, Estágio ou campos personalizados. Para permitir que o bot leia campos personalizados, marque essa opção em Leia todos os campos de caso especificados no papel. Veja Como alterar as funções de um papel.
GET /whoami desempenha o papel de chave nesse caso. case_read_fields e case_write_fields indicam os detalhes que podem ser lidos e alterados. case_write_fields é deixado sem definição, pois pode não mudar nada. Um campo personalizado é representado por meta_data.<field key>. Ele também relaciona-se a case_modules, ou seja, às seções que o caso inclui, excluindo as seções ocultas nesse caso. Qualquer chamada feita a uma seção que não está presente no caso será rejeitada.
Lendo um caso
curl https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"case_id": "cc-1a2b3c4d5e6f70",
"host_id": "ca-7e6d5c4b3a2f10",
"ref_id": "rear-end-2026",
"title": "Jane Sample auto accident",
"description": "Rear-end collision on Route 9. Waiting on the insurer's estimate.",
"case_type": "general",
"case_status": 1,
"case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
"date_opened": "2026-03-05",
"meta_data": {
"schema": [{"schema": {"type": "object", "properties": {"policy_number": {"type": "string", "title": "Policy number"}}}}],
"content": [{"policy_number": "PN-5521"}]
},
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case"
}
}
- Por padrão, a chave é lida como…
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.),case_status,date_opened,title,description,case_typeE…case_stage. Um detalhe importante do caso foi omitido. case_stageé o ID de 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.;GET /v1/<hub id>/stageslista os nomes dessas etapas.meta_data.contentcontém os valores dos campos personalizados. Um objeto é criado para cada campo, de acordo com a chave do campo. No entanto, apenas os campos cuja chave permitem leitura são utilizados. Por padrão, nenhum valor é lido; assim, a primeira página fica vazia. No exemplo, um administrador permitiu que o sistema lesse o número da política.meta_data.schemadescreve os campos de cada página.hidden_moduleslista as seções ocultas neste caso, caso existam.
Alterar um caso
PUT /case aceita qualquer um desses campos como JSON, e altera apenas aqueles que você envia.
| Campo | O que faz | Obrigatório | Padrão |
|---|---|---|---|
title | O nome do caso, mostrado para todos. | Não | Inalterado |
description | Descrição para o pessoal: Envie "" para limpar essa informação. | Não | Inalterado |
date_opened | A data em que o caso foi iniciado, como 2026-03-15 | Não | Inalterado |
case_status | 0 Para fechar o caso. Uma chave de hub não pode reabri-lo. | Não | Inalterado |
case_stage | O ID da etapa é GET /v1/<hub id>/stages. Envie "" para retirar o item da etapa em questão. | Não | Inalterado |
meta_data | Valores de campos personalizados: uma lista com um objeto por página de campo, em ordem sequencial. Cada objeto contém os valores correspondentes ao campo em questão. Apenas a primeira página pode ser alterada aqui; além disso, apenas os campos que você definir podem ser modificados. Use "" ou null para limpar um campo; um campo obrigatório não pode ser limpo. | Não | Inalterado |
curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_stage": "stage::20260927120000_8c1f0e2d3b4a59", "meta_data": [{"policy_number": "PN-5521"}]}'
Ele responde a 200 com o ID do caso. Se algum dos campos que você envia não for um dos campos chave, então o valor pode mudar. Nesse caso, toda a chamada é rejeitada com o código 403, e nada muda. reason indica os campos, sendo que um deles é personalizado, representado por meta_data.<field key>. Um campo cujo valor já existe no caso não representa uma alteração, então ele não é rejeitado nem modificado. Uma chamada que não altera nada responde a 204.
- Mover um caso aberto para uma fase adicional adiciona um marco nessa fase. Isso acontece porque o Assistente Virtual, se o seu hub tiver esse recurso, fará isso automaticamente. Veja “Adicionar uma publicação automaticamente quando um caso atinge uma fase específica”. Nada mais é publicado ou enviado: a conclusão de um caso ou a alteração dos seus detalhes não afeta ninguém.
- Uma vez que um caso é encerrado, qualquer alteração feita por meio de uma chave de acesso é recusada. Isso inclui a possibilidade de reabrir o caso. Para reabrir o caso, utilize o painel administrativo ou uma chave de gerenciamento. Veja Cerrar ou reabrir um caso.
- O ID do tag e o tipo de caso não podem ser alterados aqui. A chave de gerenciamento é capaz de alterar o tipo.
A equipe
GET /team lista todos os membros envolvidos no caso, incluindo o Assistente Virtual e os membros com deficiência. Um caso pode conter até 20 pessoas ao mesmo tempo. O Assistente Virtual fez essa contagem.
{
"data": {
"items": [
{
"case_id": "cc-1a2b3c4d5e6f70",
"user_id": "cu-4f1c2a9e8b7d60",
"case_role_id": "role::clients",
"case_designation": "primary",
"case_notify": 1,
"host_user_status": 1,
"given_name": "Jane",
"family_name": "Sample",
"locale": "en",
"zoneinfo": "America/New_York"
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/team"
}
}
case_role_idrepresenta o papel da pessoa nesse caso.case_designation, por sua vez, refere-se à sua designaçãoDesignação Uma designação que designa a função de alguém em um caso, como Advogado Principal, Assistente Jurídico ou Tutor., como por exemploprimary.host_user_statusé igual a0para alguém que está com deficiência em seu centro de atendimento.- Os nomes de cada pessoa, a língua que ela fala…
locale) E o fuso horário…zoneinfo) Voltar para trás, por padrão. Endereços de e-mail e números de telefone nunca funcionam assim. - A chave “hub” não permite adicionar ou remover pessoas das chamadas. Essas chamadas são atendidas por meio das chaves 403
HostAddCaseUserNotEnabledExceptioneHostRemoveCaseUserNotEnabledException. Use uma chave de gerenciamento para isso; veja Adicionar e remover membros do caso com a chave de gerenciamento.
Valores do modelo
Em GET /placeholders, sob placeholders, está indicado o valor que cada código nos seus modelos deve preencher nesse caso. Exemplos de esses códigos são clients.primary.full_name, clients.primary.email, case_ref_id e company.phone. Um código para uma designação que não existe no caso é deixado em branco. Quando a seção “Equipe” está desativada ou oculta no caso, todos os códigos de equipe são excluídos, mas o resto continua a ser preenchido. Veja Preencher campos do formulário com detalhes do caso.
Se uma chamada for recusada
| Status | message | Por que |
|---|---|---|
| 400 | SchemaFieldsException | O campo está inválido. Por exemplo, um campo vazio como title, um campo personalizado que não foi enviado, ou um estágio que seu hub não possui. O nome do campo é errors. |
| 403 | CaseFieldNotWritableException | O campo que você enviou não é um dos campos chave. O nome dele é reason. |
| 403 | CaseClosedException | O caso foi encerrado. |
| 403 | HostModuleDisabledException | Os detalhes do caso ou a equipe envolvida estão ocultos neste caso. Ou seja, essas informações não são exibidas no seu hub. |
| 403 | CaseModulePermissionDeniedException | O papel dos bots pode não permitir que eles leiam os detalhes do caso ou das equipes envolvidas. |
| 404 | CaseNotFoundException | O caso não existe. Ele pertence a outro hub ou está sendo apagado. |
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.