Central de ajudaIntegrações

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

ChamarO que faz
GET /caseLê os detalhes do caso.
PUT /caseIsso altera os detalhes relacionados à chave. A chave pode mudar.
GET /whoamiIndica quais detalhes o código pode ler e alterar neste caso, além das seções que ele aponta.
GET /teamLista as pessoas envolvidas no caso.
GET /placeholdersLê 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_type E… 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>/stages lista os nomes dessas etapas.
  • meta_data.content conté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.schema descreve os campos de cada página.
  • hidden_modules lista 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.

CampoO que fazObrigatórioPadrão
titleO nome do caso, mostrado para todos.NãoInalterado
descriptionDescrição para o pessoal: Envie "" para limpar essa informação.NãoInalterado
date_openedA data em que o caso foi iniciado, como 2026-03-15NãoInalterado
case_status0 Para fechar o caso. Uma chave de hub não pode reabri-lo.NãoInalterado
case_stageO ID da etapa é GET /v1/<hub id>/stages. Envie "" para retirar o item da etapa em questão.NãoInalterado
meta_dataValores 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ãoInalterado
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_id representa 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 exemplo primary.
  • host_user_status é igual a 0 para 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 HostAddCaseUserNotEnabledException e HostRemoveCaseUserNotEnabledException. 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

StatusmessagePor que
400SchemaFieldsExceptionO 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.
403CaseFieldNotWritableExceptionO campo que você enviou não é um dos campos chave. O nome dele é reason.
403CaseClosedExceptionO caso foi encerrado.
403HostModuleDisabledExceptionOs 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.
403CaseModulePermissionDeniedExceptionO papel dos bots pode não permitir que eles leiam os detalhes do caso ou das equipes envolvidas.
404CaseNotFoundExceptionO 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.

Artigos relacionados

Entenda o que a API pode fazer.Saiba o que uma chave de gerenciamento e uma chave central podem fazer, por que cada chave funciona como um Assistente Virtual e onde encontrar a lista completa de especificações técnicas.IntegraçõesEncontre casos com uma chave centralListe os casos em seu hub, abertos ou fechados, pesquise-os por ID da tag ou título e encontre o ID de um caso a partir do seu próprio software.IntegraçõesAlterar o que uma função pode fazerEdite as permissões de uma função, os campos do caso que ela pode ler ou alterar e seus limites de upload, incluindo as funções integradas.Segurança e conta · 5 minLidar com erros e códigos de status da APILeia o corpo da mensagem de erro, o que significam os códigos 400, 401, 403, 404, 500 e 503 e por que um item que sua chave não consegue ver responde ao erro 404.Integrações