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

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

Επισκόπηση

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

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

Πιστοποίηση

Ο προβολέας χρειάζεται ένα έγκυρο token που περνάει στο attribute token. Δείτε Πιστοποίηση με το API πριν συνδέσετε τον προβολέα στην εφαρμογή σας.

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

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

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. Παρακολούθηση επικύρωσης και ταυτοτήτων ρόλων

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

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

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

Οι αλλαγές στο πρότυπο αποθηκεύονται αυτόματα από τον προβολέα — δεν χρειάζεται να καλέσετε κάποια 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 ίσο με το δείκτη του γονικού υπογράφοντα + 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 από πιστοποίηση
mode="compose"	—	Απλοποιημένη λειτουργία για τοποθέτηση πεδίων και αποστολή
mode="editor"	—	Πλήρης λειτουργία επεξεργασίας προτύπου
experience στην είσοδο send	Experience	Ελέγχει branding, emails και σελίδα υπογραφής — δείτε Επεξήγηση εμπειριών

Σχετικά

• Αναφορά Προβολέα Εγγράφων — πλήρης αναφορά attributes και γεγονότων
• mutation send — αποστολή εγγράφου
• DocumentSendSettingsInput — πλήρης δομή εισόδου αποστολής
• Επεξήγηση μεθόδων αποστολής — send vs sendBatch vs sendBulk
• Ανέβασμα αρχείου ως Πρότυπο — ανέβασμα προτύπων μέσω API
• Πιστοποίηση — επιλογή τρόπου πιστοποίησης