Per: Amministratori
Invia firme elettroniche e leggi le firme con una chiave hub
Crea 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.
In questo articolo9 sezioni
Prima di iniziare
Questa pagina tratta il invio di e-segniFirma elettronica Un documento inviato per la firma elettronica, firmato direttamente nel browser. e l’uso di una chiave per autenticare tali segni. I percorsi utilizzati sono indicati sotto https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.
Chiamate
| Chiamata | Cosa fa |
|---|---|
GET /signs/templates | Elenca le tue schede di firma elettronica. |
POST /signs | Viene creata una firma elettronica per il caso in questione; tale firma non è ancora stata pubblicata. |
PUT /signs/<sign_id>/schema | Si sceglie chi firmerà ciascun campo. |
PUT /signs/<sign_id> | Si modifica il nome, la data di scadenza o le notifiche relative all’oggetto del messaggio, prima della sua pubblicazione. |
PUT /signs/<sign_id>/publish | Lo pubblica, e così lo invia ai suoi firmatari. |
GET /signs?filter=all | Elenca i documenti elettronici relativi al caso in questione. |
GET /signs/<sign_id> | Leggo un documento elettronico, con il relativo stato di avanzamento. |
DELETE /signs/<sign_id> | Lo elimina, insieme ai suoi “sigilli”. |
GET /signs/<sign_id>/responses | Elenca le sue firme. |
GET /signs/<sign_id>/responses/<response_id> | Leggi una firma. |
Un documento elettronico viene pubblicato in tre fasi: prima si crea il documento, poi si verifica chi firma ciascun campo del documento stesso, e infine il documento viene pubblicato. Fino alla pubblicazione, i firmatari non possono vedere il documento, e nessuno ne è a conoscenza. Una volta pubblicato, non è possibile modificare alcun dettaglio relativo al documento.
Creazione di una firma elettronica
GET /signs/templates elenca le tue templateModello Un feed riutilizzabile, un modulo, una firma elettronica, una nota o un'attività conservati nella Biblioteca e copiati sui casi. di firma elettronica pubblicate. Le template sono ordinate in ordine decrescente di età; per ciascuna di esse vengono indicati i valori di asset_id, title, description, due_mins (il numero di minuti che trascorrono dal momento in cui la firma viene inviata), notifications e role_field_participants. Inoltre, vengono indicati i ruoli che sono incaricati di firmare ciascun campo.
POST /signs accetta i seguenti valori:
| Campo | Cosa fa | Necessario | Predefinito |
|---|---|---|---|
name | Il titolo del documento elettronico è composto da lettere, numeri, spazi e il simbolo & ' - _ ( ) . /. Non ci sono virgole né punti e virgola. | Sì. | – |
duration | {"due_date": "2026-10-09T17:00:00-04:00"}, con il relativo fuso orario. I documenti elettronici non possono essere ripetuti: è vietato creare copie di un documento già esistente. | Sì. | – |
template | {"owner": "host", "template_id": "<asset_id>"} Per utilizzare il documento e i firmatari di un modello. | No. | Nessuno |
description | Una nota visualizzata tramite il formato elettronico. | No. | Il modello/template… |
notifications | Suggerimenti: {"names": ["days"], "values": [-1440]}. 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 |
curl -X POST https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/signs \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Retainer Agreement", "duration": {"due_date": "2026-10-09T17:00:00-04:00"}, "template": {"owner": "host", "template_id": "sign::20260915101500_7a6b5c4d3e2f10"}}'
Risponde a 201 con sign_id. Il documento del template viene copiato in background: si legge il contenuto fino a quando non rimangono più copying presenti nel testo.
Per inviare il proprio PDF, è necessario creare l’e-signature senza l’elemento template. Successivamente, caricate il PDF come documento e aspettate che sia pronto. Dopodiché, assegnate i relativi campi al documento stesso. Per ulteriori informazioni, consultate la sezione Caricare e allegare file utilizzando una chiave hub.
Scegliere chi firma
Da un modello, ogni campo viene assegnato alle persone coinvolte nel caso, che ricoprono i ruoli necessari per la creazione della firma elettronica. Quindi, è necessario inserire il cliente nel caso prima di procedere con la firma elettronica. Il field_participants indica il risultato: il nome di ogni campo, insieme alle identificazioni degli utenti che effettuano la firma.
Per modificarlo, inviare l’intera mappa a PUT /signs/<sign_id>/schema:
{"field_participants": {"Client Signature": ["cu-4f1c2a9e8b7d60"], "Attorney Signature": ["cu-9d8c7b6a5f4e30"]}}
- Ogni identità deve essere rappresentata da una persona che lavori direttamente sul caso in questione. L’assistente virtuale non può firmare i documenti necessari per svolgere il proprio ruolo.
- I nomi dei campi sono quelli presenti nel documento stesso.
- La mappa sostituisce quella vecchia: i campi che vengono lasciati vuoti non hanno alcun segno di identificazione.
Blog
PUT /signs/<sign_id>/publish non assume alcun corpo e restituisce 200. Almeno un campo deve avere un “signatore”; un campo senza “signatore” rimane vuoto.
- A ogni firmatario viene inviata via e-mail la richiesta di firmare, oppure si riceve un messaggio di testo, nel caso in cui non abbia un indirizzo e-mail verificato. 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 avviso vengono inviati ogni volta, entro l’orario indicato in
notifications. Questi messaggi continueranno ad essere inviati fino a quando le persone non firmeranno i documenti necessari. - Qualcuno che si trova lontano dal caso, smette di tenere quel oggetto in mano.
A seguito delle firme
Il documento elettronico/ digitale status Leggi completed Una volta che tutti hanno firmato, e… completed_on Indica quando, nel fuso orario UTC, ciò accadrà. 2026-10-06T21:42:10.123456+00:00. Fino ad ora, non ne ha nessuno. responses Ogni firmatario che ha firmato il documento viene associato a una specifica mappa. response_id.
GET /signs/<sign_id>/responses Vengono elencate le firme di ogni firmatario, con il nome più antico in cima a ogni firma. Tutte le firme sono riportate su una sola pagina. user_id, Quando hanno firmato, hanno compilato i campi previsti per l’invio dei dati. response.formFieldValues, Sottoscrivono sotto il documento in questione. response.annotations, Con qualsiasi immagine di firma sottostante. response.attachments, E l’indirizzo IP da cui hanno ricevuto il sigillo. response.ip.
Al personale incaricato del caso viene detto ogni volta che qualcuno firma il documento; inoltre, quando la copia firmata è pronta, viene informato anche chi ha firmato il documento stesso. A tutti coloro che hanno firmato il documento viene comunicato anche il momento in cui la copia firmata è pronta.
La copia bloccata
Una volta che tutti hanno firmato, viene creata una copia del documento, contenente ogni singola firma. L’elemento “media.schemas.items” del documento riceve il valore “flat”; il percorso della copia, invece, è flat_status, SUCCEEDED o FAILED. È possibile scaricare il documento in qualsiasi formato; per ulteriori informazioni, vedere Caricare e allegare file utilizzando una chiave di hub.
Elenco e cancellazione
GET /signs richiede l’uso di filter: all elenca tutti i documenti elettronici presenti nel caso, compresi quelli non pubblicati. I documenti più recenti vengono elencati per primo. self elenca invece quelli inviati dall’Assistente Virtuale, sia tramite le tue chiavi personali, sia tramite automatismi. completed e uncompleted elencano invece i documenti inviati dal chiamante stesso; quindi, per una determinata chiave, questi elementi sono sempre vuoti. È meglio verificare i valori di status e completed_on per ogni documento elettronico.
DELETE /signs/<sign_id> può eliminare qualsiasi firma elettronica in qualsiasi momento, rimuovendola da tutti i listati “Da fare”. Nessuno viene informato di ciò.
Se una chiamata viene rifiutata
| Stato | message | Perché |
|---|---|---|
| 400 | SchemaFieldsException | Il campo è mancante o non valido: ad esempio, potrebbe esserci una virgola nel campo name, oppure potrebbe esserci una regola di ripetizione errata. Inoltre, potrebbe esserci un firmatario che non fa parte del caso in questione; il campo errors indica proprio questo firmatario. |
| 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, quindi non può essere modificato. |
| 403 | PublishAlreadyAnsweredException | Qualcuno l’ha già firmato. |
| 403 | PublishParticipantsMissingException | Nessun campo presenta un simbolo di firma. |
| 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 | PublishDocumentUnreadableException | Il suo documento non può essere letto: è necessario eliminare il file digitale e crearne uno nuovo. |
| 403 | PublishDueTimePassedException | La data di scadenza è già passata. |
| 403 | BotNotAllowedException | Qualcuno ha cercato di firmare il documento, oppure di cancellare la firma di qualcun altro. |
| 403 | CaseClosedException | Il caso è chiuso. |
| 404 | ItemNotFoundException | La firma elettronica o il segno di firma non esistono. |
Per informazioni sul corpo dell’errore e sugli altri codici, si veda Comunicare gli errori dell’API e i codici di stato.