Para: Administradores
Adicione notas aos casos com uma chave central.
Crie anotações internas sobre um caso a partir do seu próprio software, forneça um documento e arquivos e escolha quais funções podem visualizá-los.
Neste artigo7 seções
Antes de começar
Esta página explica como adicionar e ler as notasNotas Anotações internas sobre um caso que só podem ser vistas por pessoas cujas funções permitem; os clientes não podem vê-las a menos que a empresa altere essa política. de um caso, utilizando uma chave de hub. Os caminhos estão indicados em https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Chamadas
| Chamar | O que faz |
|---|---|
GET /notes/templates | Lista dos seus modelos de notas |
POST /notes | Cria uma nota. |
GET /notes | Lista as notas relacionadas ao caso, com os dados mais recentes em primeiro lugar. |
GET /notes/<note_id> | Lê uma nota. |
PUT /notes/<note_id> | Modifica o título de uma nota ou quem a visualiza. |
DELETE /notes/<note_id> | Apaga uma nota, juntamente com os seus arquivos. |
Uma nota é um documento mantido em um caso específico, para a sua equipe. Inclui todos os arquivos relacionados a ela. O conteúdo da nota é o próprio documento: pode-se começar com um modelo pré-definido, ou carregar um arquivo PDF ou Word assim que a nota estiver pronta. Não há campo de texto para inserção de textos. Ninguém sabe quando uma nota é adicionada ou alterada. Além disso, as notas não enviam webhooks.
Criar uma nota
| Campo | O que faz | Obrigatório | Padrão |
|---|---|---|---|
name | O título da nota. Letras, números, espaços e & ' - _ ( ) . /; sem vírgulas, pontos e marcas de interrogação ou aspas. | Sim | — |
permissions | Os rolesFunção Um conjunto de permissões que define o que alguém pode ver e fazer em um caso, como funcionários ou clientes. que podem visualizá-lo, como por exemplo ["role::staff"]. Apenas os roles que têm permissão para ler as notas. | Não | As funções do modelo, ou todas as funções que podem ler as notas. |
template | De {"owner": "host", "template_id": "<asset_id>"} para GET /notes/templates, com o objetivo de trazer o documento e os arquivos do modelo. Ou então, de {"owner": "case", "template_id": "<note_id>"} para copiar uma nota sobre esse caso. | Não | Nenhum |
curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/notes \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Case representation letter", "permissions": ["role::staff"], "template": {"owner": "host", "template_id": "note::20260915101500_5e4d3c2b1a0f90"}}'
Ele responde a 201 com note_id.
- A partir de um modelo, a nota recebe o documento do modelo, os arquivos e as funções associadas ao modelo. Os códigos, como o nome do cliente, são preenchidos uma vez, quando a nota é criada. Os códigos relacionados à pessoa que criou a nota, como o nome dela, utilizam as informações do Assistente Virtual, que também inclui o nome da sua empresa. O título da nota não é copiado: basta enviar
name. - Uma cópia de uma nota sobre esse caso também mantém tudo o que foi digitado ou desenhado nela, a menos que você envie
schemapara substituir esses dados. Os códigos são preenchidos novamente, desde o momento em que a cópia é feita. - Sem um modelo pronto, carregue o seu documento da seguinte maneira: solicite um endereço com
media_group=schemas, carregue um arquivo PDF ou Word, e anexe-o comPUT /notes/<note_id>/schema/media. Um arquivo Word é convertido em PDF. Uma nota contém apenas um documento. Veja Carregar e anexar arquivos usando a chave do hub. - Outros arquivos, como fotos ou gravações, devem ser anexados com
PUT /notes/<note_id>/media.
Quem vê isso
As pessoas que ocupam os papéis relacionados às notas podem abri-las. Os funcionários, cujo papel é o de moderar as notas por padrão, conseguem visualizar todas as notas, independentemente do seu papel. Os clientes não conseguem ver as notas, a menos que um administrador tenha concedido aos clientes acesso às mesmas. Para saber mais sobre o que cada papel permite, veja Como um papel pode ser configurado.
Anotações de leitura
GET /notes recebe como parâmetros limit (padrão: 20; até 1000), start_key, e também as páginas, como em qualquer lista. Uma chave é utilizada para identificar cada nota no caso. Cada nota contém:
| Campo | O que contém |
|---|---|
note_id, case_id | Seus IDs |
name | Seu título |
user_id | Quem criou isso? A identificação do Assistente Virtual para as notas… ou será que foi uma automação que fez isso? |
permissions | Os papéis que podem ser vistos… Foram deixados de fora, quando todos os papéis que podem ler as notas puderam vê-los. |
schema_media | O media_id do seu documento |
media, media_ct | Seus documentos e arquivos… quantos são eles? Baixe-os da forma indicada em “Carregar e anexar arquivos com a chave do hub”. |
schema | O que as pessoas digitaram ou desenharam no documento, em formato Instant JSON. |
template_id | O modelo a partir do qual o texto foi criado |
created_on, updated_on | Quando foi criado e última vez modificado, no fuso horário UTC. |
GET /notes/templates lista as suas notas publicadas, organizadas em modelosModelo Um formulário, postagem, assinatura eletrônica, nota ou tarefa reutilizável, armazenado na Biblioteca e copiado para as pastas.. Os modelos são apresentados, em ordem decrescente de data de publicação. Cada modelo inclui informações sobre os parâmetros asset_id, title, description e permissions.
Alterar e excluir
PUT /notes/<note_id> recebe name e permissions. Ele altera apenas aqueles valores que você fornece. Um “key” pode alterar qualquer nota no caso. Uma lista vazia de permissions é rejeitada: seja necessário enviar os valores que devem ser exibidos nessa lista. Um corpo sem esses valores também é rejeitado.
DELETE /notes/<note_id> apaga todas as notas, juntamente com o documento e os arquivos relacionados. Ninguém é informado sobre isso.
Se uma chamada for recusada
| Status | message | Por que |
|---|---|---|
| 400 | SchemaFieldsException | O campo está ausente ou inválido. Por exemplo, pode haver uma vírgula em name, uma lista vazia em permissions, ou o rolê não existe no seu hub. errors indica os nomes dos campos. |
| 400 | SchemaFieldsException, com ItemCopyNotAllowedException em template | O modelo não foi publicado, não está disponível para o papel dos bots, ou seus arquivos ainda estão sendo processados. |
| 400 | SchemaFieldsException, com NoteRoleCannotReadNotesException em permissions.<n> | O valor em permissions não pode ser lido. |
| 403 | HostModuleDisabledException | As notas estão desativadas para o seu hub, ou escondidas neste caso. |
| 403 | CaseClosedException | O caso foi encerrado. |
| 404 | ItemNotFoundException | A nota não existe. |
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.