Ενσωμάτωση του Προβολέα Εγγράφων
Ο Προβολέας Εγγράφων είναι ένα web component που επιτρέπει στους χρήστες να επεξεργάζονται πρότυπα και να προετοιμάζουν έγγραφα για υπογραφή — απευθείας μέσα στην εφαρμογή σας. Αυτός ο οδηγός δείχνει πώς να τον συνδέσετε με το GraphQL API για να δημιουργήσετε μια πλήρη ροή εργασίας υπογραφής.
Επισκόπηση
Μια τυπική ενσωμάτωση ακολουθεί αυτά τα βήματα:
- Πιστοποίηση — λάβετε ένα token για τον προβολέα
- Αποστολή προτύπου — μέσω του GraphQL API
- Απεικόνιση του προβολέα — περάστε το ID του προτύπου και το token
- Καταγραφή γεγονότων — ο προβολέας εκπέμπει γεγονότα
updateκαιvalidateκαθώς ο χρήστης εργάζεται - Αποστολή του εγγράφου — καλέστε το 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 templateid | Template | Το πρότυπο που επεξεργάζεται ή συντίθεται |
attribute recipients | RecipientInput | Οι παραλήπτες που δίνονται στη λειτουργία σύνθεσης |
roleId από το γεγονός update | Role | Συνδέει έναν παραλήπτη με τα πεδία του στο πρότυπο |
γεγονός validate | — | Αν το πρότυπο έχει όλα τα απαιτούμενα πεδία |
mutation send | send | Στέλνει το έγγραφο μετά τη σύνθεση |
attribute token | — | Token από authentication |
mode="compose" | — | Απλοποιημένη λειτουργία για τοποθέτηση πεδίων και αποστολή |
mode="editor" | — | Πλήρης λειτουργία επεξεργασίας προτύπου |
experience στην είσοδο αποστολής | Experience | Ελέγχει branding, emails και σελίδα υπογραφής — δείτε Experiences explained |
Σχετικά
- Αναφορά Προβολέα Εγγράφων — πλήρης αναφορά attributes και γεγονότων
- mutation send — αποστολή εγγράφου
- DocumentSendSettingsInput — πλήρης δομή εισόδου αποστολής
- Επεξήγηση Μεθόδων Αποστολής — send vs sendBatch vs sendBulk
- Αποστολή Αρχείου ως Πρότυπο — αποστολή προτύπων μέσω API
- Πιστοποίηση — επιλογή τρόπου πιστοποίησης