Para: Administradores
Envie formulários e leia respostas com uma chave central.
Crie um formulário sobre um caso a partir de um modelo, publique-o para as pessoas que devem preenchê-lo e leia as respostas delas.
Neste artigo7 seções
Antes de começar
Esta página aborda o envio de formulários e a leitura das respostas deles, 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 /forms/templates | Lista dos seus modelos de formulários |
POST /forms | Cria um formulário para o caso, que ainda não foi publicado. |
PUT /forms/<form_id>/publish | Publica-o, e assim o envia aos destinatários. |
GET /forms?filter=all | Lista as formas do caso. |
GET /forms/<form_id> | Lê um formulário |
PUT /forms/<form_id> | Modifica o nome, a data de vencimento, os lembretes ou os destinatários. |
DELETE /forms/<form_id> | Apague-o, junto com as respostas relacionadas a ele. |
GET /forms/<form_id>/responses | Lista de suas respostas |
GET /forms/<form_id>/responses/<response_id> | Lê uma das respostas. |
DELETE /forms/<form_id>/responses/<response_id> | Apaga a resposta de uma pessoa, para que ela possa preencher o espaço novamente. |
O formulário é criado em dois passos: primeiro, ele é criado; depois, é publicado. Até que seja publicado, os destinatários não conseguem ver o formulário, e ninguém fica sabendo disso.
Criar um formulário
GET /forms/templates Lista do seu formato publicado Modelos/FormuláriosModelo Um formulário, postagem, assinatura eletrônica, nota ou tarefa reutilizável, armazenado na Biblioteca e copiado para as pastas., Os mais antigos primeiro, sendo cada um deles… asset_id, title, description, due_mins (Quantos minutos após o envio do documento, ele estará pronto para ser entregue?) rrule (Suas repetições) notifications E… instant_notify.
POST /forms aceita os seguintes valores:
| Campo | O que faz | Obrigatório | Padrão |
|---|---|---|---|
name | O título do formulário. Letras, números, espaços e & ' - _ ( ) . /; sem vírgulas ou hífenes. | Sim | — |
duration | {"due_date": "2026-10-09T17:00:00-04:00", "rrule": "FREQ=MONTHLY"}. A data de vencimento precisa ter o deslocamento do fuso horário correspondente. rrule, uma regra de repetição, é opcional. zoneinfo, o fuso horário em que a repetição ocorre, como America/New_York, também é opcional. Sem essa informação, a repetição manterá o fuso horário do seu dispositivo, no mesmo horário e no dia em que ocorre a mudança de hora. | Sim | — |
participants_ids | As pessoas que preenchem esses dados são os IDs de usuário das pessoas envolvidas no caso, com valor começando por GET /team. | Não, mas era necessário publicá-lo. | Ninguém |
template | {"owner": "host", "template_id": "<asset_id>"} Para usar o documento de um modelo. | Não | Nenhum |
description | Uma nota anexada ao formulário | Não | O modelo utilizado… |
notifications | Lembrâncias: {"names": ["days", "hours"], "values": [-1440, -60]}. Cada valor indica o número de minutos restantes até a data de vencimento. | Não | O modelo, ou nada. |
instant_notify | false Não enviar nenhum pedido durante o processo de publicação. Apenas os lembretes serão enviados. | Não | O modelo, ou true |
O modelo inclui o documento, a descrição, as lembranças e o parágrafo instant_notify. No entanto, não inclui a data de vencimento ou informações sobre repetição. É necessário calcular o valor de due_date a partir de due_mins. Se houver algum parágrafo rrule, então deve-se enviá-lo.
curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Case intake form", "duration": {"due_date": "2026-10-09T17:00:00-04:00"}, "participants_ids": ["cu-4f1c2a9e8b7d60"], "template": {"owner": "host", "template_id": "form::20260915101500_3c2b1a0f9e8d70"}}'
Isso responde a 201 com form_id. O documento do modelo é copiado em segundo plano: leia o formulário até que não haja mais copying, e então publique-o.
Para enviar o seu próprio documento, crie o formulário sem o elemento template. Carregue um PDF como o documento e aguarde até que este esteja pronto. Veja Carregar e anexar arquivos usando uma chave de hub.
Publicação
PUT /forms/<form_id>/publish não recebe nenhum corpo e responde a 200.
- Cada destinatário recebe um e-mail com um pedido para preencher o formulário. Caso não tenha um endereço de e-mail confirmado, ele também recebe uma mensagem de texto imediatamente.
instant_notifyÉfalse. Ele aparece nelas. O que precisa ser feitoFaçam A lista em uma maleta contém coisas que você precisa fazer, como formulários para preencher, documentos para assinar ou eventos para confirmar. E também nas notificações do seu portal. - Os lembretes são enviados a cada vez, em
notifications, ainda antes do prazo estipulado. Nada é enviado no momento certo, e as respostas só são aceitas depois disso. - A forma de repetição avança para a sua próxima data de vencimento, em cada um dos casos. As respostas são claras, e todos os participantes são questionados novamente, a menos que
instant_notifyseja igual afalse. - Alguém que está fora do caso é excluído da lista.
O documento não pode ser alterado uma vez que o formulário é publicado. O nome do documento, a data de vencimento, os lembretes, os destinatários e a descrição do documento podem ser modificados. Com PUT /forms/<form_id>, um envio repetido sem zoneinfo mantém o fuso horário atual do documento. Ao alterar a data de vencimento, os lembretes são enviados novamente para todos aqueles que ainda não responderam. As pessoas que você adiciona também recebem o documento imediatamente. Com instant_notify e false, nenhum dos elementos é enviado até que os lembretes sejam ativados.
Respostas de leitura
GET /forms/<form_id>/responses lista a resposta de cada pessoa, com as mais antigas em primeiro lugar. Um formulário repetitivo listará apenas as respostas da data atual; as respostas de datas anteriores continuarão sendo exibidas pelo seu response_id.
{
"data": {
"items": [
{
"response_id": "response::20261003153012_9f8e7d6c5b4a30",
"parent_id": "form::20261002150000_1a2b3c4d5e6f70",
"user_id": "cu-4f1c2a9e8b7d60",
"created_on": "2026-10-03T15:30:12+00:00",
"response": {
"format": "https://pspdfkit.com/instant-json/v1",
"formFieldValues": [
{"v": 1, "type": "pspdfkit/form-field-value", "name": "client_name", "value": "Jane Sample"},
{"v": 1, "type": "pspdfkit/form-field-value", "name": "accident_date", "value": "2026-09-14"}
]
}
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/forms/form::20261002150000_1a2b3c4d5e6f70/responses"
}
}
formFieldValuesarmazena cada campo que a pessoa preencheu, de acordo com os valores definidos no campo correspondentename. Uma assinatura ou desenho está incluído nos camposannotationseattachments.- A leitura feita pelo próprio formulário indica quem foi o responsável pela resposta:
responsesassocia o ID do usuário de cada pessoa ao seuresponse_id. - Quando alguém envia o documento, os funcionários responsáveis pelo caso são informados, da mesma forma que se tivessem enviado o documento por conta própria.
Apagar a resposta de uma pessoa, utilizando o {"user_id": "<their ID>"} como corpo da mensagem, faz com que o formulário volte para a lista de tarefas daquela pessoa. Ninguém é informado sobre isso. Uma chave não pode preencher um formulário por conta própria.
Formulários de listagem
GET /forms precisa de filter.
filter | O que está listado |
|---|---|
all | Todas as formas apresentadas no caso, incluindo aquelas que ainda não foram publicadas, são listadas, com as mais recentes em primeiro lugar. |
self | O assistente virtual é enviado por qualquer um dos seus dispositivos, ou por meio de automações. |
completed, uncompleted | Os formulários que o chamante foi solicitado a preencher estão sempre vazios. |
Cada formulário contém seus valores form_id, name, participants_ids, due_date, published (e 1, uma vez publicado), responses, responses_ct, além do documento associado a cada formulário, que está localizado em media.
DELETE /forms/<form_id> pode excluir um formulário a qualquer momento, juntamente com as respostas dele. Além disso, o formulário é removido da lista de tarefas de todos. 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, ou a data de vencimento não possui um deslocamento, ou ainda, pode haver alguém que não está relacionado ao caso em questão. errors indica o nome do campo. |
| 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. |
| 403 | PublishAlreadyPublishedException | Já foi publicado. |
| 403 | PublishAlreadyAnsweredException | Alguém já respondeu a essa pergunta. |
| 403 | PublishMediaMissingException | Ainda não tem nenhum documento relacionado a isso. |
| 403 | PublishMediaNotReadyException | Seu documento ainda está sendo copiado ou convertido. |
| 403 | PublishMediaFailedException | Seu documento não conseguiu ser convertido. |
| 403 | PublishDueTimePassedException | A data de vencimento já passou. |
| 403 | PublishRecipientsMissingException | Não tem ninguém para quem possa enviá-lo. |
| 403 | BotNotAllowedException | Uma chave tentou preencher o espaço vazio. |
| 403 | CaseClosedException | O caso foi encerrado. |
| 404 | ItemNotFoundException | O formulário ou a resposta em questão 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.