Neidio i’r prif gynnwys

Integreiddio’r Gwylwr Dogfennau

Y Gwylwr Dogfennau yw elfen we sy’n caniatáu i ddefnyddwyr olygu templedi a pharatoi dogfennau ar gyfer arwyddo — yn uniongyrchol o fewn eich cais. Mae’r canllaw hwn yn dangos sut i’w gysylltu â’r API GraphQL i adeiladu llif gwaith arwyddo cyflawn.

Trosolwg​

Mae integreiddiad arferol yn dilyn y camau hyn:

  1. Dilysu — cael tocyn ar gyfer y gwylwr
  2. Llwytho template — trwy’r API GraphQL
  3. Gosod y gwylwr — pasio ID y template a’r tocyn
  4. Dal digwyddiadau — mae’r gwylwr yn anfon digwyddiadau update a validate wrth i’r defnyddiwr weithio
  5. Anfon y ddogfen — galw’r newidiad send gyda’r data derbynnydd a rôl o’r gwylwr

Dilysu​

Mae’r gwylwr angen tocyn dilys a basiwyd i’w briodwedd token. Mae’ch cefndir yn darparu tocyn elfen byrhoedlog o generateComponentToken. Edrychwch ar Awdurdodi Widget cyn cysylltu’r gwylwr â’ch cais.

Modd Cyfansoddi — Anfon Dogfen Wedi’i Adeiladu Eisoes​

Mae modd Cyfansoddi ar gyfer llifoedd gwaith lle mae eich system eisoes yn gwybod y derbynwyr. Mae’r defnyddiwr yn rhoi meysydd llofnodi yn unig a chael y dogfen yn anfon.

1. Gosod y gwylwr​

<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. Olrhain dilysiad a ID rôl​

Wrth i’r defnyddiwr ychwanegu meysydd, mae’r gwylwr yn anfon digwyddiadau. Mae angen dwy beth arnoch o’r digwyddiadau hyn:

  • validate — yn dweud a oes gan y templed yr holl feysydd angenrheidiol (yn leiaf, un llofnod fesul derbynnydd)
  • update — yn darparu statws cyfredol y templed, gan gynnwys roleId ar gyfer pob cyfranogwr pan fyddwch angen mapio rôl templed
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;
});
});

Mae’r roleId o’r digwyddiad update yn cysylltu pob derbynnydd gyda’u meysydd ar y templed. Cynnwys hwn pan fydd eich llif anfon angen y map hwnnw.

3. Anfon y ddogfen​

Pan mae’r defnyddiwr yn clicio anfon, galwch y newidiad send gyda data derbynnydd a IDau rôl a ddalwyd o’r gwylwr:

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);
});

Mae’r newidiad send yn dychwelyd ID tasg. Gwnewch holiadur o’r ymholiad task a monitro task.report.status nes ei fod yn cyrraedd COMPLETED neu FAILED i gadarnhau bod creu’r ddogfen wedi gorffen.

Modd Golygydd — Creu Templed​

Mae modd golygydd yn rhoi’r profiad golygu templed llawn i ddefnyddwyr — ychwanegu rolau, rhoi meysydd, ffurfweddu opsiynau. Defnyddiwch hwn pan fyddwch am i ddefnyddwyr adeiladu templedi y gellir eu hailddefnyddio.

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

Yn modd golygydd, mae’r digwyddiad update yn cael ei alw bob tro mae’r templed yn newid. Gallwch ddefnyddio hyn i olrhain statws y templed neu ddangos dangosydd cadw:

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);
});

Mae newidiadau i’r templed yn cael eu cadw’n awtomatig gan y gwylwr — nid oes angen i chi alw unrhyw newidiad GraphQL i gadw’r golygiadau.

Integreiddio React​

Mae’r lapio React yn darparu’r un nodweddion gyda gweithdrefn digwyddiadau arddull 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>
);
};

Tystebwyr​

I ychwanegu tyst am lofnodwr, gosodwch roleType: "WITNESS" a defnyddio signerIndex yn gyfwerth â mynegai’r lofnodwr rhieni + 100. Er enghraifft, mae tyst ar gyfer llofnodwr 2 yn cael 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>

Cysyniadau Allweddol​

Cysyniad GwylwrMath GraphQLDisgrifiad
Briodwedd templateidTemplateY templed sydd mewn golygu neu gyfansoddi
Briodwedd recipientsRecipientInputDerbynwyr a basiwyd i fodd cyfansoddi
roleId o ddigwyddiad updateRoleYn cysylltu derbynnydd â’u meysydd ar y templed
Digwyddiad validate—A oes gan y templed yr holl feysydd angenrheidiol
Newidiad sendsendYn anfon y ddogfen ar ôl cyfansoddi
Briodwedd token—Tocyn o ddilysu
mode="compose"—Modd symleiddiedig ar gyfer rhoi meysydd ac anfon
mode="editor"—Modd golygu templed llawn
experience yn fewnbwn anfonExperienceRheoli brandio, e-byst, a thudalen arwyddo — gweler Esboniad o Brofiadau