Dove va la firma sulla pagina

Ci sono due modi per dire dove firma un firmatario. Metti un tag nel documento (il modo abituale): la firma finisce dove si trova il tag, ovunque lo spinga il testo intorno. Oppure indica delle coordinate nella richiesta. Se per un firmatario mandi entrambi, prevalgono le coordinate.

Con un tag nel documento

Nel modello, un tag si scrive come ogni altro campo, con signature e la chiave che il firmatario ha in signers:

Signed for the customer: {{ signature.A }}
Name: {{ signature.A.name }}      Date: {{ signature.A.date }}

Signed for the supplier: {{ signature.B.box(0.3, 0.08) }}

Tag	Posiziona
`{{ signature.A }}`	la firma del firmatario A
`{{ signature.A.name }}`	il suo nome, stampato quando firma
`{{ signature.A.date }}`	la data in cui firma
`.box(width, height)`	la dimensione, in frazioni della pagina (predefinita `0.25` × `0.06`), su ognuno dei tre

L'angolo in alto a sinistra della firma è dove comincia il tag. Il tag in sé non stampa nulla: quando si fa il PDF viene trovato, trasformato in un campo e tolto dal file prima che il file venga sottoposto a impronta, sigillato o conservato, così non resta testo nascosto che qualcuno possa copiare. Un tag funziona nei modelli Word e HTML nel corpo, in una cella di tabella, in un' intestazione o in un piè di pagina; in Excel in una cella di un foglio (non nell'intestazione o nel piè di pagina di stampa), un tag per cella, posizionato dove comincia il testo della cella, quindi dagli una cella tutta sua. Scrivilo tutto di seguito: Word può dividere un tag che modifichi dopo (Errori comuni).

Più tag per un firmatario fanno più campi: una firma su ogni pagina, o la data accanto a ciascuna. Al massimo 20 tag per firmatario, e 200 in un documento.
Un firmatario senza fields nella richiesta è posizionato dai suoi tag. Un firmatario con fields tiene quelli.
Rifiutato, mai indovinato: un tag per un firmatario che la richiesta non ha (SIGNATURE_TAG_UNKNOWN_SIGNER), e, quando il modello usa i tag, un firmatario senza tag né fields (SIGNER_NOT_PLACED). In POST /api/v1/flow entrambi sono rifiutati prima che il documento sia composto, quindi non costano nulla — tranne per i tag scritti in un allegato caricato, che si leggono quando il documento esiste.
Un tag dentro una condizione che risulta falsa non è nel documento. Un firmatario i cui tag erano tutti nascosti così non è sulla busta: non riceve email, non gli si chiede nulla, ed è nominato nell'avviso SIGNER_NOT_ON_ENVELOPE. Solo quando non resta nessuno a firmare la richiesta è rifiutata (SIGNER_NOT_PLACED, indicando il documento addebitato).
Una persona in più posizioni: dai alle etichette la stessa email (e lo stesso nome, telefono, modo di verifica e lingua) e diventano un solo firmatario, che riceve un invito e firma una volta, con la firma su ogni posizione. Un modello a tre posizioni serve quindi una, due o tre persone. In una busta con ordine, le etichette di una persona devono avere lo stesso order.
Un riquadro vicino al bordo destro o inferiore viene riportato dentro la pagina, mai rimpicciolito.
Un tag dentro un link esistente in un documento Word è rifiutato (un link non può contenerne un altro).
Se i tuoi data hanno un campo proprio chiamato signature, vince il tuo campo e il documento non ha tag.

Un documento composto da solo (POST /api/v1/compose/documents/generate) ricorda dove sono finiti i suoi tag. Mandalo in firma più tardi con il suo documentId e i firmatari senza fields vengono posizionati ai loro tag allo stesso modo.

In un PDF che carichi

Scrivi lo stesso tag come testo nel documento, per esempio {{ signature.A }}, e chiedi che venga letto con "signatureTags": true su quel documento:

"documents": [ { "fileId": "6d1c...", "signatureTags": true } ]

Un file caricato non viene mai analizzato se non lo chiedi. La posizione è esatta quando il tag comincia una riga sua (o sta in una casella di testo sua); dentro una riga più lunga è stimata dai caratteri che lo precedono. Il testo resta nel tuo file: un file caricato è firmato esattamente come l'hai mandato.

Con le coordinate

Le coordinate dei campi sono frazioni della pagina, non millimetri o punti, con l'origine in alto a sinistra. Quindi x: 0.1, y: 0.78 è a un decimo della larghezza e al 78% dell'altezza dall'alto. Sono frazioni perché un modello impaginato di nuovo con un altro formato di pagina metta comunque il segno nello stesso punto.

"signers": {
  "A": { "email": "anna@example.com", "fullName": "Anna Rossi",
         "fields": [ { "kind": "signature", "page": 2, "x": 0.1, "y": 0.78,
                       "width": 0.3, "height": 0.08 } ] }
}

Come leggere x e y da un PDF

Apri il PDF in un visualizzatore che mostra la posizione del cursore in punti (quasi tutti lo fanno: lo strumento di misura di Acrobat, o qualsiasi editor PDF). Una pagina A4 è 595 × 842 punti. Supponi che la riga dove firma il cliente cominci a 70 punti dal bordo sinistro e a 650 punti dall'alto:

x = 70 / 595  = 0.118
y = 650 / 842 = 0.772

Se il tuo visualizzatore misura dal basso (la convenzione propria del PDF), sottrai prima: un punto a 192 dal basso è a 842 − 192 = 650 dall'alto. Larghezza e altezza funzionano allo stesso modo: un riquadro largo 180 punti è 180 / 595 = 0.30. Un campo deve restare sulla pagina: x + width e y + height valgono ciascuno al massimo 1.

Campi che fanno una domanda

Oltre ai segni (signature, name, date), un campo può essere un input a cui il firmatario risponde sulla pagina di firma: text, checkbox o dropdown. La risposta è stampata nel riquadro del campo, registrata nell'evento di firma del registro delle prove, elencata sotto il firmatario nel certificato e restituita nell'API (recipients[].fields[].answer).

{ "kind": "checkbox", "page": 2, "x": 0.1, "y": 0.60,
  "label": "I have read annex B", "required": true }

{ "kind": "dropdown", "page": 2, "x": 0.1, "y": 0.68, "width": 0.4,
  "label": "Role", "options": ["Director", "Employee", "Contractor"],
  "value": "Employee" }

{ "kind": "text", "page": 2, "x": 0.1, "y": 0.76, "width": 0.5,
  "label": "Tax code", "required": false }

Chiave	Significa
`label`	La domanda che vede il firmatario. Obbligatoria per un input.
`required`	Predefinito `true`. La firma è rifiutata (`SIGNER_FIELD_INVALID`) finché non c'è risposta; una casella obbligatoria deve essere spuntata. `false` la lascia vuota, e allora non stampa nulla.
`options`	Solo dropdown: da 2 a 20 scelte, ciascuna fino a 80 caratteri, tutte diverse. Ogni altra risposta è rifiutata.
`value`	Quello che hai precompilato. Il firmatario può cambiarlo…
`locked`	…a meno che sia `true`: allora la risposta è il tuo valore qualunque cosa dica il modulo. Un campo bloccato ha bisogno di un valore.

Nessuna di queste ha senso su un signature, name o date, e una richiesta che ne imposta una lì è rifiutata, mai ignorata. La pagina di firma funziona con gli script disattivati: le domande sono semplici controlli di modulo nell'unico modulo lineare.

Quando la busta ha più di un documento

In una busta possono andare fino a dieci documenti. Vengono uniti, nell' ordine in cui li elenchi, in un solo PDF prima che qualcuno firmi — quindi c'è un solo insieme di segni, un certificato di completamento, un'impronta su /verify, e il firmatario legge un solo file.

"settings": {
  "documents": [
    { "documentId": "contract-9f2a..." },
    { "fileId": "6d1c..." }
  ],
  "subject": "Service agreement"
}

documentId da solo funziona ancora e significa esattamente quello che ha sempre significato; usa documents quando ce n'è più di uno.

Un campo allora dice quale documento e quale pagina di quel documento:

{ "kind": "signature", "document": 2, "page": 1,
  "x": 0.1, "y": 0.8, "width": 0.3, "height": 0.08 }

Mai una pagina assoluta del pacchetto unito. Non puoi sapere quanto lungo il nostro unire abbia reso il file, e la prima volta che un allegato acquista una pagina ogni firma dopo di esso si sposterebbe — in silenzio. Lo scostamento è nostro da conoscere, quindi è nostro da applicare. document vale per impostazione predefinita 1, così una busta scritta prima che esistesse significa esattamente quello che ha sempre significato.

Due cose sono rifiutate invece di essere accettate in silenzio: un campo su un documento che la busta non ha, e un campo oltre l'ultima pagina del suo documento. La seconda prima era accettata e il segno perso al momento della firma, cioè un segno che nessuno vede mai e di cui nessuno viene avvisato.

Una volta firmato, il certificato di completamento elenca ogni sorgente con la sua impronta, e il fascicolo delle prove porta ciascuna separatamente accanto al pacchetto. Il pacchetto ha sostituito le sue parti, quindi senza questo, "quali documenti c'erano dentro" non avrebbe più risposta.

Dove sta tutto questo nel corpo della richiesta: La firma da sola.