Centro assistenzaIntegrazioni

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

ChiamataCosa fa
GET /forms/templatesElenca i modelli di formulari presenti nel sistema.
POST /formsViene creato un modulo relativo al caso in questione; tale modulo non è ancora pubblicato.
PUT /forms/<form_id>/publishLo pubblica, in modo che possa essere inviato ai destinatari.
GET /forms?filter=allElenca 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>/responsesElenca 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:

CampoCosa faNecessarioPredefinito
nameIl 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_idsLe 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
descriptionUna nota presente insieme al moduloNo.Il modello/template…
notificationsSuggerimenti: {"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_notifyfalse 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_notify non sia uguale a false.
  • 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"
  }
}
  • formFieldValues contiene i dati inseriti dalla persona per ciascun campo, indicati tramite i valori name corrispondenti a ciascun campo. Una firma o un disegno viene invece indicato tramite i valori annotations e attachments.
  • Il valore letto dal form è in grado di indicare chi ha risposto: responses associa l’ID dell’utente di ciascuna persona al relativo response_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.

filterCosa elenca
allOgni forma di questo caso, comprese quelle inedite, presentate in ordine di priorità cronologica.
selfIl assistente virtuale viene inviato tramite qualsiasi delle tue chiavi, oppure tramite automatismi.
completed, uncompletedI 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

StatomessagePerché
400SchemaFieldsExceptionC’è 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.
400SchemaFieldsException, con ItemCopyNotAllowedException a templateIl modello non è pubblicato, non è accessibile ai robot, oppure i suoi file sono ancora in fase di elaborazione.
403PublishAlreadyPublishedExceptionÈ già stato pubblicato.
403PublishAlreadyAnsweredExceptionQualcuno l’ha già risposto.
403PublishMediaMissingExceptionNon esiste ancora alcun documento relativo a questo argomento.
403PublishMediaNotReadyExceptionIl suo documento è ancora in fase di copiatura o conversione.
403PublishMediaFailedExceptionIl suo documento non è riuscito a essere convertito.
403PublishDueTimePassedExceptionLa data di scadenza è già passata.
403PublishRecipientsMissingExceptionNon ha nessuno a cui possa essere inviato.
403BotNotAllowedExceptionUna chiave cercava di completare il tutto.
403CaseClosedExceptionIl caso è chiuso.
404ItemNotFoundExceptionLa 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.

Articoli correlati

Comprendere cosa può fare l'APIScopri quali funzioni possono svolgere un tasto di gestione e un tasto hub, perché ogni tasto funge da Assistente Virtuale e dove trovare l'elenco tecnico completo.IntegrazioniInvia firme elettroniche e leggi le firme con una chiave hubCrea una firma elettronica per una pratica utilizzando un modello, scegli chi firma ciascun campo, pubblicala per la firma e scarica la copia protetta una volta che tutti hanno firmato.IntegrazioniCarica e allega file con una chiave hubOttieni un indirizzo di caricamento, carica un file, allegalo a un post, una nota, un'attività, un modulo o firma elettronicamente e scarica i file di un caso.IntegrazioniGestire gli errori e i codici di stato delle APILeggi il corpo dell'errore, cosa significano i codici 400, 401, 403, 404, 500 e 503 e perché un elemento che la tua chiave non riesce a vedere risponde al codice 404.Integrazioni