Per: Amministratori
Invia moduli e leggi le risposte con una chiave hub
Crea un modulo per un caso utilizzando un modello, pubblicalo per le persone che devono compilarlo e leggi le loro risposte.
In questo articolo7 sezioni
Prima di iniziare
Questa pagina riguarda il invio di moduli e la lettura delle loro risposte, utilizzando una chiave per gestire i processi di invio e lettura dei dati. I percorsi per eseguire tali operazioni sono indicati sotto https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Chiamate
| Chiamata | Cosa fa |
|---|---|
GET /forms/templates | Elenca i modelli di formulari presenti nel sistema. |
POST /forms | Viene creato un modulo relativo al caso in questione; tale modulo non è ancora pubblicato. |
PUT /forms/<form_id>/publish | Lo pubblica, in modo che possa essere inviato ai destinatari. |
GET /forms?filter=all | Elenca le forme del caso. |
GET /forms/<form_id> | Leggi un modulo. |
PUT /forms/<form_id> | Cambia il nome, la data di scadenza, le notifiche o i destinatari delle informazioni. |
DELETE /forms/<form_id> | Eliminatelo, insieme alle risposte relative a esso. |
GET /forms/<form_id>/responses | Elenca le risposte. |
GET /forms/<form_id>/responses/<response_id> | Leggi una risposta. |
DELETE /forms/<form_id>/responses/<response_id> | Elimina la risposta di una persona, in modo che possa inserire nuovamente la propria risposta. |
La creazione di un modulo avviene in due fasi: prima si crea il modulo, poi si pubblica. Fino a quando il modulo non viene pubblicato, i destinatari non lo vedono, e nessuno ne è informato.
Creazione di un modulo
GET /forms/templates Elenca il tuo formato pubblicato. ModelliModello Un feed riutilizzabile, un modulo, una firma elettronica, una nota o un'attività conservati nella Biblioteca e copiati sui casi., Prima quelli più vecchi, e poi tutti gli altri. asset_id, title, description, due_mins Quanti minuti passano da quando il messaggio viene inviato fino al momento in cui arriva a destinazione? rrule (Ripetizione dello stesso contenuto.) notifications E… instant_notify.
POST /forms accetta i seguenti valori:
| Campo | Cosa fa | Necessario | Predefinito |
|---|---|---|---|
name | Il titolo del modulo. Lettere, numeri, spazi e & ' - _ ( ) . /; nessun virgola o punto e virgola. | Sì. | – |
duration | {"due_date": "2026-10-09T17:00:00-04:00", "rrule": "FREQ=MONTHLY"}. La data di scadenza deve essere corrispondente al fuso orario appropriato. rrule, Una regola di ripetizione è opzionale. zoneinfo, Il fuso orario in cui avviene la ripetizione, ad esempio… America/New_York, È opzionale: senza di esso, il fuso orario del proprio dispositivo viene mantenuto, nel momento e nel giorno in cui avviene il cambio di fuso orario. | Sì. | – |
participants_ids | Le persone che compilano questi dati sono le identificazioni degli utenti coinvolti nel caso, provenienti da GET /team. | No, ma era necessario pubblicarlo. | Nessuno |
template | {"owner": "host", "template_id": "<asset_id>"} Per utilizzare il documento di un modello. | No. | Nessuno |
description | Una nota presente insieme al modulo | No. | Il modello/template… |
notifications | Suggerimenti: {"names": ["days", "hours"], "values": [-1440, -60]}. Ogni valore indica il numero di minuti che mancano alla data di scadenza. | No. | Il modello… o niente. |
instant_notify | false Non vengono inviati alcun messaggi durante il processo di pubblicazione; vengono soltanto inviati gli avvisi necessari. | No. | Il modello, o true |
Un template include il documento, la descrizione, i reminder e instant_notify. Tuttavia, non include l’ora di scadenza né le informazioni riguardanti le ripetizioni. È necessario calcolare l’due_date partendo da due_mins. Inoltre, è necessario inviare l’rrule del documento, se ce ne è uno.
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"}}'
Risponde a 201 con form_id. Il documento del template viene copiato in background: si legge il form fino a quando non rimangono più copying presenti; poi il documento viene pubblicato.
Per inviare il proprio documento, è necessario creare il modulo senza l’elemento template. Successivamente, è possibile caricare un PDF come documento da inviare. Aspetti che il processo sia completato… Si veda la sezione [Caricare e allegare file utilizzando una chiave hub](admin/integration/api/attach-files-with-a-hub-key).
Blog
PUT /forms/<form_id>/publish non assume alcun corpo e restituisce 200.
- A ogni destinatario viene inviato un’e-mail con l’invito a compilare il modulo, oppure viene inviato un messaggio di testo, nel caso in cui non abbia un indirizzo e-mail confermato. Questo avviene immediatamente, a meno che…
instant_notifyÈfalse. Sembra che appaia tra le loro cose. Cosa fareFare L'elenco delle cose che ti aspettano, come moduli da compilare, documenti da firmare o eventi da confermare. E anche nelle notifiche presenti nel loro portale. - I messaggi di ricordo vengono inviati ogni volta entro l’orario previsto, cioè entro
notifications. Nessun messaggio viene inviato in tempo utile, e le risposte vengono accettate solo dopo quel termine. - Una forma ripetitiva si sposta alla sua prossima data di scadenza, in ogni caso. Le risposte sono chiare, e tutti coloro che compongono quella forma vengono chiamati di nuovo, a meno che
instant_notifynon sia uguale afalse. - Chiunque sia escluso dalla lista dei partecipanti viene eliminato dal formulario.
Il documento non può essere modificato una volta che il modulo viene pubblicato. Il nome del documento, la data di scadenza, i reminder, i destinatari e la descrizione possono essere modificati. Con PUT /forms/<form_id> si può inviare un messaggio di ripetizione, senza utilizzare zoneinfo; in questo modo, il fuso orario del documento viene mantenuto. Se si modifica la data di scadenza, i reminder vengono inviati nuovamente a tutti coloro che non hanno ancora risposto. Le persone aggiunte vengono contattate immediatamente. Con instant_notify e false, entrambi i messaggi vengono inviati, ma senza alcun effetto particolare.
Risposte di lettura
GET /forms/<form_id>/responses elenca le risposte di ciascun individuo, in ordine decrescente di età, tutte su una sola pagina. Una forma di elenco che si ripete indica soltanto le risposte relative alla data attuale; le risposte relative a date precedenti vengono comunque visualizzate grazie al 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"
}
}
formFieldValuescontiene i dati inseriti dalla persona per ciascun campo, indicati tramite i valorinamecorrispondenti a ciascun campo. Una firma o un disegno viene invece indicato tramite i valoriannotationseattachments.- Il valore letto dal form è in grado di indicare chi ha risposto:
responsesassocia l’ID dell’utente di ciascuna persona al relativoresponse_id. - Quando qualcuno invia il modulo, il personale incaricato del caso viene informato, proprio come se fosse stato lui stesso a inviare il modulo.
Eliminare la risposta di una persona, utilizzando il codice {"user_id": "<their ID>"} come corpo della risposta stessa, fa sì che il modulo torni nella lista delle cose da fare di quella persona. Nessuno viene informato di questo cambiamento. Una chiave non può inserire da sola i dati nel modulo.
moduli di inserzione
GET /forms richiede filter.
filter | Cosa elenca |
|---|---|
all | Ogni forma di questo caso, comprese quelle inedite, presentate in ordine di priorità cronologica. |
self | Il assistente virtuale viene inviato tramite qualsiasi delle tue chiavi, oppure tramite automatismi. |
completed, uncompleted | I moduli che il chiamante deve compilare sono sempre vuoti per una chiave. |
Ogni forma contiene i valori form_id, name, participants_ids, due_date, published (e 1, una volta pubblicato), responses, responses_ct, nonché il documento corrispondente, che è indicato con media.
DELETE /forms/<form_id> può eliminare un modulo in qualsiasi momento, insieme alle relative risposte, e lo rimuove da tutti gli elenchi delle cose da fare. Nessuno viene informato di questo.
Se una chiamata viene rifiutata
| Stato | message | Perché |
|---|---|---|
| 400 | SchemaFieldsException | C’è un campo che è mancante o non valido: ad esempio, una virgola presente in name, una data di scadenza senza eventuale spostamento temporale, oppure una persona che non fa parte del gruppo di persone coinvolte nel caso. errors indica il nome di quella persona. |
| 400 | SchemaFieldsException, con ItemCopyNotAllowedException a template | Il modello non è pubblicato, non è accessibile ai robot, oppure i suoi file sono ancora in fase di elaborazione. |
| 403 | PublishAlreadyPublishedException | È già stato pubblicato. |
| 403 | PublishAlreadyAnsweredException | Qualcuno l’ha già risposto. |
| 403 | PublishMediaMissingException | Non esiste ancora alcun documento relativo a questo argomento. |
| 403 | PublishMediaNotReadyException | Il suo documento è ancora in fase di copiatura o conversione. |
| 403 | PublishMediaFailedException | Il suo documento non è riuscito a essere convertito. |
| 403 | PublishDueTimePassedException | La data di scadenza è già passata. |
| 403 | PublishRecipientsMissingException | Non ha nessuno a cui possa essere inviato. |
| 403 | BotNotAllowedException | Una chiave cercava di completare il tutto. |
| 403 | CaseClosedException | Il caso è chiuso. |
| 404 | ItemNotFoundException | La forma o la risposta in questione non esistono. |
Per informazioni sul corpo dell’errore e sugli altri codici, si veda Comunicare gli errori dell’API e i codici di stato.