Central de ajudaIntegrações

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

ChamarO que faz
GET /casesLista os casos do seu hub, com os mais recentes em primeiro lugar.
POST /casesCria 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 /stagesLista as etapas do seu hub, para encontrar seus IDs.
GET /schemas?schema_type=casesLê os campos personalizados do seu hub.

Listagem de casos

ParâmetroO que fazObrigatórioPadrão
type1 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ãoAmbos
limitQuantos casos uma página pode conter, até 1000.Não20
start_keyO startKey da página anteriorNãoPrimeira 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"
  }
}
  • users associa 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, como role::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, e startKey. Chame nextLink, ou envie startKey como start_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.

CampoO que fazObrigatórioPadrão
ref_idO 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.—
titleO nome do caso, mostrado para todos.Sim, ao criar.—
descriptionUma descrição para o pessoal. Os clientes não veem isso. Em uma mudança, "" apaga essa informação.NãoNenhum
case_typegeneral, 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ãogeneral
case_status1 para aberto, 0 para fechado.Não1
case_stageO 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ãoNenhuma fase
date_openedA data em que o caso foi iniciado, como 2026-03-15NãoHoje, no fuso horário UTC
hidden_modulesSeçõ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ãoNenhum escondido.
meta_dataSeus campos personalizados… Veja abaixo.NãoNenhum

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_data substitui 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

StatusmessagePor que
400SchemaFieldsExceptionO campo está ausente ou inválido; o nome do campo é errors. Um tipo de caso ou estágio desconhecido está associado ao campo FieldValidatorFailedException.
400CaseReferenceIdExistsExceptionHá 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.
404ItemNotFoundExceptionO caso não existe. Ele pertence a outro hub ou está sendo apagado.
403ManageBillingInactiveExceptionO 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.

Artigos relacionados

Adicione e remova membros do caso com uma chave de gerenciamento.Atribua funções e designações às pessoas responsáveis pelos casos, envie o e-mail de convite, verifique quem está alocado a um caso ou remova alguém da equipe.IntegraçõesPesquise casos e usuários com uma chave de gerenciamento.Encontre casos, pessoas, membros do caso, funções e importe linhas por texto, com filtros, a partir do seu próprio software.IntegraçõesLidar 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