# Electronic Signature Module

<WebSDK2 />

The Electronic Signature module handles eIDAS-aligned electronic signing flows: render documents to be signed, collect compliance consents, capture the signature, and finalize. Three variants exist — base AES, Advanced Electronic Signature (AE), and Qualified Electronic Signature (QE) — that share a single state machine and manager API.

> Follows the [document-signing pattern](doc:web-sdk-2-module-patterns#4-document-signing-modules). See the patterns page for the shared lifecycle.

## Variants

`ae-signature` and `qe-signature` are thin wrappers around `electronic-signature`:

| Module                                  | Manager factory                    | Consent keys               |
| --------------------------------------- | ---------------------------------- | -------------------------- |
| `@incodetech/core/electronic-signature` | `createElectronicSignatureManager` | Caller-provided            |
| `@incodetech/core/ae-signature`         | `createAeSignatureManager`         | `AE_CONSENT_KEYS` (3 keys) |
| `@incodetech/core/qe-signature`         | `createQeSignatureManager`         | `QE_CONSENT_KEYS` (5 keys) |

The wrappers hardcode `variant: 'ae'` or `'qe'` and re-export the same state machine, state types, and helpers from the base module (`AeSignatureState` is `ElectronicSignatureState`, etc.).

Web components: `<incode-electronic-signature>`, `<incode-ae-signature>`, `<incode-qe-signature>`. All three import paths register their own tag and ship their own CSS.

```ts
// Base AES
import '@incodetech/web/electronic-signature';
import '@incodetech/web/electronic-signature/styles.css';

// Advanced Electronic Signature
import '@incodetech/web/ae-signature';
import '@incodetech/web/ae-signature/styles.css';

// Qualified Electronic Signature
import '@incodetech/web/qe-signature';
import '@incodetech/web/qe-signature/styles.css';
```

## Properties

| Property   | Type                        | Required | Description                   |
| ---------- | --------------------------- | -------- | ----------------------------- |
| `config`   | `ElectronicSignatureConfig` | ❌        | Configuration options         |
| `onFinish` | `() => void`                | ❌        | Called when signing completes |
| `onError`  | `(error: string) => void`   | ❌        | Called when an error occurs   |

## Configuration

```typescript
type ElectronicSignatureConfig = {
  variant?: 'ae' | 'qe'; // Hardcoded by the AE/QE wrapper modules
  uploadDocument?: boolean;
  downloadDocument?: boolean;
};
```

| Option             | Type           | Required | Description                                                        |
| ------------------ | -------------- | -------- | ------------------------------------------------------------------ |
| `variant`          | `'ae' \| 'qe'` | ❌        | Set automatically by the AE/QE wrapper modules. Omit for base AES. |
| `uploadDocument`   | `boolean`      | ❌        | Allow the user to upload a custom document to be signed.           |
| `downloadDocument` | `boolean`      | ❌        | Allow the user to download the signed document afterwards.         |

### Consent keys

The user must check all required consent boxes before signing. Each variant defines its own keys (re-exported from the variant's module):

```typescript
const AE_CONSENT_KEYS = ['terms', 'signElectronically', 'signDisplayed'] as const;

const QE_CONSENT_KEYS = [
  'issuance',
  'qesAcknowledgement',
  'qscdConfirmation',
  'termsAgreement',
  'documentsReviewed',
] as const;
```

Helpers from `@incodetech/core/electronic-signature` (also re-exported from the AE/QE wrappers): `getDefaultConsentChecks()` returns a fresh `ConsentChecks` map, `areAllConsented(consents, keys)` returns whether every required key is checked.

## State machine

`ElectronicSignatureState` is a discriminated union over `status`:

| Status       | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `loading`    | Fetching the documents to be signed.                             |
| `reviewing`  | Documents shown; user toggles consent checkboxes; confirms file. |
| `signing`    | User is producing the signature.                                 |
| `uploading`  | Uploading the signed document to the backend.                    |
| `processing` | Server-side processing.                                          |
| `success`    | Signing accepted.                                                |
| `finished`   | Terminal.                                                        |
| `closed`     | User dismissed.                                                  |
| `error`      | Fatal error.                                                     |

The `state.documents` array (when populated) carries the `ElectronicSignatureDocument[]` to render: `{ documentRef, documentUrl }`.

## API methods

| Method                                      | Purpose                                                      |
| ------------------------------------------- | ------------------------------------------------------------ |
| `load()`                                    | Fetch documents.                                             |
| `setConsent(name, checked)`                 | Toggle a consent checkbox by key.                            |
| `selectFile(fileName, fileData, fileUrl)`   | Provide a custom document (when `uploadDocument` is `true`). |
| `replaceFile()`                             | Clear the previously selected file.                          |
| `confirmFile()`                             | Confirm document selection and proceed to signing.           |
| `viewDocument(url)` / `closeDocumentView()` | Open / close the document preview.                           |
| `sign()`                                    | Produce the signature once consents are checked.             |
| `finish()`                                  | Acknowledge `success` and finish.                            |
| `retry()`                                   | After `error`, restart.                                      |
| `close()`                                   | Dismiss (transitions to `closed`).                           |

Plus the universal lifecycle: `subscribe`, `getState`, `reset`, `stop`.

## See also

* [Module: Signature](doc:web-sdk-2-module-signature): handwritten signature on canvas (no document review)
* [Module Patterns → document-signing](doc:web-sdk-2-module-patterns#4-document-signing-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)