Πήγαινε στο κύριο περιεχόμενο

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

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

Επισκόπηση​

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

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

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

Ο προβολέας χρειάζεται ένα έγκυρο token που περνάει στην ιδιότητα token. Το backend σας μπορεί να παρέχει είτε ένα SRP JWT είτε ένα βραχύβιο 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. Παρακολούθηση της επικύρωσης και των IDs ρόλων​

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

  • 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 με τα δεδομένα παραληπτών και τα IDs ρόλων που καταγράφηκαν από τον προβολέα:

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 επιστρέφει ένα αναγνωριστικό εργασίας. Κάντε 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);
});

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

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

Το React wrapper παρέχει την ίδια λειτουργικότητα με χειρισμό γεγονότων με στυλ 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 ίσο με το index του γονικού υπογράφοντα + 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Περιγραφή
Ιδιότητα templateidTemplateΤο πρότυπο που επεξεργάζεται ή συντίθεται
Ιδιότητα recipientsRecipientInputΠαραλήπτες που δίνονται στη λειτουργία σύνθεσης
roleId από το γεγονός updateRoleΣυνδέει έναν παραλήπτη με τα πεδία του στο πρότυπο
Γεγονός validate—Αν το πρότυπο έχει όλα τα απαιτούμενα πεδία
Mutation sendsendΣτέλνει το έγγραφο μετά τη σύνθεση
Ιδιότητα token—Token από authentication
mode="compose"—Απλοποιημένη λειτουργία για τοποθέτηση πεδίων και αποστολή
mode="editor"—Πλήρης λειτουργία επεξεργασίας προτύπου
experience στην είσοδο αποστολήςExperienceΕλέγχει το branding, email και σελίδα υπογραφής — δείτε Experiences explained

Export This Article

Save a copy of this page as PDF or plain text.