Centro assistenzaIntegrazioni

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

ChiamataCosa fa
GET /signs/templatesElenca le tue schede di firma elettronica.
POST /signsViene creata una firma elettronica per il caso in questione; tale firma non è ancora stata pubblicata.
PUT /signs/<sign_id>/schemaSi 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>/publishLo pubblica, e così lo invia ai suoi firmatari.
GET /signs?filter=allElenca 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>/responsesElenca 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:

CampoCosa faNecessarioPredefinito
nameIl 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
descriptionUna nota visualizzata tramite il formato elettronico.No.Il modello/template…
notificationsSuggerimenti: {"names": ["days"], "values": [-1440]}. 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
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

StatomessagePerché
400SchemaFieldsExceptionIl 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.
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, quindi non può essere modificato.
403PublishAlreadyAnsweredExceptionQualcuno l’ha già firmato.
403PublishParticipantsMissingExceptionNessun campo presenta un simbolo di firma.
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.
403PublishDocumentUnreadableExceptionIl suo documento non può essere letto: è necessario eliminare il file digitale e crearne uno nuovo.
403PublishDueTimePassedExceptionLa data di scadenza è già passata.
403BotNotAllowedExceptionQualcuno ha cercato di firmare il documento, oppure di cancellare la firma di qualcun altro.
403CaseClosedExceptionIl caso è chiuso.
404ItemNotFoundExceptionLa 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.

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 moduli e leggi le risposte con una chiave hubCrea un modulo per un caso utilizzando un modello, pubblicalo per le persone che devono compilarlo e leggi le loro risposte.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