Μετάβαση στο κύριο περιεχόμενο

Ενσωμάτωση του Προβολέα Εγγράφων

Ο Προβολέας Εγγράφων είναι ένα web component που επιτρέπει στους χρήστες να επεξεργάζονται πρότυπα και να προετοιμάζουν έγγραφα για υπογραφή — απευθείας μέσα στην εφαρμογή σας. Αυτός ο οδηγός δείχνει πώς να τον συνδέσετε με το GraphQL API για να δημιουργήσετε μια πλήρη ροή εργασίας υπογραφής.

Επισκόπηση​

Μια τυπική ενσωμάτωση ακολουθεί αυτά τα βήματα:

  1. Πιστοποίηση — λάβετε ένα token για τον προβολέα
  2. Αποστολή προτύπου — μέσω του GraphQL API
  3. Απεικόνιση του προβολέα — περάστε το ID του προτύπου και το token
  4. Καταγραφή γεγονότων — ο προβολέας εκπέμπει γεγονότα update και validate καθώς ο χρήστης εργάζεται
  5. Αποστολή του εγγράφου — καλέστε το mutation send με τα δεδομένα των παραληπτών και ρόλων από τον προβολέα

Πιστοποίηση​

Ο προβολέας χρειάζεται ένα έγκυρο token που περνάει στο attribute token. Το backend σας παρέχει ένα βραχυπρόθεσμο token component από το generateComponentToken. Δείτε το Widget Authorization πριν συνδέσετε τον προβολέα στην εφαρμογή σας.

Λειτουργία Σύνθεσης — Αποστολή Προ-κατασκευασμένου Εγγράφου​

Η λειτουργία σύνθεσης προορίζεται για ροές εργασίας όπου το σύστημά σας γνωρίζει ήδη τους παραλήπτες. Ο χρήστης απλώς τοποθετεί πεδία υπογραφής και στέλνει.

1. Απεικόνιση του προβολέα​

<ls-document-viewer
id="viewer"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="compose"
recipients='[
{"email": "jane@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 1},
{"email": "john@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 2}
]'
filtertoolbox="signature|initials|date|text"
>
<span slot="right-button">
<button id="send-btn" disabled>Send</button>
</span>
</ls-document-viewer>

2. Παρακολούθηση επικύρωσης και ID ρόλων​

Καθώς ο χρήστης προσθέτει πεδία, ο προβολέας εκπέμπει γεγονότα. Χρειάζεστε δύο πράγματα από αυτά τα γεγονότα:

  • validate — σας λέει αν το πρότυπο έχει όλα τα απαιτούμενα πεδία (τουλάχιστον μία υπογραφή ανά παραλήπτη)
  • update — παρέχει την τρέχουσα κατάσταση του προτύπου, συμπεριλαμβανομένου του roleId για κάθε συμμετέχοντα όταν χρειάζεστε αντιστοίχιση ρόλων προτύπου
const viewer = document.getElementById('viewer');
const sendBtn = document.getElementById('send-btn');

let isValid = false;
const recipientRoles = {};

viewer.addEventListener('validate', (e) => {
isValid = e.detail.valid;
sendBtn.disabled = !isValid;
});

viewer.addEventListener('update', (e) => {
const roles = e.detail.template.roles;
roles.forEach((role) => {
recipientRoles[role.signerIndex] = role.id;
});
});

Το roleId από το γεγονός update αντιστοιχεί κάθε παραλήπτη στα πεδία του πάνω στο πρότυπο. Συμπεριλάβετε το όταν η ροή αποστολής σας χρειάζεται αυτή την αντιστοίχιση.

3. Αποστολή του εγγράφου​

Όταν ο χρήστης πατάει αποστολή, καλέστε το mutation send με τα δεδομένα παραληπτών και τα ID ρόλων που συλλέχθηκαν από τον προβολέα:

sendBtn.addEventListener('click', async () => {
const token = '<token-from-authentication-guide>';

const recipients = [
{
firstName: 'Jane',
lastName: 'Smith',
email: 'jane@example.com',
role: 'Signer',
roleId: recipientRoles[1],
signerIndex: 1,
order: 1,
},
{
firstName: 'John',
lastName: 'Doe',
email: 'john@example.com',
role: 'Signer',
roleId: recipientRoles[2],
signerIndex: 2,
order: 2,
},
];

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
title: "Contract - Jane Smith & John Doe"
recipients: ${JSON.stringify(recipients).replace(/"(\w+)":/g, '$1:')}
sequentialSigning: true
})
}`,
}),
});

const result = await response.json();
const taskId = result.data.send;

// Poll for completion
console.log('Task started:', taskId);
});

Το mutation send επιστρέφει ένα task ID. Πραγματοποιήστε polling στο ερώτημα task και παρακολουθήστε το task.report.status μέχρι να φθάσει σε COMPLETED ή FAILED για να επιβεβαιώσετε ότι η δημιουργία εγγράφου έχει ολοκληρωθεί.

Λειτουργία Επεξεργασίας — Δημιουργία Προτύπων​

Η λειτουργία επεξεργασίας παρέχει στους χρήστες πλήρη εμπειρία επεξεργασίας προτύπου — προσθήκη ρόλων, τοποθέτηση πεδίων, ρύθμιση επιλογών. Χρησιμοποιήστε την όταν θέλετε οι χρήστες να δημιουργούν επαναχρησιμοποιήσιμα πρότυπα.

<ls-document-viewer
id="editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="editor"
></ls-document-viewer>

Στη λειτουργία επεξεργασίας, το γεγονός update ενεργοποιείται κάθε φορά που το πρότυπο αλλάζει. Μπορείτε να το χρησιμοποιήσετε για να παρακολουθείτε την κατάσταση του προτύπου ή να δείχνετε ένδειξη αποθήκευσης:

const editor = document.getElementById('editor');

editor.addEventListener('update', (e) => {
console.log('Template updated:', e.detail);
});

editor.addEventListener('validate', (e) => {
console.log('Template valid:', e.detail.valid);
});

Οι αλλαγές στο πρότυπο αποθηκεύονται αυτόματα από τον προβολέα — δεν χρειάζεται να καλέσετε κάποιο mutation GraphQL για να αποθηκεύσετε τις επεξεργασίες.

Ενσωμάτωση με React​

Το wrapper για React παρέχει τις ίδιες λειτουργίες με χειρισμό γεγονότων με στυλ React:

import { useState } from 'react';
import { LsDocumentViewer } from 'legalesign-document-viewer-react';

const DocumentCompose = ({ templateId, recipients, token }) => {
const [isValid, setIsValid] = useState(false);
const [roleMap, setRoleMap] = useState({});

const handleValidate = (e) => {
setIsValid(e.detail.valid);
};

const handleUpdate = (e) => {
const roles = e.detail.template.roles;
const map = {};
roles.forEach((role) => {
map[role.signerIndex] = role.id;
});
setRoleMap(map);
};

const handleSend = async () => {
const mappedRecipients = recipients.map((r, i) => ({
...r,
roleId: roleMap[r.signerIndex],
order: i + 1,
}));

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "${templateId}"
title: "Document"
recipients: ${JSON.stringify(mappedRecipients).replace(/"(\w+)":/g, '$1:')}
})
}`,
}),
});

const result = await response.json();
console.log('Task ID:', result.data.send);
};

if (!token) return null;

return (
<LsDocumentViewer
templateid={templateId}
token={token}
mode="compose"
recipients={JSON.stringify(recipients)}
onValidate={handleValidate}
onUpdate={handleUpdate}
>
<div slot="right-button">
<button onClick={handleSend} disabled={!isValid}>
Send
</button>
</div>
</LsDocumentViewer>
);
};

Μάρτυρες​

Για να προσθέσετε έναν μάρτυρα για έναν υπογράφοντα, ορίστε roleType: "WITNESS" και χρησιμοποιήστε signerIndex ίσο με τον δείκτη του γονικού υπογράφοντα + 100. Για παράδειγμα, ένας μάρτυρας για τον υπογράφοντα 2 έχει signerIndex: 102:

<ls-document-viewer
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "Alice", "lastname": "Jones", "signerIndex": 1},
{"email": "signer2@example.com", "firstname": "Bob", "lastname": "Brown", "signerIndex": 2},
{"email": "witness@example.com", "firstname": "Carol", "lastname": "White", "signerIndex": 102, "roleType": "WITNESS"}
]'
...
></ls-document-viewer>

Βασικές Έννοιες​

Έννοια προβολέαΤύπος GraphQLΠεριγραφή
attribute templateidTemplateΤο πρότυπο που επεξεργάζεται ή συντίθεται
attribute recipientsRecipientInputΟι παραλήπτες που δίνονται στη λειτουργία σύνθεσης
roleId από το γεγονός updateRoleΣυνδέει έναν παραλήπτη με τα πεδία του στο πρότυπο
γεγονός validate—Αν το πρότυπο έχει όλα τα απαιτούμενα πεδία
mutation sendsendΣτέλνει το έγγραφο μετά τη σύνθεση
attribute token—Token από authentication
mode="compose"—Απλοποιημένη λειτουργία για τοποθέτηση πεδίων και αποστολή
mode="editor"—Πλήρης λειτουργία επεξεργασίας προτύπου
experience στην είσοδο αποστολήςExperienceΕλέγχει branding, emails και σελίδα υπογραφής — δείτε Experiences explained